WSO2 SOA Enablement Server 6.5.4 supports these J2EE features:

Figure 26. JNDI Over SOAP Illustrated

With WSO2 SOA Enablement Server for Java 6.5.4, you can turn existing communication between a J2EE server and a client into SOAP. In most cases, the only thing a client has to do to access its existing business logic via SOAP with WSO2 SOA Enablement Server for Java 6.5.4 is to change its JNDI properties. You need to install the JNDI connector component to do so.

Deploy the component WASP_HOME/conf/porting/dist/j2ee_jndi_connector.jar on the WSO2 SOA Enablement Server that has the accessible JNDI context you want to expose. If you use the J2eeIntegrate tool and you installed J2EE Support during the installation process, it will be done automatically.

On the client side, you must include the component WASP_HOME/lib/j2ee_jndi_connector_client.jar into the classpath of your J2EE client. Then simply replace the original JNDI context with com.idoox.jndi.InitialContextFactoryImpl (usually done by changing the value of the property java.naming.factory.initial) and set the property java.naming.provider.url according to the following rules :

Configuring the JNDI Connector  ^Locate

You can prohibit the exposure of an object from the JNDI namespace in the configuration of the JNDI connector:

<!-- Copyright WSO2 Inc. All rights reserved. 
     Use is subject to license terms. -->
<!--    ...   -->
<JNDIServiceConfig name="jndi_connector">
    <include>ejb/MyAccount</include>
    <exclude>MyBank</exclude>
    <exclude>ejb/*</include>
</JNDIServiceConfig>
<!--    ...   -->

JNDIServiceConfig may contain property tags holding properties used when WSO2 SOA Enablement Server creates an instance of InitialContext as shown in Example 268. If they are present, they initialize a hash table passed to the constructor of the InitialContext used to lookup objects from the JNDI namespace. If they are not present, the InitialContext is created using a default constructor without any parameter.

Example 268. JNDIServiceConfig With Property Tags

<JNDIServiceConfig name="jndi_connector">
    <property propertyName="java.naming.factory.initial"
              propertyValue="..."/>
    <property propertyName="java.naming.provider.url"
              propertyValue="..."/>
    <include>ejb/MyAccount</include>
    <exclude>MyBank</exclude>
    <exclude>ejb/*</include>
</JNDIServiceConfig>

	Note
	When accessing EJBs using the JNDI connector, WSO2 SOA Enablement Server must have the home and remote interfaces of the EJBs in the classpath. When WSO2 SOA Enablement Server runs as a servlet, this is usually done by adding them to the WEB-INF/classes of the web application containing WSO2 SOA Enablement Server.

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.applicationIntegration.j2eeIntegration;

import demo.advanced.jndiOverSoap.Account;
import demo.advanced.jndiOverSoap.AccountHome;

import javax.naming.InitialContext;

import javax.rmi.PortableRemoteObject;


public class Ejb {
    public static void main(String[] args) throws Exception {
        Object obj = (new InitialContext()).lookup("beanPerson.PersonHome");
        AccountHome accountHome =
            (AccountHome) PortableRemoteObject.narrow(obj, AccountHome.class);
        Account a = accountHome.create();
    }
}

To enable this feature, you must deploy the component WASP_HOME/conf/porting/dist/j2ee_ejb_webservice.jar on the WSO2 SOA Enablement Server that has the accessible JNDI context you want to expose. If you use the J2eeIntegrate tool and you installed J2EE Support during the installation process, it will be done automatically.

There is a deprecated mechanism for implementing EJBs for versions of WSO2 SOA Enablement Server prior to 4.5. This is provided in the Appendix.

In most cases, WSO2 SOA Enablement Server handles Web services implemented by EJB in the same way as it handles other Web services. The deployment of a common Web service usually starts with the creation of a package containing the deployment descriptor of the Web service and its implementing classes.

For Web services implemented by EJB, the only change is that you pass a class name to the WaspPackager tool in the form jndi:JNDI_NAME where JNDI_NAME is the JNDI name of the deployed EJB. When WaspPackager processes a Web service with this class name, it handles it in a special way. It does not create a WSDL and the deployment descriptor does not contain any information about the WSDL in the corresponding service-endpoint element.

The following command creates a package with a Web service, with the JNDI name AccountBean, implemented by EJB:

WaspPackager --package EjbWS --output EjbWS.jar --service-name EJB_webservice --class jndi:AccountBean --uri /ejb-ws/

Although WaspPackager does not create the WSDL, you can pass your own WSDL to the WaspPackager. For a stateful session or entity EJB, this WSDL should reflect the home interface. For a stateless session EJB, it should reflect the remote interface. You can generate it in the standard way using the Java2WSDL tool.

When a package containing a Web service implemented by EJB is deployed and the package does not include a WSDL, a default one is created on the server side. You can customize its creation by setting the target namespace of the WSDL and name of the service in the deployment descriptor:

<?xml version="1.0" encoding="UTF-8"?>
<package name="EjbWS" targetNamespace="http://wso2.com/demos/ejb-ws/"
    version="1.1" 
    xmlns="http://wso2.com/wasp/package/1.0" 
    xmlns:tns="http://wso2.com/demos/ejb-ws/">

    <service-endpoint name="EJB_webservice" path="/ejb-ws/"
        processing="tns:Ejb-ws_Processing" 
        service-instance="tns:Ejb-ws_Instance">
        <wsdl service="wsdls:AccountEjbService" 
            xmlns:wsdls="http://wso2.com/test/"/>
    </service-endpoint>
    <service-instance implementation-class="jndi:AccountBean" 
        name="Ejb-ws_Instance"/>
    <!-- message processing, serialization etc. -->
    <processing name="Ejb-ws_Processing"/>
    <processing name="EJBRemoteWSDLService_processing"/>
</package>

All options and settings related to a Web service can be used for a Web service implemented by EJB.

When an EJBModule is initialized, it creates an InitialContext the same way as one is created when configuring JNDI. However, the initialization of the properties is done from the element called EJBServiceConfig. This element contains the option javaMappingExtension, which if set to true adds custom WSDL extensions to the WSDL, which can describe either remote or local EJB interfaces:

<?xml version="1.0" encoding="UTF-8"?>
<EJBServiceConfig javaMappingExtension="true" name="ejb_webservice" 
   xmlns="http://wso2.com/wasp/package/j2ee_ejb_webservice">
    <property propertyName="java.naming.factory.initial" propertyValue="..."/>
    <property propertyName="java.naming.provider.url" propertyValue="..."/>
</EJBServiceConfig>

On the client side, you access a Web service implemented by EJB in the standard way:

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.applicationIntegration.j2eeIntegration;

import demo.advanced.jndiOverSoap.Account;
import demo.advanced.jndiOverSoap.AccountHome;

import org.systinet.wasp.webservice.LookupException;
import org.systinet.wasp.webservice.Registry;


public class EjbWsExample {
    public static void main(String[] args) throws Exception {
        // Account home is the home interface of the EJB
        AccountHome accountHome = null;

        try {
            // Lookup the web service implemented by EJB
            accountHome =
                (AccountHome) Registry.lookup("http://localhost:7001/ejb-ws/",
                    AccountHome.class);
        } catch (LookupException e) {
            e.printStackTrace();
        }

        // Create a new statefull session bean
        Account account = accountHome.create();

        // Call methods
        account.deposit(new Integer(100));
        System.out.println(account.getBalance());
    }
}

	Note
	When exposing EJBs or deploying Web services implemented by EJBs, WSO2 SOA Enablement Server must have home and remote interfaces of the EJBs in the classpath. When WSO2 SOA Enablement Server runs as a servlet, this us usually done by adding them to the WEB-INF/classes of the web application containing WSO2 SOA Enablement Server.

For SOAP communication between the J2EE client and the WSO2 SOA Enablement Server server, you can apply any security supported by WSO2 SOA Enablement Server, as with any regular Web service. The same is true when you expose an EJB as a web service (please see Web Services Implemented by EJBs). This means you can set up, for example, the HttpDigest security provider on a JNDI service to secure communication with this service (please see Security Guide). (Of course, you must provide credentials on the client side. Please read the section on JNDI Connector to see how to do it).

Consider the communication between client and WSO2 SOA Enablement Server from the security point of view. The WSO2 SOA Enablement Server functions as a bridge between the J2EE application server and clients. The client side is fundamentally a WSO2 SOA Enablement Server Client regardless of the type of integration. If you use JNDI connector, your J2EE client runs over the WSO2 SOA Enablement Server implementation of JNDI context, which transforms calls into SOAP communication with the JNDI connector service. From the perspective of the JNDI connector service, the client is an ordinary Web service client. If you expose your EJB as a Web service, it is simplest to use such an ordinary Web service client to access it.

The drawback of the solution described in the previous paragraphs is that there is no relation between the identity passed from the client to the WSO2 SOA Enablement Server and the identity under which the WSO2 SOA Enablement Server server performs a call in the environment of the application server. The call is always made under the identity of the WSO2 SOA Enablement Server running within the application server, regardless of the identity received in the SOAP call from the client. The rest of the Securing J2EE Integration section discusses propagation of the caller identity to the hosting J2EE environment and related issues.

NamePasswordAN{
   com.idoox.security.jaas.NamePasswordLoginModule required debug=true;
          };

NamePasswordAN{
   com.idoox.security.jaas.WlNamePasswordLoginModule required
   debug=true; com.idoox.security.jaas.NamePasswordLoginModuleNoAuth
   required debug=true;
  };

<example>
    <entries alias="NamePasswordAN" xmi:id="WaspNamePasswordAN">
        <loginModules authenticationStrategy="REQUIRED"
            moduleClassName="com.idoox.security.jaas.NamePasswordLoginModule" 
            xmi:id="NamePasswordAN">
            <options name="debug" value="true" xmi:id="debug_property_7"/>
        </loginModules>
    </entries>
</example>

<example>
  <entries alias="NamePasswordAN" xmi:id="WaspNamePasswordAN">
    <loginModules authenticationStrategy="REQUIRED"
      moduleClassName="com.idoox.security.jaas.NamePasswordLoginModuleNoAuth"
      xmi:id="NamePasswordAN">
      <options name="debug" value="true" xmi:id="debug_property_x"/>
    </loginModules>
    <loginModules authenticationStrategy="REQUIRED"
      moduleClassName="com.idoox.security.jaas.WasNamePasswordLoginModule" 
      xmi:id="NamePasswordAN">
      <options name="debug" value="true" xmi:id="debug_property_x"/>
    </loginModules>
  </entries>
</example>

NamePasswordAN{
          com.idoox.security.jaas.NamePasswordLoginModule required debug=true;
          };

NamePasswordAN{
     com.idoox.security.jaas.WasNamePasswordLoginModule required
     debug=true;
     com.idoox.security.jaas.NameLoginModuleNoAuth required
     debug=true;
    };

JNDI Connector Setup  ^Locate

To secure JNDI connector, you must set the accepting security provider to its appropriate endpoint and pass security properties to the WSO2 SOA Enablement Server JNDI context.

JNDI Connector Service Setup  ^Locate

You can set up the HttpBasic security provider for the JNDI service endpoint (either /internal/jndi-dl/ or /internal/jndi-/) using either WSO2 SOA Enablement Server Administration Console or the ProvidersManager command line tool (a GUI version is available as well):

ProvidersManager -t http//host]:[port]//wasp

ProvidersManager -t http//[host]:[ port]//WSO2 SOA Enablement Server -b /internal/jndi-dl/ -a HttpBasic

JNDI Connector Client Setup  ^Locate

If your J2EE client program uses WSO2 SOA Enablement Server JNDI context implementation, the only thing you need to secure the SOAP communication is to specify two properties:

1. java.naming.security.principal, which will be the username.

2. java.naming.security.credentials, which will be the password.

You can specify the properties either on the command line, with java -Djava.naming.security.principal=asUsername -Djava.naming.security.credentials=asPassword ... or in the code:

Hashtable env = new Hashtable();
        env.put(java.naming.provider.url,
        http://[host]:[port]/WSO2 SOA Enablement Server);
        env.put(java.naming.security.principal,
        asUsername);
        env.put(java.naming.security.credentials,
        asPassword); InitialContext initialContext = new
        InitialContext(env);

	Note
	asUsername and asPassword stand for a real username and password of the identity within the application server. WASP_HOME stands for you WSO2 SOA Enablement Server installation home directory.

Securing the jndiOverSoap Demo  ^Locate

The jndiOverSoap demo shows the use of JNDI Connector. No security mechanisms are used in this demo, by default. To set up HttpBasic authentication against the application server's user database for this demo, follow these steps:

1. Change the source code of the demo's EJB, at WASP_HOME/demo/advanced/j2eeIntegration/src/demo/advanced/jndiOverSoap/BankBean.java so the create method prints the caller principal, as shown in Example 273 :

   Example 273. BankBeanSession Modified to Print Caller Principal

   /*
    * Generated file - Do not edit!
    */
   package demo.advanced.jndiOverSoap;
   
   import java.lang.*;
   
   import java.security.Principal;
   
   import java.util.Vector;
   
   import javax.ejb.CreateException;
   import javax.ejb.EJBException;
   
   import javax.naming.InitialContext;
   import javax.naming.NamingException;
   
   
   /**
    * Session layer for BankBean.
    * This version prints in the method ejbCreate caller principal on 
    * the standard output.
    */
   public class BankBeanSession extends demo.advanced.jndiOverSoap.BankBean
       implements javax.ejb.SessionBean {
       static final long serialVersionUID = 406790000992848677L;
       javax.ejb.SessionContext ctx = null;
   
       public void ejbActivate() {
       }
   
       public void ejbPassivate() {
       }
   
       public void setSessionContext(javax.ejb.SessionContext ctx) {
           this.ctx = ctx;
       }
   
       public void unsetSessionContext() {
       }
   
       public void ejbRemove() {
       }
   
       public void ejbCreate() throws javax.ejb.CreateException {
           if (this.ctx != null) {
               Principal principal = this.ctx.getCallerPrincipal();
   
               if (principal == null) {
                   System.err.println("Principal is null");
               } else {
                   System.err.println("Caller principal name : "
                       + principal.getName());
               }
           }
   
           super.ejbCreate();
       }
   }
   

2. Redeploy WSO2 SOA Enablement Server into the application server using the J2eeIntegrate tool. To do so, run deployWithEJBs.bat j2eeIntegrate from the directory WASP_HOME/demo/advanced/j2eeIntegration.

3. Set up JAAS login modules within the application server you use ( please see JAAS Login Modules.

4. Set up JNDI Connector.

5. Edit the run file (run.bat on Windows or run.sh on Unix). Modify the command that invokes the demo by adding these properties:

   • -Djava.naming.security.credentials=asUsername

   • -Djava.naming.security.principal=asPassword

   • -Djava.security.auth.login.config=WASP_HOME/conf/jaas.config

   We recommend adding these properties after -Djava.naming.factory.initial.

6. Add WASP_HOME/lib/security_providers_client.jar to the demo classpath. To do so, modify the system variable RUN_CLIENT_CLASSPATH by adding WASP_HOME/lib/security_providers_client.jar.

7. Run the client. In the stdout log of the application server you should see the username of the authenticated user.

org.systinet.wasp.webservice.ServiceClient myEJBServiceClient =
    org.systinet.wasp.webservice.ServiceClient.create(
        "http://[host]:[port]/myEJBServiceLocation");

org.idoox.security.Credentials credentials = 
    WaspSecurity.acquireClientCredentials(username, password, "HttpBasic");

WaspSecurity.setCredentials(myEJBServiceClient, credentials);

WaspSecurity.setInitiatingProvider(myEJBServiceClient, "HttpBasic");

JMS (Java Message Service) is part of the J2EE specification. You can send SOAP messages over JMS using WSO2 SOA Enablement Server. For more information see JMS Transport in Message Processing.

To call JTA transactions over SOAP, you must deploy the component WASP_HOME/conf/porting/dist/j2ee_jta.jar on the WSO2 SOA Enablement Server that has the accessible JNDI context you want to expose. If you use the J2eeIntegrate tool and you installed J2EE Support during the installation process, it will be done automatically.

On the client side, you must include the component WASP_HOME/lib/j2ee_jndi_connector_client.jar into the classpath of your J2EE client. Note please, that we use the interface javax.transaction.TransactionManager to handle JTA transactions on the server side. The implementation of this interface is usually accessible in the JNDI namespace.

To set this interface to correspond to your application server, edit the deployment descriptor of the component WASP_HOME/conf/porting/dist/j2ee_jta.jar and replace the string [jndi_name] with the JNDI name of the transaction manager before you deploy it.

Please note that this component is dependent on the JNDI connector on the client side - you must have WASP_HOME/lib/j2ee_jndi_connector_client.jar in the classpath.

Most application servers provide JTA's java.transaction.UserTransaction interface. The J2EE client program may use this interface to demarcate transactions by calling its begin(), commit() or rollback() methods. The client program may obtain a reference to the interface through JNDI lookup. In the WSO2 SOA Enablement Server Server's java.naming.InitialContext implementation, the UserTransaction interface may be obtained through the JNDI name java:comp/UserTransaction.

	Note
	For the sake of backward compatibility, the user transaction can be still obtained using the old JNDI name 'wasp.userTransaction'.

When you call the UserTransaction.begin() method, the following takes place:

All subsequent Web service calls (including JDBC, JMS and EJB over SOAP calls) from the client's thread that called the begin() method are associated with the newly-started transaction.

The new transaction sits in suspended state on the server until an associated Web service method call is made, at which point the following happens:

This process repeats with all subsequent Web service method calls until the commit() or rollback() method is called.

Example 275 shows a piece of code that uses the UserTransaction interface.

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.applicationIntegration.j2eeIntegration;

import demo.advanced.jndiOverSoap.Account;
import demo.advanced.jndiOverSoap.AccountHome;

import javax.naming.InitialContext;

import javax.transaction.UserTransaction;


public class Jta {
    public static void main(String[] args) throws Exception {
        InitialContext context = new InitialContext();
        AccountHome accountHome = (AccountHome) context.lookup("AccountBean");
        UserTransaction userTransaction =
            (UserTransaction) context.lookup("java:comp/UserTransaction");

        // Create new entity bean
        Account account = accountHome.findByPrimaryKey(new Integer(123456));
        account.setName("account_1");

        // Begin transaction
        userTransaction.begin();
        account.deposit(new Integer(25000));

        // Rollback the transaction - no new entity bean is created
        userTransaction.rollback();
    }
}

We provide two demos that show WSO2 SOA Enablement Server's ability to handle user transactions.

The first is the JTA Over SOAP demo. More information about it is in the readme.txt file within the demo directory.

The second is the EJB Under JTA demo. This demo uses Microsoft SOAP Toolkit to access Enterprise JavaBeans under JTA transaction from the Microsoft Excel worksheet.

Supported application servers, and notes about each of them, are described in the Release Notes. For information about porting WSO2 SOA Enablement Server on the application server, please see Porting WSO2 SOA Enablement Server Overview.