Orbeon Forms User Guide

EJB Support

1. Classification

Orbeon Forms provides EJB support in two different areas:

  • Calling existing EJBs
  • Encapsulating a processor in an EJB

2. Calling Existing EJBs

Regular EJBs (typically implementing business logic) can be called from a pipeline using the Delegation processor. For instance, this could be used in a Web application to call a credit card validation service available in an EJB session bean to validate a number entered by a user on a Web page. The Delegation processor can not only call EJB session beans, but also Web services and JavaBeans. Please see the Delegation processor documentation for more information about how to call existing EJBs.

3. Processor EJB Encapsulation

3.1. Overview

When code is encapsulated inside an EJB, the EJB container will provide a number of features to the developer almost hassle-free (i.e. with no coding involved), including:

  • Load balancing: the application can be deployed on a cluster of servers and the application server will take care of load balancing.
  • Transaction handling: one can define in a declarative way (XML in the ejb-jar.xml) the transactional behavior of a component. For example, when deciding which set of operations need to be executed in a single transaction. Then, the application server will automatically do whatever is necessary to handle those transactions properly.
  • Code distribution: one can decide at deploy-time to deploy EJB A on a given server and EJB B on another remote server (perhaps because B is intensively accessing a database local to that remote server).

With Processor EJB Encapsulation, Orbeon Forms processors can benefit from the same advantages provided to EJB components by the application server.

3.2. Usage

In the pipeline language, the attribute delegation="ejb" can be added to any <p:processor> element.

<p:config><p:processor name="oxf:sql" delegation="ejb"><p:input name="config">...</p:input><p:input name="data">...</p:input><p:output name="data" id="result-set"/></p:processor><p:processor name="oxf:xslt"><p:input name="config">...</p:input><p:input name="data" ref="result-set">...</p:input><p:output name="data" id="result-set"/></p:processor></p:config>

In the above example we first execute some SQL using the SQL processor and then transform the returned data via the XSLT processor. Since we have a delegation="ejb" attribute:

  1. The pipeline processor will get the home interface stub by looking up java:comp/env/ejb/oxf/proxy from the JNDI tree.
  2. From the home interface stub, the pipeline processor creates the Proxy Service stub and then calls the service.
  3. Wherever it is deployed, the service creates and runs the processor.

The figure below illustrates a scenario where the Proxy Service EJB is deployed on a remote server.

3.3. Deployment Descriptors

To find the Proxy Service EJB, the pipeline processor must be able to lookup the name java:comp/env/ejb/oxf/proxy. Typically for Web applications, this pipeline will be called from the OPSServlet which is deployed in a WAR. In that case, the WAR's web.xml will have to declare an EJB reference:

<ejb-ref><ejb-ref-name>ejb/oxf/proxy</ejb-ref-name><ejb-ref-type>Session</ejb-ref-type><home>org.orbeon.oxf.proxy.ProxyServiceHome</home><remote>org.orbeon.oxf.proxy.ProxyService</remote></ejb-ref>

Depending on the application server, additional configuration will be needed. For instance, on WebLogic, the WAR's weblogic.xml descriptor might look like this:

<weblogic-web-app><reference-descriptor><ejb-reference-description><ejb-ref-name>ejb/oxf/proxy</ejb-ref-name><jndi-name>org/orbeon/oxf/ProxyService</jndi-name></ejb-reference-description></reference-descriptor></weblogic-web-app>