<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
      "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  <title>Guide to using EJB Provider for Axis2</title>
  <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/"
  />
</head>

<body xml:lang="en">
<h1>Guide to using EJB Provider for Axis2</h1>

<p>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 EJB provider that ships with axis2 to access EJBs
deployed on a J2EE server such as Geronimo or Jboss.</p>

<p>This example explains how to use Geronimo 1.1 and Jboss 4.0.4.GA as
application server. </p>

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

<h2>1. Creating a Simple Stateless Session EJB</h2>

<p>First, we need to create a stateless session EJB. Use the following files
to make an EJB for testing:</p>
<pre>Remote interface (Hello.java)
package my.ejb;
import javax.ejb.EJBObject;

public interface Hello extends EJBObject, HelloBusiness {
}</pre>

<p>The following interface defines the business methods available in</p>

<p><code>1.</code>HelloBusiness.java</p>
<pre>package my.ejb;
import java.rmi.RemoteException;

public interface HelloBusiness {
public String sayHello(String name) throws RemoteException;
}</pre>

<p>2, Remote home interface - HelloHome.java</p>
<pre>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;
}</pre>

<p>3. Bean class - HelloBean.java</p>
<pre>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!";
    }

}</pre>

<p>4. Deployment descriptor - ejb-jar.xml</p>
<pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;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"&gt;

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

<p>Now we have to write application server specific deployment descriptor(s)
for the Hello EJB. Following listing shows an example Geronimo/OpenEJB
deployment descriptor (openejb-jar.xml)</p>
<pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;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"&gt;
    &lt;enterprise-beans&gt;
        &lt;session&gt;
            &lt;ejb-name&gt;Hello&lt;/ejb-name&gt;
            &lt;jndi-name&gt;my/ejb/HelloBean&lt;/jndi-name&gt;
        &lt;/session&gt;
    &lt;/enterprise-beans&gt;
&lt;/openejb-jar&gt;</pre>

<p>If you want to test on JBoss, use the following JBoss deployment
descriptor (jboss.xml)</p>
<pre>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS 4.0//EN"
      "http://www.jboss.org/j2ee/dtd/jboss_4_0.dtd"&gt;
&lt;jboss&gt;
    &lt;enterprise-beans&gt;
      &lt;session&gt;
         &lt;ejb-name&gt;Hello&lt;/ejb-name&gt;
         &lt;jndi-name&gt;my/ejb/HelloBean&lt;/jndi-name&gt;
      &lt;/session&gt;
    &lt;/enterprise-beans&gt;
&lt;/jboss&gt;</pre>

<p>Compile the above java classes and bundle the compiled classes and the XML
files into a jar file (HelloEJB.jar) as shown below.</p>
<pre> 
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
 </pre>

<p>Deploy HelloEJB.jar on appropriate J2EE application server.</p>

<h2>Creating the Axis2 Service Archive</h2>

<p>Now we need to make the services.xml file.</p>
<pre>&lt;serviceGroup&gt;
    &lt;service name="HelloBeanService"&gt;
        &lt;description&gt;Hello! web service&lt;/description&gt;
        &lt;messageReceivers&gt;
            &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
                class="org.apache.axis2.rpc.receivers.ejb.EJBInOnlyMessageReceiver"/&gt;
        &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
                class="org.apache.axis2.rpc.receivers.ejb.EJBMessageReceiver"/&gt;
        &lt;/messageReceivers&gt;
        &lt;parameter name="ServiceClass" locked="false"&gt;my.ejb.HelloBusiness&lt;/parameter&gt;
        &lt;parameter name="remoteInterfaceName"&gt;my.ejb.Hello&lt;/parameter&gt;
        &lt;parameter name="homeInterfaceName"&gt;my.ejb.HelloHome&lt;/parameter&gt;
        &lt;parameter name="beanJndiName"&gt;my/ejb/HelloBean&lt;/parameter&gt;
        &lt;parameter name="providerUrl"&gt;[URL]&lt;/parameter&gt;
        &lt;parameter name="jndiContextClass"&gt;[Context Factory Class
             Name]&lt;/parameter&gt;
     &lt;/service&gt;
&lt;/serviceGroup&gt;</pre>

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

<p><strong>i.e. If the EJB is deployed on Geronimo:</strong></p>

<p>Replace [URL] by 127.0.0.1:4201</p>

<p>Replace [Context Factory Class Name] by org.openejb.client.JNDIContext</p>

<p><strong>For Jboss:</strong></p>

<p>Replace [URL] by jnp://localhost:1099</p>

<p>Replace [Context Factory Class Name] by
org.jnp.interfaces.NamingContextFactory</p>

<p>Bundle the HelloBeanService.wsdl, services.xml, remote interface class and
home interface class as illustrated below:</p>
<pre> 
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
 </pre>

<p>The lib directory of HelloBeanService.aar must contain all the libraries
needed to access the EJB. If the EJB is deployed on
<strong>Geronimo</strong>, add the following jar files to the lib
directory.</p>
<ul>
  <li>cglib-nodep-2.1_3.jar</li>
  <li>geronimo-ejb_2.1_spec-1.0.1.jar</li>
  <li>geronimo-j2ee-jacc_1.0_spec-1.0.1.jar</li>
  <li>geronimo-kernel-1.1.jar</li>
  <li>geronimo-security-1.1.jar</li>
  <li>openejb-core-2.1.jar</li>
</ul>

<p>For <strong>JBoss</strong> add the following jar files.</p>
<ul>
  <li>jnp-client.jar</li>
  <li>jboss-client.jar</li>
  <li>jboss-common-client.jar</li>
  <li>jboss-remoting.jar</li>
  <li>jboss-serialization.jar</li>
  <li>jboss-transaction-client.jar</li>
  <li>concurrent.jar</li>
  <li>jbosssx-client.jar</li>
  <li>jboss-j2ee.jar</li>
</ul>

<p>Deploy HelloBeanService.aar on an Axis2 server.</p>

<p>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.</p>
<pre>...

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());

...</pre>
</body>
</html>