Obszary niekompatybilności między środowiskiem Eclipse w wersji 2.1 i 3.0

Środowisko Eclipse zmieniło się w taki sposób, że wersje 2.1 i 3.0 nie są kompatybilne, a różnice wpływają między innymi na moduły dodatkowe. W przedstawionych dalej sekcjach opisano obszary zmian i podano instrukcje umożliwiające przeprowadzenie migracji modułów dodatkowych z wersji 2.1 do wersji 3.0. Należy pamiętać, że skorzystanie z podanych tutaj informacji jest konieczne tylko wtedy, gdy przy uruchomianiu modułu dodatkowego z wersji 2.1 w środowisku w wersji 3.0 występują problemy.

  1. Wersja manifestu modułu dodatkowego
  2. Restrukturyzacja modułów dodatkowych interfejsu użytkownika platformy
  3. Restrukturyzacja modułów dodatkowych głównego środowiska wykonawczego platformy
  4. Usunięcie modułu dodatkowego Xerces
  5. Lepsza obsługa współbieżności w środowisku Eclipse 3.0
  6. Otwieranie edytorów na elementach IFile
  7. Znacznik przechodzenia w edytorze
  8. Program uruchamiający edytor
  9. Rejestr edytora
  10. Rejestr pomocy dotyczącej znaczników środowiska roboczego
  11. Dostawcy dokumentów edytora tekstu
  12. Edytory tekstu
  13. Obsługa adnotacji bez nagłówka
  14. Widok konsoli
  15. Funkcje nasłuchiwania punktów zatrzymania Java
  16. Dostęp do schowka w wątku interfejsu użytkownika
  17. Zdarzenia naciśnięcia klawiszy
  18. Przechodzenie między niestandardowymi elementami sterującymi za pomocą klawisza Tab
  19. Porządek zdarzeń wyboru w widgetach drzew i tabel SWT
  20. Nowy poziom istotności w obiektach statusu
  21. Powiadomienia dotyczące zmian zasobów związanych z budowaniem
  22. Powiadomienia pośrednie podczas operacji w obszarze roboczym
  23. Rozszerzenia procedury obsługi strumienia URL
  24. Porządek ładowania klas
  25. Nieustawiona domena ochrony programu ładującego klasy
  26. Rzutowanie obiektu PluginModel
  27. Niekompletna implementacja interfejsu ILibrary
  28. Niepoprawne założenia dotyczące formy adresów URL
  29. Przeniesione/usunięte metody z klasy BootLoader
  30. Eksport modułu dodatkowego nie obejmuje automatycznie plików JAR modułu dodatkowego
  31. Ponowne eksportowanie interfejsu API środowiska wykonawczego
  32. Metody analizy modułów dodatkowych z klasy Platform
  33. Biblioteki modułów dodatkowych udostępniane przez fragmenty
  34. Zmiany w skryptach budowania
  35. Zmiany w czynności budowania PDE narzędzia Ant
  36. Zmiany w czynności Ant eclipse.build
  37. Zmiany w czynności Ant eclipse.fetch
  38. Zastąpienie pliku install.ini

1. Wersja manifestu modułu dodatkowego

Nagłówek plików manifestu dla modułów dodatkowych (i fragmentów modułów) uległ zmianie polegającej na dodaniu nowego wiersza, który identyfikuje wersję manifestu odpowiedniego modułu dodatkowego. Przed wprowadzeniem wersji 3.0 moduły dodatkowe nie zawierały wierszy <?eclipse ...?>; począwszy od wersji 3.0 obecność takiego wiersza jest obowiązkowa. Zmiana ma na celu umożliwienie bezbłędnego rozpoznania przez środowisko wykonawcze Eclipse modułów dodatkowych z wersji wcześniejszych niż 3.0, które nie zostały przeniesione do wersji 3.0 - dzięki temu możliwe jest automatycznie udostępnienie większego stopnia kompatybilności binarnej na potrzeby tego rodzaju modułów. Ogólna forma pliku plugin.xml wygląda następująco (plik fragment.xml jest podobny):

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin ...>
    ...
</plugin>

Manifesty modułów dodatkowych utworzone w środowisku PDE 3.0 przyjmują taką formę automatycznie. Zaleca się stanowczo użycie narzędzia do migrowania modułów dodatkowych dostępnego w środowisku PDE. Pozwala ono wstawiać automatycznie wskazane wiersze do manifestu modułów dodatkowych i ich fragmentów z wersji 2.1, a także rozwiązać problemy wynikające z innych opisanych tutaj zmian.

Po dodaniu tej dyrektywy do pliku plugin.xml (ręcznie lub przy użyciu narzędzia PDE) należy jeszcze zaktualizować plik, tak aby jawnie uwzględniał listę modułów dodatkowych, od których jest zależny. Przykładowo przed wprowadzeniem środowiska Eclipse w wersji 3.0 zależności od modułu org.eclipse.core.runtime i org.eclipse.core.boot miały charakter niejawny. Wraz z wprowadzeniem wersji 3.0 moduł org.eclipse.core.boot nie jest już potrzeby i programiści powinni korzystać odpowiednio z modułu org.eclipse.core.runtime lub org.eclipse.core.runtime.compatibility (albo nie używać żadnego z nich).

Uwaga: Jest to jedna z niekompatybilności, które nie mają wpływu na sposób uruchamiania binarnych modułów dodatkowych z wersji 2.1 w środowisku Eclipse 3.0.

2. Restrukturyzacja modułów dodatkowych interfejsu użytkownika platformy

Moduł dodatkowy org.eclipse.ui, który do tej pory stanowił główny moduł interfejsu użytkownika platformy, teraz udostępnia jedynie interfejs API oraz punkty rozszerzeń dla ogólnego (tj. niezwiązanego z żadnym konkretnym środowiskiem IDE) środowiska roboczego. Interfejsy API i punkty rozszerzeń o charakterze opcjonalnym lub związanym z określonym środowiskiem IDE zostały przeniesione do innych modułów dodatkowych.

Ma to konsekwencje dwojakiego rodzaju: (1) przeniesione punkty rozszerzeń modułu org.eclipse.ui mają nowe identyfikatory; (2) lista wymaganych modułów dodatkowych uległa zmianie.

Punkty rozszerzeń z modułu org.eclipse.ui w przedstawionej poniżej tabeli zostały przeniesione do innych modułów, co pociągnęło za sobą zmianę ich identyfikatorów. Jeśli istniejący moduł dodatkowy wnosi rozszerzenie do przeniesionych punktów rozszerzeń, należy zmodyfikować odwołanie w atrybucie "point" przy elemencie <extension> w pliku manifestu modułu dodatkowego, tak aby wskazywało na nowy identyfikator danego punktu rozszerzenia. Odpowiednią poprawkę można wprowadzić za pomocą narzędzia do migrowania modułów dodatkowych wchodzącego w skład środowiska PDE.

Uwaga: Jest to jedna z niekompatybilności, które nie mają wpływu na sposób uruchamiania binarnych modułów dodatkowych z wersji 2.1 w środowisku Eclipse 3.0. Środowisko wykonawcze Eclipse 3.0 automatycznie wykrywa moduły dodatkowe z wersji wcześniejszych niż 3.0 (na podstawie nieobecności wspomnianego wcześniej wiersza <?eclipse version="3.0"?> w manifeście modułu) i uwzględnia opisane zmiany w zakresie zależności punktów rozszerzeń i modułów dodatkowych.

Stary identyfikator punktu rozszerzenia

Nowy identyfikator punktu rozszerzenia

org.eclipse.ui.markerHelp org.eclipse.ui.ide.markerHelp
org.eclipse.ui.markerImageProviders org.eclipse.ui.ide.markerImageProviders
org.eclipse.ui.markerResolution org.eclipse.ui.ide.markerResolution
org.eclipse.ui.projectNatureImages org.eclipse.ui.ide.projectNatureImages
org.eclipse.ui.resourceFilters org.eclipse.ui.ide.resourceFilters
org.eclipse.ui.markerUpdaters org.eclipse.ui.editors.markerUpdaters
org.eclipse.ui.documentProviders org.eclipse.ui.editors.documentProviders
org.eclipse.ui.workbench.texteditor.
markerAnnotationSpecification
org.eclipse.ui.editors.markerAnnotationSpecification

W kolejnej tabeli wymieniono pakiety API udostępniane wcześniej przez moduł org.eclipse.ui, które zostały przeniesione do innych modułów dodatkowych (nazwy pakietów API, klas, pól i metod nie uległy zmianie). W niektórych przypadkach pakiety API zostały podzielone między kilka modułów dodatkowych. Ponieważ klasy API widoczne dla danego modułu zależą od zdefiniowanej w nim listy wymaganych modułów dodatkowych, zmiany te mogą wymagać dostosowania elementów "<requires>" w manifeście istniejącego modułu dodatkowego w celu ponownego uzyskania dostępu do klasy API.

Ta zmiana dotyczy jedynie modułów dodatkowych zależnych od modułu org.eclipse.ui (tzn. zawierających wpis <import plugin="org.eclipse.ui"/> w sekcji <requires> manifestu modułu) - zmiana nie ma natomiast wpływu na żadne inne moduły dodatkowe. Jeśli moduł należy do pierwszej z wymienionych grup, być może konieczne będzie zmodyfikowanie elementu <import> lub wstawienie dodatkowych elementów <import>, tak aby wszystkie wymagane klasy API znalazły się w zasięgu. Zaleca się stanowczo, aby moduły dodatkowe deklarowały zależności wyłącznie od modułów, które są faktycznie wykorzystywane. Uwzględnienie niepotrzebnych zależności wpływa negatywnie na wydajność środowiska wykonawczego, ponieważ program ładujący klasy Java musi wyszukiwać klasy we wszystkich zależnych jednostkach kompilacji (narzędzie do migrowania modułów dodatkowych wchodzące w skład środowiska PDE pozwala wprowadzić odpowiednie poprawki w zakresie zależności i określić niezbędny zestaw).

Pakiet API

Moduł dodatkowy w wersji 2.1

Odpowiadający mu moduł (lub moduły) w wersji 3.0

org.eclipse.jface.text.* org.eclipse.ui org.eclipse.jface.text
org.eclipse.text.* org.eclipse.ui org.eclipse.jface.text
org.eclipse.ui org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.actions org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.dialogs org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.editors.* org.eclipse.ui org.eclipse.ui.editor
org.eclipse.ui.model org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.part org.eclipse.ui org.eclipse.ui, org.eclipse.ui.ide
org.eclipse.ui.texteditor org.eclipse.ui org.eclipse.ui.workbench.texteditor, org.eclipse.ui.editors
org.eclipse.ui.texteditor.* org.eclipse.ui org.eclipse.ui.workbench.texteditor
org.eclipse.ui.views.bookmarkexplorer org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.views.contentoutline org.eclipse.ui org.eclipse.ui.views
org.eclipse.ui.views.markers org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.views.navigator org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.views.properties org.eclipse.ui org.eclipse.ui.views
org.eclipse.ui.views.tasklist org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.wizards.datatransfer org.eclipse.ui org.eclipse.ui.ide
org.eclipse.ui.wizards.newresource org.eclipse.ui org.eclipse.ui.ide

3. Restrukturyzacja modułów dodatkowych głównego środowiska wykonawczego platformy

Środowisko wykonawcze platformy Eclipse 3.0 bazuje na specyfikacji OSGi, co wiąże się ze zmianami w zakresie struktury dwóch modułów dodatkowych tego środowiska: org.eclipse.core.runtime oraz org.eclipse.core.boot.

Nowy moduł dodatkowy org.eclipse.core.runtime.compatibility udostępnia pomost implementacyjny między starymi i nowymi interfejsami API i pełni rolę magazynu dla wielu przestarzałych interfejsów API znajdujących się wcześniej w modułach org.eclipse.core.runtime oraz org.eclipse.core.boot. Restrukturyzacja nie wpływa na punkty rozszerzeń środowiska wykonawczego platformy.

Podczas migrowania istniejącego modułu dodatkowego do wersji 3.0 jego manifest wymaga aktualizacji w celu uwzględnienia nowej struktury modułów dodatkowych środowiska wykonawczego platformy Eclipse. Jeśli zachodzi taka konieczność, odpowiednią zależność można dodać do modułu org.eclipse.core.runtime.compatibility za pomocą narzędzia do migrowania manifestów modułów dodatkowych wchodzącego w skład środowiska PDE.

Należy również zauważyć, że oznaczenie modułu dodatkowego jako modułu 3.0 (za pomocą wpisu <?eclipse version="3.0"?>) w przypadku modułu, który definiuje klasę Plugin, pociąga za sobą konieczność jawnego uwzględnienia instrukcji <import plugin="org.eclipse.core.runtime.compatibility"/> w manifeście modułu albo zapewnienia, że klasa Plugin definiuje konstruktor domyślny.

Uwaga: Jest to jedna z niekompatybilności, które nie mają wpływu na sposób uruchamiania binarnych modułów dodatkowych z wersji 2.1 w środowisku Eclipse 3.0. Środowisko wykonawcze Eclipse 3.0 automatycznie wykrywa moduły dodatkowe z wersji wcześniejszych niż 3.0 (na podstawie nieobecności wiersza <?eclipse version="3.0"?> w manifeście modułu) i uwzględnia opisane wyżej zmiany.

4. Usunięcie modułu dodatkowego Xerces

Moduł dodatkowy org.eclipse.xerces nie jest już potrzebny i został usunięty. Obsługa analizy składni XML jest wbudowana w narzędzie J2SE 1.4, a obecność modułu Xerces powoduje konflikty programów ładujących klasy. Pakiety API javax.xml.parsers, org.w3c.dom.* oraz org.xml.sax.*, udostępniane wcześniej przez moduł dodatkowy org.eclipse.xerces, są teraz dostępne z poziomu bibliotek J2SE.

Jeśli dany moduł dodatkowy wymaga modułu org.eclipse.xerces, należy zmodyfikować jego manifest w celu usunięcia zadeklarowanej zależności. Po wykonaniu tej czynności kod modułu powinien kompilować się i uruchamiać bez konieczności dalszych zmian.

W przypadku próby uruchomienia w standardowej konfiguracji środowiska Eclipse 3.0 binarnych modułów dodatkowych z wersji 2.1 z zadeklarowaną zależnością od modułu org.eclipse.xerces wystąpi błąd niespełnienia wymagań wstępnych. Wskutek tego dany moduł nie zostanie aktywowany.

5. Lepsza obsługa współbieżności w środowisku Eclipse 3.0

Przed wprowadzeniem wersji 3.0 środowisko Eclipse operowało w przeważającej części w ramach pojedynczego wątku. Większość punktów rozszerzeń i metod API operowała w wątku interfejsu użytkownika lub w wątku utworzonym przez okno dialogowe postępu blokujące wątek interfejsu użytkownika. Autorzy modułów dodatkowych nie musieli przeważnie martwić się o bezpieczeństwo wątku poza zapewnieniem, że cała aktywność związana z interfejsem użytkownika odbywa się w ramach wątku tego interfejsu. Środowisko Eclipse 3.0 charakteryzuje się dużo większym stopniem współbieżności. Wiele operacji odbywa się obecnie w tle, gdzie mogą one być wykonywane współbieżnie z innymi wątkami, w tym z wątkiem interfejsu użytkownika. Wszystkie moduły dodatkowe, których kod wykonywany jest w wątku tła, muszą uwzględniać względy bezpieczeństwa.

Oprócz modułów dodatkowych jawnie wykonujących operacje w tle przy użyciu interfejsu API org.eclipse.core.runtime.jobs dostępnych jest kilka punktów rozszerzeń i funkcji API korzystających z wątków tła. Moduły dodatkowe posiłkujące się tymi udogodnieniami muszą gwarantować, że ich kod jest wątkowo bezpieczny. W tabeli poniżej przedstawiono podsumowanie interfejsów API i punktów rozszerzeń, których kod jest wykonywany w środowisku Eclipse 3.0 w całości lub w części w ramach wątku tła:

Punkt rozszerzenia lub klasa API

Uwagi

org.eclipse.core.runtime.IRegistryChangeListener Nowy element w środowisku Eclipse 3.0, wykonywany w tle.
org.eclipse.core.resources.IResourceChangeListener Zdarzenia AUTO_BUILD są obecnie wykonywane w tle.
org.eclipse.core.resources.builders (punkt rozszerzenia) Automatyczne budowanie odbywa się teraz w tle.
org.eclipse.core.resources.ISaveParticipant Element SNAPSHOT działa teraz w tle.
org.eclipse.ui.workbench.texteditor.quickdiffReferenceProvider (punkt rozszerzenia) Nowy element w środowisku Eclipse 3.0, wykonywany w tle.
org.eclipse.ui.decorators (punkt rozszerzenia) Element wykonywany w tle już w wersji Eclipse 2.1.
org.eclipse.ui.startup (punkt rozszerzenia) Element wykonywany w tle już w wersji Eclipse 2.1.
org.eclipse.team.core.org.eclipse.team.core.repository (punkt rozszerzenia) Wiele operacji jest teraz wykonywanych w tle.
org.eclipse.team.ui.synchronizeParticipants (punkt rozszerzenia) Nowy element w środowisku Eclipse 3.0, wykonywany w tle.
org.eclipse.debug.core.launchConfigurationTypes (punkt rozszerzenia) Teraz wykonywany w tle.
org.eclipse.jdt.core.IElementChangedListener Element ElementChangedEvent.PRE_AUTO_BUILD jest obecnie wykonywany w tle, element POST_RECONCILE był wykonywany w tle już w poprzedniej wersji.

Istnieją różne strategie umożliwiające nadanie kodowi charakteru wątkowo bezpiecznego. Najprostsze rozwiązanie polega na tym, że wszystkie działania odbywają się w wątku interfejsu użytkownika, co zapewnia wykonywanie w postaci szeregowej. Jest to podejście stosowane często w przypadku takich modułów dodatkowych interfejsu użytkownika, które nie wymagają przetwarzania znacząco obciążającego procesor. Decydując się na to podejście, należy zdawać sobie sprawę z ryzyka zakleszczenia związanego nieodłącznie z metodą Display.syncExec. Metoda Display.asyncExec jest zwykle bezpieczniejsza, ponieważ nie powoduje ryzyka zakleszczenia, ale kosztem utraty precyzyjnej kontroli nad tym, kiedy kod zostanie wykonany.

Inne techniki umożliwiające zagwarantowanie, że kod będzie wątkowo bezpieczny, to:

6. Otwieranie edytorów na elementach IFile

Z interfejsu org.eclipse.ui.IWorkbenchPage usunięto następujące metody. Interfejs IWorkbenchPage jest deklarowany w ogólnym środowisku roboczym, ale metody są zasadniczo specyficzne dla zasobów.

Klienci tych metod IWorkbenchPage.openEditor powinni zamiast nich wywoływać odpowiadające im metody public static zadeklarowane w klasie org.eclipse.ui.ide.IDE (w module dodatkowym org.eclipse.ui.ide).

Klienci metod IWorkbenchPage.openSystemEditor(IFile) powinni przekształcić interfejs IFile w interfejs IEditorInput przy użyciu nowego interfejsu FileEditorInput(IFile), a następnie wywołać metodę openEditor(IEditorInput,String). Innymi słowy, należy przebudować metodę page.openSystemEditor(file) na page.openEditor(new FileEditorInput(file), IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID). Uwaga: Klienci korzystający z identyfikatora edytora IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID muszą przekazać dane wejściowe edytora implementujące interfejs org.eclipse.ui.IPathEditorInput (warunek ten spełnia FileEditorInput).

Uwaga: Jest to jedna z niekompatybilności, które nie mają wpływu na sposób uruchamiania binarnych modułów dodatkowych z wersji 2.1 w środowisku Eclipse 3.0. Platforma Eclipse 3.0 zawiera mechanizm kompatybilności binarnej środowiska wykonawczego, który zapewnia, że istniejące elementy binarne modułów dodatkowych z wersji 2.1, w których wykorzystuje się dowolne z usuniętych metod openEditor i openSystemEditor, będą nadal działały w nowej wersji pomimo zmienionego interfejsu API (usunięte metody są więc de facto "przywracane" przez fragment org.eclipse.ui.workbench.compatibility).

7. Znacznik przechodzenia w edytorze

Następująca metoda została usunięta z interfejsu org.eclipse.ui.IEditorPart. Interfejs IEditorPart jest deklarowany w ogólnym środowisku roboczym, ale metoda jest zasadniczo specyficzna dla zasobu.

Odpowiednie metody zostały również usunięte z klas w pakiecie org.eclipse.ui.part implementujących interfejs IEditorPart - są to klasy EditorPart, MultiEditor, MultiPageEditorPart oraz MultiPageEditor. 

Klienci wywołujący tę metodę powinni zamiast tego sprawdzić, czy interfejs edytora implementuje lub adaptuje interfejs org.eclipse.ui.ide.IGotoMarker (w module dodatkowym org.eclipse.ui.ide) - jeśli tak, należy wywołać metodę gotoMarker(IMarker). Klasa IDE oferuje w tym celu wygodną metodę: IDE.gotoMarker(editor, marker);

Klienci implementujący edytor, który można automatycznie ustawić na podstawie informacji IMarker, powinni zaimplementować lub zaadaptować interfejs org.eclipse.ui.ide.IGotoMarker.

Ponieważ interfejs IGotoMarker ma tylko jedną metodę - gotoMarker(IMarker) - i ma tę samą sygnaturę i specyfikację co stara metoda IEditorPart.gotoMarker(IMarker), istniejące implementacje edytora można adaptować pod kątem opisywanej zmiany przez włączenie interfejsu IGotoMarker w klauzuli implements w definicji klasy.

W przypadku próby uruchomienia w standardowej konfiguracji środowiska Eclipse 3.0 binarnych modułów dodatkowych z wersji 2.1 z kodem wywołującym tę metodę wystąpi wyjątek związany z błędem łączenia klasy.

8. Program uruchamiający edytor

Interfejs uruchamiający edytor org.eclipse.ui.IEditorLauncher jest implementowany przez moduły dodatkowe udostępniające edytory zewnętrzne. Z interfejsu tego została usunięta przedstawiona dalej metoda. Interfejs IEditorLauncher jest deklarowany w ogólnym środowisku roboczym, ale metoda jest zasadniczo specyficzna dla danego zasobu.

Metoda ta została zastąpiona przez metodę:

Klienci wywołujący metodę IEditorLauncher.open(file) powinni zamiast niej wywoływać metodę IEditorLauncher.open(file.getLocation()). Klienci, którzy implementują ten interfejs, powinni zastąpić (lub przebudować) implementację metody open(IFile) implementacją metody open(IPath).

W przypadku próby uruchomienia w standardowej konfiguracji środowiska Eclipse 3.0 binarnych modułów dodatkowych z wersji 2.1 z kodem wywołującym tę metodę wystąpi wyjątek związany z błędem łączenia klasy.

9. Rejestr edytora

Z interfejsu org.eclipse.ui.IEditorRegistry usunięto następujące metody. Interfejs IEditorRegistry jest deklarowany w ogólnym środowisku roboczym, ale metody są zasadniczo specyficzne dla zasobów.

Klienci wywołujący metodę getEditors(file) lub getImageDescriptor(file) powinni wywoływać odpowiadające im metody typu "String": Klienci wywołujący metody setDefaultEditor(IFile file, String editorId) oraz getDefaultEditor(IFile file) powinni zamiast nich wywoływać odpowiadające im metody public static zadeklarowane w klasie org.eclipse.ui.ide.IDE (w module dodatkowym org.eclipse.ui.ide): Ponadto zmodyfikowano kontrakt API dla metody IEditorRegistrygetDefaultEditor(). Obecnie metoda ta jest również nieaktualna i będzie zawsze zwracać opis zewnętrznego edytora systemowego. Zmiana dotyczy klientów, którzy zakładają, że zwrócony edytor domyślny będzie edytorem tekstu.

Dostępne są nowe stałe reprezentujące identyfikatory zewnętrznego edytora systemowego oraz edytora wbudowanego (SYSTEM_EXTERNAL_EDITOR_ID oraz SYSTEM_INPLACE_EDITOR_ID). Te dwa edytory wymagają danych wejściowych edytora, które implementują lub adaptują interfejs org.eclipse.ui.IPathEditorInput. Należy zauważyć, że deskryptor edytora wbudowanego nie jest dostępny w konfiguracjach środowiska Eclipse, które nie obsługują edycji wewnętrznej.

10. Rejestr pomocy dotyczącej znaczników środowiska roboczego

Następująca metoda została usunięta z interfejsu org.eclipse.ui.IWorkbench. Interfejs IWorkbench jest deklarowany w ogólnym środowisku roboczym, ale metoda jest zasadniczo specyficzna dla danego zasobu.

Klienci metody IWorkbench.getMarkerHelpRegistry() powinni zamiast niej wywoływać metodę public static org.eclipse.ui.ide.IDE.getMarkerHelpRegistry() (w module dodatkowym org.eclipse.ui.ide).

Próba uruchomienia w standardowej konfiguracji środowiska Eclipse 3.0 binarnych modułów dodatkowych z wersji 2.1 z kodem wywołującym tę metodę spowoduje wystąpienie wyjątku.

11. Dostawcy dokumentów edytora tekstu

Aby uniezależnić klasę org.eclipse.ui.texteditor.AbstractTextEditor od interfejsu IFile, klasa org.eclipse.ui.texteditor.AbstractDocumentProvider wprowadza pojęcie operacji dostawcy dokumentów (DocumentProviderOperation) i programu uruchamiającego dostawcę dokumentów (IRunnableContext). Po zgłoszeniu żądania wykonania operacji resetowania, zapisu lub synchronizacji klasa AbstractDocumentProvider powoduje utworzenie odpowiednich operacji dostawcy dokumentów i korzysta z programu uruchamiającego w celu ich przeprowadzenia. Uruchamialny kontekst może być udostępniony przez podklasy za pośrednictwem metody getOperationRunner. Poniżej przedstawiono zmiany, do których klienci powinni się dostosować:

Podklasa org.eclipse.ui.editors.text.StorageDocumentProvider klasy AbstractDocumentProvider implementuje metodę getOperationRunner w taki sposób, że zawsze zwraca wartość null. Oznacza to, że omawiana zmiana nie powinna mieć wpływu na podklasy klasy StorageDocumentProvider.

Podklasa org.eclipse.ui.editors.text.FileDocumentProvider klasy StorageDocumentProvider implementuje metodę getOperationRunner, która zwraca interfejs IRunnableContext w celu wykonania operacji DocumentProviderOperations w ramach WorkspaceModifyOperation. Inne zmiany w zakresie podklasy FileDocumentProvider są następujące:

12. Edytory tekstu

Zmiany w zakresie klasy org.eclipse.ui.texteditor.AbstractTextEditor:

Podklasa org.eclipse.ui.texteditor.StatusTextEditor klasy AbstractTextEditor udostępnia metodę predykatu isErrorStatus(IStatus). W podklasach może być stosowane przesłanianie w celu określenia, czy dany stan ma być uznany za błąd, czy też nie.

Zmiany w zakresie klasy org.eclipse.ui.editors.text.AbstractDecoratedTextEditor:

13. Obsługa adnotacji bez nagłówka

W ramach wprowadzenia obsługi adnotacji bez nagłówka dokonano następujących zmian w klasie Annotation:

        org.eclipse.jface.text.source.Annotation 
        org.eclipse.jface.text.source.AnnotationModel 
        org.eclipse.jface.text.source.AnnotationModelEvent 
        org.eclipse.jface.text.source.IAnnotationModel 
        org.eclipse.jface.text.source.IAnnotationModelListener 
        org.eclipse.jface.text.source.IAnnotationModelListenerExtension

14. Widok Konsola

Środowisko Eclipse 3.0 udostępnia teraz ogólną obsługę konsoli. Dostęp do ogólnej konsoli można uzyskać za pomocą opcji Okna > Pokaż widok > Podstawowe > Konsola. Korzysta się z niej w ramach debugowania w środowisku Eclipse oraz integracji narzędzia Ant.

Identyfikator widoku konsoli został zmieniony z org.eclipse.debug.ui.ConsoleView na org.eclipse.ui.console.ConsoleView. Działanie modułów dodatkowych z wersji 2.1, które programowo otwierają konsolę, nie powiedzie się, ponieważ stary widok już nie istnieje.

15. Funkcje nasłuchiwania punktów zatrzymania Java

W wersji 3.0 typy zwracanych wartości dla metod org.eclipse.jdt.debug.core.IJavaBreakpointListener.breakpointHit(IJavaBreakpoint, IJavaThread) oraz installingBreakpoing(IJavaTarget, IJavaBreakpoint, IJavaType) zostały zmienione z boolean na int, tak aby funkcję nasłuchujące mogły zgłaszać sygnał "nieistotne". W wydaniach poprzedzających wersję 3.0 funkcje nasłuchiwania mogły jedynie zgłaszać sygnały "zawieś" lub "nie zawieszaj" w razie natrafienia na punkt zatrzymania albo "instaluj" lub "nie instaluj", gdy punkt zatrzymania miał zostać zainstalowany. W wersji 3.0 funkcje nasłuchiwania mogą również zgłaszać sygnał "nieistotne" dla każdej z powyższych okoliczności. Pozwala to klientom podejmować konkretną decyzję tylko w tych sytuacjach, w których ma ona dla nich istotne znaczenie. W przypadku powiadomień typu "napotkano punkt zatrzymania" punkt zatrzymania spowoduje zawieszenie, jeśli którakolwiek z funkcji nasłuchiwania zgłosi sygnał "zawieś" lub wszystkie funkcje nasłuchiwania zgłoszą sygnał "nieistotne"; punkt zatrzymania nie spowoduje zawieszenia, jeśli przynajmniej jedna klasa nasłuchiwania zgłosi sygnał "nie zawieszaj" i żadna klasa nie zagłosuje "zawieś". W przypadku powiadomień typu "instalowanie punktu zatrzymania" punkt zatrzymania zostanie zainstalowany, jeśli którakolwiek z funkcji nasłuchiwania zagłosuje za jego zainstalowaniem lub wszystkie funkcje nasłuchiwania zgłoszą sygnał "nieistotne"; punkt zatrzymania nie zostanie zainstalowany, jeśli przynajmniej jedna funkcja nasłuchiwania zgłosi sygnał "nie instaluj" i żadna funkcja nie zagłosuje "instaluj". Ogólnie implementatorzy powinni zwracać wartość DONT_CARE (nieistotne), chyba że istnieje wyraźna przesłanka przemawiająca za wyborem konkretnej opcji. Ważne aby pamiętać, że np. zagłosowanie "zawieś" spowoduje przesłonięcie sygnału "nie zawieszaj" zgłoszonego przez dowolną z pozostałych funkcji nasłuchiwania.

Interfejs IJavaBreakpointListener jest implementowany przez klientów, którzy tworzą punkty zatrzymania w kodzie Java albo reagują na nie. Prawdopodobnie istnieje niewielu takich klientów oprócz samego zestawu narzędzi JDT oraz klienta, który zgłosił problem (defekt 37760) będący przyczyną opracowania opisywanej zmiany. Zmiana ta ma istotne znaczenie z punktu widzenia istniejącego kodu, który implementuje interfejs IJavaBreakpointListener. Taki kod wymaga modyfikacji, aby zwracał odpowiednią wartość int, zanim będzie możliwe jego skompilowanie lub uruchomienie w wersji 3.0.

16. Dostęp do schowka w wątku interfejsu użytkownika

Przed wprowadzeniem wersji 3.0 metody w klasie SWT org.eclipse.swt.dnd.Clipboard mogły być domyślnie uruchamiane w wątkach innych niż wątek interfejsu użytkownika. To przeoczenie powodowało awarie w zestawie GTK, gdzie system operacyjny wymaga, aby wszystkie interakcje schowka odbywały się w obrębie wątku interfejsu użytkownika. Nie zostało ono wcześniej wykryte, ponieważ wiele aplikacji ma charakter jednowątkowy, a większość przeprowadzanych na nich testów odbywa się w systemie Windows. Aby interfejs API schowka działał prawidłowo i miał charakter wieloplatformowy, w wersji 3.0 zmieniono specyfikację i implementację wszystkich metod tego interfejsu w taki sposób, aby zgłaszały wyjątek SWT (ERROR_THREAD_INVALID_ACCESS) w razie wywołania z wątku innego niż wątek interfejsu użytkownika. Usługi schowka są często udostępniane automatycznie przez komponenty środowiska Eclipse takie jak edytor tekstu, co izoluje wielu klientów od tej istotnej zmiany. Istniejący kod, który bezpośrednio odwołuje się do schowka, powinien gwarantować, że metody API są wywoływane w ramach odpowiedniego wątku - w razie potrzeby należy użyć metody Display.asyncExec lub syncExecwhen, aby przełączyć dostęp do wątku interfejsu użytkownika.

17. Zdarzenia naciśnięcia klawiszy

W wersji 3.0 zestaw SWT zgłasza zdarzenia naciśnięcia klawiszy przed uruchomieniem odpowiedniego procesu w systemie operacyjnym. Zdarzenia te są zatem zgłaszanie dużo wcześniej, niż miało to miejsce we wcześniejszych wersjach. Odpowiednia zmiana została wprowadzona w celu umożliwienia przypisań klawiszy w środowisku Eclipse, co rodzi konieczność przechwytywania zdarzeń klawiszy, zanim jakikolwiek widget uzyska możliwość przetworzenia danego znaku. Konsekwencje tej zmiany są widoczne w kodzie, który bezpośrednio obsługuje zdarzenia niskopoziomowe org.eclipse.swt.SWT.KeyDown. Oznacza to na przykład, że gdy funkcja nasłuchiwania widgetu Text odbierze zdarzenie naciśnięcia klawisza, treść widgetu (getText()) nie będzie jeszcze obejmowała naciśniętego klawisza (w przeciwieństwie do wersji wcześniejszych niż 3.0). Zalecanym sposobem uzyskania pełnego tekstu z widgetu wraz z bieżącym klawiszem jest użycie zdarzeń wyższego poziomu SWT.Modify lub SWT.Verify zamiast zdarzenia niskiego poziomu SWT.KeyDown. Opisana tutaj zmiana nie ma żadnego wpływu na kod, w którym stosowano już wcześniej takie podejście.

18. Przechodzenie między niestandardowymi elementami sterującymi za pomocą klawisza Tab

W wersjach poprzedzających wersję 3.0 naciśnięcie kombinacji klawiszy Ctrl+Tab, Shift+Tab, Ctrl+PgUp lub Ctrl+PgDn przy aktywnej klasie SWT org.eclipse.swt.widgets.Canvas lub jednej z jej podklas (łącznie z widgetami niestandardowymi) powodowało automatyczne przejście do następnego/poprzedniego widgetu bez zgłaszania zdarzenia klawisza. Zachowanie to nie wynikało ze specyfikacji i jest niezgodne z zasadą, że klasy Canvas widzą każdy klawisz wpisany w ich obrębie. Prawidłowy sposób obsługi przechodzenia po elementach polega na zarejestrowaniu odpowiedniej funkcji nasłuchującej. Aby zapewnić właściwą obsługę przypisań klawiszy w środowisku Eclipse 3.0, zmieniono domyślne zachowanie, tak że zamiast przechodzenia klasa Canvas widzi teraz zdarzenia klawiszy Ctrl+Tab, Shift+Tab, Ctrl+PgUp oraz Ctrl+PgDn. Jeśli korzysta się bezpośrednio z klasy Canvas lub definiuje jej podklasę, trzeba się upewnić, że zarejestrowano funkcję nasłuchiwania przechodzenia.

19. Kolejność zdarzeń wyboru w widgetach drzew i tabel SWT

Wybór elementów w klasach SWT org.eclipse.swt.widgets.Table oraz Tree za pomocą myszy powoduje we wszystkich środowiskach operacyjnych wygenerowanie jednakowej sekwencji: naciśnięcie przycisku myszy-wybór-zwolnienie przycisku myszy. Podobnie wybór elementów za pomocą klawiatury powoduje we wszystkich środowiskach operacyjnych wygenerowanie takiej samej sekwencji zdarzeń: naciśnięcie klawisza-wybór-zwolnienie klawisza. W wersjach wcześniejszych niż wersja 3.0 porządek zdarzeń nie był jednakowy - środowiska Motif oraz Photon odbiegały tutaj od pozostałych, zawsze w pierwszej kolejności zgłaszając zdarzenie wyboru, tzn. wybór-naciśnięcie przycisku myszy-zwolnienie przycisku myszy lub wybór-naciśnięcie klawisza-zwolnienie klawisza. W wersji 3.0 kolejność zdarzeń w środowiskach Motif i Photon została dopasowana do pozostałych środowisk. Istniejący kod, który działał prawidłowo w środowiskach Windows, GTK, Motif i Photon, najprawdopodobniej nie będzie wymagać żadnych zmian. Zaleca się jednak sprawdzenie kodu i upewnienie się, że nie polega na niepoprawnej kolejności zdarzeń.

20. Nowy poziom istotności w obiektach statusu

Interfejs org.eclipse.core.runtime.IStatus ma nową stałą istotności, IStatus.CANCEL, która może posłużyć do wskazania anulowania. Dodatek ten wpływa na metody wywołujące metodę IStatus.getSeverity(), które polegają na zestawie możliwych statusów istotności ograniczonym do stałych IStatus.OK, INFO, WARNING oraz ERROR. Należy zaktualizować kod metod wywołujących metodę getSeverity w celu uwzględnienia nowego poziomu istotności.

21. Powiadomienia dotyczące zmian zasobów związanych z budowaniem

W środowisku Eclipse 3.0 automatyczne budowanie obszaru roboczego odbywa się w wątku tła. Wymagało to zmiany kontraktu API na org.eclipse.core.resources.IResourceChangeEvent. Kontrakt interfejsu IResourceChangeEvent gwarantował wcześniej następujący porządek zdarzeń w przypadku wszystkich zmian obszaru roboczego:

  1. Powiadomienie o zdarzeniu PRE_DELETE lub PRE_CLOSE (jeśli ma zastosowanie).
  2. Wykonanie operacji.
  3. Powiadomienie o zdarzeniu PRE_AUTO_BUILD.
  4. Jeśli automatyczne budowanie jest włączone, wykonanie przyrostowego budowania obszaru roboczego.
  5. Powiadomienie o zdarzeniu POST_AUTO_BUILD.
  6. Powiadomienie o zdarzeniu POST_CHANGE.

Ponieważ automatyczne budowanie odbywa się teraz w tle, nie ma gwarancji dotyczących czasowego związku między zdarzeniami AUTO_BUILD i zdarzeniem POST_CHANGE. W środowisku 3.0 kroki 3-5 w powyższej strukturze zostały usuniętej z operacji. Efekt przedstawia się następująco:

  1. Powiadomienie o zdarzeniu PRE_DELETE lub PRE_CLOSE (jeśli ma zastosowanie).
  2. Wykonanie operacji.
  3. Powiadomienie o zdarzeniu POST_CHANGE.

Operacja budowania obszaru roboczego w tle jest wykonywana okresowo przez platformę. Należy zauważyć, że ma to miejsce niezależnie od tego, czy automatyczne budowanie jest włączone, czy wyłączone. Nie jest możliwe podanie dokładnych ram czasowych, w jakich zostanie przeprowadzone budowanie. Struktura przykładowej operacji budowania może wyglądać następująco:

  1. Powiadomienie o zdarzeniu PRE_BUILD (PRE_BUILD to nowa nazwa dla PRE_AUTO_BUILD).
  2. Jeśli automatyczne budowanie jest włączone, wykonanie przyrostowego budowania obszaru roboczego.
  3. Powiadomienie o zdarzeniu POST_BUILD (POST_BUILD to nowa nazwa dla POST_AUTO_BUILD).
  4. Powiadomienie o zdarzeniu POST_CHANGE.

Punkt odniesienia dla wartości delta odebranych przez funkcje nasłuchiwania automatycznego budowania będzie inny niż w przypadku nasłuchiwania zdarzeń post-change. Funkcje nasłuchiwania budowania będą odbierać powiadomienia o wszystkich zmianach od momentu zakończenia ostatniej operacji budowania. Funkcje nasłuchiwania zdarzeń post-change będą odbierać wartości delta opisujące wszystkie zmiany od ostatniego powiadomienia o wprowadzonych zmianach. Ta nowa struktura zachowuje trzy cechy charakterystyczne funkcji nasłuchiwania zmian zasobów aktualne od czasu pojawienia się środowiska Eclipse w wersji 1.0:

Z tym podejściem wiążą się jednak istotne różnice. Przed wprowadzeniem wersji Eclipse 3.0 funkcje nasłuchiwania automatycznego budowania były zawsze wywoływane przed funkcjami nasłuchiwania POST_CHANGE. Z tego powodu wartość delta odbierana przez te pierwsze była zawsze podzbiorem wartości delta odbieranych przez funkcje nasłuchiwania POST_CHANGE. W zasadzie ten związek został obecnie odwrócony. Funkcje nasłuchiwania automatycznego budowania odbierają wartość delta, która jest nadzbiorem wszystkich delt dostarczanych do funkcji nasłuchiwania POST_CHANGE od momentu ostatniego budowania w tle. Tak jak wcześniej, funkcje nasłuchiwania automatycznego budowania mogą modyfikować obszar roboczy, a funkcje nasłuchiwania post-change nie mają takiej możliwości.

Nie jest już tak, że po zakończeniu operacji zmiany obszaru roboczego funkcje nasłuchujące zdarzenia AUTO_BUILD zostaną o tym powiadomione. Opisywana zmiana prawdopodobnie nie będzie miała wpływu na kod klienta, który rejestruje funkcje nasłuchiwania zmian zasobów za pomocą metody IWorkspace.addResourceChangeListener(IResourceChangeListener), ponieważ zdarzenia AUTO_BUILD nigdy nie były raportowane do tych funkcji. Jednak w przypadku klientów korzystających z metody IWorkspace.addResourceChangeListener(IResourceChangeListener,int) i określających maskę zdarzeń obejmującą zdarzenia AUTO_BUILD prawdopodobnie dojdzie do błędów w wyniku opisywanej zmiany, jeśli zakłada się w nich, kiedy funkcje nasłuchiwania automatycznego budowania są uruchamiane lub w jakim wątku się odbywają. Przykładowo jeśli funkcja nasłuchiwania automatycznego budowania aktualizuje model domeny w celu uwzględnienia zmian wprowadzonych w obszarze roboczym, aktualizacja może nie zostać przeprowadzona przy ponownej operacji zmiany obszaru roboczego. Należy zauważyć, że dotyczy to jedynie kodu na poziomie interfejsu użytkownika. Kod na poziomie jądra wywoływany za pośrednictwem interfejsu API może być wywoływany w ramach zasięgu interfejsu IWorkspaceRunnable, dlatego nie ma pewności co do dokładnej pory wywołania nasłuchiwania zmian. Aby naprawić błędy wynikające z opisywanej modyfikacji, należy korzystać ze zdarzenia POST_CHANGE zamiast funkcji nasłuchiwania budowania, jeśli konieczne jest wystąpienie powiadomienia przed zakończeniem operacji.

22. Powiadomienia pośrednie podczas operacji w obszarze roboczym

Nie ma już gwarancji, że wszystkie zmiany zasobów odbywające się w ramach dynamicznego zasięgu interfejsu IWorkspaceRunnable zostaną uwzględnione w pojedynczym powiadomieniu. Z mechanizmu tego można w dalszym ciągu korzystać w celu uniknięcia niepotrzebnego budowania i powiadamiania, ale platforma może przeprowadzić powiadomienie podczas operacji. Ta zmiana kontraktu API prawdopodobnie nie będzie miała negatywnego wpływu na istniejących klientów. Jest analogiczna do sytuacji, w której platforma wywołuje okresowo metodę IWorkspace.checkpoint podczas długotrwałych operacji. Opisywana zmiana była spowodowana potrzebą wprowadzenia możliwości współbieżnego modyfikowania obszaru roboczego przez wiele wątków. Po zakończeniu modyfikowania obszaru roboczego przez jeden wątek wymagane jest powiadomienie w celu uniknięcia problemu zaniku reakcji, nawet jeśli inne operacje nie zostały jeszcze zakończone. Ponadto zmiana ta pozwala użytkownikom rozpocząć pracę na zbiorze zasobów przed zakończeniem operacji. Przykładowo użytkownik może rozpocząć przeglądanie plików w projekcie, który jest w dalszym ciągu pobierany. Nowa metoda IWorkspace.run(IWorkspaceRunnable, ISchedulingRule, int, IProgressMonitor) ma opcjonalną flagę AVOID_UPDATE, której operacje mogą używać jako sygnału dla platformy w celu określenia, czy mają być przeprowadzane okresowe aktualizacje.

23. Rozszerzenia procedury obsługi strumienia URL

Elementy, których dotyczy ta zmiana: Moduły dodatkowe, które wnoszą rozszerzenia do punktu rozszerzenia org.eclipse.core.runtime.urlHandlers.

Opis: Zmieniono kontrakt dla punktu rozszerzenia org.eclipse.core.runtime.urlHandlers w celu użycia procedury obsługi strumienia URL udostępnianej przez usługi OSGi. Obsługa OSGi jest lepsza od tej, która była dostępna w środowisku Eclipse 2.1, i poprawnie współpracuje z dynamicznymi procedurami obsługi. Ze względu na różne problemy projektowe z podstawowym mechanizmem obsługi URL Java, klasy URLStreamHandler zarejestrowane za pomocą procedury obsługi OSGi muszą implementować interfejs org.osgi.service.url.URLStreamHandlerService.

Wymagana akcja: We wcześniejszych wersjach klasa z procedurą obsługi musiała implementować interfejs java.net.URLStreamHandler i rozszerzać punkt rozszerzenia urlHandlers. Punkt ten nie jest już obsługiwany i należy zaktualizować procedurę obsługi w celu zaimplementowania interfejsu org.osgi.service.url.URLStreamHandlerService. Środowisko OSGi udostępnia abstrakcyjną klasę bazową (org.osgi.service.url.AbstractURLStreamHandlerService), którą można łatwo wykorzystać do utworzenia podklasy, aby przeprowadzić wspomnianą aktualizację.

Zamiast rejestrować procedurę obsługi za pomocą punktu rozszerzenia, moduły dodatkowe muszą obecnie rejestrować procedury obsługi jako usługi. Na przykład:

    Hashtable properties = new Hashtable(1);
    properties.put(URLConstants.URL_HANDLER_PROTOCOL, new String[] {MyHandler.PROTOCOL});
    String serviceClass = URLStreamHandlerService.class.getName();
    context.registerService(serviceClass, new MyHandler(), properties);

24. Porządek ładowania klas

Elementy, których dotyczy ta zmiana: Moduły dodatkowe dostarczające pakiety udostępniane również przez inne moduły dodatkowe. Dotyczy to jedynie nielicznych modułów, a niektóre z nich mogą nawet skorzystać na wprowadzonej zmianie (patrz niżej).

Opis: W środowisku Eclipse 2.x program ładujący klasy wyszukuje klasy w następującym porządku: (1) program ładujący klasy macierzystej (w praktyce jest to program ładujący startowej klasy Java), następnie (2) treść jego własnej ścieżki klasy i wreszcie (3) wszystkie jego wymagania wstępne w zadeklarowanym porządku. Specyfikacja OSGi oferuje możliwość optymalizacji tego modelu. W tym podejściu program ładujący klasy sprawdzi (1) program ładujący klasy macierzystej (znowu, jest to ostatecznie program ładujący startowej klasy Java), następnie albo (2a) pojedyncze wymaganie wstępne, które udostępnia klasy w przeszukiwanym pakiecie, albo (2b) pozycje z jego własnej ścieżki klasy dla wymaganej klasy.

Program ładujący ustala, czy sprawdza samego siebie lub swoje wymagania wstępne na podstawie zaimportowanych i wymaganych pakietów. Informacje te pobiera się z treści modułu dodatkowego w przypadku tradycyjnych modułów dodatkowych albo określa bezpośrednio w przypadku modułów dodatkowych z jawnym manifestem pakunku OSGi. W obu przypadkach wiadomo a priori, które programy ładujące klas dostarczą klasy dla określonych pakietów. Pozwala to na zwiększenie wydajności oraz stanowi rozwiązanie dla stale powracającego problemu, gdy wiele wymagań wstępnych wnosi te same klasy.

Za przykład mogą tutaj posłużyć moduły Xerces i Xalan - oba zawierają różne klasy z pakietów org.xml. Przy pierwszym podejściu moduł Xerces zobaczyłby swoją kopię tych klas, a pakiet Xalan zobaczyłby ich kopię. Ponieważ te moduły dodatkowe muszą się ze sobą komunikować, wystąpią wyjątki ClassCastExceptions. Przy drugim podejściu tylko jeden z tych modułów wnosi zduplikowane klasy i oba widzą te same kopie.

Wymagana akcja: Wymagana akcja zależy od szczegółów danego przypadku użycia. Programiści, których dotyczy ta zmiana, musza przejrzeć ścieżkę klasy i rozwiązać potencjalne konflikty.

25. Nieustawiona domena ochrony programu ładującego klasy

Elementy, których dotyczy ta zmiana: Moduły dodatkowe, które oczekują stale ustawionej domeny ochrony swoich programów ładujących klas.

Opis: W środowisku Eclipse 2.1 programy ładujące klas modułów dodatkowych (java.security.SecureClassloaders) miały zawsze ustawioną domenę ochrony. W wersji Eclipse 3.0 programy ładujące klas nie rozszerzają klasy SecureClassloader i ustawiają domenę ochrony tylko wtedy, gdy włączona jest ochrona Java (nie jest tak domyślnie).

Wymagana akcja: Wymagana akcja będzie zależeć od konkretnego scenariusza, w którym moduł dodatkowy korzysta z domeny ochrony.

26. Rzutowanie obiektu PluginModel

Elementy, których dotyczy ta zmiana: Moduły dodatkowe, które rzutują obiekty typu org.eclipse.core.runtime.IPlugin* na org.eclipse.core.runtime.model.Plugin*Model. Choć związek między tymi interfejsami i klasami modeli nie jest określony w interfejsie API środowiska Eclipse 2.1, zwracamy uwagę na niniejszą zmianę, ponieważ znaleziono przypadki modułów dodatkowych polegających na tym związku w implementacji wersji 2.1.

Opis: Interfejs API środowiska Eclipse udostępnia zestaw interfejsów (np. IPluginDescriptor) i tzw. klasy "modeli" (np. PluginDescriptorModel) związane z modułami dodatkowymi i rejestrem modułów dodatkowych. W implementacji Eclipse 2.1 zdarza się, że klasy modeli implementują te interfejsy. W nowym środowisku wykonawczym bazującym na specyfikacji OSGi rejestr modułów dodatkowych został znacznie przeprojektowany, aby umożliwić oddzielenie aspektów ładowania klas i wymagań wstępnych od aspektów rozszerzeń i punktów rozszerzeń. Z tego względu środowisko wykonawcze platformy Eclipse 3.0 nie jest w stanie zachować relacji implementacji obecnej w wersji 2.1.

Wymagana akcja: Należy przebudować moduły dodatkowe, które polegają na tym związku niebędącym związkiem API, uwzględniając konkretny przypadek użycia. Więcej informacji na ten temat można znaleźć w sekcji niniejszego dokumentu, która traktuje o zalecanych zmianach, a także w dokumentacji Javadoc dotyczącej powiązanych klas i metod.

27. Niekompletna implementacja interfejsu ILibrary

Elementy, których dotyczy ta zmiana: Moduły dodatkowe korzystające z interfejsu org.eclipse.core.runtime.ILibrary.

Opis: Nowe środowisko wykonawcze przechowuje pozycje ścieżek klas w innej formie, która nie jest kompatybilna z platformą Eclipse. Powoduje to, że warstwa kompatybilności nie jest w stanie prawidłowo modelować bazowych struktur OSGi jako obiektów ILibrary. Obsługa kompatybilności środowiska wykonawczego tworzy obiekty ILibrary, ale musi zakładać wartości domyślne dla wszystkich elementów z wyjątkiem ścieżki biblioteki.

Wymagana akcja: Użytkownicy interfejsu ILibrary powinni wziąć pod uwagę uzyskanie dostępu do wartości nagłówka (np. Bundle-Classpath) z poziomu odpowiedniego pakunku (patrz Bundle.getHeaders()) i użycie klasy pomocniczej ManifestElement do interpretacji wpisów. Więcej szczegółów zawiera dokumentacja Javadoc tej klasy.

28. Niepoprawne założenia dotyczące formy adresów URL

Elementy, których dotyczy ta zmiana: Moduły dodatkowe z założeniami co do struktury instalacji, położenia i układu lokalnego systemu plików.

Opis: Metody takie jak IPluginDescriptor.getInstallURL() zwracają adresy URL w określonej formie. Choć forma ta nie jest wyraźne opisana, różne moduły dodatkowe czynią odnośne założenia na podstawie bieżącej implementacji. Przykładowo mogą oczekiwać adresu URL w formie file: oraz skorzystać z metody URL.getFile() i użyć manipulacji java.io.File na zwróconym wyniku. Do tej pory takie podejście sprawdzało się, chociaż istniało ryzyko wystąpienia nieprawidłowości. Przykładowo jeśli moduł dodatkowy jest zainstalowany na serwerze WWW, możliwe, że zostanie zwrócony adres URL w formie http:. Nowe środowisko wykonawcze Eclipse 3.0 jest jeszcze bardziej elastyczne i otwiera nowe możliwości w zakresie konfiguracji wykonywania (np. możliwość zachowania całych modułów dodatkowych w plikach JAR zamiast w postaci rozpakowanej w katalogach). Choć nowe środowisko wykonawcze bazujące na specyfikacji OSGi nie odbiega całkowicie od interfejsu API z wersji 2.1 API, powoduje więcej przypadków, w których założenia obecne w bieżących modułach dodatkowych są niepoprawne.

Wymagane działania: Autorzy modułów dodatkowych powinni się upewnić, że potrzebne informacje są dostępne za pośrednictwem metody getResource() (i znajdują się w ścieżce klasy), albo powinni użyć odpowiedniego interfejsu API w celu uzyskania dostępu do treści modułu dodatkowego (np. Bundle.getEntry(String)).

29. Przeniesione/usunięte metody z klasy BootLoader

Elementy, których dotyczy ta zmiana: Kod spoza modułów dodatkowych, który wywołuje określone metody z klasy org.eclipse.core.boot.BootLoader.

Opis: Metody statyczne BootLoader.startup(), shutdown() oraz run() zostały przeniesione do klasy org.eclipse.core.runtime.adaptor.EclipseStarter, która wchodzi w skład środowiska OSGi. Ten interfejs API łączy metodę main() w pliku startup.jar ze środowiskiem OSGi/środowiskiem wykonawczym Eclipse. Restrukturyzacja środowiska wykonawczego uniemożliwiła pozostawienie tych metod w klasie BootLoader. Stara klasa BootLoader znajduje się teraz w warstwie kompatybilności środowiska wykonawczego i jest nieaktualna, a wymienione metody zostały zablokowane.

Nie ma zastępnika dla starej metody BootLoader.getRunnable(), ponieważ środowisko wykonawcze nie może obsługiwać przejęcia pojedynczych aplikacji. Użytkownicy muszą zamiast tego wskazać odpowiednią aplikację podczas uruchamiania platformy.

Wymagana akcja: Ten interfejs API jest na ogół używany przez nieliczną grupę użytkowników (nie można z niego skorzystać z poziomu modułu dodatkowego środowiska Eclipse). W rzadkich przypadkach jego użycia należy zaadaptować kod w celu wykorzystania odpowiednich metod z klasy EclipseStarter.

30. Eksport modułu dodatkowego nie obejmuje automatycznie plików JAR modułu dodatkowego

Elementy, których dotyczy ta zmiana: Wszystkie moduły dodatkowe.

Opis: W środowisku Eclipse 2.1 wiersz bin.includes w pliku build.properties nie musiał zawierać listy plików JAR z odpowiednich deklaracji bibliotek w pliku plugin.xml. Pliki te były dodawane za darmo. W wersji Eclipse 3.0 lista plików w sekcji bin.includes w pliku build.properties ma charakter wyczerpujący i musi zawierać wszystkie pliki, które autor modułu dodatkowego chce zawrzeć w tworzonym module podczas budowy lub eksportu.

Wymagana akcja: Należy się upewnić, że wiersz bin.includes w pliku build.properties zawiera wszystkie pliki JAR wymienione w pliku plugin.xml.

31. Ponowne eksportowanie interfejsu API środowiska wykonawczego

Elementy, których dotyczy ta zmiana: Moduły dodatkowe prezentujące interfejs API z elementami ze zmienionego interfejsu API środowiska wykonawczego.

Opis: Różne moduły dodatkowe prezentują interfejs API zawierający elementy ze zmienionego interfejsu API środowiska wykonawczego. Biorąc pod uwagę opisane tutaj zmiany wprowadzone w środowisku wykonawczym Eclipse 3.0, należy zrewidować użycie interfejsu API tego środowiska w modułach dodatkowych klientów.

Wymagana akcja: Ten scenariusz jest dość rzadki, ponieważ interfejs API środowiska wykonawczego platformy Eclipse uległ zmianie tylko w nieznacznym stopniu. W zależności od konkretnej sytuacji może zaistnieć konieczność zmodyfikowania interfejsu API stosowanego przez klienta. Można również w dalszym ciągu polegać na warstwie kompatybilności.

32. Metody analizy modułów dodatkowych z klasy Platform

Elementy, których dotyczy ta zmiana: Moduły dodatkowe korzystające z metody org.eclipse.core.runtime.Platform.parsePlugins(..., Factory).

Opis: Metoda org.eclipse.core.runtime.Platform.parsePlugins(..., Factory) została przeniesiona. Interfejs API powiązany z argumentem Factory został przeniesiony z modułu dodatkowego org.eclipse.core.runtime do modułu org.eclipse.core.runtime.compatibility (który zależy od modułu środowiska wykonawczego). W wyniku tej zmiany metoda analizy została również przeniesiona.

Wymagana akcja: Użytkownicy tej metody powinni korzystać z tej samej metody w klasie org.eclipse.core.runtime.model.PluginRegistryModel.

33. Biblioteki modułów dodatkowych udostępniane przez fragmenty

Elementy, których dotyczy ta zmiana: Moduły dodatkowe określające kod w ścieżce klasy, ale nie dostarczające tego kodu (tzn. plik JAR jest dostarczany przez fragment; np. moduł dodatkowy org.eclipse.swt).

Opis: Nowe środowisko wykonawcze musi przekształcić pliki plug.xml w pliki manifest.mf w tle. Odbywa się to z użyciem prostej transformacji mechanicznej i analizy plików jar zadeklarowanych i dostarczonych przez moduł dodatkowy. W sytuacji gdy moduł deklaruje plik jar w ścieżce klasy, ale go nie dostarcza, nie ma kodu, który można poddać analizie, i konwerter modułu nie jest w stanie wygenerować poprawnego pliku manifest.mf.

Wymagana akcja: Dostawcy tego rodzaju modułów dodatkowych muszą je zmodyfikować, aby dostarczały odpowiedni plik jar, albo ręcznie przebudować plik META-INF/MANIFEST.MF pod kątem modułu. Zwykle za pomocą środowiska PDE uzyskuje się początkowy manifest, a następnie dodaje odpowiedni nagłówek Provide-Package.

34. Zmiany skryptów budowania

Elementy, których dotyczy ta zmiana: Skrypty (np. pliki build.xml narzędzia Ant) definiujące ścieżki klas z katalogami klas i plikami jar powiązanymi ze środowiskiem wykonawczym.

Opis: Nowe środowisko wykonawcze zawiera klika nowych modułów dodatkowych i plików jar. Ich wprowadzenie wynikało z refaktoryzacji środowiska wykonawczego na konfigurowalne fragmenty. W większości sytuacji zmiany te mają charakter niewidoczny dla użytkownika. Jeśli jednak wykorzystuje się niestandardowe skrypty build.xml (lub podobne), które kompilują kod w odniesieniu do modułu org.eclipse.core.runtime, należy je zaktualizować, aby mogły działać poprawnie. Typowy skrypt zawiera wpis ścieżki klasy w czynności <javac>, która odwołuje się do modułu dodatkowego org.eclipse.core.runtime w następujący sposób:

    ../org.eclipse.core.runtime/bin;../org.eclipse.core.runtime/runtime.jar

Moduł dodatkowy środowiska wykonawczego nadal zawiera znaczną część kodu oryginalnego środowiska. Niektóre elementy tego środowiska, które pozostawiono wyłącznie ze względu na zachowanie kompatybilności, znajdują się w module kompatybilności (org.eclispe.core.runtime.compatibility). Większość nowego kodu znajduje się w zestawie modułów dodatkowych org.eclipse.osgi.*.

Wymagana akcja: Programiści powinni w razie potrzeby dodać poniższe wpisy w celu wyeliminowania błędów kompilacji. Choć przedstawiono tutaj kompletny zestaw dostarczanych plików jar, w typowych zastosowaniach wymagany jest tylko ich podzbiór znajdujący się w ścieżce klasy podczas kompilacji. Jak zwykle uwzględnienie katalogów /bin jest opcjonalne. Przedstawione wpisy zestawiono w logicznych grupach według modułu dodatkowego:

Oprócz tego w szczególnych przypadkach mogą być wymagane następujące pliki jar:

Aktualizując tego rodzaju skrypty, można jednocześnie wyczyścić (tzn. usunąć) odwołania do modułu org.eclipse.core.boot. Jest on przestarzały i nie zawiera już żadnego kodu. Odpowiadające mu wpisy można pozostawić w ścieżce klasy, ale nie są one do niczego potrzebne i najlepiej je usunąć. Wpis do usunięcia to:

    ../org.eclipse.core.boot/bin;../org.eclipse.core.boot/boot.jar

35. Zmiany w czynności budowania PDE narzędzia Ant

Elementy, których dotyczy ta zmiana: Skrypty (np. pliki build.xml narzędzia Ant) korzystające z czynności eclipse.buildScript.

Opis: Budowanie w środowisku PDE wiąże się z wprowadzeniem nowej właściwości do czynności eclipse.buildScript, która pozwala sterować generowaniem skryptów budowania modułów dodatkowych. Zmiana była spowodowana wprowadzeniem nowego środowiska wykonawczego bazującego na specyfikacji OSGi.

Wymagana akcja: Aby użyć środowiska Eclipse 3.0 do budowy produktu opartego na wersji 2.1, należy wprowadzić w czynności eclipse.buildScript właściwość "buildingOSGi" i ustawić ją na false. Na przykład:

<eclipse.buildScript ... buildingOSGi="false"/>

36. Zmiany w czynności Ant eclipse.build

Elementy, których dotyczy ta zmiana: Skrypty (np. pliki build.xml narzędzia Ant) korzystające z czynności eclipse.buildScript.

Opis: Budowanie w środowisku PDE wiąże się z wprowadzeniem nowej właściwości do czynności eclipse.buildScript, która pozwala sterować generowaniem skryptów budowania modułów dodatkowych. Zmiana była spowodowana wprowadzeniem nowego środowiska wykonawczego bazującego na specyfikacji OSGi.

Wymagana akcja: Aby użyć środowiska Eclipse 3.0 do budowy produktu opartego na wersji 2.1, należy wprowadzić w czynności eclipse.buildScript właściwość "buildingOSGi" i ustawić ją na false. Na przykład:

<eclipse.buildScript ... buildingOSGi="false"/>

37. Zmiany w czynności Ant eclipse.fetch

Elementy, których dotyczy ta zmiana: Skrypty (np. pliki build.xml narzędzia Ant) korzystające z czynności eclipse.buildScript.

Opis: Budowanie w środowisku PDE wiąże się ze zmianą zachowania czynności eclipse.fetch w celu ułatwienia zautomatyzowanego budowania na platformie Eclipse. Elementy style obsługują teraz tylko pojedyncze wpisy, a elementy scriptName są zawsze ignorowane.

Wymagana akcja: Jeśli w znaczniku "elements" wywołania eclipse.fetch występuje lista pozycji, należy je rozdzielić na kilka wywołań. Jeśli element scriptName jest ustawiany, należy zwrócić uwagę, że wygenerowany skrypt pobierania nosi zawsze nazwę "fetch_{elementId}". Na przykład:

<eclipse.fetch elements="plugin@org.eclipse.core.runtime, feature@org.eclipse.platform" .../>

jest przekształcany w

<eclipse.fetch elements="plugin@org.eclipse.core.runtime" .../>
<eclipse.fetch elements="feature@org.eclipse.platform" .../>

38. Zastąpienie pliku install.ini

Plik install.ini nie jest już dostępny. Zastąpiono go plikiem config.ini w podkatalogu configuration. Produkty, które korzystały z pliku install.ini do określenia składnika podstawowego (np. w celu udostępnienia informacji o oznakowaniu marką), muszą teraz zamiast niego modyfikować plik config.ini. Oprócz zmiany nazwy pliku zmianie uległy również nazwy kluczy.

Wartość klucza feature.default.id z wersji 2.1 należy ustawić jako wartość nowego klucza eclipse.product. Wartość klucza eclipse.application należy ustawić na "org.eclipse.ui.ide.workbench".

Ostatnia kwestia to obraz używany na ekranie startowym - w wersji 2.1 był to zawsze plik splash.bmp w katalogu marki modułu dodatkowego. W wersji 3.0 położenie obrazu startowego jest określane bezpośrednio przez klucz osgi.splashPath w pliku config.ini.