Wenn die Plattform ausgeführt wird und das Ressourcen-Plug-in aktiv ist, wird der Arbeitsbereich durch ein Exemplar der Schnittstelle IWorkspace dargestellt, die 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 zugreifen (in org.eclipse.core.resources definiert).
IWorkspace workspace = 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 einem Datenträger 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.png 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 einem Datenträger gespeicherte Version der Informationen dar, die für ein Projekt in IProjectDescription gespeichert sind.
Neben dem Verzeichnis .metadata und den Dateien .project können die Ordner und Dateien im Arbeitsbereichsverzeichnis frei von anderen Tools verwendet werden. Die Dateien und Ordner können über nicht-integrierte Tools (z.B. Texteditoren oder Dateisystemdienstprogramme) geändert werden. Der Benutzer muss lediglich vorsichtig sein, wenn er diese Dateien sowohl in der Workbench als auch extern bearbeitet. (Dies ist nicht anders, als würde ein Benutzer zwei unabhängige Standalone-Tools zur Bearbeitung von Dateien verwenden.) Die Workbench enthält Aktualisierungsoperationen, um die Sicht "Ressourcen" des Arbeitsbereichs an den tatsächlichen Status im Dateisystem anzugleichen und den Arbeitsbereich regelmäßig basierend auf dem Status des Dateisystems zu aktualisieren.
Mit der Ressourcen-API kann diese Ressourcenbaumstruktur im Code bearbeitet werden. Im Folgenden werden einige Codeausschnitte 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 Änderung von Ressourcen ähnelt stark der Änderung von Dateien unter Verwendung von java.io.File. Die API beruht auf Kennungen. Wenn Sie APIs wie getProject oder getFolder verwenden, wird ihnen eine Kennung an die Ressource zurückgegeben. Es gibt weder eine Garantie noch eine Bestimmung, dass die Ressource selbst existiert, bis Sie versuchen, die Kennung zu verwenden. Wenn Sie erwarten, dass eine Ressource existiert, können Sie die Methode exists verwenden, um dies sicherzustellen.
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 Projekte im Arbeitsbereich zugreifen.
IProject myWebProject = myWorkspaceRoot.getProject("MyWeb"); // open if necessary 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 einem Dateinträger 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 weil geöffnete Projekte an zahlreichen Ereignissen im 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 ein Paramter von Null ü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 eine Schnittstelle IProgressMonitor. Hierdurch kann das Ressourcen-Plug-in den Status 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 Statusü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()) { // create a new file IFile newLogo = imagesFolder.getFile("newLogo.png"); FileInputStream fileStream = new FileInputStream( "c:/MyOtherData/newLogo.png"); newLogo.create(fileStream, false, null); // create closes the file stream, so no worries. }
In diesem 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 Zeile erstellt wurde. In diesem Beispiel erstellen wir die Datei durch Auffüllen mit dem Inhalt von logo.png.
Der nächste Ausschnitt 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.png"); if (logo.exists()) { IPath newLogoPath = new Path("newLogo.png"); logo.copy(newLogoPath, false, null); IFile newLogo = imagesFolder.getFile("newLogo.png"); ... }
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.png"); newLogo.move(renamedPath, false, null); IFile renamedLogo = newImagesFolder.getFile("renamedLogo.png");
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 hierzu 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 auf die Position des Projekts (für gewöhnlich das Verzeichnis workspace) bezogen angegeben. Um den vollständigen Dateisystempfad für eine Ressource zu ermitteln, müssen Sie ihre Position mit IResource.getLocation abrufen. 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. Das Ressourcen-Plug-in verwendet außerdem einen für jedes native Betriebssystem geeigneten Mechanismus zur Feststellung externer Änderungen am Dateisystem. Darüber hinaus können Clients mit der Ressourcen-API 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.
Viele 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, wie z. B. IResource.refreshLocal(int depth, IProgressMonitor monitor). Informationen zur korrekten Verwendung und zum Aufwand finden Sie unter IResource.
Plug-ins, die ihren eigenen Mechanismus zur regelmäßigen Aktualisierung des Arbeitsbereichs basierend auf dem Status des externen Dateisystems verwenden möchten, können hierfür den Erweiterungspunkt org.eclipse.core.resources.refreshProviders verwenden. Weitere Informationen finden Sie unter Aktualisierungsprovider.