Wenn der Plattformkern ausgeführt wird und das Ressourcen-Plug-in aktiv ist, wird der Arbeitsbereich durch ein Exemplar von IWorkspace dargestellt, das das Protokoll für den Zugriff auf die enthaltenen Ressourcen zur Verfügung stellt. Ein Exemplar von IWorkspace ist eine zugeordnete Objektgruppe aus Dateien und Verzeichnissen im lokalen Dateisystem. Auf den Arbeitsbereich können Sie über die Klasse des Ressourcen-Plug-ins in org.eclipse.core.resources zugreifen.
ResourcesPlugin.getWorkspace();
Wenn das Ressourcen-Plug-in nicht aktiv ist, existiert der Arbeitsbereich ausschließlich im lokalen Dateisystem und wird durch den Endbenutzer über dateibasierte Standardtools angezeigt oder bearbeitet. Zur Erläuterung der API für das Ressourcen-Plug-in soll zunächst dargestellt werden, wie ein Arbeitsbereich auf Platte vorliegt.
Bei der Installation der Plattform-SDK haben Sie die Dateien in einem Verzeichnis Ihrer Wahl dekomprimiert. Dieses Verzeichnis wird als Stammverzeichnis der Plattform bezeichnet. Dieses Verzeichnis enthält - neben anderen - auch das Verzeichnis plugins. Im Stammverzeichnis der Plattform gibt es ein Arbeitsbereichsverzeichnis namens workspace, in dem die Ressourcen gespeichert sind, die durch die Plattform erstellt und bearbeitet wurden. Wenn Sie sich den Inhalt Ihres Verzeichnisses workspace ansehen, stellen Sie fest, dass es für jedes im Arbeitsbereich vorhandene Projekt ein eigenes Unterverzeichnis gibt. In diesen Unterverzeichnissen befinden sich die Ordner und Dateien, das jeweilige Projekt enthält.
Beispiel: SDK wurde unter c:\MySDK installiert. Daher befinden sich im Verzeichnis c:\MySDK\workspace Unterverzeichnisse, die nach den Projekten des Arbeitsbereichs benannt sind (z. B. MyWeb und MyServlet). Diese werden als Verzeichnisse für den Projektinhalt bezeichnet. Verzeichnisse für Inhalt werden durch die Plattform eingerichtet, wenn der Benutzer ein Projekt erstellt.
In jedem Verzeichnis befinden sich die Dateien und Ordner des Projekts, wobei das Layout exakt mit der Ressourcenbaumstruktur des Arbeitsbereichs identisch ist. Unabhängig davon, ob Sie über das Dateisystem oder aus dem Arbeitsbereich heraus auf Dateien zugreifen: die Namen und der Inhalt der Dateien sind immer identisch. Den einzigen Sonderfall stellt hierbei die Datei .project dar, die später noch erläutert wird.
C:\MySDK\workspace (Stammverzeichnis des Arbeitsbereichs) .metadata\ (Metadatenverzeichnis der Plattform) MyWeb\ (Verzeichnis des Projektinhalts von MyWeb) .project index.html images\ logo.gif MyServlet\ (Verzeichnis des Projektinhalts von MyServlet) .project src\ main.java bin\ main.class
Die Plattform enthält ein spezielles Verzeichnis namens .metadata, das für die Aufnahme von plattforminternen Daten verwendet wird. Das Verzeichnis .metadata eines Arbeitsbereichs wird als "Black Box" betrachtet. Wichtige Angaben über die Struktur des Arbeitsbereichs (z. B. Verweise eines Projekts oder Eigenschaften einer Ressource) werden im Metadatenbereich des Arbeitsbereichs gespeichert. Tools sollten auf diese Daten nur über die Plattform-API zugreifen. Die entsprechenden Dateien dürfen nicht unter Verwendung der generischen Dateisystem-API bearbeitet oder verändert werden.
Darüber hinaus verfügt jedes Projekt über eine eigene Datei .project, in der die Metadaten des Projektes gespeichert werden. Diese Datei stellt eine auf Platte gespeicherte Version der Informationen dar, die für ein Projekt in IProjectDescription gespeichert sind.
Abgesehen vom Verzeichnis .metadata und den Dateien .project können die Ordner und Dateien im Arbeitsbereichsverzeichnis von anderen Tools verwendet werden. Die Dateien und Ordner können über nicht integrierte Tools wie Texteditoren und Dateisystemdienstprogramme bearbeitet werden. Wichtig ist lediglich, dass der Benutzer bei der Bearbeitung dieser Dateien - ob nun in der Workbench oder extern - sorgfältig vorgeht. Hierbei bestehen keine Unterschiede zum Bearbeiten einer Datei mit zwei unabhängigen Standalone-Tools. Die Workbench enthält Aktualisierungsoperationen, um die Sicht "Ressourcen" des Arbeitsbereichs an den tatsächlichen Status im Dateisystem anzugleichen.
Mit der Ressourcen-API kann diese Ressourcenbaumstruktur im Code bearbeitet werden. Im Folgenden werden einige Code-Snippets vorgestellt, um Ihnen einen Eindruck von der Ressourcen-API zu vermitteln. Die Ressourcen-API ist in einer Reihe von Schnittstellen in org.eclipse.core.resources definiert. Es gibt Schnittstellen für alle Ressourcentypen wie IProject, IFolder und IFile. Ein extensives allgemeines Protokoll ist in IResource definiert. Außerdem wird aus org.eclipse.core.runtime die Schnittstelle IPath verwendet, die segmentierte Pfade wie Ressourcen- oder Dateisystempfade darstellt.
Die Bearbeitung von Ressourcen hat große Ähnlichkeit mit der Bearbeitung von Dateien unter Verwendung von java.io.File. Die API basiert auf Kennungen. Wenn Sie eine API wie getProject oder getFolder verwenden, müssen Sie eine Kennung an die Ressource zurückgeben. Es gibt keine Garantie oder Voraussetzung dafür, dass die Ressource selbst vorhanden ist. Dies wird erst dann erkennbar, wenn Sie versuchen, eine Operation für die Kennung auszuführen. Wenn Sie erwarten, dass eine Ressource vorhanden ist, können Sie mit der Methode exists sicherstellen, dass dies der Fall ist.
Um im Arbeitsbereich von einem Plug-in aus navigieren zu können, muss zunächst das Objekt IWorkspaceRoot abgerufen werden, das die Ausgangsebene der Ressourcenhierarchie im Arbeitsbereich darstellt.
IWorkspaceRoot myWorkspaceRoot = ResourcesPlugin.getWorkspace().getRoot();
Sobald ein Stammverzeichnis für den Arbeitsbereich bekannt ist, können Sie auf die Projekt im Arbeitsbereich zugreifen.
IProject myWebProject = myWorkspaceRoot.getProject("MyWeb"); // Ggfs. öffnen if (myWebProject.exists() && !myWebProject.isOpen()) myWebProject.open(null);
Bevor ein Projekt bearbeitet werden kann, muss es geöffnet werden. Beim Öffnen des Projekts wird die Projektstruktur von Platte gelesen und die speicherinterne Objektdarstellung für die Ressourcenbaumstruktur des Projekts erstellt. Das Öffnen eines Projekts ist eine explizite Operation, da jedes geöffnete Projekt Speicherkapazität belegt, um die Ressourcenbaumstruktur intern darzustellen, und da geöffnete Projekte an zahlreichen Ereignissen für den Ressourcenlebenszyklus (z. B. Erstellung) beteiligt sind, die sehr lange dauern können. Auf geschlossene Projekte kann generell nicht zugegriffen werden. Obwohl die Ressourcen im Dateisystem immer noch vorhanden sind, werden sie als leere Projekte angezeigt.
Sie haben vielleicht bereits festgestellt, dass in vielen dieser Ressourcenbeispiele bei der Bearbeitung von Ressourcen einen Nullparameter übergeben wird. Viele Ressourcenoperationen sind potenziell systembelastend genug, um einen Fortschrittsbericht und den Benutzerabbruch zu garantieren. Wenn Ihr Code eine Benutzerschnittstelle enthält, übergeben Sie normalerweise ein Objekt IProgressMonitor. Hierdurch kann das Ressourcen-Plug-in den Fortschritt melden, sobald die Ressource bearbeitet wird, und der Benutzer kann die Operation abbrechen, wenn er dies wünscht. Im Beispiel wird einfach der Wert null übergeben, damit keine Fortschrittsüberwachung stattfindet.
Sobald ein Projekt geöffnet wurde, ist der Zugriff auf seine Dateien und Ordner und auch die Erstellung zusätzlicher Dateien und Ordner möglich. Im folgenden Beispiel wird aus dem Inhalt einer Datei, die sich außerhalb des Arbeitsbereichs befindet, eine Dateiressource erstellt.
IFolder imagesFolder = myWebProject.getFolder("images"); if (imagesFolder.exists()) { // Eine neue Datei erstellen IFile newLogo = imagesFolder.getFile("newLogo.gif"); FileInputStream fileStream = new FileInputStream( "c:/MyOtherData/newLogo.gif"); newLogo.create(fileStream, false, null); // create schließt den Dateistrom. }
Im vorstehenden Beispiel ruft die erste Zeile eine Kennung für den Ordner mit den Images ab. Es muss überprüft werden, ob dieser Ordner vorhanden ist ("exists"), bevor die gewünschten Operationen ausgeführt werden können. Ebenso stellt die Kennung beim Abrufen der Datei newLogo erst dann eine reale Datei dar, wenn die Datei in der letzten Linie erstellt wurde. Im Beispiel wird die Datei erstellt, indem der Inhalt aus der Datei logo.gif eingefügt wird.
Das nächste Snippet hat Ähnlichkeit mit dem vorherigen, kopiert jedoch die neue Datei newLogo aus dem Originallogo, statt aus dem Inhalt dieses Logos eine neue Datei zu erstellen.
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"); ... }
Schließlich kann ein weiterer Image-Ordner erstellt und die neu erstellte Datei in diesen versetzt werden. Beim Versetzen wird die Datei gleichzeitig umbenannt.
... 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");
Viele Methoden für die Ressourcen-API enthalten den Booleschen Parameter force. Dieser gibt an, ob Ressourcen aktualisiert werden sollen, die nicht mehr mit den entsprechenden Dateien im lokalen Dateisystem synchron sind. Weitere Informationen finden Sie unter IResource. Sie können auch IResource.isSynchronized verwenden, um festzustellen, ob eine bestimmte Ressource mit dem Dateisystem synchronisiert ist.
Im Beispiel für die Ressourcenbaumstruktur wurde davon ausgegangen, dass sich alle Verzeichnisse für den Projektinhalt im Verzeichnis workspace befinden, das ein Unterverzeichnis des Stammverzeichnisse für die Plattform ist (C:\MySDK\workspace). Dies entspricht der Standardkonfiguration für Projekte. Das Verzeichnis für den Inhalt eines Projekts kann jedoch einem anderen, willkürlich gewählten Verzeichnis im Dateisystem, möglicherweise sogar auf einem anderen Plattenlaufwerk, neu zugeordnet werden.
Durch die Möglichkeit, die Position eines Projekts unabhängig von anderen Projekten zuzuordnen, kann der Benutzer den Inhalt eines Projekts in einer Position speichern, die für das Projekt und für das Projektteam sinnvoll ist. Das Verzeichnis mit dem Inhalt eines Projekts sollte als allgemein bekanntes und zugängliches Verzeichnis betrachtet werden. Dies bedeutet, dass Benutzer zum Erstellen, Änderung und Löschen von Ressourcen die Workbench und ihre Plug-ins, aber auch direkt auf dem Dateisystem basierende Tools und Editoren verwenden können.
Die Namen von Ressourcenpfaden sind keine vollständigen Dateisystempfade. Ressourcenpfade werden immer ausgehend von der Position des Projekts (normalerweise das Verzeichnis workspace) angegeben. Um den vollständigen Dateisystempfad für eine Ressource zu ermitteln, müssen Sie ihre Position mit IResource.getLocation ermitteln. Die Verwendung von IProjectDescription.setLocation zum Ändern dieser Position ist jedoch nicht möglich, da diese Methode lediglich ein einfacher Setter für eine Datenstruktur ist.
Wenn Sie hingegen das zugehörige Ressourcenobjekt auf der Basis eines Dateisystempfads ermitteln wollen, können Sie IWorkspaceRoot.getFileForLocation oder IWorkspaceRoot.getContainerForLocation verwenden.
Wenn die Ressourcenbaumstruktur des Arbeitsbereichs unter Verwendung der Ressourcen-API geändert wird, werden nicht nur die Ressourcenobjekte aktualisiert, sondern auch die Dateien im Dateisystem geändert. Was passiert aber, wenn Ressourcendateien außerhalb der Plattform-API geändert werden?
Externe Änderungen an Ressourcen werden erst dann im Arbeitsbereich und den Ressourcenobjekten wiedergegeben, wenn sie durch das Ressourcen-Plug-in festgestellt wurden. Mit der Ressourcen-API können Clients den Arbeitsbereich und Ressourcenobjekte einfach und ohne Eingreifen des Benutzers an das lokale Dateisystem angleichen. Der Benutzer kann in der Workbench-Sicht "Navigator" für die Ressource jederzeit eine Aktualisierung explizit anfordern.
Hinweis: Viele der Methoden in den Ressourcen-APIs enthalten einen Parameter "force", der angibt, wie Ressourcen verarbeitet werden sollen, die nicht mehr mit dem Dateisystem synchron sind. Die API-Referenz zu den einzelnen Methoden enthält spezifische Informationen zu diesem Parameter. Über zusätzliche Methoden in der API kann die Dateisystemaktualisierung programmatisch gesteuert werden (z. B. IResource.refreshLocal(int depth, IProgressMonitor monitor). Informationen zur korrekten Verwendung und zum Aufwand finden Sie unter IResource.