Wenn der Plattformkern 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 der Schnittstelle 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 im Paket 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. Es 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, die 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. Ganz gleich, ob Sie über das Dateisystem oder aus dem Arbeitsbereich heraus auf Dateien zugreifen: die Namen und der Inhalt der Dateien sind immer identisch.
C:\MySDK\workspace (Stammverzeichnis des Arbeitsbereichs)
.metadata\ (Metadatenverzeichnis der Plattform)
MyWeb\ (Verzeichnis des Projektinhalts von MyWeb)
index.html
images\
logo.gif
MyServlet\ (Verzeichnis des Projektinhalts von MyServlet)
src\
main.java
bin\
main.class
main$$1.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. die Verweise eines Projekts oder die 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.
Abgesehen vom Verzeichnis .metadata 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. Dies ist nicht anders als der Fall, in dem ein Benutzer eine Datei mit zwei unabhängigen Standalone-Tools bearbeitet. 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-Ausschnitte 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 der Schnittstelle IResource definiert. Außerdem wird aus dem Paket 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, wird eine Kennung an die Ressource zurückgegeben. 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 dem Protokoll exists() sicherstellen, dass dies der Fall ist.
Um im Arbeitsbereich von einem Plug-in aus navigieren zu können, muss zunächst die Schnittstelle IWorkspaceRoot abgerufen werden, die 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");
// 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 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 werden vielleicht feststellen, dass viele Ressourcenbeispiele bei der Bearbeitung von Ressourcen einen Nullparameter übergeben. Viele Ressourcen 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 externen Datei, die sich außerhalb des Arbeitsbereichs befindet, eine Dateiressource erstellt.
IFolder imagesFolder = myWebProject.getFolder("images");
if (imagesFolder.exists()) {
// Neue Datei erstellen
IFile newLogo = imagesFolder.getFile("newLogo.gif");
FileInputStream fileStream = new FileInputStream(
"c:/MyOtherData/newLogo.gif");
newLogo.create(fileStream, false, null);
fileStream.close();
}
Im vorstehenden Beispiel ruft die erste Zeile eine Kennung für den Imageordner 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 wird. Im Beispiel wird die Datei erstellt, indem der Inhalt aus der Datei logo.gif eingefügt wird.
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.gif");
if (logo.exists()) {
IPath newLogoPath = new Path("newLogo.gif");
logo.copy(newLogoPath,
false, null);
IFile newLogo = imagesFolder.getFile("newLogo.gif");
...
}
Abschließend wird ein weiterer Imageordner erstellt und die neu erstellte Datei in diesen versetzt. 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.
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, Ändern 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 Dateisystemposition einer bestimmten Ressource können Sie feststellen, indem Sie ihre Position mit getLocation() abfragen. 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 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 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 für die einzelnen Methoden enthält spezifische Informationen zu diesem Parameter. Über zusätzliche Methoden in der API kann die Dateisystemaktualisierung programmgestützt gesteuert werden (z. B. IResource.refreshLocal(int depth, IProgressMonitor monitor). Informationen zur korrekten Verwendung und zum Aufwand finden Sie unter IResource.