HOWTO: Using a BC4J Application Module in an Stateless EJB Session Bean

Question

HOWTO: Using a BC4J Application Module in an Stateless EJB Session Bean
by Steve Muench
Overview
BC4J provides automatic facilities for deploying any application module as a stateful EJB session bean. If you want to leverage the features of your BC4J application module from a stateless EJB session bean, it's not automatic but it is straightforward to implement. This howto article explains the details.
For our example, we will create a stateless EJB session bean that uses a container-managed transaction. To keep things simple, let's assume the session bean has a single public method on its remote interface named createDepartment() with the following signature:
public void createDepartment(int id, String name, String loc) throws AppException
AppException is an example of an application-specific exception that our method will throw if any problems arise during its execution.The goal of this article is to illustrate how to use the BC4J application module named com.example.hr.HRApp as part of the implementation of this createDepartment method on our stateless enterprise bean. Let's assume that the HRApp application module has a view object member named Departments, based on the com.example.hr.DeptView view object, based on the familiar DEPT table and related to the com.example.hr.Dept entity object so our view can be updateable.
Creating the Stateless Session Bean
We can start by using the JDeveloper Enterprise Bean wizard to create a new stateless session bean called StatelessSampleEJB implemented by:[list][*]com.example.StatelessSampleEJBBean (Bean class)[*]com.example.StatelessSampleEJBHome (Home interface)[*]com.example.StatelessSampleEJB (Remote interface)[list]
We then use the EJB Class Editor to add the createDepartment method to the remote interface of StatelessSampleEJB with the signature above. We edit the remote interface to make sure that it also reflects that the createDepartment method thows the AppException like this:
package com.example;
import javax.ejb.EJBObject;
import java.rmi.RemoteException;
public interface StatelessSampleEJB extends EJBObject {
  void createDepartment(int id, String name, String loc)
  throws RemoteException,AppException;
}Before we start adding BC4J into the picture for our implementation, our StatelessSampleEJBBean class looks like this:
package com.example;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
public class StatelessSampleEJBBean implements SessionBean {
  public void ejbCreate(){}
  public void ejbActivate(){}
  public void ejbPassivate(){}
  public void ejbRemove(){}
  public void setSessionContext(SessionContext ctx){
  public void createDepartment(int id, String name, String loc) 
  throws AppException {
    // TODO: Implement method here
}We can double-click on the ejb-jar.xml file in our project to see the XML deployment descriptor for the bean we just created:
<ejb-jar>
   <enterprise-beans>
      <session>
         <description>Session Bean ( Stateless )</description>
         <display-name>StatelessSampleEJB</display-name>
         <ejb-name>StatelessSampleEJB</ejb-name>
         <home>com.example.StatelessSampleEJBHome</home>
         <remote>com.example.StatelessSampleEJB</remote>
         <ejb-class>com.example.StatelessSampleEJBBean</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Container</transaction-type>
      </session>
   </enterprise-beans>
</ejb-jar>We need to add the extra <assembly-descriptor> section in this file to indicate that the createDepartment method will require a transaction. After this edit, the ejb-jar.xml file looks like this:
<ejb-jar>
   <enterprise-beans>
      <session>
         <description>Session Bean ( Stateless )</description>
         <display-name>StatelessSampleEJB</display-name>
         <ejb-name>StatelessSampleEJB</ejb-name>
         <home>com.example.StatelessSampleEJBHome</home>
         <remote>com.example.StatelessSampleEJB</remote>
         <ejb-class>com.example.StatelessSampleEJBBean</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Container</transaction-type>
      </session>
   </enterprise-beans>
   <assembly-descriptor>
      <container-transaction>
         <method>
            <ejb-name>StatelessSampleEJB</ejb-name>
            <method-name>createDepartment</method-name>
            <method-params>
               <method-param>int</method-param>
               <method-param>java.lang.String</method-param>
               <method-param>java.lang.String</method-param>
            </method-params>
         </method>
         <trans-attribute>Required</trans-attribute>
      </container-transaction>
   </assembly-descriptor>
</ejb-jar>
Aggregating a BC4J Application Module
With the EJB aspects of our bean setup, we can proceed to implementing the BC4J application module aggregation.
The first thing we do is add private variables to hold the EJB SessionContext and the instance of the aggregated BC4J ApplicationModule, like this:
// Place to hold onto the aggregated appmodule instance
transient private ApplicationModule _am  = null;
// Remember the SessionContext that the EJB container provides us
private           SessionContext    _ctx = null;and we modify the default, empty implementation of the setSessionContext() method to remember the session context like this:
public void setSessionContext(SessionContext ctx){ _ctx = ctx; }We add additional constants that hold the names of the J2EE datasource that we want BC4J to use, as well as the fully-qualified name of the BC4J application module that we'll be aggregating:
// JNDI resource name for the J2EE datasource to use
private static final String DATASOURCE = "jdbc/OracleCoreDS";
// Fully-qualified BC4J application module name to aggregate
private static final String APPMODNAME = "com.example.hr.HRApp";We expand the now-empty ejbCreate() and ejbRemove() methods to create and destory the aggregated instance of the BC4J application module that we'll use for the lifetime of the stateless session bean. When we're done, ejbCreate() it looks like this:
public void ejbCreate() throws CreateException {
  try {
    // Setup a hashtable of environment parameters for JNDI initial context
    Hashtable env = new Hashtable();
    env.put(JboContext.INITIAL_CONTEXT_FACTORY,JboContext.JBO_CONTEXT_FACTORY);
    // NOTE: we want to use the BC4J app module in local mode as a simple Java class!
    env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);
    env.put(PropertyConstants.INTERNAL_CONNECTION_PARAMS,DATASOURCE);
    // Create an initial context, using this hashtable of environment params
    InitialContext ic = new InitialContext(env);
    // Lookup a home interface for the application module
    ApplicationModuleHome home = (ApplicationModuleHome)ic.lookup(APPMODNAME);
    // Using the home, create the instance of the appmodule we'll use
    _am = home.create();
    // Register the BC4J factory to handle EJB container-managed transactions
    registerContainerManagedTransactionHandlerFactory();
  catch(Exception ex) {
     ex.printStackTrace();
    throw new CreateException(ex.getMessage());
}and ejbRemove() looks like this:
public void ejbRemove() {
  try {
    // Cleanup any appmodule resources before getting shutdown
    _am.remove();
  catch(JboException ex) { /* Ignore */ }
}The helper method named reigsterContainerManagedTransactionHandlerFactory() looks like this:
private void registerContainerManagedTransactionHandlerFactory() {
  SessionImpl session = (SessionImpl)_am.getSession();
  session.setTransactionHandlerFactory(
    new TransactionHandlerFactory() {
      public TransactionHandler  createTransactionHandler() {
        return new ContainerManagedTxnHandlerImpl();
      public JTATransactionHandler createJTATransactionHandler() {
        return new ContainerManagedTxnHandlerImpl();
}The last detail is to use the BC4J appmodule to implement the createDepartment() method. It ends up looking like this:
public void createDepartment(int id, String name, String loc)
throws AppException {
  try {
    // Connect the AM to the datasource we want to use for the duration
    // of this single method call.
    _am.getTransaction().connectToDataSource(null,DATASOURCE,false);
    // Use the "Departments" view object member of this AM
    ViewObject departments = _am.findViewObject("Departments");
    // Create a new row in this view object.
    Row newDept = departments.createRow();
    // Populate the attributes from the parameter arguments.
    newDept.setAttribute("Deptno", new Number(id));
    newDept.setAttribute("Dname", name);
    newDept.setAttribute("Loc", loc);
    // Add the new row to the view object's default rowset
    departments.insertRow(newDept);
    // Post all changes in the AM, but we don't commit them. The EJB
    // container managed transaction handles the commit.
    _am.getTransaction().postChanges();
  catch(JboException ex) {
    // To be good EJB Container-Managed Transaction "citizens" we have
    // to mark the transaction as needing a rollback if there are problems
    _ctx.setRollbackOnly();
    throw new AppException("Error creating dept "+ id +"\n"+ex.getMessage());
  finally {
    try {
      // Disconnect the AM from the datasource we're using
      _am.getTransaction().disconnect();
    catch(Exception ex) { /* Ignore */ }
Building a Test Client
With the EJB-Tier work done, we can build a sample client program to test this new stateless EJB Session Bean by selecting the bean in the Oracle9i JDeveloper IDE and choosing "Create Sample Java Client" from the right-mouse menu.
When the "Sample EJB Client Details" dialog appears, we take the defaults of connecting to embedded OC4J container. Clicking the (OK) button generates the following test class:
import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.InitialContext;
import com.example.StatelessSampleEJB;
import com.example.StatelessSampleEJBHome;
public class SampleStatelessSampleEJBClient {
  public static void main(String [] args) {
    SampleStatelessSampleEJBClient sampleStatelessSampleEJBClient =
       new SampleStatelessSampleEJBClient();
    try {
      Hashtable env = new Hashtable();
      env.put(Context.INITIAL_CONTEXT_FACTORY,
              "com.evermind.server.rmi.RMIInitialContextFactory");
      env.put(Context.SECURITY_PRINCIPAL, "admin");
      env.put(Context.SECURITY_CREDENTIALS, "welcome");
      env.put(Context.PROVIDER_URL,
              "ormi://localhost:23891/current-workspace-app");
      Context ctx = new InitialContext(env);
      StatelessSampleEJBHome statelessSampleEJBHome =
           (StatelessSampleEJBHome)ctx.lookup("StatelessSampleEJB");
      StatelessSampleEJB statelessSampleEJB;
      // Use one of the create() methods below to create a new instance
      // statelessSampleEJB = statelessSampleEJBHome.create();
      // Call any of the Remote methods below to access the EJB
      // statelessSampleEJB.createDepartment( int id, java.lang.String name, java.lang.String loc );
    catch(Throwable ex) {
      ex.printStackTrace();
}We uncomment the call to the create() method and add a few calls to the createDepartment() method so that the body of the test program now looks like this:
// Use one of the create() methods below to create a new instance
statelessSampleEJB = statelessSampleEJBHome.create();
// Call any of the Remote methods below to access the EJB
statelessSampleEJB.createDepartment( 13, "Test1","Loc1");
System.out.println("Created department 13");
statelessSampleEJB.createDepartment( 14, "Test2","Loc2");
System.out.println("Created department 14");
try {
  // Try setting a department id that is too large!
  statelessSampleEJB.createDepartment( 23456, "Test3","Loc3");
catch (AppException ax) {
  System.err.println("AppException: "+ax.getMessage());
}Before we can successfully run our SampleStatelessSampleEJBClient we need to first run the EJB bean that the client will try to connect to. Since Oracle9i JDeveloper supports local running and debugging of the EJB-Tier without doing through a full J2EE deployment step, to accomplish this prerequisite step we just need to right-mouse on the StatelessSampleEJB node in the System Navigator and select "Run". This starts up the embedded OC4J instance and runs the EJB right out of the current out path.Finally, we can run the SampleStatelessSampleEJBClient, and see the output of the test program in the JDeveloper log window:
Created department 13
Created department 14
AppException: Error creating dept 23456
JBO-27010: Attribute set with value 23456 for Deptno in Dept has invalid precision/scale
Troubleshooting
One error that might arise while running the example is that the database connection information in your data-sources.xml for the jdbc/OracleCoreDS datasource does not correspond to the database you are trying to test against. If this happens, then double-check the file .\jdev\system\oc4j-config\data-sources.xml under the JDeveloper installation home directory to make sure that the url value provided is what you expect. For example, to work against a local Oracle database running on your current machine, listening on port 1521, with SID of ORCL, you would edit this file to have an entry like this for jdbc/OracleCoreDS :
<data-source
    class="com.evermind.sql.DriverManagerDataSource"
    name="OracleDS"
    location="jdbc/OracleCoreDS"
    xa-location="jdbc/xa/OracleXADS"
    ejb-location="jdbc/OracleDS"
    connection-driver="oracle.jdbc.driver.OracleDriver"
    username="scott"
    password="tiger"
    url="jdbc:oracle:thin:@localhost:1521:ORCL"
    inactivity-timeout="30"
/>This is the data-sources.xml file that gets used by the embedded OC4J instance running in JDeveloper.
Conclusion
Hopefully this article has illustrated that it is straightforward to utilize the full power of BC4J in local mode as part of your EJB Stateless Session Beans using container-managed transaction. This example illustrated a single createDepartment method in the enterprise bean, but by replicating the application module interaction code that we've illustrated in createDepartment, any number of methods in your stateless session bean can use the aggregated application module instance created in the ejbCreate() method.
Code Listing
The full code listing for the SampleStatelessEJB bean implementation class looks like this:
* StatelessSampleEJB
* Illustrates how to use an aggregated BC4J application module
* in local mode as part of the implementation of a stateless
* EJB session bean using container-managed transaction.
* HISTORY
* smuench/dmutreja 14-FEB-2002 Created
package com.example;
import oracle.jbo.*;
import oracle.jbo.server.*;
import javax.ejb.*;
import oracle.jbo.domain.Number;
import oracle.jbo.common.PropertyConstants;
import java.util.Hashtable;
import javax.naming.InitialContext;
import oracle.jbo.server.ejb.ContainerManagedTxnHandlerImpl;
public class StatelessSampleEJBBean implements SessionBean {
  // JNDI resource name for the J2EE datasource to use
  private static final String DATASOURCE = "jdbc/OracleCoreDS";
  // Fully-qualified BC4J application module name to aggregate
  private static final String APPMODNAME = "com.example.hr.HRApp";
  // Place to hold onto the aggregated appmodule instance
  transient private ApplicationModule _am  = null;
  // Remember the SessionContext that the EJB container provides us
  private           SessionContext    _ctx = null;
  public void ejbCreate() throws CreateException {
    try {
      // Setup a hashtable of environment parameters for JNDI initial context
      Hashtable env = new Hashtable();
      env.put(JboContext.INITIAL_CONTEXT_FACTORY,JboContext.JBO_CONTEXT_FACTORY);
      env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);
      env.put(PropertyConstants.INTERNAL_CONNECTION_PARAMS,DATASOURCE);
      // Create an initial context, using this hashtable of environment params
      InitialContext ic = new InitialContext(env);
      // Lookup a home interface for the application module
      ApplicationModuleHome home = (ApplicationModuleHome)ic.lookup(APPMODNAME);
      // Using the home, create the instance of the appmodule we'll use
      _am = home.create();
      // Register the BC4J factory to handle EJB container-managed transactions
      registerContainerManagedTransactionHandlerFactory();
    catch(Exception ex) {
       ex.printStackTrace();
      throw new CreateException(ex.getMessage());
  public void ejbActivate(){}
  public void ejbPassivate(){}
  public void ejbRemove(){}
  public void setSessionContext(SessionContext ctx){ _ctx = ctx; }
  public void createDepartment(int id, String name, String loc)
  throws AppException {
    try {
      // Connect the AM to the datasource we want to use for the duration
      // of this single method call.
      _am.getTransaction().connectToDataSource(null,DATASOURCE,false);
      // Use the "Departments" view object member of this AM
      ViewObject departments = _am.findViewObject("Departments");
      // Create a new row in this view object.
      Row newDept = departments.createRow();
      // Populate the attributes from the parameter arguments.
      newDept.setAttribute("Deptno", new Number(id));
      newDept.setAttribute("Dname", name);
      newDept.setAttribute("Loc", loc);
      // Add the new row to the view object's default rowset
      departments.insertRow(newDept);
      // Post all changes in the AM, but we don't commit them. The EJB
      // container managed transaction handles the commit.
      _am.getTransaction().postChanges();
    catch(JboException ex) {
      // To be good EJB Container-Managed Transaction "citizens" we have
      // to mark the transaction as needing a rollback if there are problems
      _ctx.setRollbackOnly();
      throw new AppException("Error creating dept "+ id +\n"+ex.getMessage());
    finally {
      try {
        // Disconnect the AM from the datasource we're using
        _am.getTransaction().disconnect();
      catch(Exception ex) { /* Ignore */ }
  private void registerContainerManagedTransactionHandlerFactory() {
    SessionImpl session = (SessionImpl)_am.getSession();
    session.setTransactionHandlerFactory(
      new TransactionHandlerFactory() {
        public TransactionHandler createTransactionHandler() {
          return new ContainerManagedTxnHandlerImpl();
        public JTATransactionHandler createJTATransactionHandler() {
          return new ContainerManagedTxnHandlerImpl();

Answer 1

Hi Steve, It4s me again;
About the question I made, I tried with a single assembly-descriptor tag and a single container-transaction tag in the deployment descriptor of the session bean and these were the results.
java.lang.NullPointerException
     void com.evermind.server.rmi.RMIConnection.EXCEPTION_ORIGINATES_FROM_THE_REMOTE_SERVER(java.lang.Throwable)
     java.lang.Object com.evermind.server.rmi.RMIConnection.invokeMethod(com.evermind.server.rmi.RMIContext, long, long, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.rmi.RemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.rmi.RecoverableRemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.ejb.StatelessSessionRemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     void __Proxy1.modificaEnvoltura(java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.String)
     void SamplemdeController.envolturaControlEJBClient.main(java.lang.String[])
Then I tried with multiple assembly-descriptor tags each with a single container-transaction tag and the results were:
java.lang.NullPointerException
     void com.evermind.server.rmi.RMIConnection.EXCEPTION_ORIGINATES_FROM_THE_REMOTE_SERVER(java.lang.Throwable)
     java.lang.Object com.evermind.server.rmi.RMIConnection.invokeMethod(com.evermind.server.rmi.RMIContext, long, long, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.rmi.RemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.rmi.RecoverableRemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.ejb.StatelessSessionRemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     void __Proxy1.modificaEnvoltura(java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.String)
     void SamplemdeController.envolturaControlEJBClient.main(java.lang.String[])
Finally I tried with a single assembly-descriptor and multiple container tags and the results were:
java.lang.NullPointerException
     void com.evermind.server.rmi.RMIConnection.EXCEPTION_ORIGINATES_FROM_THE_REMOTE_SERVER(java.lang.Throwable)
     java.lang.Object com.evermind.server.rmi.RMIConnection.invokeMethod(com.evermind.server.rmi.RMIContext, long, long, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.rmi.RemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.rmi.RecoverableRemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     java.lang.Object com.evermind.server.ejb.StatelessSessionRemoteInvocationHandler.invoke(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])
     void __Proxy1.modificaEnvoltura(java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.Integer, java.lang.String)
     void SamplemdeController.envolturaControlEJBClient.main(java.lang.String[])
How can I make my Stateless Session bean work out?