Gestori

org.eclipse.ui.handlers

3.1

Il punto di estensione gestori è un'elaborazione dell'elemento sperimentale handlerSubmission definito in Eclipse 3.0. Un gestore rappresenta il comportamento di un comando in un particolare momento. Ad un comando possono essere associati zero o più gestori. In un determinato momento, tuttavia, un comando può avere nessun o un solo gestore attivo. Il gestore attivo è quello attualmente responsabile del comportamento del comando. Questo è molto simile al concetto di gestore di azione e di azione ridestinabile.

Il punto di estensione gestori consente agli sviluppatori di plugin di specificare un gestore che diventa attivo e/o abilitato in determinate condizioni. Se un gestore non è attivo, nessun comando delegherà il proprio comportamento al gestore. Se un gestore è disabilitato, non verrà richiesta l'esecuzione del gestore; l'esecuzione del gestore è bloccata. Le condizioni sono definite utilizzando la funzione di linguaggio delle espressioni aggiunta nella versione 3.0. Queste sono espresse utilizzando le proposizioni activeWhen e enabledWhen.

Il workbench fornisce alcune variabili sulle quali si basano queste espressioni. Le variabili supportate sono: i contesti attivi, l'editor attivo, la parte attiva e la selezione corrente. Anche se non supportato nella progettazione iniziale, sarebbe chiaramente possibile aggiungere altre variabili o anche consentire agli sviluppatori di plugin di fornire altre variabili.

Un gestore che non specifica alcuna condizione è un gestore predefinito. Un gestore predefinito è attivo solo se nessun altro gestore soddisfa tutte le proprie condizioni. Se due gestori presentano ancora condizioni soddisfatte, queste condizioni sono confrontate. L'obiettivo è di selezionare un gestore le cui condizioni siano più specifiche o locali. Per fare ciò, si osservano le variabili a cui fa riferimento la condizione. La condizione con riferimento alla variabile più specifica è "vincente". L'ordine di specificità (dal meno specifico al più specifico) viene definito in org.eclipse.ui.ISources.

Se comunque non si risolve il conflitto, non si attiva alcun gestore. Se è stata attivata una particolare opzione di traccia, viene generato un messaggio nel log. Si può anche verificare un conflitto se sono presenti due gestori predefiniti. È responsabilità degli sviluppatori di plugin e dei tester di integrazione assicurare che non si verifichi tale situazione. Queste condizioni sono utilizzate per evitare il caricamento di plugin non necessari. Queste definizioni di gestori sono incluse in un proxy. Affinché un proxy effettui il caricamento del gestore sottostante, si devono verificare quanto segue: devono essere soddisfatte le condizioni per l'attivazione del proxy e deve essere effettuata una richiesta al comando di eseguire un'azione da delegare (ad esempio, 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)*>

Un elemento principale generico. L'elemento può essere utilizzato in un punto di estensione per definire la relativa espressione di attivazione. Gli elementi secondari di un'espressione di attivazione vengono associati utilizzando l'operatore and.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

Questo elemento rappresenta un'operazione NOT sul risultato della valutazione della relativa espressione dell'elemento secondario.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Questo elemento rappresenta un'operazione AND sul risultato della valutazione di tutte le espressioni dei relativi elementi secondari.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Questo elemento rappresenta un'operazione OR sul risultato della valutazione di tutte le espressioni dei relativi elementi secondari.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Questo elemento viene utilizzato per eseguire un controllo instanceof dell'oggetto attivo. L'espressione restituisce EvaluationResult.TRUE se il tipo dell'oggetto è un tipo secondario del tipo specificato dal valore dell'attributo. In caso contrario, viene restituito EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Questo elemento viene utilizzato per valutare lo stato della proprietà dell'oggetto in questione. L'insieme di proprietà verificabili può essere esteso utilizzando il punto di estensione del tester delle proprietà. L'espressione di verifica restituisce EvaluationResult.NOT_LOADED se il tester delle proprietà non è ancora stato caricato.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Verifica una proprietà di sistema richiamando il metodo System.getProperty e confronta il risultato con il valore specificato dall'attributo del valore.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Questo elemento viene utilizzato per eseguire un controllo di eguaglianza dell'oggetto attivo. L'espressione restituisce EvaluationResult.TRUE se l'oggetto è uguale al valore fornito dal valore dell'attributo. In caso contrario, viene restituito EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Questo elemento viene utilizzato per verificare il numero di elementi in una raccolta.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

Questo elemento modifica l'oggetto da esaminare per tutti i relativi elementi secondari indicati da una determinata variabile. Se non è possibile risolvere la variabile, l'espressione genera un ExpressionException durante la valutazione. Gli elementi secondari di una espressione WITH sono combinati con l'operatore AND.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Questo elemento modifica l'oggetto da esaminare per tutti i relativi elementi secondari indicati da una determinata variabile. Se non è possibile risolvere la variabile, l'espressione genera un ExpressionException durante la valutazione. Gli elementi secondari di una espressione WITH sono combinati con l'operatore AND.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

Questo elemento viene utilizzato per adattare l'oggetto attivo al tipo specificato dal tipo di attributo. L'espressione restituisce non caricato se l'adattatore o il tipo indicato non è stato ancora caricato. Viene generata una ExpressionException durante la valutazione se il nome del tipo non esiste. Gli elementi secondari di una espressione di adattamento sono combinati con l'operatore AND.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

Questo elemento viene utilizzato per iterare una variabile di tipo java.util.Collection. Se l'oggetto attivo non è del tipo java.util.Collection viene generata una ExpressionException durante la valutazione dell'espressione.



<extension point=

"org.eclipse.ui.handlers"

>

<handler commandId=

"commandId"

class=

"org.eclipse.compare.Command"

>

<activeWhen>

<with variable=

"selection"

>

<count value=

"1"

/>

<iterate operator=

"and"

>

<adapt type=

"IResource"

/>

</iterate>

</with>

</activeWhen>

</handler>

</extension>

Per evitare ulteriori caricamenti di plugin, è possibile specificare quando un gestore è abilitato. Se il proxy non ha ancora caricato il gestore, viene utilizzata solo la sintassi delle espressioni per decidere se il gestore è abilitato. Se il proxy ha già caricato il gestore, la sintassi delle espressioni viene valutata per prima. Se la sintassi delle espressioni viene considerata come verificata, viene chiesto se il gestore è abilitato. (Questa è un'operazione "and" booleana abbreviata tra la sintassi delle espressioni e lo stato di abilitazione del gestore).

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

Tutti i gestori implementano org.eclipse.core.commands.IHandler. All'interno del workbench, è possibile attivare e disattivare i gestori utilizzando l'interfaccia org.eclipse.ui.handlers.IHandlerService. Questa interfaccia può essere richiamata dagli oggetti del workbench che la supportano, ad esempio IWorkbench. Per richiamare il servizio, si può effettuare una chiamata del tipo IWorkbench.getAdapter(IHandlerService.class).

Inoltre, è possibile attivare o disattivare i gestori utilizzando il codice legacy nel workbench. Questa azione può essere eseguita mediante il meccanismo legacy illustrato di seguito. Questo meccanismo risulta utile per i client che utilizzano azioni per contribuire ai menu o alle barre degli strumenti.

 IWorkbenchPartSite mySite;
 IAction myAction;
 
 myAction.setActionDefinitionId(commandId);
 IKeyBindingService service = mySite.getKeyBindingService();
 service.registerAction(myAction);