Quando l'elemento centrale della piattaforma è in esecuzione e il plug-in delle risorse è attivo, lo spazio di lavoro viene rappresentato mediante un'istanza di IWorkspace, che fornisce il protocollo per l'accesso alle risorse in esso contenute. Un'istanza IWorkspace rappresenta una raccolta associata di file e directory all'interno del file system locale. L'utente può accedere allo spazio di lavoro dalla classe del plug-in delle risorse in org.eclipse.core.resources.
ResourcesPlugin.getWorkspace();
Quando il plug-in delle risorse non è in esecuzione, lo spazio di lavoro è presente solo nel file system locale e viene visualizzato o modificato dall'utente attraverso gli strumenti standard basati su file. Mentre viene illustrata l'API del plug-in di risorse, verrà descritto come appare lo spazio di lavoro sul disco.
Durante l'installazione dell'SDK della piattaforma, i file sono stati decompressi in una directory scelta dall'utente. Tale directory viene definita directory principale della piattaforma e contiene, tra le altre, la directory plugins. All'interno della directory principale della piattaforma, è presente una directory workspace che viene utilizzata per conservare le risorse create e manipolate dalla piattaforma. Esaminando la directory workspace, è possibile individuare sottodirectory separate per ciascun progetto esistente nello spazio di lavoro. All'interno di queste sottodirectory sono conservate le cartelle e i file che ogni progetto contiene.
Se, nell'esempio, SDK è installato in c:\MySDK, all'interno della directory c:\MySDK\workspace, dopo i progetti dello spazio di lavoro sono presenti sottodirectory denominate MyWeb e MyServlet. Queste vengono dette directory del contenuto dei progetti. Le directory del contenuto vengono create dalla piattaforma quando l'utente crea un progetto.
All'interno di ciascuna directory si trovano i file e le cartelle del progetto, disposte esattamente come appaiono nella struttura delle risorse dello spazio di lavoro. Tutti i nomi file sono gli stessi e il relativo contenuto rimane lo stesso se si accede dal file system oppure dallo spazio di lavoro. L'unica novità è rappresentata dal file .project, che verrà illustrato tra breve.
C:\MySDK\workspace (directory principale dello spazio di lavoro) .metadata\ (directory dei metadati della piattaforma) MyWeb\ (directory del contenuto del progetto per MyWeb) .project index.html images\ logo.gif MyServlet\ (directory del contenuto del progetto per MyServlet) .project src\ main.java bin\ main.class
La piattaforma dispone di una speciale directory .metadata per la conservazione di informazioni interne della piattaforma. La directory .metadata di uno spazio di lavoro viene considerata come una "scatola nera". Le informazioni importanti relative alla struttura dello spazio di lavoro, ad esempio i riferimenti di un progetto oppure le proprietà di una risorsa, vengono memorizzate nella porzione di metadati dello spazio di lavoro e l'accesso a tali informazioni dovrebbe avvenire solo mediante gli strumenti attraverso l'API della piattaforma. Questi file non dovrebbero mai essere modificati o manipolati mediante API generiche del file system.
Inoltre, ogni progetto dispone del proprio file .project in cui vengono conservati i metadati relativi al progetto. Tale file rappresenta sostanzialmente un equivalente su disco delle informazioni reperibili in un IProjectDescription del progetto.
Oltre che dalla directory .metadata e dai file .project, le cartelle e i file della directory dello spazio di lavoro possono essere utilizzati da altri strumenti. I file e le cartelle possono essere manipolati da strumenti non integrati, quali gli editor di testo e le utilità del file system. L'utente deve tuttavia prestare attenzione durante la modifica di tali file sia nel workbench che esternamente, esattamente come quando si modifica un file utilizzando due strumenti autonomi. Il workbench fornisce operazioni di aggiornamento per riconciliare la vista delle risorse nello spazio di lavoro con lo stato effettivo all'interno del file system.
L'API delle risorse consente all'utente di manipolare questa struttura di risorse in codice. Per una rapida descrizione dell'API delle risorse verranno illustrati alcuni frammenti di codice. L'API delle risorse è definita in una serie di interfacce in org.eclipse.core.resources. Esistono interfacce per tutti i tipi di risorse, come IProject, IFolder e IFile. Il protocollo comune completo è definito in IResource. Viene anche utilizzata l'interfaccia di org.eclipse.core.runtime, IPath, che rappresenta percorsi segmentati quali i percorsi di risorsa o di file system.
La manipolazione delle risorse è molto simile alla manipolazione dei file mediante java.io.File. L'API si basa sugli handle. Quando si utilizza un'API quale getProject o getFolder, viene restituito un handle per la risorsa. Finché non si tenta l'esecuzione di un'operazione con l'handle non si può esser certi che la risorsa esista o sia necessaria. Per verificare l'esistenza di una risorsa è possibile utilizzare il metodo exists.
Per esplorare lo spazio di lavoro da un plug-in, è prima necessario ottenere IWorkspaceRoot, che rappresenta il livello più alto della gerarchia delle risorse nello spazio di lavoro.
IWorkspaceRoot myWorkspaceRoot = ResourcesPlugin.getWorkspace().getRoot();
Una volta ottenuta la directory principale dello spazio di lavoro, è possibile accedere ai progetti in esso contenuti.
IProject myWebProject = myWorkspaceRoot.getProject("MyWeb"); // aprire se necessario if (myWebProject.exists() && !myWebProject.isOpen()) myWebProject.open(null);
Prima di poter manipolare un progetto, è necessario aprirlo. L'apertura del progetto provoca la lettura della struttura del progetto dal disco e la creazione della rappresentazione di oggetto in memoria della struttura delle risorse del progetto. L'apertura di un progetto è un'operazione esplicita poiché ogni progetto aperto consuma memoria per rappresentare internamente la struttura delle risorse e perché i progetti aperti partecipano a diversi eventi del ciclo di vita della risorsa (ad esempio la creazione) che possono essere lunghi. In generale, non è possibile accedere a progetti chiusi e questi ultimi appariranno vuoti anche se le risorse sono ancora presenti nel file system.
Si noterà che molti di questi esempi di risorse trasmettono un parametro null durante la manipolazione delle risorse. Numerose operazioni relative alle risorse sono potenzialmente abbastanza pesanti da garantire rapporti sull'avanzamento e l'annullamento da parte degli utenti. Se il proprio codice dispone di un'interfaccia utente, in genere viene trasmesso a un IProgressMonitor, che consente al plug-in delle risorse di segnalare lo stato di avanzamento mentre la risorsa viene manipolata e permette all'utente di annullare l'operazione, se lo desidera. Per il momento, viene semplicemente trasmesso null per indicare l'assenza di un controllo dello stato di avanzamento.
Quando si dispone di un progetto aperto, è possibile accedere alle cartelle e ai file ivi contenuti nonché crearne di nuovi. Nell'esempio riportato di seguito, viene creata una risorsa di file dal contenuto di un file esterno ubicato al di fuori dello spazio di lavoro dell'utente.
IFolder imagesFolder = myWebProject.getFolder("images"); if (imagesFolder.exists()) { // crea un nuovo file IFile newLogo = imagesFolder.getFile("newLogo.gif"); FileInputStream fileStream = new FileInputStream( "c:/MyOtherData/newLogo.gif"); newLogo.create(fileStream, false, null); // crea istruzioni di chiusura per il flusso di file, per cui non si verificheranno problemi. }
Nell'esempio riportato sopra, la prima riga ottiene un handle per la cartella delle immagini. Prima di eseguire qualsiasi operazione relativa a tale cartella, è necessario verificarne l'esistenza. Analogamente, quando si ottiene il file newLogo, l'handle non rappresenta un file reale finché il file non viene creato nell'ultima riga. In questo esempio, il file viene creato inserendovi il contenuto di logo.gif.
Il seguente frammento di codice è simile al precedente, con l'eccezione che copia il file newLogo dal logo originale anziché crearne uno nuovo dal suo contenuto.
IFile logo = imagesFolder.getFile("logo.gif"); if (logo.exists()) { IPath newLogoPath = new Path("newLogo.gif"); logo.copy(newLogoPath, false, null); IFile newLogo = imagesFolder.getFile("newLogo.gif"); ... }
Infine, verrà creata un'altra cartella di immagini in cui si sposterà il file appena creato. Come conseguenza dello spostamento, si ridenominerà il file.
... IFolder newImagesFolder = myWebProject.getFolder("newimages"); newImagesFolder.create(false, true, null); IPath renamedPath = newImagesFolder.getFullPath().append("renamedLogo.gif"); newLogo.move(renamedPath, false, null); IFile renamedLogo = newImagesFolder.getFile("renamedLogo.gif");
Molti dei metodi dell'API delle risorse includono un indicatore booleano force che specifica se le risorse non sincronizzate rispetto ai corrispondenti file nel file system locale verranno comunque aggiornate. Per ulteriori informazioni, vedere IResource. È anche possibile utilizzare IResource.isSynchronized per stabilire se una particolare risorsa è sincronizzata con il file system.
Nella struttura delle risorse di esempio, si presuppone che tutte le directory del contenuto di progetto si trovino nella directory workspace all'interno della directory principale della piattaforma (C:\MySDK\workspace). Questa rappresenta la configurazione predefinita per i progetti. Tuttavia, la directory del contenuto di un progetto può essere riassociata a qualsiasi altra directory del file system, anche su una diversa unità disco.
La capacità di associare il percorso di un progetto indipendente ad altri progetti consente all'utente di memorizzare il contenuto di un progetto in un'ubicazione significativa per il progetto e per il team del progetto. La directory del contenuto di un progetto dovrebbe essere considerata "sempre aperta". Ciò significa che gli utenti possono creare, modificare ed eliminare risorse utilizzando il workbench e i plug-in oppure utilizzando direttamente strumenti ed editor basati sul file system.
I nomi di percorso delle risorse non sono percorsi di file system completi. I percorsi delle risorse sono sempre basati sulla posizione del progetto (generalmente la directory workspace). Per ottenere il percorso completo del file system per una risorsa, è necessario eseguire una query del percorso utilizzando IResource.getLocation. Tuttavia, non è possibile utilizzare IProjectDescription.setLocation per modificarne il percorso, in quanto si tratta semplicemente di un metodo di impostazione per una struttura di dati.
Al contrario, se si desidera ottenere da un percorso di file system l'oggetto di risorsa corrispondente, è possibile utilizzare IWorkspaceRoot.getFileForLocation o IWorkspaceRoot.getContainerForLocation.
Quando si utilizzano API di risorse per modificare la struttura delle risorse dello spazio di lavoro, oltre ad aggiornare gli oggetti risorsa, i file vengono modificati nel file system. E le modifiche di file di risorse apportate al di fuori dell'API della piattaforma?
Le modifiche esterne alle risorse non verranno riflesse nello spazio di lavoro e negli oggetti risorsa fino a quando non verranno rilevate dal plug-in di risorse. I client possono utilizzare l'API delle risorse per riconciliare lo spazio di lavoro e gli oggetti risorsa con il file system locale, in modo automatico e senza l'intervento dell'utente. L'utente può sempre forzare esplicitamente un aggiornamento nella vista Selezione delle risorse del workbench.
Nota: molti dei metodi delle API delle risorse includono un parametro force che specifica il modo in cui devono essere gestite le risorse non sincronizzate con il file system. Il Riferimento API di ciascun metodo fornisce informazioni specifiche su questo parametro. Metodi aggiuntivi presenti nell'API consentono il controllo programmatico dell'aggiornamento del file system, ad esempio IResource.refreshLocal(int depth, IProgressMonitor monitor). Per informazioni sul corretto utilizzo e sui costi, vedere IResource.