How Do I Deploy BC4J Applications to JBoss?

An Oracle JDeveloper How To Document
April 29, 2002

Content

• Introduction
• Creating a BC4J Project.
• Starting JBoss
• Deploying the BC4J runtime to JBoss.
• Creating a Library in JDeveloper for JBoss.
• BC4J As a Web Module
  • Deploying Your BC4J Application as A Web Module.
• Creating a BC4J JSP Application.
• Deploying the BC4J JSP Application.
• BC4J as an EJB Session Bean
  • Creating an Oracle DataSource in JBoss
  • Creating a BC4J configuration for JBoss
  • Creating a JSP to Access Your Application Module as a EJB.
  • Creating an Application Test Client for Your Application Module
• Testing the BC4J EJB Application Client
• References

Introduction

This TechNote describes in detail the requirements and steps to deploy the BC4J runtime components as well as a BC4J Application as both as Web Module and as Enterprise JavaBeans to JBoss.

This document was written for Oracle9i JDeveloper Release Candidate 2 and JBoss 2.4.4 with Tomcat 4.0.1 (Dated December 29, 2001), although other versions of Oracle9i JDeveloper and/or JBoss should behave the same.

Creating a BC4J Project.

Our BC4J Project will be created on the DEPT table in the SCOTT sample schema which is part of the Oracle database.

On Step 1 of the Business Components Project Wizard, change the SQL Flavor toSQL92 and the Type Map to Java. This is required since we will be using the JBoss emulated XA DataSource implementation when our BC4J Application is deployed as an EJB Session Bean.

Create an Entity Object, with default View Object and default Application Module in the Business Components Wizard. Once created, your project should look similar to the following:

Starting JBoss

On Windows:

Use the setvars.bat script on Windows, located in your JDeveloper\jdev\bin directory to set the JAVA_HOME and PATH environment variables. For help on using the setvars script, just execute setvars.bat and usage examples will be displayed.

Example:

setvars -go

On UNIX:

Set the JAVA_HOME environment variable and add the Java2 SDK�s bin directory to your PATH. 

Example:

            export JAVA_HOME=/usr/java/jdk1.3

            export PATH=${PATH}:${JAVA_HOME}/bin

Then execute the run_with_catalina script (or run_with_tomcat) located in the JBoss/bin directory. ( For example, this might be C:\JBoss-2.4.4_Tomcat-4.0.1\jboss\bin).

After JBoss is started, you will see many lines of information printed to the command shell.

Once started you can ensure that JBoss with Tomcat 4.0.1 is running by ensuring that http://localhost:8080/jboss/index.html works. Here is the display that you should see.

Note: If you are behind a proxy server, you may need to change localhost to the DNS name of your machine.

Deploying the BC4J runtime to JBoss.

To deploy the BC4J runtime to JBoss, the following JAR files need to be copied to the JBOSS_HOME\lib\ext directory (for example C:\JBoss-2.4.4_Tomcat-4.0.1\jboss\lib\ext).

If you will be using BC4J web applications (which we will), the file bc4j.ear must also be deployed. Copy this file from %JDEV_HOME%\bc4j\redist to JBOSS_HOME\deploy (for example C:\JBoss-2.4.4_Tomcat-4.0.1\jboss\deploy).

After these files have been copied to the lib\ext directory for JBoss, JBoss must be restarted.

Creating a Library in JDeveloper for JBoss

Oracle9i JDeveloper needs a library definition which contains all of the client side libraries from JBoss to test an Enterprise JavaBean deployed inside JBoss.  All of these archives are located in the client directory under the JBoss directory. (For example: C:\JBoss-2.4.4_Tomcat-4.0.1\jboss\client).  Create a new Library in JDeveloper, call it �JBoss� and add all of these .jar files to the library. Here is an example of the library definition as created with JDeveloper:

BC4J As a Web Module

The following sections will demonstrate how to deploy your BC4J Application as a Web Module. If you are only going to be deploying your BC4J Application as an EJB Session Bean, then you may skip to the section BC4J as an EJB Session Bean.

Deploying Your BC4J Application as A Web Module.

We will invoke the Business Components for Java Deployment Wizard to deploy our BC4J Application. Here are the steps:

1. In the Navigator, Select the Project Node.
2. Right-click this node, and choose Deploy Business Components...
3. In the wizard, click Next
4. From the Profiles Page of the Wizard, Shuttle Simple Archive Files from the Available to the Selected list.
5. Click Next
6. Check Deploy and click Next
7. Click Finish

After we create a BC4J JSP Application, we will package the middle-tier JAR file with the Web Application (WAR). The default name if this JAR file is Project1CSMT.jar

Creating a BC4J JSP Application.

In order to test our BC4J business components, we will create a JSP application which will use them.

1. Create a New Empty Project
2. Using the Business Components JSP Application wizard, create a default JSP Application for the BC4J objects just created.
3. From the main menu, Choose File > Save All.

Deploying the BC4J JSP Application.

When you create a default BC4J JSP Application, a default deployment profile will be created automatically. The name of this profile is myappwar.deploy.

Here are the steps to deploy our WAR file:

1. In the Navigator, right-click Project1EJB.deploy, and choose Deploy to WAR file.
2. On the Message window, under the Deployment tab, a message will state the location of the newly created EJB .jar file. Copy this file to the JBoss\deploy directory.

Here is an example of the text displayed in the Message Log on the Deployment tab:

Wrote WAR file to C:\jdev\jdev\mywork\Workspace1\Project2\src\myappwar.war
----  Deployment finished.  ----    Mar 14, 2002 5:46:50 PM

You now have a fully functional BC4J JSP Application deployed as a Web Module. You may now invoke the Application with your web browser with the URL http://localhost:8080/<context root>, where <context root> is the J2EE Context Root for your Project containing the BC4J JSP Application ( For example: Workspace1-Project1-context-root/ )

BC4J as an EJB Session Bean

You have successfully completed the exercise of deploying your BC4J Application as a Web Module. The instructions in the following sections will take this BC4J application and redeploy it as a EJB Session Bean.

Creating an Oracle DataSource in JBoss

To create a DataSource for the Oracle JDBC driver, we will edit the jboss.jcml file which is located in the JBoss/conf/<configuration> directory. (For example: C:\JBoss-2.4.4_Tomcat-4.0.1\jboss\conf\catalina). There is one modification, and one addition to make to this file.

1. Replace this entry:
   
   

   <mbean code="org.jboss.jdbc.JdbcProvider" name="DefaultDomain:service=JdbcProvider"> <attribute name="Drivers">org.hsqldb.jdbcDriver</attribute> </mbean>

   With this entry:

   <mbean code="org.jboss.jdbc.JdbcProvider" name="DefaultDomain:service=JdbcProvider"> <attribute name="Drivers">oracle.jdbc.driver.OracleDriver,org.hsqldb.jdbcDriver</attribute> </mbean>

   
   
2. Add the following entry just below the "</mbean>" we just modified: ( change the properties of the URL, JDBCUser, and Password to match your database configuration )
   
   

   <mbean code="org.jboss.jdbc.XADataSourceLoader" name="DefaultDomain:service=XADataSource,name=OracleDS"> <attribute name="PoolName">OracleDS</attribute> <attribute name="DataSourceClass"> org.jboss.pool.jdbc.xa.wrapper.XADataSourceImpl </attribute> <attribute name="URL"> jdbc:oracle:thin:@rcleveng-sun:1521:RCLEVENG </attribute> <attribute name="JDBCUser">scott</attribute> <attribute name="Password">tiger</attribute> <attribute name="MinSize">0</attribute> <attribute name="MaxSize">10</attribute> </mbean>

The first modification will allow the Oracle JDBC driver to be loaded and thus registered with the JDBC DriverManager class.

The second modification will create a JDBC DataSource bound to the JNDI name of "java:/OracleDS".

Creating a BC4J configuration for JBoss

Creating a proper EJB configuration for JBoss allows JDeveloper to do the hard parts automatically with the wizards. We will create a deployment profile for the BC4J Application Module which will create an iAS configuration, then copy it to a configuration for JBoss. Here are the steps:

1. In the Navigator, Select the Project Node.
2. Right click this node, and choose Deploy Business Components...
3. In the wizard, click Next
4. From the Profiles Page of the Wizard, Shuttle EJB Session Beans from the Available to the Selected list.
5. Click Next
6. Shuttle AppModule Session Bean (BMT) from the Available to the Selected list.
7. Click Next.
8. Shuttle your Application Module, which should be named Mypackage1Module from the Available to the Selected list.
9. Click Finish
10. In the Navigator, select your BC4J Application Module.
11. Right click this node and choose Configurations...
12. Select the configuration which ends in "IAS"
13. Choose Copy and then Edit the new configuration
14. Rename your configuration to "JBoss"
15. Rename your DataSource"java:/OracleDS"

Creating a JSP to Access Your Application Module as a EJB.

In order to test our BC4J business components, we will create a new JSP application which will use them.

1. Create a New Empty Project
2. Using the Business Components JSP Application wizard, create a default JSP Application for the BC4J objects just created.
3. On step 2 of 4, be sure to select the JBoss Configuration
4. From the main menu, Choose File > Save All.
5. In the Navigator, right click web.xml and choose Settings...
6. Ensure that there is a EJB Reference to your Application Module from your BC4J project.
7. In the Navigator, select myappwar.deploy.
8. Right click this node and choose Deploy to EAR file. It is imperative that you deploy this to an .EAR file and not a .WAR file, as JBoss will not add the EJB references under the java:comp/env/ JNDI namespace for a .WAR file.
9. Copy this .EAR file to your JBOSS_HOME\deploy (for example C:\JBoss-2.4.4_Tomcat-4.0.1\jboss\deploy).

You can access this EAR with the URL http://localhost:8080/<context root>, where <context root> is the J2EE Context Root for your Project containing the BC4J JSP Application ( For example: Workspace1-Project2-context-root/ )

Creating an Application Test Client for Your Application Module

Apart from the JSP client, a stand-alone Java Application can access your BC4J Application Module which is deployed as an EJB Session Bean.

We will create a new Class to talk to our BC4J Application Module deployed as a Session Bean. This will be a stand alone java application which will lookup our Session Bean and then use an ApplicationModuleProxy class to obtain a reference to our Application Module.

1. From the Main Menu choose New
2. Choose the Objects category, then choose Class, and click OK.
3. In the New Class dialog, click OK, to accept the default settings.
4. Add the following import statements to the newly created java source file:

   import oracle.jbo.*; import javax.naming.*; import java.util.*; import mypackage2.common.ejb.beanmanaged.Mypackage2ModuleHome; import oracle.jbo.client.remote.ejb.ApplicationModuleProxy;

5. Add the following main method to the class:

   public static void main(String[] args) { try { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory"); env.put(Context.PROVIDER_URL, "localhost"); env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming:org.jnp.interfaces" ); Context ctx = new InitialContext(env); Mypackage2ModuleHome beanHome = (Mypackage2ModuleHome )ctx.lookup("mypackage2.Mypackage2Module"); // Create the proxy. If you have exported methods then you can cast it to your common am interface. ApplicationModule am = ApplicationModuleProxy.create(beanHome, env); // // Note: Change this connect string to the connect string you use to connect to your database // am.getTransaction().connectToDataSource( null, "java:/OracleDS", null, null, false ); System.out.println( am.getClass() ); String[] voNames = am.getViewObjectNames(); ViewObject vo = am.findViewObject("DeptView"); Row row; while ( ( row = vo.next() ) != null ) { int numAttrs = row.getAttributeCount(); for ( int i=0; i < numAttrs; i++ ) { System.out.println( "Name= " + vo.getAttributeDef(i).getName() + " Value= " + row.getAttribute(i) ); } System.out.println(""); } am.getTransaction().disconnect(); } catch ( Exception ex ) { ex.printStackTrace(); } }

Testing the BC4J EJB Application Client

1. Edit your project settings, and remove the J2EE and Oracle9i iAS libraries, and add the JBoss library to your project.
2. Run the test client.
3. Verify that the contents of the DEPT database table are displayed in the message log of your application.

Note: You may need to choose View > Message Log from the main menu if the message log is not already visible.

References

• How Do I Deploy Enterprise JavaBeans to JBoss?
• JBoss 3.0 Documentation
• JBoss Web Site