Task: Create Entity ESB Services
Create Entity ESB Services that are published as Web services for external consumption and may also be consumed as part of an orchestrated business process.
Disciplines: Service Development
Purpose
Entity services are developed to manage persistant entities.
Relationships
RolesPrimary Performer: Additional Performers:
InputsMandatory:
    		Optional:
    • None
    Outputs
      Main Description

      Use the Service Model to identify the service name, task name, and request, response, and fault xsds.

      Entity services imply persistence, and persistence implies Java objects. Since the data is on the message body as XML, we need actions to transform the XML to POJOs. We also need actions to transfrom the POJOs to relational data (we will assume the use of JPA in the following discussion, although alternate persistence mapping architectures would have similar requirements).

      JPA requires a transaction. This requires use of the JCA JMS provider or have the persistence action manage the transaction explicitly.

      The following is an example of an action chain for an entity service:

      SmooksAction (XML2POJO)

      JPA custom action

      SmooksAction (POJO2XML)


      Steps
      Use the Eclipse File -> New JBoss ESB Project.
      Name the project the name of the service.
      E.g. AccountEntityService.
      Use the JBoss ESB editor to edit the jboss-esb.xml file.
      First add the providers to jboss-esb.xml.

      With ESB services deployed as web services there are no gateway providers required, instead only a single JMS provider is required for the ESB Service endpoint (or the specification of InVM scope = global).

      Create JCA provider specifying XAConnectionFactory.

      Use the JBoss ESB Editor to create the service. Name it the same as the project, and name the Category EntityServices (or pick some other category naming convention).
      Create a listener and choose the jms-jca-provider to let the container manage the transaction boundaries (i.e. the entire action chain).
      Use the source tab to add the XSD of the request message, response message, and fault message.

      E.g.,  <actions inXsd="/accountRequest.xsd" outXsd="/accountReply.xsd faultXsd="/accountFault.xsd" >

      Add a SmooksAction to map the XML to POJOs.

      Create a smooks resource configuration file to configure this transformation based on domain model.

      At least two POJOs will be created, a Task object and the Entity object.

      Provide the following properties:class, name, smooksConfig, set-payload-location

      E.g., <action class="org.jboss.soa.esb.smooks.SmooksAction" name="CreateAccountObject">

                <property name="smooksConfig" value="AccountConfig.smooks"/>

      <property name="resultType" value="JAVA"/>

      <property name="set-payload-location" value="accountPayload"/>

      </action>

      Add action to create a JPA EntityManager, join the transaction in progress, determine and execute the appropriate task (create, get, update, or delete), and update the message.

      public JPAAction(ConfigTree config) {

      try {

      _config = config;

      // Because ESB services are not handled by EJB deployer, EJB

      // dependency injection isn't going to work.

      // Need to get transaction and entity manager manually

      String entityManagerJNDIName = config.getAttribute("entityManagerJNDIName");

      InitialContext jndiContext = new InitialContext();

      SessionFactory sFactory = (SessionFactory)jndiContext.lookup(entityManagerJNDIName);

      emfImpl = new EntityManagerFactoryImpl(sFactory, PersistenceUnitTransactionType.JTA, true, null);

      tMgr = (TransactionManager)jndiContext.lookup("java:/TransactionManager");

      }



      public Message process(Message message) throws ActionProcessingException {

      // make a copy of the message

      newMessage = message.copy();

      Map accountPayload = (Map) newMessage.getBody().get("accountPayload");

      Task task = (Task) accountPayload.get("task");

      String taskName = (String) task.getTaskName()

      // create an entityManager and join the transaction

      em = emfImpl.createEntityManager();

      em.joinTransaction();

      if (taskName.startsWith("create"))

         Account account = (Account) accountPayload.get("account");

         em.persist(account);

      }

      ...



      Add JPA action to jboss-esb.xml

      E.g.,

      <action class="org.acme.account.AccountPersistanceAction" name="JPAAction">

            <property name="entityManagerJNDIName" value="persistence.units:unitName=AccountEntity"/>

      </action>



      Add another SmooksAction to transform POJOs back to XML.

      Use FremarkerTemplate

      Test service with an ESB aware client created from examples.

      Help -> Project Examples -> ESB Examples -> JBoss ESB HelloWorld Example – Client


      Test service as Web service using Eclipse Web Serivces explore, SoapUI, or other Web service client.

      Use WSDL in jboss-as/server/default/data/wsdl/...(or copy it into workspace).

      Copy in sample message data to populate message.

      Key Considerations
      Where action names are specified without spaces (e.g., SmooksAction), they are the names of out-of-the-box actions provided in the JBoss SOA Platform. Where the names have spaces (e.g., JPA custom action) they describe an action that must be provided to perform this functionality.
      More Information
      Concepts