Inkompatibilitet mellem Eclipse 3.1 og 3.2

Eclipse er ændret på en inkompatibel måde fra 3.1 til 3.2 på en måde, som påvirker plugins. Indgangene nedenfor beskriver de områder, der er ændret, og giver en vejledning i, hvordan man overfører 3.1-plugins til 3.2. Bemærk, at du kun behøver læse disse oplysninger, hvis du får problemer med at udføre 3.1-plugins i 3.2.

  1. Ressourcer er ikke længere nødvendigvis i det lokale filsystem
  2. API-ændringer til MultiPageEditorSite
  3. Indholdsændringer i config.ini
  4. Indholdsændringer i JNLP-distribuerede programmer
  5. Eksplicitte kald til Bundle.start() fremtvinger, at bundtet aktiveres ved næste genstart
  6. Understregning erstattes ikke længere af bindestreg i versionsnumre for plugins

1. Ressourcer er ikke længere nødvendigvis i det lokale filsystem

Hvad påvirkes: Klienter for API'et IWorkspace, der antager, at ressourcer er gemt i det lokale filsystem.

Beskrivelse: Før Eclipse 3.2 havde hver IResource en tilsvarende fil eller bibliotek i filsystemet, som man kunne få adgang til med java.io.File. I Eclipse 3.2 er der tilføjet understøttelse til oprettelse af ressourcer, der er gemt i et vilkårligt baggrundsfilsystem. Ressourcer, der anvender denne understøttelse, kan ikke længere være repræsenteret direkte som en java.io.File.

Påkrævet handling: Den gamle metode IResource.getLocation() returnerer den lokale sti til filsystemet for en ressource. Denne metode returnerer NULL for ressourcer, der ikke er gemt i det lokale filsystem. De fleste kaldere af getLocation() gjorde dette for at hente en forekomst af java.io.File, der ikke længere kan anvendes til ressourcer, der ikke er gemt i det lokale filsystem.

Den nye plugin org.eclipse.core.filesystem stiller et generisk filsystem-API til rådighed, der kan anvendes i stedet for java.io.File. I særdeleshed stiller en forekomst af org.eclipse.core.filesystem.IFileStore de fleste af de samme metoder til rådighed, som er tilgængelige i java.io.File. Følgende stykke kode henter en forekomst af IFileStore for en given ressource:

   IResource resource = ...;//en ressource
   IFileStore store = EFS.getStore(resource.getLocationURI());

Den følgende tabel indeholder ækvivalente metoder på IFileStore for funktioner, der normalt udføres med java.io.File:

java.io.FileIFileStore
slet slet
getName getName
getParentgetParent
Liste childNames
mkdirmkdir(EFS.SHALLOW, null)
mkdirsmkdir(EFS.NONE, null)
renameTomove
new FileInputStream(file)openInputStream
new FileOutputStream(file)openOutputStream

I API'et IFileStore gemmes de fleste oplysninger om filer i en struktur, der kaldes IFileInfo, der hentes ved at kalde IFileStore.fetchInfo(). Dette design tillader større optimering af kode, der anvender java.io.File, fordi mange attributter omkring en fil ofte kan hentes med et enkelt filsystemkald. Bemærk, at oplysningerne i IFileInfo bliver forældede, hvis den underliggende fil ændres, så forekomster skal kun beholdes, så længe de er nødvendige. Her er nogle metoder på java.io.File, der har tilsvarende metoder på IFileInfo:

java.io.FileIFileInfo
canWriteisReadOnly
existsexists
getName getName
isDirectoryisDirectory
isFile!isDirectory()
isHiddenisHidden
lastModifiedgetLastModified
length getLength
setLastModifiedsetLastModified
setReadOnlysetAttribute(EFS.ATTRIBUTE_READ_ONLY, true)

Eksempel: Kode som tidligere kaldte med java.io.File.exists(), kan nu kalde IFileStore.fetchInfo().exists(). Når en IFileInfo ændres, skal resultatet gemmes tilbage vha. metoden IFileStore.putInfo. Dette stykke angiver attributten Skrivebeskyttet på en fil

  	IFileStore store = ...//fillagring
	IFileInfo info = store.fetchInfo();
   boolean readOnly = info.getAttribute(EFS.ATTRIBUTE_READ_ONLY);
   info.setAttribute(EFS.ATTRIBUTE_READ_ONLY, !readOnly);
		store.putInfo(info, EFS.SET_ATTRIBUTES, null);

IProjectDescription.getLocation()

Som med metoden getLocation() er projektbeskrivelsesplaceringen ikke længere i det lokale filsystem. Metoden IProjectDescription.getLocationURI() kan anvendes til at hente placeringen af en ressource i et vilkårligt filsystem.

Lokal cache

Visse klienter skal absolut have en lokal repræsentation af en fil. F.eks. kan de starte et oprindeligt værktøj mod den fil eller bruge biblioteker, der ikke kendes af Eclipse, der kun kan behandle filsystemressourcer, f.eks. java.util.zip.ZipFile. I disse tilfælde kan du bede en IFileStore om at returnere en lokal kopi i cache af dens indhold:

  	IFileStore store = ...//fillagring
   //se, om den kan være direkte repræsenteret som en lokal fil
   java.io.File local = store.toLocalFile(EFS.NONE, null);
   //hvis ikke, så anmod om en lokal kopi i cache af filen
   if (local == null)
      local = store.toLocalFile(EFS.CACHE, null);

Bemærk, at når en kopi af en fil i cache er hentet, bevarer den ikke synkroniseringen med det aktuelle filsystem, den kom fra. Når kopien i cache ændres, bliver den underliggende fil ikke ændret.

Elegante fejl

Klienter, der ikke kan behandle ressourcer uden for det lokale filsystem, kan stadig ønske at tilpasse deres kode, så der opstår fejl mere elegant. Klienter kan kontrollere, om en ressource er på det lokale filsystem og enten ignorere ressourcen eller advare brugeren, når de opdager en ressource, de ikke kan behandle. For at bestemme, om en ressource er på det lokale filsystem, skal du prøve at finde skemaet for dens filsystem. Det kan hentes fra en ressource på følgende måde:

   IResource resource = ...;//en ressource
   URI uri = resource.getLocationURI();
   if (uri != null && EFS.SCHEME_LOCAL.equals(uri.getScheme())) {
      //filen er i det lokale filsystem
        } else {
      //filen er ikke i det lokale filsystem
   }

Hvis du har en forekomst af IFileStore ved hånden, kan du hente skemaet sådan:

   IFileStore store = ...;//fillagring
   store.getFileSystem().getScheme();

2. API-ændringer til MultiPageEditorSite

Hvad påvirkes: Klienter, der kalder MultiPageEditorSite.progressStart() eller MultiPageEditorSite.progressEnd().

Beskrivelse: Under udviklingen af Eclipse 3.0 blev disse metoder tilføjet som en del af statusunderstøttelsesarbejdet. Før release 3.0 blev den måde, status blev behandlet på, ændret, og denne metode var ikke længere nødvendig. På grund af programmeringsfejl blev disse offentlige metoder ladt tilbage for release 3.0. De to metoder har aldrig tjent noget formål i en Eclipse-release og er derfor slettet.

Påkrævet handling Klienter, der kalder MultiPageEditorSite.progressStart() eller MultiPageEditorSite.progressEnd() skal skifte til IWorkbenchSiteProgressService i stedet for.

3. Indholdsændringer i config.ini

Hvad påvirkes: Klienter, der skal tilpasse en config.ini og flytter deres program til 3.2.

Beskrivelse: Før 3.2 var den typiske værdi for osgi.bundles i config.ini org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start. På grund af runtime-refactoring skal denne værdi opdateres, for at programmet kan starte korrekt.

Påkrævet handling: Revidér værdien for osgi.bundles, så den inkluderer org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start.

4. Indholdsændringer i JNLP-distribuerede programmer

Hvad påvirkes: Klienter, der distribuerer RCP-programmer, og har angivet en værdi til osgi.bundles.

Beskrivelse: Før 3.2 var den typiske værdi for osgi.bundles i JNLP-hovedfilen org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start. På grund af runtime-refactoring skal denne værdi opdateres, ellers kan NullPointerException'er sende en fejl, der forhindrer programmet i at starte.

Påkrævet handling: Revidér værdien af osgi.bundles for at inkludere org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start.

5. Eksplicitte kald til Bundle.start() fremtvinger, at bundtet aktiveres ved næste genstart

Hvad påvirkes: Klienter, der kalder Bundle.start().

Beskrivelse: I Eclipse angives et bundt til at være et lazy-startbundt ved at bruge headeren Eclipse-LazyStart eller den forældede header Eclipse-AutoStart. I Eclipse 3.1 markerede metoden org.osgi.framework.Bundle.start() ikke lazy-startbundter som vedholdende startet. Da lazy-startbundter aldrig blev valgte som vedholdende startet, blev de ikke automatisk startet, når Eclipse blev genstartet. Javadoc for Bundle.start() angiver, at følgende skal ske, når metoden kaldes:

"Registrer vedholdende, at dette bundt er startet. Når Struktur er genstartet, skal dette bundt startes automatisk."

I Eclipse 3.2 er metoden Bundle.start() rettet, så bundtet markeres korrekt som vedholdende startet, også selvom bundtet er et lazy-startbundt. Denne rettelse var påkrævet for at overholde OSGI-strukturspecifikationen. Som resultat vil kaldere af Bundle.start() fremtvinge, at bundtet startes, når Eclipse genstartes. Generelt betragtes dette som dårligt, fordi det vil forårsage, at unødvendige bundter aktiveres, hver gang Eclipse startes. I visse tilfælde kan det forårsage uventede resultater, se f.eks. programfejl 134412.

Handling påkrævet Klienter for Bundle.start() skal vurdere, om deres intention er vedholdende at aktivere bundtet for hver genstart. Hvis det ikke er intentionen, skal klienter finde en anden måde at aktivere bundtet på. I de fleste tilfælde kan kald til Bundle.start() undgås ved simpelthen at tillade målbundtet at blive lazy-aktiveret, når der indlæses klasser fra det. Der er sjældne scenarier, der kræver, at et lazy-startbundt bliver aktiveret aggressivt, men ikke vedholdende valgte for aktivering ved genstart. Disse typer scenarier skal bruge Bundle.loadClass() til at indlæse en klasse fra bundtet, der skal aktiveres i stedet for at kalde Bundle.start().

5. Understregning erstattes ikke længere af bindestreg i versionsnumre for plugins

I Eclipse 3.0 blev brugen af en understregning ('_') i kvalifikatorsegmentet ikke understøttet, men det blev heller ikke fremtvunget. Hvis en pluginversions-id indeholdt en understregning i kvalifikatoren, blev tegnet ændret til en bindestreg ('-'), når plugin'en blev eksporteret til filsystemet og desuden, når plugin'en blev installeret fra et opdateringswebsted.
I Eclipse 3.1 blev reglerne for tilladte tegn i kvalifikatorer udvidet til understregning, så når en krænkende plugin blev eksporteret eller installeret, blev kvalifikatoren ikke ændret. Den ændring blev ved et uheld udeladt af overførselsguiden for 3.0 til 3.1. Eclipse 3.2 vedligeholder kompatibilitet med Eclipse 3.1, og plugins, der anvender understregning i deres versionskvalifikatorer, skal være opmærksomme på de føromtalte ændringer, når de har at gøre med gamle plugins, både ved eksport og når de findes på opdateringswebsteder. Det betyder f.eks., at pluginudbydere, der har gamle versioner af deres plugins på et opdateringswebsted, skal sikre, at navnet i filsystemet matcher navnet på plugin'en.