SeamFramework.orgCommunity Documentation

Chapitre 31. Les annotations Seam

31.1. Les annotations pour la définition des composants.
31.2. Les annotations pour les bijections
31.3. Les annotations pour les méthodes de cycle de vie.
31.4. Les annotations pour la démarcation de contexte
31.5. Les annotations utilisées avec les composants JavaBean Seam dans une environnement JEE
31.6. Les annotations pour les exceptions
31.7. Les annotations pour Seam Remoting
31.8. Les annotations pour les intercepteurs de Seam.
31.9. Les annotations pour l'asynchronicité
31.10. Les annotations utilisés avec JSF
31.10.1. Les annotations pour dataTable
31.11. Les metas-annotations pour le databinding
31.12. Les annotations pour le packaging
31.13. Les annotations pour l'intégration avec le conteneur de Servlets

Quand vous écrivez une application Seam, vous serez amené à utiliser de nombreuses annotations. Avec les annotations, Seam vous permettra de programmer de façon déclarative. La plupart des annotations que vous utiliserez appartiennent à la spécification EJB3. Les annotations pour la validation des données appartiennent au package Hibernate Validator. Enfin Seam définit lui-même son propre sous-ensemble d'annotations, que nous allons décrire dans ce chapitre.

Toutes ces annotations sont définis dans le package org.jboss.seam.annotations.

31.1. Les annotations pour la définition des composants.

Le premier groupe d'annotations vous permet de définir un composant Seam. Ces annotations sont déclarées au niveau de la classe.

@Name 
@Name("componentName")

Définit le nom du composant Seam pour une classe donnée. Cette annotation est obligatoire pour tout composant Seam.

@Scope 
@Scope(ScopeType.CONVERSATION)

Définit le scope (contexte) par défaut auquel ce composant appartient. Les valeurs qui peuvent être prises sont définies par l'énumération ScopeType : EVENT, PAGE, CONVERSATION, SESSION, BUSINESS_PROCESS, APPLICATION, STATELESS.

Quand aucun scope n'est défini, la valeur par défaut dépend du type du composant. Pour les beans session stateless, la valeur par défaut est STATELESS. Pour les beans entité et les bean session stateful la valeur par défaut est CONVERSATION. Pour les JavaBeans, la valeur par défaut est EVENT.

@Role 
@Role(name="roleName", scope=ScopeType.SESSION)

Permet à un composant Seam d'être lié à plusieurs variables de contexte à la fois. Les annotations @Name/@Scope définissent en quelques sorte un "role par défaut". Mais chaque annotation @Role permet de définir alors un rôle supplémenataire.

@Roles 
@Roles({

        @Role(name="user", scope=ScopeType.CONVERSATION),

        @Role(name="currentUser", scope=ScopeType.SESSION)

   })

Permet de spécifier des rôles additionnels.

@BypassInterceptors 
@BypassInterceptors

Désactive toutes interceptions de Seam sur le composant ou sur l'une de ses méthodes.

@JndiName 
@JndiName("my/jndi/name")

Spécifie le nom JNDI que Seam utilisera pour rechercher le composant EJB. Si aucun nom JNDI n'est explicitement spécifié, Seam utilisera le pattern JNDI spécifié par org.jboss.seam.core.init.jndiPattern.

@Conversational 
@Conversational

Spécifie que le scope du composant est conversationnel, cela signifie qu'aucune méthode du composant ne peut être invoquée à moins qu'une conversation longue soit active.

@PerNestedConversation 
@PerNestedConversation

Limite la visibilité du composant au scope de la conversation dans laquelle il a été créé. Cette instance du composant ne sera pas visible par les conversations enfants, qui obtiendront alors leur propre instance de ce composant.

Attention, cette définition présente ses propres limites, car elle implique qu'un composant sera visible depuis certaines parties de la requète, mais plus après l'éxécution de ces dernières. Nous ne recommandons donc pas l'utilisation de cette fonctionnalité.

@Startup 
@Scope(APPLICATION) @Startup(depends="org.jboss.seam.bpm.jbpm")

Spécifie qu'un composant ayant un scope application est démarré immédiatement pendant la phase d'initialisation de l'application. C'est principalement utilisé pour les composant natif de Seam qui ont des rôles structurels critiques comme jNDI, Datasources, etc. 

@Scope(SESSION) @Startup

Spécifie qu'un composant ayant un scope session est démarré immédiatemnt durant la phase de création de la session.

@Install 
@Install(false)

Spécifie si un composant doit ou ne doit pas par défaut être installé . L'absence de l'annotation @Install indique implicitement qie le composant doit être installé. 

@Install(dependencies="org.jboss.seam.bpm.jbpm")

Spécifie qu'un composant ne doit être installé que si les composants listés comme des dépendances sont aussi installés. 

@Install(genericDependencies=ManagedQueueSender.class)

Spécifie qu'un composant ne doit être installé que si des composants implémentés par certaines classes sont aussi installés. Ceci est utile quand on ne dispose pas des noms précis des composants présents dans l'application, mais que l'on connait leur classe. 

@Install(classDependencies="org.hibernate.Session")

Spécifice qu'un composant de doit être installé que si la classe nommée est présente dans le classpath. 

@Install(precedence=BUILT_IN)

Spécifie la précédence du composant. Si plusieurs composants existe avec le même nom, c'est celui qui aura la précédence la plus élevée qui sera installé. Les différentes valeurs de précédences sont (dans l'ordre croissant) :

@Synchronized 
@Synchronized(timeout=1000)

Spécifie qu'un composant est accédé de façon concurentielle par plusieurs clients et que Seam doit alors placer les requètes dans une file d'attente. Si une requète ne parvient pas à obtenir le verrou sur le composant dans un laps de temps égal au timeout, une exception est levée.

@ReadOnly 
@ReadOnly

Spécifie qu'un composant JavaBean ou une méthode de composant de nécessite pas une réplication d'état à l'issu de son invocation.

@AutoCreate 
@AutoCreate

Spécifie que le composant sera automatiquement créé, même si le code client ne spécifie pas create=true.

31.2. Les annotations pour les bijections

Les deux annotations suivantes contrôle le processus de bijection. Ces attributs peuvent être placés sur les propriétés du composants ou sur leurs accesseurs (ie getter et setter)

@In 
@In

Spécifie qu'une variable de contexte doit être injecté dans un attribut de composant au début de chaque invocation du composant. Si la variable de contexte est nulle une exception est levée. 

@In(required=false)

Spécifie qu'une variable de contexte doit être injecté dans un attribut de composant au début de chaque invocation du composant. Cette variable de contexte peut être nulle. 

@In(create=true)

Spécifie qu'une variable de contexte doit être injecté dans un attribut de composant au début de chaque invocation du composant. Si la variable est nulle, alors Seam instanciera une instance de ce composant. 

@In(value="contextVariableName")

Spécifie le nom de la variable de contexte explicitement au lieu d'utiliser le nom de la variable annotée. 

@In(value="#{customer.addresses['shipping']}")

Spécifie que l'attribut du composant doit être injecté en évaluant une expression JSF EL au début de chaque invocation du composant.

@Out 
@Out

Spécifie que l'attribut de composant, qui est aussi un composant Seam, doit être "exposé" dans l'un des contextes (scopes) de Seam à la fin de chaque invocation du composant. Si l'attribut est null, une exception est levée. 

@Out(required=false)

Spécifie qu'un attribut de composant, qui est aussi un composant Seam, doit être "exposé" dans l'un des contextes (scopes) de Seam à la fin de chaque invocation du composant. L'attribut peut-être null. 

@Out(scope=ScopeType.SESSION)

Spécifie qu'un attribut de composant qui n'est pas un composant Seam doit être exposé dans un scope (context) spécifique de Seam à la fin de l'invocation du composant.

Mais si aucun scope (context) n'est spécifié, c'est le scope du composant qui porte l'attribut annoté @Out qui sera utilisé (Si le composant porteur est stateless alors l'attribut annoté sera oujecté dans le scope (context) EVENT). 

@Out(value="contextVariableName")

Spécifie le nom de la variable de contexte explicitement au lieu d'utiliser le nom de la variable annotée.

Remarquer qu'il est assez fréquent pour ces annotations d'être utilisées ensemble, par exemple : 

@In(create=true) @Out private User currentUser;

The next annotation supports the manager component pattern; a Seam component manages the lifecycle of an instance of some other class that is to be injected. It appears on a component getter method.

@Unwrap 
@Unwrap

Spécifie que l'objet retourné par la méthode getter annotée sera injecté à la place du composant lui-même.

The next annotation supports the factory component pattern; a Seam component is responsible for initializing the value of a context variable. This is especially useful for initializing any state needed for rendering the response to a non-faces request. It appears on a component method.

@Factory 
@Factory("processInstance") public void createProcessInstance() { ... }

Spécifie que la méthode annotée du composant sera invoquée pour initialiser la valeur de la variable de contexte quand celle-ci n'a pas encore de valeur. Ce style est utilisée avec des méthodes ne renvoyant aucune valeur (type de retour void). 

@Factory("processInstance", scope=CONVERSATION) public ProcessInstance createProcessInstance() { ... }

Spécifie que la méthode renvoie une valeur que Seam devra utiliser pour pour initialiser la variable de contexte lorsque celle-ci n'a pas de valeur. Ce style est utilisé avec les méthodes renvoyant une valeur. Si aucun scope n'est spécifié, le scope du composant possedant la méthode annotée @Factory est utilisée (a moins que le composant soit stateless dans ce cas c'est le scope (context) EVENT qui sera utilisée).

Cette annottion vous permet d'injecter un Log:

@Logger 
@Logger("categoryName")

Spécifie qu'il faut injecter dans un attribut du composant une instance de org.jboss.seam.log.Log. Pour un bean entité il faut que l'attribut injecté soit déclaré statique.

La dernière annotation vous permet d'injecter un paramètre de requète.

@RequestParameter 
@RequestParameter("parameterName")

Spécifie que l'on injecte dans l'attribut du composant un paramètre de requète. Les conversions des types de base sont faits automatiquement.

31.3. Les annotations pour les méthodes de cycle de vie.

Ces annotations permettent à un composant de réagir aux événement de son propre cycle de vie. On ne peut en déclarer qu'une par classe.

@Create 
@Create

Spécifie que cette méthode doit être appellée quand une instance du composant a été instancié par Seam. Attention les méthodes annotés @Create ne nont applicable que pour les JavaBean et les beans session stateful.

@Destroy 
@Destroy

Spécifie que la méthode doit être invoqué lorsque que le contexte se termine et que chaque variable de celui-ci va être supprimée. Attention seul les JavaBean et les session bean stateful peuvent déclaré des méthodes destroy.

Les méthodes destroy ne devrait être utilisés que pour la libération des ressources. Seam intercepte et log toutes exceptions qu'une méthodes destroy pourrait propager.

@Observer 
@Observer("somethingChanged")

Spécifie que la méthode devrait être invoquée lorsqu'un événement issus d'un composant est émis. 

@Observer(value="somethingChanged",create=false)

Spécifie que la méthode doit être invoquée si un évenement de ce type survient, mais que l'instance du composant écouteur ne devrait pas être créé si il n'existe pas. Si l'instance n'existe pas l'événement ne sera pas écouté. La valeur par défaut de create est true.

31.4. Les annotations pour la démarcation de contexte

Ces annotations permetent de démarquer de façon déclarative les conversations. Elles apparaissent le plus souvent sur des méthodes écouteurs.

Chaque requete web a un context de conversation qui lui est associé. La plupart de ces conversations s'acheve avec la requète. Si vous voulez que la conversation s'étende sur plusieurs requètes il vous faudra "Promouvoir" la conversation courante au rang de longue conversation en invoquent une méthode annotée @Begin.

@Begin 
@Begin

Spécifie qu'une conversation longue démarre quand cette méthode renvoie une valeur non nulle sans lever d'exception. 

@Begin(join=true)

Spécifie qu'une longue conversation a déjà démarré, le contexte the conversation est simplement propagé. 

@Begin(nested=true)

Spéciifie qu'une longue conversation est déjà engagée, un nouveau contexte de conversation enfant est démarré. La conversation enfant se terminera à la prochaine invoquation d'une méthode annotée @End, la conversation parente reprendra alors. Il est tout à fait possible que plusieurs conversations enfants existent concurentiellement au sein de la même conversation parente. 

@Begin(pageflow="process definition name")

Spécifie q'une définition de pageflow JBPM sera utilisée pour conduire cette conversation. 

@Begin(flushMode=FlushModeType.MANUAL)

Spécifie le flush mode de tous les contextes de persistence managés par Seam. flushMode=FlushModeType.MANUAL apporte la notion de conversation atomique où toutes opérations d'écriture est mis en queue dans le contexte de persistence jusqu'à ce qu'un appel explicite à flush() ait lieu ( en général à la fin de la conversation).

  • join — détermine le mode de propagation lorsque qu'une conversation est déjà engagée. Si join vaut true,le contexte est propagé. Si join vaut false, un exception est levée. Par défaut join vaut false. Ce paramétrage est ignoré si nested=trueest spécifié.

  • nested — Spécifie qu'une conversation enfant devrait être démarrée si une longue conversation est déjà engagée.

  • flushMode — fixe le flush mode de toutes les sessions Hibernate ou de tous les contextes de persistence managé par Seam qui seront créés durant cette conversation.

  • pageflow — Le nom de la définition d'un process jBPM qui sera déployé via org.jboss.seam.bpm.jbpm.pageflowDefinitions.

@End 
@End

Spécifie qu'une longue conversation s'achève si la méthode retourne une valeur non null sans lever d'exception.

@StartTask 
@StartTask

Démarre une nouvelle tâche JBPM. Spécifie aussi qu'une longue conversation démarre lorsque la méthode ainsi annotée a un retour non null sans lever d'exception. La tâche JBPM qui sera associée à ce contexte de conversation sera spécifiée grâce à un paramètre de requête nommé, le buisness process associé à cette tâche est lui aussi associé à cette conversation.

@BeginTask 
@BeginTask

Reprend une tâche JBPM qui n'a pas été terminé. Spécifie aussi qu'une longue conversation démarre lorsque la méthode ainsi annotée a un retour non null sans lever d'exception. La tâche JBPM qui sera associée à ce contexte de conversation sera spécifiée grâce à un paramètre de requête nommé, le buisness process associé à cette tâche est lui aussi associé à cette conversation.

@EndTask 
@EndTask

Termine une tache JBPM. Spécifie qu'une conversation longue termine si la méthode ainsi annotée renvoie un résultat non null sans lever d'exception, spécifie aussi que la tâche courante a été complétée. Ceci déclanche alors une transition JBPM. La transition déclanchée sera alors la transition par défaut à moins que l'application n'ait invoqué Transition.setName() sur le composant intégré dont le nom est transition. 

@EndTask(transition="transitionName")

Déclanche la transition JBPM.

@CreateProcess 
@CreateProcess(definition="process definition name")

Crée une nouvelle instance d'un JBPM process lorsque la méthode ainsi annotée retourne un résultat non null sans lever d'exception L'object ProcessInstance sera disponible dans une variable de contexte nomée processInstance.

@ResumeProcess 
@ResumeProcess(processIdParameter="processId")

Ré-entre dans le scope d'une instance de process JBPM lorsque la méthode ainsi annotée renvoie une valeur non null sans lever d'exception. L'object ProcessInstance sera alors accessible grâce à une variable de contexte nomée processInstance.

@Transition 
@Transition("cancel")

Une méthode ainsi annotée déclenche une transition au sein du contexte JBPM courant à chaque fois qu'elle renvoie une valeur non null.

31.5. Les annotations utilisées avec les composants JavaBean Seam dans une environnement JEE

Seam met à disposition des annotations qui permettent de forcer un rollback JTA en fonction des retours renvoyer par un listener.

@Transactional 
@Transactional

Spécifie que le composant JavaBean doit avoir un comportement similaire à celui d'un bean session. C'est à dire que l'invocation de la méthode doit rejoindre une transaction, et si aucune transaction n'existe lors de la l'appel de la méthode, une transaction sera crée juste pour cette méthode. Cette annotation peut s'appliquer au niveau de la classe toute entière ou au niveau d'une méthode.

N'utiliser pas cette annotation sur un composant EJB 3.0, utiliser@TransactionAttribute!

@ApplicationException 
@ApplicationException

Synonyme de javax.ejb.ApplicationException, à utiliser dans les environnements pre Java EE 5. Elle est appliquéee sur une exception pour qualifier l'exception "d'exception applicative" et doit être remontée directement au client (c'est à dire sans être encapsulée).

N'utiliser pas cette annotation sur les composants EJB 3.0, utiliser à la place @javax.ejb.ApplicationException instead.

@Interceptors 
@Interceptors({DVDInterceptor, CDInterceptor})

Synonyme de javax.interceptors.Interceptors, à utiliser dans les environnements pre Java EE 5. Remarquer que c'est à utiliser comme une meta-annotation. Declare une liste d'intercepteurs pour une classe ou une méthode.

n'utiliser pas cette annotation sur les composants EJB 3.0, utiliser @javax.interceptor.Interceptors à la place.

Ces annotations sont essentiellement utilisées pour les composants Seam JavaBean. Si vous utiliser des composants EJB 3.0, vous devriez plutôt utiliser les annotations standards Java EE5.

31.6. Les annotations pour les exceptions

Ces annotations vous permettent de spécifier comment Seam doit prendre en charge les exceptions qui se propagent hors d'un composant Seam.

@Redirect 
@Redirect(viewId="error.jsp")

Spécifie que l'exception annotée provoque une redirection du navigateur vers la vue ayant pour id viewID

@HttpError 
@HttpError(errorCode=404)

Spécifie que l'exception annotées cause l'envoie d'une 'erreur HTTP.

31.7. Les annotations pour Seam Remoting

Seam remoting exige que les interfaces locale d'un bean de session soient annotées avec les annotations suivantes :

@WebRemote 
@WebRemote(exclude="path.to.exclude")

Indique que la méthode annotée peut être appelée depuis le code client JavaScript. La propriétété exclude est optionnelle, elle permet aux objets d'être exclu du graphe résultant (voir le chapitre Remoting pour plus de détails).

31.8. Les annotations pour les intercepteurs de Seam.

Les annotations suivantes sont utilisées pour les intercepteurs Seam.

Nous vous demandons de vous référer à la documentation EJB 3.0 pour connaître les spécifications des intercepteurs EJB.

@Interceptor 
@Interceptor(stateless=true)

Spécifie que l'intercepteur est stateless et que Seam pourra optimiser leur réplication. 

@Interceptor(type=CLIENT)

Spécifie que c'est un intercepteur "coté client" qui est appelé avant le conteneur EJB. 

@Interceptor(around={SomeInterceptor.class, OtherInterceptor.class})

Spécifie que l'intercepteur est positionné plus haut dans la pile d'intercepteurs que les intercepteurs cités dans l'énumération. 

@Interceptor(within={SomeInterceptor.class, OtherInterceptor.class})

Spécifie que l'intercepteur est positionné plus bas dans la pile d'intercepteurs que les intercepteurs cités dans l'énumération.

31.9. Les annotations pour l'asynchronicité

Les annotations suivantes sont utilisées pour déclarer des méthodes asynchrones, par exemple: 

@Asynchronous public void scheduleAlert(Alert alert, @Expiration Date date) { ... }
@Asynchronous public Timer scheduleAlerts(Alert alert, 

   @Expiration Date date, 

   @IntervalDuration long interval) { ... }
@Asynchronous 
@Asynchronous

Spécifie que l'invocation de la methode a lieu de façon asynchrone.

@Duration 
@Duration

Spécifie que l'un des paramètres de l'appel asynchrone est la durée avant laquelle l'appel asynchrone aura lieu (ou en cas de récurrence le temps avant le premier appel)

@Expiration 
@Expiration

Spécifie que l'un des paramètres de l'appel asynchrone est la date à laquelle l'appel asynchrone aura lieu (ou en cas de récurrence le temps avant le premier appel)

@IntervalDuration 
@IntervalDuration

Spécifie que l'appel asynchrone de la méthode est récurrent, et que le paramètre annoté est la durée entre chaque appel.

31.10. Les annotations utilisés avec JSF

Les annotations suivantes permettent de travailler plus facilement avec JSF.

@Converter

Permet à un composant Seam d'agir comme un converter. La classe annoté doit être un composant Seam, et doit implémenter javax.faces.convert.Converter.

@Validator

Permet à un composant Seam d'agir comme un validator. La classe annotée doit être un composant Seam, et doit implémenter javax.faces.validator.Validator.

Les annotations suivantes facilitent l'implémentations de listes cliquables référencées par des bean session stateful Ils apparaissent sur les attributs.

@DataModel 
@DataModel("variableName")

Expose une propriété de type List, Map, Set ou Object[] comme un DataModel JSF dans le scope du composant qui le porte (ou dans le scope EVENTsi le scope du composant porteur est STATELESS). dans le cas d'une Map, chaque ligne du DataModel est une Map.Entry.

@DataModelSelection 
@DataModelSelection

Injecte la valeur du DataModel qui a été selectionnée (c'est a dire l'élément de la collection sous-jacente, ou de la map). Si un seul attribut @DataModel est défini sur le composant, la valeur sélectionnée du DataModel sera injectée. Le nom de chaque @DataModel doit être spécifié pour chaque @DataModelSelection.

Si le scope PAGE est spécifié pour le @DataModel, alors le DataModelSelection sera non seulement injecté mais aussi le DataModel , donc si l'attribut @DataModel annote une méthode getter, alors le composant devra aussi exposer un setter public.

@DataModelSelectionIndex 
@DataModelSelectionIndex

Expose l'index de la ligne selectionnée du DataModel comme un attribut du composant (c'est le numéro de la ligne de la collection sous-jacente, ou la valeur de la clé si le DataModel est une map). Si un seul attribut @DataModel est défini pour ce composant, la valeur selectionnée duDataModel sera injectée. Autrement le nom de chaque @DataModel doit être spécifié pour chaque @DataModelSelectionIndex.

31.11. Les metas-annotations pour le databinding

Ces meta-annotations permettent d'implémenter des fonctionnalités similaires à @DataModel et @DataModelSelection pour des structures de données différentes des listes.

@DataBinderClass 
@DataBinderClass(DataModelBinder.class)

Spécifie qu'une annotation est utilisée pour le databinding.

@DataSelectorClass 
@DataSelectorClass(DataModelSelector.class)

Spécifie qu'une annotation est utilisée pour les dataselection.

31.12. Les annotations pour le packaging

Cette annotation fournit un mécanisme pour déclarer des informations sur un ensemble de composants qui sont packagés ensembles. Elle s'applique à n'importe quel package Java.

@Namespace 
@Namespace(value="http://jboss.com/products/seam/example/seampay")

Spécifie que les composants présents dans le package courants sont associés avec le namespace (espace de nom). Le namespace ainsi déclaré peut-être utilisé directement comme un namespace XML dans un fichier components.xml pour simplifier la configuration de l'application. 

@Namespace(value="http://jboss.com/products/seam/core", prefix="org.jboss.seam.core")

Spécifie l'espace de nommage associé à un package donné. Additionnellement, il spécifie un préfixe à ajouter au nom du composant lors de sa déclaration dans le fichier XML. Par exemple un élément XML noté init qui est associé avec cet espace de nommage serait interprété comme se référant au composant nommé org.jboss.seam.core.init.

31.13. Les annotations pour l'intégration avec le conteneur de Servlets

Ces annotations vous permettent d'intégrer vos composants seam avec le conteneur de servlets

@Filter

Utiliser ce coposant seam (qui devra implémenter javax.servlet.Filter) annoté avec @Filter comme un filter de servlet. Il sera exécuté par le filtre Seam principal.