Guide to using EJB Provider for Axis2

The EJB message receiver allows one to access stateless session EJBs (Enterprise JavaBeans) through Web services. The example used in this guide illustrates how to use the EJB provider that ships with Axis2 to access EJBs deployed on a J2EE server such as Geronimo or JBoss.

This example explains how to use Geronimo 1.1 and JBoss 4.0.4.GA as application server.

The following steps will take you through the example through which we will explain how to use an EJB provider in Axis2

1. Creating a Simple Stateless Session EJB

First we need to create a stateless session EJB. Use the following files to make an EJB for testing:

Remote interface (Hello.java)
package my.ejb;
import javax.ejb.EJBObject;

public interface Hello extends EJBObject, HelloBusiness {
}

The following interface defines the business methods available in

1.HelloBusiness.java

package my.ejb;
import java.rmi.RemoteException;

public interface HelloBusiness {
   public String sayHello(String name) throws RemoteException;
}

2, Remote home interface - HelloHome.java

package my.ejb;
import javax.ejb.EJBHome;
import javax.ejb.CreateException;
import java.rmi.RemoteException;

public interface HelloHome extends EJBHome {
   public Hello create() throws CreateException, RemoteException;
}

3. Bean class - HelloBean.java

package my.ejb;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import javax.ejb.EJBException;
import javax.ejb.CreateException;

public class HelloBean implements SessionBean {
   public void setSessionContext(SessionContext sessionContext) throws
      EJBException {}

   public void ejbRemove() throws EJBException {}
   public void ejbActivate() throws EJBException {}
   public void ejbPassivate() throws EJBException {}
   public void ejbCreate() throws CreateException {}

   public String sayHello(String name) {
      return "Hello " + name + ", Have a nice day!";
   }

}

4. Deployment descriptor - ejb-jar.xml

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
        http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"
        version="2.1">

  <enterprise-beans>
     <session>
       <ejb-name>Hello</ejb-name>
       <home>my.ejb.HelloHome</home>
       <remote>my.ejb.Hello</remote>
       <ejb-class>my.ejb.HelloBean</ejb-class>
       <session-type>Stateless</session-type>
       <transaction-type>Bean</transaction-type>
     </session>
  </enterprise-beans>
  <assembly-descriptor>
     <container-transaction>
       <method>
          <ejb-name>Hello</ejb-name>
          <method-name>*</method-name>
       </method>
       <trans-attribute>Required</trans-attribute>
     </container-transaction>
  </assembly-descriptor>
</ejb-jar>

Now we have to write application server specific deployment descriptor(s) for the Hello EJB. The following listing shows an example Geronimo/OpenEJB deployment descriptor (openejb-jar.xml)

<?xml version="1.0" encoding="UTF-8"?>
<openejb-jar 
    xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"
    xmlns:pkgen="http://www.openejb.org/xml/ns/pkgen-2.0">
    <enterprise-beans>
        <session>
            <ejb-name>Hello</ejb-name>
            <jndi-name>my/ejb/HelloBean</jndi-name>
        </session>
    </enterprise-beans>
</openejb-jar>

If you want to test on JBoss, use the following JBoss deployment descriptor (jboss.xml)

<?xml version="1.0"?>
<!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS 4.0//EN"
      "http://www.jboss.org/j2ee/dtd/jboss_4_0.dtd">
<jboss>
    <enterprise-beans>
      <session>
         <ejb-name>Hello</ejb-name>
         <jndi-name>my/ejb/HelloBean</jndi-name>
      </session>
    </enterprise-beans>
</jboss>

Compile the above java classes and bundle the compiled classes and the XML files into a jar file (HelloEJB.jar) as shown below.

 
HelloEJB.jar
  |
  +--META-INF
  |    +--ejb-jar.xml
  |    +--jboss.xml [If you want to deploy on Jboss]
  |    +--openejb-jar.xml  [If you want to deploy on Geronimo/Openejb]
  |
  +--my
       +--ejb
             |
             +--Hello.class
             +--HelloBean.class
             +--HelloBusiness.class
             +--HelloHome.class

Next, deploy the HelloEJB.jar file onto the appropriate J2EE application server.

Creating the Axis2 Service Archive

Now we need to make the services.xml file.

<serviceGroup>
    <service name="HelloBeanService">
        <description>Hello! web service</description>
        <messageReceivers>
            <messageReceiver mep="http://www.w3.org/ns/wsdl/in-only"
                class="org.apache.axis2.rpc.receivers.ejb.EJBInOnlyMessageReceiver"/>
        <messageReceiver mep="http://www.w3.org/ns/wsdl/in-out"
                class="org.apache.axis2.rpc.receivers.ejb.EJBMessageReceiver"/>
        </messageReceivers>
        <parameter name="ServiceClass">my.ejb.HelloBusiness</parameter>
        <parameter name="remoteInterfaceName">my.ejb.Hello</parameter>
        <parameter name="homeInterfaceName">my.ejb.HelloHome</parameter>
        <parameter name="beanJndiName">my/ejb/HelloBean</parameter>
        <parameter name="providerUrl">[URL]</parameter>
        <parameter name="jndiContextClass">[Context Factory Class
             Name]</parameter>
     </service>
</serviceGroup>

In the above services.xml file, replace the [URL] and [Context Factory Class Name] with valid values as follows:

i.e. If the EJB is deployed on Geronimo:

Replace [URL] by 127.0.0.1:4201

Replace [Context Factory Class Name] by org.openejb.client.JNDIContext

For Jboss:

Replace [URL] by jnp://localhost:1099

Replace [Context Factory Class Name] by org.jnp.interfaces.NamingContextFactory

Bundle the HelloBeanService.wsdl, services.xml, remote interface class and home interface class as illustrated below:

 
HelloBeanService.aar
  |
  +--META-INF
  |    +--services.xml
  |
  +--lib
  |    +--[jars used by the ejb client eg.initial context factory classes]
  |
  +--my
       +--ejb
             +--Hello.class
             +--HelloBusiness.class
             +--HelloHome.class

The lib directory of HelloBeanService.aar must contain all the libraries needed to access the EJB. If the EJB is deployed on Geronimo, add the following jar files to the lib directory.

cglib-nodep-2.1_3.jar
geronimo-ejb_2.1_spec-1.0.1.jar
geronimo-j2ee-jacc_1.0_spec-1.0.1.jar
geronimo-kernel-1.1.jar
geronimo-security-1.1.jar
openejb-core-2.1.jar

For JBoss add the following jar files.

jnp-client.jar
jboss-client.jar
jboss-common-client.jar
jboss-remoting.jar
jboss-serialization.jar
jboss-transaction-client.jar
concurrent.jar
jbosssx-client.jar
jboss-j2ee.jar

Deploy HelloBeanService.aar on an Axis2 server.

Now you can access the Hello EJB through Web services. Since our EJB message receivers extend RPC message receivers, org.apache.axis2.rpc.client.RPCServiceClient can be used to invoke the service as illustrated in the following code fragment.

...

RPCServiceClient serviceClient = new RPCServiceClient();
Options options = serviceClient.getOptions();

EndpointReference targetEPR = new
   EndpointReference("http://localhost:8080/axis2/services/HelloBeanService");

options.setTo(targetEPR);
QName hello = new QName("http://ejb.my/xsd", "sayHello");
Object[] helloArgs = new Object[] {"John"};

System.out.println(serviceClient.invokeBlocking(hello,
   helloArgs).getFirstElement().getText());

...