Incompatibilità tra Eclipse 3.1 e 3.2

Eclipse è stato modificato tra le versioni 3.1 e 3.2 in modi incompatibili che influiscono sui plugin. Le sezioni di seguito riportate descrivono le aree modificate e forniscono istruzioni per la migrazione dei plugin dalla versione 3.1 alla versione 3.2. È opportuno fare riferimento a queste sezioni solo se si verificano problemi durante l'esecuzione del plugin 3.1 su 3.2.

  1. Risorse non più necessarie nel file system locale
  2. Modifiche API a MultiPageEditorSite
  3. Content changes in config.ini
  4. Content changes in jnlp deployed applications
  5. Explicit calls to Bundle.start() force the bundle to be activated on next restart
  6. Underscore no longer replaced by hyphen in plug-ins version numbers

1. Resources are no longer necessarily in the local file system

Elementi interessati: i client dell'API IWorkspace che considerano le risorse memorizzate nel file system locale.

Descrizione: nelle versioni precedenti a Eclipse 3.2, ciascuna IResource esistente aveva un file o una directory corrispondente nel file system a cui era possibile accedere da java.io.File. In Eclipse 3.2, è stato aggiunto supporto per la creazione di risorse il cui contenuto viene archiviato in un file system arbitrario. Le risorse che utilizzano questo supportano non possono più essere rappresentate direttamente come java.io.File.

Azione richiesta: il vecchio metodo IResource.getLocation() restituisce il percorso del file system locale di una risorsa. Questo metodo restituisce null per le risorse non archiviate nel file system locale. La maggior parte dei chiamanti di getLocation() hanno lo stesso comportamento per ottenere un'istanza di java.io.File, che non può più essere utilizzata per le risorse non archiviate nel file system locale.

The new org.eclipse.core.filesystem plug-in provides a generic file system API that can be used in place of java.io.File. In particolare, un'istanza di org.eclipse.core.filesystem.IFileStore fornisce più metodi di quelli disponibili in java.io.File. Il seguente frammento di codice ottiene un'istanza di IFileStore per una determinata risorsa:

   IResource resource = ...;//indicare la risorsa
   IFileStore store = EFS.getStore(resource.getLocationURI());

La seguente tabella fornisce metodi equivalenti a IFileStore per operazioni generalmente effettuate con java.io.File:

java.io.FileIFileStore
eliminaelimina
getNamegetName
getParentgetParent
elencochildNames
mkdirmkdir(EFS.SHALLOW, null)
mkdirsmkdir(EFS.NONE, null)
renameTomove
new FileInputStream(file)openInputStream
new FileOutputStream(file)openOutputStream

Nell'API IFileStore, la maggior parte delle informazioni relative a un file, sono archiviate in una struttura chiamata IFileInfo, ottenuta richiamando IFileStore.fetchInfo(). Questa progettazione consente di ottimizzare i codice utilizzando java.io.File, perché molti attributi relativi a un file possono essere spesso ottenuti con una singola chiamata al file system. Tenere presente che le informazioni contenute in un IFileInfo diventeranno obsolete se viene modificato il file in questione, quindi le istanze dovrebbero essere conservate solo fino a quando sono necessarie. Alcuni metodi in java.io.File hanno metodi equivalenti in IFileInfo:

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

Ad esempio, il codice precedentemente noto come java.io.File.exists() adesso richiama IFileStore.fetchInfo().exists(). Quando un file IFileInfo viene modificato, il risultato deve essere nuovamente archiviato mediante il metodo IFileStore.putInfo. Ad esempio, questo frammento modifica l'attributo di sola lettura di un file

   IFileStore store = ...;//indicare l'archivio file
   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()

Così come il metodo getLocation(), il percorso della descrizione del progetto non può essere più ubicato nel file system locale. È possibile utilizzare il metodo IProjectDescription.getLocationURI() per ottenere il percorso di una risorsa in un file system arbitrario.

Cache locale

Alcuni client richiedono la rappresentazione locale dei file. Ad esempio, potrebbero avviare uno strumento nativo per questo file, o utilizzare librerie non compatibili con Eclipse che gestiscono solo le risorse del file system (java.util.zip.ZipFile). In questi casi, è possibile richiedere a IFileStore di restituire una copia locale memorizzata nella cache del contenuto:

   IFileStore store = ...;//indicare l'archivio file
   //verificare se può essere rappresentato come file locale
   java.io.File local = store.toLocalFile(EFS.NONE, null);
   //in caso contrario, richiedere una copia locale memorizzata nella cache del file
   if (local == null)
      local = store.toLocalFile(EFS.CACHE, null);

Tenere presente che dopo aver ottenuto una copia del file, tale file non rimarrà sincronizzato con il file system di provenienza. Se viene modificata la copia memorizzata nella cache, il file reale non verrà modificato.

Errore non grave

I client che non gestiscono le risorse esterne possono adattare il proprio codice in modo che gli eventuali errori che possono verificarsi non siano gravi. I client possono verificare se una risorsa è presente nel file system locale e se ignorare la risorsa o informare l'utente quando viene rilevata una risorsa che non possono gestire. Per determinare se una risorsa è contenuta nel file system locale, è necessario individuare lo schema del file system. Tale schema può essere ottenuto da una risorsa nel modo seguente:

   IResource resource = ...;//indicare la risorsa
   URI uri = resource.getLocationURI();
   if (uri != null && EFS.SCHEME_LOCAL.equals(uri.getScheme())) {
      //il file si trova nel file system locale
   } else {
      //il file non si trova nel file system locale
   }

Se si dispone di un'istanza IFileStore, è possibile ottenere lo schema come segue:

   IFileStore store = ...;//un archivio file
   store.getFileSystem().getScheme();

2. API changes to MultiPageEditorSite

Elementi interessati: client ce richiamano MultiPageEditorSite.progressStart() o MultiPageEditorSite.progressEnd().

Descrizione: durante lo sviluppo con Eclipse 3.0, questi metodi devono essere aggiunti come parte del lavoro di supporto. Prima del release 3.0, la gestione era diversa e questo metodo non era necessario. A causa di un errore di programmazione, questi metodi pubblici sono stati lasciati per il release 3.0. Questi due metodi non sono mai stati utilizzati, quindi sono stati eliminati.

Azione richiesta: i client che richiamano Clients calling MultiPageEditorSite.progressStart() o MultiPageEditorSite.progressEnd() devono passare a IWorkbenchSiteProgressService.

3. Content changes in config.ini

What is affected: Clients who have a custom a config.ini and are moving their application to 3.2.

Description: Prior to 3.2, the typical value for osgi.bundles contained in the config.ini was org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start. Because of the runtime refactoring, this value needs to be updated for the application to successfully start.

Action required:Change the value of osgi.bundles to includes org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start.

4. Content changes in jnlp deployed applications

What is affected: Clients deploying RCP applications and specified a value to osgi.bundles.

Description: Prior to 3.2, the typical value for osgi.bundles contained in the main jnlp file was org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start. Because of the runtime refactoring, this value needs to be updated otherwise NullPointerExceptions could be thrown preventing the application to start.

Action required:Change the value of osgi.bundles to includes org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start.

5. Explicit calls to Bundle.start() force the bundle to be activated on next restart

What is affected: Clients that call Bundle.start().

Description: In Eclipse a bundle is specified to be a lazy start bundle by using the Eclipse-LazyStart header (or the deprecated Eclipse-AutoStart header). In Eclipse 3.1, the method org.osgi.framework.Bundle.start() did not mark lazy start bundles as persistently started. Since lazy start bundles never got marked as persistently started they would not be automatically started when eclipse was restarted. The javadoc for Bundle.start() states that the following must occur when the method is called:

"Persistently record that this bundle has been started. When the Framework is restarted, this bundle must be automatically started."

In Eclipse 3.2 the Bundle.start() method has been fixed to properly mark the bundle as persistently started even if the bundle is a lazy start bundle. This fix was required to comply with the OSGi Framework specification. As a result callers of Bundle.start() will force the bundle to be started when Eclipse is restarted. In general this is considered a bad practice because it will cause unnecessary bundles to be activated each time Eclipse is started. In some cases it can cause unexpected results such as bug 134412.

Action required: Clients of Bundle.start() need to evaluate if their intention is to persistently activate the bundle for every restart. If that is not the intention then clients should find another way to activate the bundle. In most cases calls Bundle.start() can be avoided by simply allowing the target bundle to be lazily activated when classes are loaded from them. There are rare scenarios that require a lazy start bundle to be agressively activated, but not persistenly marked for activation on a restart. These types of scenarios should use Bundle.loadClass() to load a class from the bundle which needs to be activated instead of calling Bundle.start().

5. Underscore no longer replaced by hyphen in plug-in version numbers

In Eclipse 3.0, the use of an underscore ('_') character in the qualifier segment of a version identifier was not supported, but also was not enforced. If a plug-in version identifier contained an underscore in the qualifier, then this character was transformed to a hyphen ('-') when exporting the plug-in to the file-system and also when installing the plug-in from an update site.
In Eclipse 3.1 the rules for characters allowed in qualifiers was relaxed to include the underscore character, so when an offending plug-in was exported or installed the qualifier was not modified from its original state. This subtle change was accidently left out from the migration guide for 3.0 to 3.1. The story going forward (and for Eclipse 3.2) is that we are maintaining compatibility with Eclipse 3.1 and plug-ins who use underscore characters in their version qualifiers, should be aware of the aforementioned changes when dealing with old plug-in versions (both when exporting and when they exist on update sites). This means, for instance, that plug-in providers who have old versions of their plug-in on an update site should ensure that the name in the file-system matches the name of the plug-in.