Środowisko Eclipse zmieniło się w taki sposób, że wersje 3.0 i 3.1 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 3.0 do wersji 3.1. Skorzystanie z podanych tutaj informacji jest konieczne tylko wtedy, gdy przy uruchamianiu modułu dodatkowego z wersji 3.0 w środowisku w wersji 3.1 występują problemy.
Zmiany obejmują: Moduły dodatkowe, które inicjują domyślne wartości swoich preferencji
poprzez zastąpienie metody Plugin#initializeDefaultPreferences
lub użycie obiektów nasłuchiwania
zmian preferencji.
Opis: W środowisku Eclipse 3.1 nastąpiła migracja obiektu org.eclipse.jface.preference.IPreferenceStore
zwracanego przez metodę org.eclipse.ui.plugin.AbstractUIPlugin#getPreferenceStore
.
Został on przeniesiony bezpośrednio na szczyt struktury preferencji środowiska Eclipse w wersji 3.0,
dostarczanej przez moduł dodatkowy org.eclipse.core.runtime
.
Wymagana akcja: W klientach korzystających z tych interfejsów API preferencji należy z tego powodu sprawdzić, czy nie pojawił się jeden z dwóch możliwych problemów:
String
lub być obiektem określonego typu. Dlatego funkcje
nasłuchiwania zmian preferencji dobrze przygotowanych klientów powinny obsługiwać wszystkie
trzy możliwe sytuacje.org.eclipse.ui.plugin.AbstractUIPlugin#initializeDefaultPreferences
, należy koniecznie
uwzględnić moduł dodatkowy org.eclipse.core.runtime.compatibility
na liście wymaganych
modułów dodatkowych, ponieważ ta zależność została usunięta z modułu dodatkowego org.eclipse.ui.workbench
.Szczegółowe informacje na ten temat można znaleźć w sekcji Składnica preferencji.
Zmiany obejmują: Moduły dodatkowe, które tworzą lub przechowują obiekty IPath, a także nimi operują.
Opis: W środowisku Eclipse 3.0 na interfejs IPath było nałożonych wiele ograniczeń dotyczących segmentów ścieżek, które były bardziej rygorystyczne niż analogiczne ograniczenia bazowego systemu operacyjnego. Niektóre z tych ograniczeń:
Wymienione ograniczenia zostały usunięte w środowisku Eclipse 3.1 w przypadkach, gdy nie zawiera ich system plików, na którym znajduje się położenie danych platformy (obszar roboczy).
Wymagana akcja: Aby aktywować odpowiedni sposób obsługi rozszerzonego zakresu ścieżek, należy przejrzeć i poprawić zgodnie z poniższym opisem składnię dotyczącą obiektów Path i IPath w modułach dodatkowych. Większość niezmienionych modułów dodatkowych dla ścieżek uznawanych za poprawne w wersji 3.0 będzie się zachowywać dokładnie tak, jak w wersji 3.0. Jeśli jednak zmiany nie zostaną wprowadzone, podanie ścieżki poprawnej w wersji 3.1 i niepoprawnej w wersji 3.0 może zakończyć się niepowodzeniem.
W przypadku modułów dodatkowych przechowujących łańcuchowe reprezentacje ścieżek w formacie, który powinien być możliwy do odczytu na różnych platformach, powinna zostać przeprowadzona migracja do nowej metody fabrycznej Path.fromPortableString. Tworzy ona instancję obiektu IPath na podstawie formatu niezależnego od platformy. Łańcuchowa reprezentacja ścieżek może być tworzona za pomocą metody IPath.toPortableString. Omawiana zmiana dotyczy między innymi plików metadanych, takich jak pliki przechowywane w projektach obszaru roboczego środowiska Eclipse (rozszerzenia .project, .classpath itd.), a także wszystkich ścieżek zapisanych w składnicy preferencji (org.eclipse.core.runtime.preferences.IPreferencesService).
Uwaga: Metoda fromPortableString odczyta poprawnie wszystkie łańcuchy ścieżek utworzone za pomocą dostępnej w środowisku Eclipse 3.0 metody IPath.toString, ale nie metody toString środowiska Eclipse 3.1. Oznacza to, że najczęściej istniejące formaty plików metadanych nie wymagają zmian, chyba że powinny od tej pory zapisywać ścieżki przy użyciu metody toPortableString, a odczytywać je metodą fromPortableString.
W przypadku modułów dodatkowych, które tworzyły ścieżki z zakodowanych na stałe literałów łańcuchowych i zakładały, że znaki dwukropka i odwrotnego ukośnika miały specjalne znaczenie, będzie wymagana migracja. Najprostszym rozwiązaniem jest ograniczenie literałów ścieżek do podzbioru, który jest obsługiwany przez wszystkie platformy (unikając znaków dwukropka i odwrotnego ukośnika). Aby literały ścieżek obsługiwały cały zbiór poprawnych ścieżek systemu Unix, można użyć przenośnego formatu łańcucha ścieżki uzyskiwanego za pomocą metody Path.toPortableString. Pojedynczy dwukropek (":") jest w nim interpretowany jako separator urządzeń, ukośnik ("/") jako separator segmentów, a podwójny dwukropek ("::") jako znak dwukropka. Na przykład kod new Path("c:/temp") utworzy na platformach Unix ścieżkę względną z dwoma segmentami. Analogicznie kod new Path("a\\b") utworzy na platformach Unix ścieżkę z jednym segmentem, a na platformach Windows - ścieżkę z dwoma segmentami.
W modułach dodatkowych tworzących ścieżki przy użyciu metody IPath.append(String), które zakładały, że znaki dwukropka i odwrotnego ukośnika miały specjalne znaczenie na wszystkich platformach, będzie potrzebna aktualizacja kodu. W środowisku Eclipse 3.1 ta metoda używa przy interpretacji otrzymanego łańcucha ścieżki separatorów urządzeń i segmentów konkretnego systemu operacyjnego. Na przykład wywołanie append("a\\b") na platformie Unix spowoduje dodanie pojedynczego segmentu, podczas gdy na platformie Windows nadal będzie powodowało dodanie dwóch segmentów.
Pliki danych odczytane i zinterpretowane przez platformę nie będą już traktowały znaków ":" i "\" jako znaków specjalnych na wszystkich platformach. Wszystkie ścieżki zapisane w plikach danych, które można odczytać na wielu platformach, muszą mieć formę przenośną. Na przykład w ścieżkach plików ikon i innych ścieżkach w pliku plugin.xml należy używać tylko ukośnika "/" jako separatora segmentu ścieżki.
Zmiany obejmują: Moduły dodatkowe, które używają obiektów IExtensionPoint
,
IExtension
i IConfigurationElement
z rejestru modułów dodatkowych lub z rejestru rozszerzeń platformy Eclipse.
Opis: Przed wersją 3.0 wszystkie obiekty uzyskane z rejestru rozszerzeń
(wcześniej rejestru modułów dodatkowych) były zawsze poprawne. Zmiany w środowisku Eclipse 3.0
pozwalały na dynamiczne dodawanie i usuwanie modułów dodatkowych bez potrzeby jego restartowania.
Usunięcie modułu dodatkowego bez restartowania środowiska powoduje, że jego pozycje w rejestrze
rozszerzeń stają się niepoprawne. Z tego powodu inny moduł dodatkowy, korzystający z obiektu uzyskanego
z (obecnie) usuniętej pozycji rejestru rozszerzeń, miałby dostęp do niepoprawnego obiektu. Jedyne
wskazówki informujące o wystąpieniu tego problemu można było uzyskać, nasłuchując zdarzenia IRegistryChangeEvent
.
Problem ten istniał od wersji 3.0 środowiska Eclipse, ale jest rzadko spotykany w praktyce, gdyż moduły dodatkowe
zwykle nie są usuwane bez restartowania środowiska Eclipse.
Wersja 3.1 zapobiega opisanemu problemowi w następujący sposób:
IExtensionPoint
, IExtension
i IConfigurationElement
określają teraz, że jeśli obiekt nie będzie poprawny, zostanie zgłoszony wyjątek InvalidRegistryObjectException
.
Wyjątek ten nie jest sprawdzany, aby klienci niedziałający w sposób dynamiczny nie byli zmuszani do jego kontrolowania.isValid()
, która pozwala określić, czy dany obiekt jest nadal poprawny.Wymagana akcja: Jeśli moduł dodatkowy powinien obsługiwać dynamiczne dodawanie i usuwanie
modułów dodatkowych, należy zmienić kod dotyczący obiektów IExtensionPoint
,
IExtension
i IConfigurationElement
innych modułów dodatkowych.
Powinien on przechwytywać wyjątek IRegistryChangeEvent
dokładnie w taki sposób, jakby był on sprawdzany.
Przechwytywanie wyjątku (zamiast jedynie sprawdzania poprawności obiektu metodą isValid()
)
jest jedyną pewną metodą zabezpieczenia na wypadek usunięcia modułu dodatkowego przez wątek współbieżny.
Zmiany obejmują: Moduły dodatkowe, które korzystają z programowego dostępu do opcji formatera kodu Java.
Opis: W środowisku Eclipse 3.0 opcja formatera kodu
org.eclipse.jdt.core.formatter.DefaultCodeFormatterConstants#FORMATTER_TAB_CHAR
mogła przyjmować jedynie wartości TAB
lub SPACE
. W specyfikacji
nie podano jawnie, że była to wartość wyliczeniowa, która mogła być rozszerzana w
kolejnych wersjach. W środowisku Eclipse 3.1 dodano trzecią możliwą wartość, MIXED
,
która zapobiega błędowi 73104.
Specyfikacja została odpowiednio zmieniona. Zawiera nową wartość i
informuje o możliwości dodawania kolejnych wartości w przyszłości.
Wymagana akcja: Kod klientów programowo odczytujących i ustawiających tę opcję formatera kodu należy sprawdzić pod kątem użycia nowej trzeciej wartości. Dodatkowo należy zapewnić odporność na podanie innych (przyszłych, obecnie nieznanych) wartości i kontrolę wynikających z tego błędów.
Zmiany obejmują: Moduły dodatkowe, które są podklasami lub tworzą
instancje klasy org.eclipse.ant.core.AntCorePreferences
.
Opis: W środowisku Eclipse 3.0 nie było zabronione tworzenie podklas lub instancji obiektów
klasy org.eclipse.ant.core.AntCorePreferences
.
Było to przeoczenie, które poprawiono w środowisku Eclipse 3.1 przez dodanie oznaczenia informującego,
że nie należy tworzyć podklas ani instancji obiektów tej klasy.
Wymagana akcja: W przypadku klientów programowo tworzących instancje obiektów klasy
org.eclipse.ant.core.AntCorePreferences
należy przeprowadzić migrację kodu w celu
pobierania preferencji przy użyciu metody org.eclipse.ant.core.AntCorePlugin.getPreferences()
.
Każda podklasa musi zostać zmieniona tak, aby nie była podklasą klasy org.eclipse.ant.core.AntCorePreferences
.
Zmiany obejmują: Aplikacje RCP, które nadpisują ustawiany przez środowisko robocze protokół biblioteki JFace.
Opis: Środowisko robocze Eclipse w wersji 3.0 ustawiało protokół
środowiska jako ten, w którym mają być zapisywane błędy biblioteki JFace,
przekazując protokoły modułów dodatkowych środowiska bezpośrednio do
metody org.eclipse.jface.util.Policy.setLog(ILog)
. W wersji 3.1
zależność związana z interfejsem ILog
została usunięta z biblioteki
JFace, aby umożliwić aplikacjom autonomicznym korzystanie z bibliotek SWT i JFace
poza środowiskiem wykonawczym platformy Eclipse. Na potrzeby biblioteki JFace
dodano nowy interfejs ILogger
. Środowisko robocze zostało zmodyfikowane
w celu udostępnienia opakowania interfejsu ILog
środowiska roboczego przez
interfejs ILogger
. Więcej informacji na ten temat można uzyskać w opisie błędu
88608.
Wymagana akcja: Większość aplikacji RCP nie powinna wymagać nadpisywania
protokołu ustawianego przez środowisko robocze, ale jeśli wywoływały one wcześniej
metodę Policy.setLog(ILog)
, należy zmienić podawany w wywołaniu
metody argument na ILogger
.
Zmiany obejmują: Aplikacje RCP, które oczekują domyślnej perspektywy o wartości różnej od NULL.
Opis: W celu umożliwienia aplikacjom RCP rozpoczynania działania z
pustym oknem bez otwartych perspektyw, dodano w metodach
WorkbenchAdvisor.getInitialWindowPerspectiveId()
i IPerspectiveRegistry.getDefaultPerspective()
możliwość zwracania wartości NULL (rozszerzenie 71150).
Środowisko IDE zawsze zawiera domyślną perspektywę, dlatego metoda
IPerspectiveRegistry.getDefaultPerspective()
nigdy nie zwraca wartości NULL.
Analogicznie istniejące aplikacje RCP zwracające dotąd wartości różne od NULL po wywołaniu metody
WorkbenchAdvisor.getInitialWindowPerspectiveId()
będą nadal zwracały takie wartości
po wywołaniu metody IPerspectiveRegistry.getDefaultPerspective()
.
Wymagana akcja: Żadne zmiany nie powinny być wymagane przez klientów.
Zmiany obejmują: Moduły dodatkowe implementujące interfejs org.eclipse.ui.IViewLayout
.
Opis: W środowisku Eclipse 3.0 nie zaznaczono, że klasa org.eclipse.ui.IViewLayout
nie powinna być implementowana przez klientów. Było to przeoczenie, które
poprawiono w środowisku Eclipse 3.1 przez dodanie oznaczenia informującego, że klienci
nie powinni implementować tej klasy.
Wymagana akcja: Wszystkie klasy implementujące interfejs org.eclipse.ui.IViewLayout
muszą zostać poprawione w taki sposób, aby nie implementowały wymienionego interfejsu.
Zmiany obejmują: Moduły dodatkowe implementujące interfejs org.eclipse.jdt.launching.IVMInstall
.
Opis: W środowisku Eclipse 3.0 nie zaznaczono, że klasa org.eclipse.jdt.launching.IVMInstall
nie powinna być implementowana bezpośrednio przez klientów. Było to
przeoczenie, które poprawiono w środowisku Eclipse 3.1 przez dodanie oznaczenia
informującego, że klienci nie powinni bezpośrednio implementować tej klasy. Aby zachować zgodność
binarną, ciągle dozwolone jest bezpośrednie implementowanie interfejsu przez klientów, ale zaleca
się, aby klienci tworzyli podklasy klasy org.eclipse.jdt.launching.AbstractVMInstall
. Klienci
implementujący interfejs IVMInstall
powinni także implementować nowy, opcjonalny
interfejs org.eclipse.jdt.launching.IVMInstall2
, który jest obecnie implementowany
przez podklasę AbstractVMInstall
. Zaleca się zaimplementowanie nowego interfejsu
IVMInstall2
przez klientów, aby uniknąć problemu przedstawionego w błędzie 73493.
Zalecana migracja polega na utworzeniu podklasy klasy AbstractVMInstall
.
Wymagana akcja: Wszystkie klasy implementujące wymieniony interfejs, które
nie są podklasami klasy org.eclipse.jdt.launching.AbstractVMInstall
, powinny zostać
poprawione w taki sposób, aby były podklasami klasy org.eclipse.jdt.launching.AbstractVMInstall
.
Zmiany obejmują: Moduły dodatkowe korzystające z klasy org.eclipse.ui.SelectionEnabler.SelectionClass
.
Opis: W środowisku Eclipse 3.0 zagnieżdżona klasa implementacji org.eclipse.ui.SelectionEnabler.SelectionClass
była publiczna i nie istniały ograniczenia w jej używaniu. Było to przeoczenie, które poprawiono w środowisku Eclipse 3.1
przez ograniczenie widoczności tej klasy do jej pakietu.
Wymagana akcja: Wszystkie klasy tworzące instancje obiektów lub rozszerzające klasę org.eclipse.ui.SelectionEnabler.SelectionClass
należy poprawić tak, aby nie odwoływały się do tej klasy.
Zmiany obejmują: Moduły dodatkowe wywołujące metodę getParent()
podklasy klasy
org.eclipse.jface.action.ContributionItem
.
Opis: W środowisku Eclipse 3.0 nie podano, że metoda org.eclipse.jface.action.ContributionItem.getParent()
może zwrócić wartość NULL. Było to przeoczenie, które poprawiono w środowisku Eclipse 3.1 przez dodanie w dokumentacji Javadoc
informacji o tym, kiedy metoda może zwrócić wartość NULL. Więcej informacji na ten temat można znaleźć w opisie
błędu 92777.
Wymagana akcja: Każdy kod wywołujący metodę ContributionItem.getParent() musi zapewniać obsługę przypadku, w którym otrzymany wynik będzie równy NULL.
Zmiany obejmują: Moduły dodatkowe implementujące interfejs org.eclipse.ui.views.properties.IPropertySource
lub IPropertySource2
.
Opis: W środowisku Eclipse 3.0 specyfikacja metody org.eclipse.ui.views.properties.IPropertySource.isPropertySet(boolean)
została błędnie zmieniona i informowała, że jeśli podana właściwość nie będzie miała istotnej wartości domyślnej, to metoda zwróci wartość true.
We wcześniejszych wersjach specyfikacja określała, że w takim przypadku metoda zwróci wartość false.
Był to błąd wynikający z nieuwagi, który istotnie zmieniał interfejs API, ale implementacja działała bez zmian,
jeśli źródło właściwości implementowało interfejs IPropertySource
, a nie IPropertySource2
.
Poprawiono to w wersji 3.1, cofając specyfikację metody IPropertySource.isPropertySet(boolean)
do jej poprzedniej wersji (wartość false zwracana w podanym przypadku), przy czym metoda IPropertySource2.isPropertySet(boolean)
wymusza w tym samym przypadku zwrócenie wartości true. Więcej informacji na ten temat można znaleźć w opisie błędu
21756.
Wymagana akcja: Wszystkie klasy implementujące interfejs IPropertySource lub IPropertySource2, które zawierają właściwości bez istotnych wartości domyślnych, należy sprawdzić pod kątem zwracania właściwych wartości jako wyniku metody isPropertySource(boolean). Dodatkowo należy się upewnić, że przycisk Odtwórz wartość domyślną w widoku Właściwości działa zgodnie z oczekiwaniami dla odpowiedniego źródła właściwości.
Zmiany obejmują: Moduły dodatkowe, które używały eksperymentalnego elementu
handlerSubmission
wprowadzonego do punktu rozszerzenia
org.eclipse.ui.commands
platformy Eclipse 3.0.
Opis: W środowisku Eclipse 3.0 wprowadzono eksperymentalny element do punktu
rozszerzenia org.eclipse.ui.commands
. Celem tego elementu było
zapewnienie sposobu rejestracji procedur obsługi poprzez kod XML. Od tamtego momentu
wprowadzono znacznie lepszy mechanizm, punkt rozszerzenia org.eclipse.ui.handlers
.
Ponieważ ten element był oznaczony jako eksperymentalny, został usunięty.
Wymagana akcja: Należy dokonać migracji wszystkich modułów dodatkowych definiujących
element handlerSubmission
do punktu rozszerzenia org.eclipse.ui.commands
.
Zmiany obejmują: Moduły dodatkowe ustawiające pole GLOBAL_IGNORES_CHANGED w klasie TeamUI.
Opis: W środowisku Eclipse 3.0 pole GLOBAL_IGNORES_CHANGED zostało dodane do klasy TeamUI. Pole to jest stałą używaną w zdarzeniu zmiany właściwości w celu wskazania, że lista globalnego ignorowania, która jest obsługiwana przez moduł dodatkowy Zespół, została zmieniona. Pole to nie było oznaczone jako final w wersji 3.0, choć powinno. Poprawiono to w wersji 3.1.
Wymagana akcja: Moduły dodatkowe ustawiające powyższe pole nie będą już miały takiej możliwości.
Zmiany obejmują: Moduły dodatkowe, które niepoprawnie korzystają z menedżera układu FillLayout.
Opis: W środowisku Eclipse 3.0 z menedżerem układu FillLayout nie były powiązane żadne dane układu. Jeśli aplikacja przypisała dane układu do elementu potomnego zarządzanego przez tego menedżera, były one ignorowane. W środowisku Eclipse 3.1 dodano do menedżera układu FillLayout obsługę buforowania informacji o wielkości w celu poprawienia wydajności funkcji zmiany wielkości. Dane przechowywane w pamięci podręcznej są zapisywane w obiekcie FillData powiązanym z każdym elementem potomnym zarządzanym przez menedżera układu FillLayout. Jeśli aplikacja niepoprawnie przypisała dane układu do elementu potomnego, wyjątek ClassCastException zostanie zgłoszony po wywołaniu metody computeSize dla elementu nadrzędnego.
Wymagana akcja: W menedżerze układu FillLayout należy znaleźć wszystkie elementy potomne z przypisanymi danymi układu oraz zaprzestać przypisywania danych układu.
Zmiany obejmują: Moduły dodatkowe przechwytujące wyjątki w czasie tworzenia widgetów.
Opis: Jeśli w środowisku Eclipse 3.0 został utworzony widget ze zutylizowanym elementem nadrzędnym, nie był zgłaszany żaden wyjątek, a działanie kodu widgetu kończyło się błędem w późniejszym czasie lub zgłaszany był wyjątek SWTException zawierający komunikat "Widget został zutylizowany". Jeśli widget ze zutylizowanym elementem nadrzędnym zostanie utworzony w środowisku Eclipse 3.1, konstruktor zgłosi wyjątek IllegalArgumentException zawierający komunikat "Argument nie jest poprawny".
Wymagana akcja: Kod obsługujący wyjątek SWTException w czasie tworzenia widgetu powinien obsługiwać także wyjątek IllegalArgumentException.