Je-li spuštěná platforma a modul prostředků je aktivní, pracovní prostor je reprezentován instancí IWorkspace, která poskytuje protokol pro přístup k prostředkům, jež obsahuje. Instance IWorkspace reprezentuje přidruženou kolekci souborů a adresářů v lokálním systému souborů. Do pracovního prostoru můžete získat přístup ze třídy modulu prostředků (definované v org.eclipse.core.resources).
IWorkspace workspace = ResourcesPlugin.getWorkspace();
Když není modul plug-in prostředků spuštěný, pracovní prostor existuje pouze v lokálním systému souborů a uživatel jej zobrazuje nebo s ním manipuluje prostřednictvím standardních nástrojů na bázi souborů. Podívejme se, jak vypadá pracovní soubor na disku, což pochopíme na základě vysvětlení rozhraní API modulu prostředků.
Když jste instalovali platformu SDK, dekomprimovali jste soubory do adresáře, který jste si sami zvolili. Tomuto adresáři budeme říkat kořenový adresář platformy. Je to adresář, který mimo jiné obsahuje také adresář plugins. Uvnitř kořenového adresáře platformy je adresář pracovní prostor, který se používá k ukládání prostředků, jež platforma vytváří a manipuluje s nimi. Když se podíváte do svého adresáře pracovní prostor, uvidíte jednotlivé podadresáře pro každý projekt, který existuje v pracovním prostoru. V těchto podadresářích jsou složky a soubory obsažené v každém projektu.
Pokud je platforma SDK v našem příkladu instalovaná v adresáři c:\MySDK, potom v adresáři c:\MySDK\workspace najdeme podadresáře pojmenované podle projektů v pracovním prostoru, tedy MyWeb a MyServlet. Těm se říká adresáře obsahu projektu. Platforma vytvoří adresáře obsahu, když uživatel vytvoří projekt.
V každém adresáři najdeme soubory a složky patřící do projektu, jež jsou uspořádány naprosto stejně jako ve stromu prostředků pracovního prostoru. Všechny názvy souborů jsou totožné a obsah souborů je stejný, ať se do nich přistupuje ze systému souborů nebo z pracovního prostoru. Jediným překvapením je soubor .project, který si vysvětlíme za okamžik.
C:\MySDK\workspace (kořen pracovního prostoru) .metadata\ (adresář metadat platformy) MyWeb\ (adresář obsahu projektu pro MyWeb) .project index.html images\ logo.png MyServlet\ ((adresář obsahu projektu pro MyServlet) .project src\ main.java bin\ main.class
Platforma má speciální adresář .metadata pro ukládání interních informací platformy. Adresář .metadata pracovního prostoru je považován za "černou skříňku". Důležité informace o struktuře pracovního prostoru, jako např. odkazy projektu nebo vlastnosti prostředku, se ukládají v části pracovního prostoru obsahující metadata a pro přístup k nim by se měly používat pouze nástroje zprostředkované rozhraním API platformy. Tyto soubory by se nikdy neměly upravovat ani by se s nimi nemělo manipulovat za použití generického rozhraní API systému souborů.
Kromě toho má každý projekt svůj vlastní soubor .project, v němž se uchovávají metadata o projektu. Tento soubor je v podstatě diskovým ekvivalentem informací obsažených v popisu projektu IProjectDescription.
Kromě adresáře .metadata a souborů .project jsou ostatní složky a soubory v adresáři pracovního prostoru určeny pro použití běžných nástrojů. Se soubory a složkami je možno manipulovat pomocí neintegrovaných nástrojů, jako např. textových editorů a obslužných programů systému souborů. Uživatel musí pouze dávat pozor při upravování těchto souborů na pracovní ploše a externě. (To se nijak neliší od situace, kdy uživatel upravuje soubor za pomoci dvou navzájem nezávislých samostatných nástrojů.) Pracovní plocha poskytuje obnovovací operace, jejichž pomocí se zobrazení prostředků pracovního prostoru porovnává se skutečným stavem v systému souborů a pracovní prostor se pravidelně aktualizuje na základě stavu systému souborů.
Rozhraní API prostředků nám umožňuje manipulovat s tímto stromem prostředků ve formě kódu. Nyní si prohlédneme některé úseky kódu, abychom si udělali stručnou představu o rozhraní API prostředků. API prostředků je definováno v sérii rozhraní v org.eclipse.core.resources. Jsou zde rozhraní pro všechny typy prostředků, jako např. IProject, IFolder a IFile. Rozsáhlý společný protokol je definován v IResource. Také využíváme org.eclipse.core.runtime rozhraní IPath, které reprezentuje rozsegmentované cesty, a to například k prostředkům nebo systému souborů.
Manipulace s prostředky je velmi podobná jako manipulace se soubory za použití java.io.File. Rozhraní API je založeno na popisovačích (handle). Když použijete API jako getProject nebo getFolder, obdržíte popisovač prostředku. Neexistuje žádná záruka ani požadavek, aby samotný prostředek existoval, dokud se nepokusíte něco udělat s popisovačem. Pokud předpokládáte, že prostředek existuje, můžete se o tom přesvědčit pomocí metody exists.
Pro přechod do pracovního prostoru z modulu plug-in musíme nejprve získat IWorkspaceRoot, který představuje vrchol hierarchie prostředků v pracovním prostoru.
IWorkspaceRoot myWorkspaceRoot = ResourcesPlugin.getWorkspace().getRoot();
Jakmile máme kořen pracovního prostoru, můžeme získat přístup k projektům v pracovním prostoru.
IProject myWebProject = myWorkspaceRoot.getProject("MyWeb"); // v případě potřeby otevřít if (myWebProject.exists() && !myWebProject.isOpen()) myWebProject.open(null);
Abychom mohli s projektem manipulovat, musíme jej otevřít. Při otevření projektu se jeho struktura načte z disku a v paměti se vytvoří objektová reprezentace stromu prostředků daného projektu. Otevření projektu je explicitní operace, jelikož každý otevřený projekt spotřebovává paměť nutnou k interní reprezentaci stromu prostředků a otevřené projekty se podílejí na různých událostech v rámci životního cyklu prostředků (například sestavení), které mohou trvat dost dlouho. Obecně lze říci, že do zavřených projektů nelze získat přístup a že zavřené projekty vypadají, jako by byly prázdné, i když jejich prostředky jsou v systému souborů stále přítomny.
Všimnete si, že při manipulaci s prostředky mnohé z příkladů těchto prostředků poskytují nulový parametr. Mnohé operace s prostředky jsou potenciálně dostatečně náročné, než aby zaručovaly vytváření zpráv o průběhu a zrušení uživatelem. Pokud má váš kód uživatelské rozhraní, zpravidla předáte IProgressMonitor, který modulu prostředků umožňuje vykazovat průběh při manipulaci s prostředkem a dovoluje uživateli, aby v případě potřeby operaci zrušil. Prozatím jednoduše zadáme hodnotu null, což znamená, že žádný monitor průběhu není přítomen.
Jakmile máme projekt otevřený, máme přístup k jeho složkám a souborům a také můžeme vytvářet další. V následujícím příkladu vytvoříme souborový prostředek z obsahu souboru umístěného mimo náš pracovní prostor.
IFolder imagesFolder = myWebProject.getFolder("images"); if (imagesFolder.exists()) { // vytvořit nový soubor IFile newLogo = imagesFolder.getFile("newLogo.png"); FileInputStream fileStream = new FileInputStream( "c:/MyOtherData/newLogo.png"); newLogo.create(fileStream, false, null); // vytvoření zavře tok souboru, takže není důvod k obavám. }
Ve výše uvedeném příkladu první řádek získává popisovač ke složce s obrazy. Musíme se přesvědčit, že složka existuje, než s ní budeme moci něco zajímavého dělat. Podobně když získáváme soubor newLogo, popisovač nepředstavuje skutečný soubor, dokud nevytvoříme soubor v posledním řádku. V tomto příkladu vytvoříme soubor tím, že jej naplníme obsahem logo.png.
Následující úsek kódu je podobný předchozímu, pouze s tím rozdílem, že nevytvoří nový soubor newLogo z obsahu původního souboru, ale zkopírováním původního souboru.
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"); ... }
Nakonec vytvoříme další složku obrazů a nově vytvořený soubor do ní přesuneme. Vedlejším účinkem přesunutí souboru je jeho přejmenování.
... 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");
Mnohé metody rozhraní API prostředků zahrnují logický příznak force, který určuje, zda prostředky, které nejsou synchronizované s odpovídajícími soubory v lokálním systému souborů, budou i přesto aktualizovány. Další informace viz téma IResource. Za pomoci IResource.isSynchronized také můžete zjistit, zda je určitý prostředek synchronizovaný se systémem souborů.
V ukázkovém stromu prostředků jsme předpokládali, že všechny adresáře obsahu projektu jsou v adresáři pracovní prostor uvnitř kořenového adresáře platformy (C:\MySDK\workspace). To je výchozí konfigurace projektů. Adresář obsahu projektu je však možno přemapovat na jakýkoli jiný adresář v systému souborů, třeba i na jiném disku.
Schopnost mapovat umístění projektu nezávisle na jiných projektech uživateli umožňuje uložit obsah projektu na místo, jež je pro daný projekt a tým, který na něm pracuje, smysluplné. Adresář obsahu projektu je nutno považovat za "zcela otevřený". Znamená to, že uživatelé mohou vytvářet, modifikovat a odstraňovat prostředky pomocí pracovní plochy a modulů plug-in, nebo přímo za použití nástrojů a editorů na bázi systému souborů.
Názvy cest k prostředkům nejsou kompletní cesty v systému souborů. Cesty k prostředkům jsou vždy založeny na umístění projektu (obvykle v adresáři pracovní prostor). Abyste získali plnou cestu k prostředku v systému souborů, musíte se na jeho umístění dotázat pomocí metody IResource.getLocation. Ke změně jeho umístění však nemůžete použít metodu IProjectDescription.setLocation , jelikož tato metoda je pouze jednoduchý mechanizmus nastavení struktury dat.
Pokud chcete naopak najít odpovídající objekt prostředku podle dané cesty v systému souborů, můžete použít metodu IWorkspaceRoot.getFileForLocation nebo IWorkspaceRoot.getContainerForLocation.
Při použití API prostředků k modifikaci stromu prostředků našeho pracovního prostoru se kromě aktualizace objektů prostředků změní i soubory v systému souborů. A co změny souborů prostředků, k nimž dojde mimo API platformy?
Externí změny prostředků se v pracovním prostoru ani na objektech prostředků neprojeví, dokud je nezjistí modul plug-in prostředků. Modul plug-in prostředků také používá vhodný mechanizmus pro každý konkrétní nativní operační systém ke zjištění externích změn provedených v systému souborů. Kromě toho mohou klienti používat rozhraní API prostředků k porovnání pracovního prostoru a objektů prostředků s lokálním systémem souborů nenápadně a bez zásahu uživatele. Uživatel také může obnovení explicitně vynutit v pohledu navigátoru prostředků pracovní plochy.
Mnohé z metod v rozhraních API prostředků zahrnují parametr force, který určuje, jak se má zacházet s prostředky, které nejsou synchronizovány se systémem souborů. Odkaz API pro každou metodu poskytuje specifické informace o tomto parametru. Další metody v API umožňují programové řízení aktualizace systému souborů, jako například IResource.refreshLocal(int depth, IProgressMonitor monitor). Informace o správném používání a ceně najdete pod tématem IResource.
Moduly plug-in, které chtějí poskytovat vlastní mechanizmus pravidelného aktualizování pracovního prostoru na základě stavu externího systému souborů, tak mohou činit za pomoci bodu rozšíření org.eclipse.core.resources.refreshProviders. Další informace viz témaObnovit poskytovatele.