<?xml version="1.0" encoding="iso-8859-1"?>

<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<!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 name="generator" content=
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
<meta http-equiv="content-type" content=
"text/html; charset=us-ascii" />
<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 the 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. The 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>Next, deploy the HelloEJB.jar file onto the 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/ns/wsdl/in-only"
                class="org.apache.axis2.rpc.receivers.ejb.EJBInOnlyMessageReceiver"/&gt;
        &lt;messageReceiver mep="http://www.w3.org/ns/wsdl/in-out"
                class="org.apache.axis2.rpc.receivers.ejb.EJBMessageReceiver"/&gt;
        &lt;/messageReceivers&gt;
        &lt;parameter name="ServiceClass"&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>