Configuration des méthodes de bean de session EJB 3.1 pour les rendre asynchrones

Cette tâche permet de configurer les méthodes de bean de session EJB 3.1 afin qu'elles s'exécutent de manière asynchrone. Vous pouvez rendre les méthodes d'un bean toutes asynchrones ou seulement certaines d'entre elles.

Avant de commencer

Avertissement : Dans les modules EJB 3.1, vous pouvez rendre asynchrones une ou plusieurs méthodes d'un bean de session et renforcer ainsi la capacité de traitement parallèle dans votre application.
  • Si vous n'êtes pas encore familiarisé avec les méthodes asynchrones EJB 3.1, lisez les rubriques Méthodes asynchrones EJB 3.1, Modèle de programmation de client pour les méthodes asynchrones EJB, Modèle de programmation d'implémentation de bean pour les méthodes asynchrones EJB et Gestionnaire de travaux du conteneur EJB pour les méthodes asynchrones. Ces rubriques fournissent une présentation des méthodes asynchrones EJB 3.1, décrivent les modèles de programmation d'implémentation des beans et des clients et parlent du gestionnaire de travaux utilisé par le conteneur EJB pour distribuer les appels de méthodes asynchrones.
  • Développez un nouveau bean de session EJB 3.1 pour votre application, ou modifiez un bean de session existant afin de le rendre conforme aux exigences du modèle de programmation EJB 3.1 en ce qui concerne les méthodes asynchrones. Pour des informations générales, consultez la rubrique sur le développement de beans enterprise.

Pourquoi et quand exécuter cette tâche

Après avoir développé un bean de session, effectuez les étapes suivantes pour rendre asynchrones une ou plusieurs méthodes du bean.

Procédure

  1. Spécifiez les méthodes à rendre asynchrones dans la classe d'implémentation du bean. Pour ce faire, vous pouvez ajouter des annotations @Asynchronous dans le code source de votre bean ou des sections <async-method> dans le descripteur de déploiement du module. Vous pouvez aussi combiner ces deux techniques. L'annotation @Asynchronous ne peut être appliquée qu'à la classe d'implémentation du bean ou à ses superclasses. Elle ne peut pas être appliquée aux classes d'interface. Par ailleurs, si l'annotation est appliquée au niveau de la classe, toutes les méthodes de cette classe sont asynchrones. De même, vous pouvez rendre asynchrones toutes les méthodes d'un bean en spécifiant "*" comme valeur de l'élément <method-name> dans votre descripteur de déploiement.
    Voici des exemples d'application de l'annotation @Asynchronous :
    • Application de l'annotation @Asynchronous à une méthode particulière d'un bean avec une vue sans interface. Dans cet exemple, la méthode m1 est synchrone et la méthode m2 est asynchrone.
      @Stateless @LocalBean
      public class MyLocalBean {
      
         public void m1() {
      
            // method code
         }
      
         @Asynchronous
         public Future<String> m2() {
      
            // method code
      
            return new javax.ejb.AsyncResult("Hello, Async World!");
         }
      }
      Important : L'objet javax.ejb.AsyncResult<V> est une implémentation de commodité de l'interface Future<V>. Pour plus d'informations, reportez-vous à la documentation de l'API.
    • Application de l'annotation @Asynchronous à l'intégralité d'une classe d'implémentation de bean. Dans cet exemple, la méthode m1 et la méthode m2 sont toutes deux asynchrones. Il s'agit d'un bean avec une vue sans interface.
      @Stateless @LocalBean @Asynchronouspublic class MyLocalBean {
      
         public void m1() {
      
            // method code
         }
      
         public Future<String> m2() { 
      
            // method code
      
            return new javax.ejb.AsyncResult("Hello, Async World!");
         }
      
      }
    • Application de l'annotation @Asynchronous à une méthode particulière de la classe d'implémentation d'un bean. Dans cet exemple, la méthode m1 est synchrone et la méthode m2 est asynchrone. Cet exemple nous donne également l'occasion de montrer que les types de retour peuvent différer entre l'interface métier et la classe d'implémentation.
      public interface MyIntf {
      
         public void m1();
      
         public Future<Integer> m2();
      
      }
      @Stateless @Local(MyIntf.class)
      public class MyBean {
      
         public void m1() {
      
            // method code
         }
      
         @Asynchronous
         public Integer m2() {
      
            // method code
      
            return new Integer(3);
         }
      }
    • Application de l'annotation @Asynchronous à l'intégralité d'une classe d'implémentation de bean. Dans cet exemple, la méthode m1 et la méthode m2 sont toutes deux asynchrones.
      @Stateless @Local(MyIntf.class) @Asynchronous
      public class MyBean {
      
         public void m1() {
      
            // method code
         }
      
         public Integer m2() {
      
            // method code
      
            return new Integer(8);
         }
      }
      
    Les exemples suivants montrent comment modifier le descripteur de déploiement du module EJB, ejb-jar.xml :
    • Dans cet exemple, on rend asynchrones toutes les méthodes métier de la classe d'implémentation du bean FullAsyncBean et de ses superclasses en spécifiant un astérisque (*) comme valeur de l'élément method-name.
      <session>
         <display-name>FullAsyncEJB</display-name>
         <ejb-name>FullAsyncBean</ejb-name>
         <business-local>com.ibm.sample.async.ejb.FullAsyncIntf</business-local>
         <ejb-class>com.ibm.sample.async.ejb.FullAsyncBean</ejb-class>
         <session-type>Stateless</session-type>   <async-method>
            <method-name>*</method-name>
         </async-method>          
      </session>
                                     
    • Dans cet exemple, seules les méthodes et signatures spécifiées (toutes les méthodes nommées m1 et la méthode m2 prenant un seul paramètre de type String) sont configurées comme méthodes asynchrones dans la classe d'implémentation du bean PartiallyAsyncBean.
      <session>
         <display-name>PartiallyAsyncEJB</display-name>
         <ejb-name>PartiallyAsyncEJB</ejb-name>
         <business-local>com.ibm.sample.async.ejb.PartiallyAsyncIntf</business-local>
         <ejb-class>com.ibm.sample.async.ejb.PartiallyAsyncBean</ejb-class>
         <session-type>Stateless</session-type>   <async-method>
            <method-name>m1</method-name>
         </async-method> 
         <async-method>
            <method-name>m2</method-name>
            <method-params>
               <method-param>java.lang.String</method-param>
            </method-params>
         </async-method>         
      </session>
                                    
    es exemples suivants montrent comment combiner l'application d'annotations @Asynchronous dans le code source et la modification du descripteur de déploiement du module EJB, ejb-jar.xml :
    • Dans cet exemple, l'annotation @Asynchronous configure la méthode m2 comme méthode asynchrone et le descripteur de déploiement configure la méthode m1 pour la rendre également asynchrone.
      @Stateless @LocalBean
      public class MyLocalBean {
      
         public void m1() {
      
            // method code
         }
      
         @Asynchronous
         public Future<String> m2() {
      
            // method code
      
            return new javax.ejb.AsyncResult("Hello, Async World!");
         }
      }
      
      
      <session>
         <display-name>MyLocalEJB</display-name>
         <ejb-name>MyLocalEJB</ejb-name>
         <local-bean/>
         <ejb-class>com.ibm.sample.async.ejb.MyLocalBean</ejb-class>
         <session-type>Stateless</session-type>   <async-method>
            <method-name>m1</method-name>
         </async-method>          
      </session>
      
      
    • Dans cet exemple, l'annotation @Asynchronous appliquée à la méthode m2 est ignorée car l'en-tête du descripteur de déploiement contient l'indicateur metadata-complete="true". Cet indicateur signifie que le descripteur de déploiement contient l'intégralité des métadonnées de configuration et que ses éléments doivent dont être les seuls à être pris en compte. Le résultat est que seule la méthode m1 de l'implémentation MyLocalBean est configurée pour être asynchrone.
      @Stateless @LocalBean
      public class MyLocalBean {
      
         public void m1() {
      
            // method code
         }
      
         @Asynchronous
         public Future<String> m2() {
      
            // method code
      
            return new javax.ejb.AsyncResult("Hello, Async World!");
         }
      }
      
      
      <ejb-jar id="ejb-jar_ID" ...
      metadata-complete="true" version="3.1">
      ...
      <session>
         <display-name>MyLocalEJB</display-name>
         <ejb-name>MyLocalEJB</ejb-name>
         <local-bean/>
         <ejb-class>com.ibm.sample.async.ejb.MyLocalBean</ejb-class>
         <session-type>Stateless</session-type>   <async-method>
            <method-name>m1</method-name>
         </async-method>          
      </session>
      ...
      </ejb-jar> 
      
  2. Assurez-vous que l'attribut de transaction appliqué à une méthode asynchrone est REQUIRED, REQUIRES_NEW ou NOT_SUPPORTED. Ce sont les seuls types d'attribut de transaction autorisés dans une méthode asynchrone. Pour ce faire, vous pouvez soit appliquer l'annotation @TransactionAttribute aux endroits appropriés du code source du bean, soit ajouter des sections <container-transaction> dans le fichier ejb-jar.xml. Vous pouvez aussi utiliser une combinaison d'annotations dans le code et de sections <container-transaction> dans le descripteur de déploiement.
    L'exemple suivant montre comment définir l'attribut de transaction d'une méthode asynchrone en utilisant des annotations :
    @Singleton @LocalBean
    public class FullAsyncBean {
    	@Asynchronous
    	@TransactionAttribute(REQUIRED) // the default; specified for illustration
    	public void m1() {
    		// ...
    	}
    
    	@Asynchronous
    	@TransactionAttribute(NOT_SUPPORTED)
    	public void m2() {
    		// ...
    	}
    
    	@Asynchronous
    	@TransactionAttribute(REQUIRES_NEW)
    	public void m3() {
    		// ...
    	}
    
    	// ...
    }
    
    L'exemple suivant montre comment définir l'attribut de transaction d'une méthode asynchrone en utilisant le descripteur de déploiement XML :
      <assembly-descriptor>
        <container-transaction>
          <method>
            <ejb-name>FullAsyncBean</ejb-name>
            <method-name>m1</method-name>
          </method>
          <trans-attribute>Required</trans-attribute>
        </container-transaction>
      
        <container-transaction>
          <method>
            <ejb-name>FullAsyncBean</ejb-name>
            <method-name>m2</method-name>
          </method>
          <trans-attribute>NotSupported</trans-attribute>
        </container-transaction>
    
        <container-transaction>
          <method>
            <ejb-name>FullAsyncBean</ejb-name>
            <method-name>m3</method-name>
          </method>
          <trans-attribute>RequiresNew</trans-attribute>
        </container-transaction>
      </assembly-descriptor>
    L'exemple suivant montre comment combiner annotations dans le code et sections du descripteur de déploiement XML pour configurer les attributs de transaction d'un bean. Dans cet exemple, les sections du descripteur de déploiement appliquées à la méthode m3 prévalent sur l'annotation appliquée à l'échelle de la classe. Le résultat est que la méthode m3 est configurée avec l'attribut REQUIRES_NEW, alors que les méthodes m1 et m2 sont configurées avec l'attribut REQUIRED :
    @Singleton @LocalBean
    @Asynchronous
    @TransactionAttribute(REQUIRED) // the default; specified for illustration
    public class FullAsyncBean {
    
    	public void m1() {
    		// ...
    	}
    
    	public void m2() {
    		// ...
    	}
    
    	public void m3() {
    		// ...
    	}
    
    	// ...
    }
    
    
    <assembly-descriptor>
        
       <container-transaction>
          <method>
             <ejb-name>FullAsyncBean</ejb-name>
             <method-name>m3</method-name>
          </method>
          <trans-attribute>RequiresNew</trans-attribute>
       </container-transaction>
    
    </assembly-descriptor>

Que faire ensuite

Continuez à développer des composants supplémentaires pour votre application ou, si vous avez terminé tous les composants requis, assemblez votre application et déployez-la. Consultez la section relative à l'assemblage et au déploiement de modules EJB.

Lors de l'exécution de l'application, si elle échoue à la première tentative d'utilisation d'un bean de session ayant une méthode asynchrone, c'est peut-être qu'il y a une erreur de configuration. Recherchez des messages d'erreur de configuration dans le fichier journal du système.

Analysez les données de trace ou transmettez-les aux personnes appropriées qui sauront les analyser. L'appel et la planification des méthodes asynchrones d'EJB sont suivis dans la trace du conteneur EJB. Pour savoir comment activer cette trace, consultez la rubrique Activation de la trace sur un serveur en cours d'exécution. Pour analyser les données de trace, consultez la section relative à la sortie de trace.


Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=tejb_dvamethods
Nom du fichier : tejb_dvamethods.html