Procedury obsługi

org.eclipse.ui.handlers

3.1

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>


<!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)>



<!ELEMENT class (parameter*)>

<!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.



<!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.



<!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.



<!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.



<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);