Deploying a Connector | Oracle Application Server 10g: J2EE Deployment and Administration

Once you've configured the Connector with oc4j-ra.xml , you can choose to deploy it as a standalone Connector at the container level, or as an embedded Connector within the application. In either case, an oc4j-connectors.xml file will end up containing a reference to the Connector along with its native library path and security permissions. Typically, this will look something like this:

 <oc4j-connectors>     <connector name="embedded" path="embedded_ra.rar"> <!--         <native-library> path="lib"</native-library> -->         <security-permission>             <security-permission-spec enabled="true">                 grant {permission java.lang.RuntimePermission "LoadLibrary.*"};             </security-permission-spec>         </security-permission>     </connector> </oc4j-connectors>

In this case, we've configured a Connector named "embedded" , which is packaged in the "embedded_ra.rar" file, which contains a lib directory with native libraries ( *.dll, *.so , and so on). We've also granted it permission to load libraries.

Note	The ra.xml descriptor should list all of the security permissions required by a Connector. When manually adding a connector to oc4j-connectors.xml , you must make an entry that specifically grants each permission by setting enabled to true.

The following sections show which oc4j-connectors file and deployment method to use for standalone vs. embedded Connectors.

Deploying Standalone Connectors

During development, you can deploy standalone Connectors simply by adding the appropriate <connector> entry to the existing global oc4j-connectors.xml file. This file is located by default in orahome/j2ee/<instance name>/connectors ; however, the location can be changed in server.xml . The next time the server is started, the Connector should be deployed.

Many times, it's more practical to deploy or undeploy a Connector using deployment tools such as admin.jar . In this case, instead of working with XML, you simply pass in the appropriate values as parameters and let the server update oc4j-connectors.xml .

In the following example, the server will deploy the Connector found in standalone_ra.rar under the name standalone , and it will expect native libraries to be contained in a lib directory inside that RAR, and finally, it will copy and grant all permissions contained in the ra.xml descriptor, as shown here:

 java -jar admin.jar ormi://localhost admin welcome -deployconnector -file standalone_ra.rar -name embedded -nativeLibPath lib grantAllPermissions

Deploying Embedded Connectors

Embedded Connectors are deployed inside an enterprise application, as defined in the J2EE specification. To configure and package an embedded Connector, do the following:

Place the RAR inside the application EAR.
Update the generic application.xml descriptor to reference it.
Place an oc4j-connectors.xml file inside the EAR (see previous examples).
Update the OC4J-specific orion-application.xml descriptor to point to it.

Let's take a look at how to build an EAR archive with an embedded Connector using Ant. You'll start with a directory structure of the project. You'll create a simple web application as well as a Connector, and package the WAR and RAR file into an EAR file.

The source for the Connector is in util/src/java ; the source for the web application is in web/src . You also need to include the META-INF directories for the EAR and RAR archives.

The directory structure of the EAR archive with an embedded Connector should be this:

 /embedded_ra.rar     META-INF/ra.xml     META-INF/oc4j-ra.xml META-INF/application.xml sample.war     WEB-INF

To build an EAR file, you'll create a build script that will compile all source files and package them into appropriate WAR, RAR and EAR files, as shown in Figure 12-3.

Figure 12-3: Directory structure for an EAR application with an embedded Connector

Let's review this directory structure: dist will contain the EAR archive; rar/dist will contain the RAR archive; rar/src/META-INF contains Connector descriptors ( oc4j-ra.xml and ra.xml ); util/src/java contains Java source codes for the Connector; web/src contains source codes for the web application, and finally ear/src/META-INF contains descriptors for the EAR archive. When deploying embedded Connector, you need to modify ear/src/META-INF/ application.xml descriptor to include a reference to the embedded Connector, as follows :

 <?xml version="1.0"?> <!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.// DTD J2EE Application 1.3//EN' 'http://java.sun.com/dtd/application_1_3.dtd'> <application>   <display-name>Chapter 12 sample application</display-name>   <description>Chapter 12 sample application's description</description>   <module>     <web>       <web-uri>sample.war</web-uri>       <context-root>/sample</context-root>     </web>   </module>  <module>   <connector>embedded_ra.rar</connector>   </module>  </application>

Once you have EAR and RAR descriptor files and Java source files, you can create an Ant build script to build the entire application, as shown here:

The build.xml script

 <project name="sample" basedir="." default="dist-ear">     <property name="dir.web.java.src" value="web/src/java"/>     <!-- configure the basic directory properties -->     <property name="dir.web.as-web.src" value="web/src/as-web"/>     <property name="dir.web.httpd-web.src" value="web/src/httpd-web"/>     <property name="dir.web.build" value="web/build"/>     <property name="dir.web.dist" value="web/dist"/>     <property name="dir.ear.src" value="ear/src"/>     <property name="dir.rar.src" value="rar/src"/>     <property name="dir.rar.dist" value="rar/dist"/>     <property name="orahome.j2ee.lib" value="D:\orahome\j2ee\home\lib"/>     <property name="dir.util.java.src" value="util/src/java"/>     <property name="dir.util.build" value="util/build"/>     <property name="dir.util.dist" value="util/dist"/>     <property name="dir.lib" value="lib"/>     <property name="dir.dist" value="dist"/>     <path id="project.classpath">         <fileset dir="${dir.lib}">             <include name="*.jar"/>         </fileset>         <fileset dir="${orahome.j2ee.lib}">             <include name="*.jar"/>         </fileset>     </path>     <!-- Create needed directories -->     <target name="init">         <!-- <mkdir dir="${dir.build}"/> -->         <mkdir dir="${dir.dist}"/>         <mkdir dir="${dir.web.build}"/>         <mkdir dir="${dir.web.dist}"/>         <mkdir dir="${dir.util.build}"/>         <mkdir dir="${dir.util.dist}"/>         <mkdir dir="${dir.rar.dist}"/>     </target>     <!-- Compile the sources -->     <target name="compile-web" depends="init, compile-util">         <javac srcdir="${dir.web.java.src}" destdir="${dir.web.build}" debug="on" debuglevel="lines,vars,source">             <classpath refid="project.classpath"/>             <classpath path="${dir.util.build}"/>             <exclude name="**/Test*.java"/>             <exclude name="**/AllTests.java"/>         </javac>     </target>     <target name="compile-util" depends="init">         <javac srcdir="${dir.util.java.src}" destdir="${dir.util.build}" debug="on"debuglevel="lines,vars,source">             <classpath refid="project.classpath"/>             <exclude name="**/Test*.java"/>             <exclude name="**/AllTests.java"/>         </javac>     </target>     <target name="dist-util" depends="compile-util">         <jar destfile="${dir.util.dist}/embedded_ra.jar">             <fileset dir="${dir.util.build}">                 <include name="**/*.class"/>             </fileset>         </jar>     </target>     <target name="dist-web" depends="compile-web, dist-util">         <delete file="${dir.dist}/sample.war"/>         <war warfile="${dir.web.dist}/sample.war" webxml="${dir.web.as-web.src}/WEB-INF/web.xml" >             <classes dir="${dir.web.build}">                 <include name="**/*.class"/>             </classes>             <lib dir="${dir.lib}" includes="*.jar"/>             <lib dir="${dir.util.dist}" includes="*.jar"/>            <fileset dir="${dir.web.as-web.src}">                <include name="**/*.xml"/>                <include name="**/*.jsp"/>                <include name="**/*.types"/>                <exclude name="**/web.xml"/>             </fileset>             <fileset dir="${dir.web.httpd-web.src}">                 <include name="**/*"/>             </fileset>         </war>     </target>  <target name="dist-rar" depends="init, compile-util">   <jar destfile="${dir.rar.dist}/embedded_ra.rar">   <fileset dir="${dir.rar.src}">   <include name="**/*"/>   </fileset>   <fileset dir="${dir.util.dist}">   <include name="**/*"/>   </fileset>   </jar>   </target>   <target name="dist-ear" depends="dist-web, dist-rar">   <delete file="${dir.dist}/sample.ear"/>   <ear destfile="${dir.dist}/sample.ear"   appxml="${dir.ear.src}/META-INF/application.xml">   <fileset dir="${dir.web.dist}">   <include name="**/*.war"/>   </fileset>   <fileset dir="${dir.rar.dist}">   <include name="**/*.rar"/>   </fileset>   </ear>   </target>  </project>

Let's take a look at what you've achieved. You've compiled Java sources that make up the Connector and a web application. You packaged the compiled class files, together with the appropriate descriptor files, into RAR and WAR archives, and then you packaged these archives into an EAR archive that you can deploy as a standard J2EE application in OC4J.