Punkt rozszerzenia procedur obsługi jest opracowaniem eksperymentalnego elementu handlerSubmission
zdefiniowanego w platformie Eclipse 3.0. Procedura obsługi określa zachowanie komendy w konkretnym momencie.
Komenda może nie mieć powiązanych z nią procedur obsługi lub może mieć ich wiele. Jednak w każdym momencie
komenda będzie miała jedną aktywną procedurę obsługi lub nie będzie miała żadnej. Aktywna procedura
obsługi to ta, która odpowiada w danej chwili za realizację zachowania komendy. Koncepcja procedur obsługi jest
bardzo podobna do procedur obsługi akcji oraz akcji o zmiennym celu.
Punkt rozszerzenia procedur obsługi umożliwia programiście wtyczki
określenie procedury obsługi aktywowanej i/lub włączanej w określonych warunkach.
Jeśli procedura obsługi jest nieaktywna, wówczas żadna komenda nie przekaże do niej swojego zachowania.
Jeśli procedura obsługi jest wyłączona, to nie zostanie wysłane do niej żądanie wykonania;
wykonanie procedury obsługi będzie zablokowane. Warunki są definiowane przy użyciu narzędzia
języka wyrażeń dodanego w wersji 3.0. Są one wyrażane przy użyciu klauzul activeWhen
i enabledWhen
.
Środowisko robocze udostępnia pewne zmienne, które mogą być stosowane w tych wyrażeniach. Obsługiwane zmienne to: aktywne konteksty, aktywny edytor, aktywna część oraz bieżący wybór. Mimo że w tym początkowym projekcie inne zmienne nie są obsługiwane, łatwo jest się przekonać, w jaki sposób można je dodawać lub nawet umożliwić ich wnoszenie przez programistów wtyczek.
Procedura obsługi nieokreślająca żadnych warunków jest procedurą domyślną. Domyślna procedura obsługi jest aktywna tylko w przypadku,
gdy nie są spełnione wszystkie warunki innych procedur. Jeśli spełnione są wszystkie warunki dwóch procedur obsługi,
to warunki te są porównywane. Wybierana jest wtedy procedura obsługi, której warunek jest bardziej precyzyjny lub
bardziej lokalny. W tym celu analizowane są zmienne, do których odwołuje się dany warunek. Wybierany jest warunek,
który odwołuje się do najbardziej precyzyjnej zmiennej. Porządek poziomów precyzji (od najniższego do najwyższego)
jest zdefiniowany w interfejsie org.eclipse.ui.ISources
.
Jeśli to nadal nie rozwiązuje konfliktu, to żadna procedura obsługi nie będzie aktywna. Jeśli włączona jest odpowiednia opcja śledzenia, spowoduje to zapisanie komunikatu w dzienniku. Konflikt może wystąpić również, gdy istnieją dwie domyślne procedury obsługi. Do programistów wtyczek oraz testerów integracji należy zapewnienie, aby tak się nie stało. Omawiane warunki pozwalają uniknąć niepotrzebnego ładowania wtyczki. Definicje procedur obsługi są opakowane w serwer proxy. Aby możliwe było załadowanie bazowej procedury obsługi serwera proxy, muszą zaistnieć dwie okoliczności: spełnione muszą zostać warunki dla serwera proxy (aby stał się on aktywny) oraz wydana musi zostać komenda w celu przeprowadzenia delegowanej czynności (np. execute()).
<!ELEMENT extension (handler*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT handler (activeWhen? , class? , enabledWhen?)>
<!ATTLIST handler
commandId CDATA #REQUIRED
class CDATA #IMPLIED
helpContextId CDATA #IMPLIED>
Od wersji 3.2
<!ELEMENT activeWhen (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ELEMENT enabledWhen (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST class
class CDATA #IMPLIED>
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Ogólny element główny. Element ten może być stosowany w ramach punktu rozszerzenia do zdefiniowania jego wyrażenia włączającego. Elementy potomne wyrażenia włączającego łączy się za pomocą operatora and
.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
Element ten odpowiada operacji NOT wykonywanej na wynikach wartościowania wyrażenia podelementu.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Element ten odpowiada operacji AND wykonywanej na wynikach wartościowania wszystkich wyrażeń podelementów.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Element ten odpowiada operacji OR wykonywanej na wynikach wartościowania wszystkich wyrażeń podelementów.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Element ten służy do wykonywania sprawdzenia instanceof
obiektu aktywnego. Wyrażenie zwraca wartość EvaluationResult.TRUE
, jeśli typ obiektu jest podtypem typu określonego atrybutem value
. W przeciwnym razie zwracana jest wartość EvaluationResult.FALSE
.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Element ten służy do wartościowania stanu właściwości obiektu aktywnego. Zbiór właściwości objętych testowaniem można rozszerzyć za pomocą punktu rozszerzenia testera właściwości. Wyrażenie testowe zwraca wartość EvaluationResult.NOT_LOADED
, jeśli nie załadowano jeszcze testera właściwości wykonującego faktyczne testowanie.
value
wyrażenia testowego.EvaluationResult.TRUE
, jeśli właściwość odpowiada danej wartości. W przeciwnym razie oczekiwana jest wartość EvaluationResult.FALSE
. Atrybut value
jest przekształcany w typ podstawowy języka Java zgodnie z następującymi regułami:
Boolean.TRUE
.Boolean.FALSE
.Float
. W przypadku niepowodzenia łańcuch jest traktowany jako klasa java.lang.String
.Integer
.Boolean
, Float
lub Integer
można zablokować, umieszczając łańcuch w pojedynczym cudzysłowie. Przykładowo atrybut value="'true'" jest przekształcany w łańcuch "true".<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Testuje właściwość systemową, wywołując metodę System.getProperty
i porównując wynik z wartością określoną za pomocą atrybutu value
.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Element ten służy do wykonywania sprawdzenia equals
obiektu aktywnego. Wyrażenie zwraca wartość EvaluationResult.TRUE
, jeśli obiekt jest równy wartości określonej atrybutem value
. W przeciwnym razie zwracana jest wartość EvaluationResult.FALSE
.
equals
. Wartość podana jako łańcuch jest przekształcana w typ podstawowy języka Java zgodnie z regułami, które zdefiniowano w odniesieniu do atrybutu value
wyrażenia testowego.<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Element ten służy do sprawdzania liczby elementów w ramach kolekcji.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
Element ten zamienia obiekt, który ma być sprawdzany w odniesieniu do wszystkich elementów potomnych, na obiekt, do którego odwołuje się dana zmienna. Jeśli zmiennej nie można zinterpretować, podczas wartościowania wyrażenie zgłasza wyjątek ExpressionException
. Elementy potomne wyrażenia with
łączy się za pomocą operatora and
.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
Element ten zamienia obiekt, który ma być sprawdzany w odniesieniu do wszystkich elementów potomnych, na obiekt, do którego odwołuje się dana zmienna. Jeśli zmiennej nie można zinterpretować, podczas wartościowania wyrażenie zgłasza wyjątek ExpressionException
. Elementy potomne wyrażenia with
łączy się za pomocą operatora and
.
IVariableResolver
) za pośrednictwem kontekstu wartościowania przekazywanego do elementu głównego wyrażenia w trakcie wartościowania tego wyrażenia.value
wyrażenia testowego.<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
Element ten służy do dostosowywania obiektu aktywnego do typu określonego atrybutem type
. Wyrażenie zwraca wartość not loaded
, jeśli nie załadowano jeszcze adaptera lub typu, którego dotyczy odwołanie. Jeśli nazwa typu w ogóle nie istnieje, podczas wartościowania zgłaszany jest wyjątek ExpressionException
. Elementy potomne wyrażenia adapt
łączy się za pomocą operatora and
.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
Element ten służy do iteracji zmiennej typu java.util.Collection
. Jeśli obiekt aktywny nie jest obiektem typu java.util.Collection
, podczas wartościowania wyrażenia zgłaszany jest wyjątek ExpressionException
.
and
lub or
. Operator określa, w jaki sposób mają być łączone elementy potomne. Jeśli nie została podana żadna wartość, stosowany jest operator and
.<extension point=
"org.eclipse.ui.handlers"
>
<handler commandId=
"commandId"
class=
"org.eclipse.compare.Command"
>
<activeWhen>
<with variable=
"Wybór"
>
<count value=
"1"
/>
<iterate operator=
"and"
>
<adapt type=
"IResource"
/>
</iterate>
</with>
</activeWhen>
</handler>
</extension>
Aby dodatkowo uniknąć ładowania wtyczki, można określić, kiedy procedura obsługi ma być włączona. Jeśli serwer proxy nie załadował jeszcze procedury obsługi, to do określenia, czy procedura obsługi ma zostać włączona, służy tylko składnia wyrażeń. Po załadowaniu procedury obsługi przez serwer proxy składnia wyrażeń jest sprawdzana w pierwszej kolejności. Jeśli składnia wyrażeń przyjmuje wartość true, to do procedury obsługi wysyłane jest pytanie, czy jest włączona (między składnią wyrażeń a stanem włączenia procedury obsługi zachodzi boolowska operacja and o niepełnym wartościowaniu).
<extension point=
"org.eclipse.ui.handlers"
>
<handler commandId=
"commandId"
class=
"org.eclipse.Handler"
>
<enabledWhen>
<with variable=
"context"
>
<property id=
"id"
value=
"debugging"
/>
</with>
</enabledWhen>
</handler>
</extension>
Wszystkie procedury obsługi implementują interfejs org.eclipse.core.commands.IHandler
.
W obrębie środowiska roboczego można aktywować oraz dezaktywować procedury obsługi przy użyciu interfejsu
org.eclipse.ui.handlers.IHandlerService
. Ten interfejs może zostać pobrany z obiektów obsługujących
środowisko robocze, takich jak sam interfejs IWorkbench
. Aby pobrać usługę, należy użyć na
przykład wywołania: IWorkbench.getAdapter(IHandlerService.class)
.
Procedury obsługi można również aktywować i dezaktywować przy użyciu wcześniejszego kodu środowiska roboczego. Można to zrobić przy użyciu wcześniejszego mechanizmu przedstawionego poniżej. Ten mechanizm jest przydatny dla klientów, które używają akcji w celu wnoszenia obiektów do menu lub pasków narzędzi.
IWorkbenchPartSite mySite; IAction myAction; myAction.setActionDefinitionId(commandId); IKeyBindingService service = mySite.getKeyBindingService(); service.registerAction(myAction);
Copyright (c) 2005 IBM Corporation i inne podmioty.
Wszelkie prawa zastrzeżone. Program ten oraz towarzyszące mu materiały są udostępniane na warunkach
licencji EPL (Eclipse Public License), wersja 1.0, dołączonej do nich i
dostępnej pod adresem http://www.eclipse.org/legal/epl-v10.html.