01 December 2006

Documentation Set For Oracle Application Server

The documentation set for Oracle Application Server 10g ( is available from the Oracle website @ http://download-west.oracle.com/docs/cd/B31017_01/web.htm

For some reason, our documentation is not searchable from Google -- I'd heard this was changing a while ago, but it still doesn't look to have happened.

23 November 2006

Hacking Eclipse WTP OC4J To Add Parent Attribute

A recent posting on the OTN OC4J forum asked whether it was possible to set the parent attribute of an application when it was deployed using the Eclipse WTP OC4J plugin.

The out-of-the-box plugin doesn't do it, but it's possible to add rudimentary support for it by editing a few of the plugins XML files.

You'll find the latest version of the plugin in the following directory: eclipse\plugins\org.eclipse.jst.server.generic.oc4j_1.5.0.v200606130315

What we need is to specify somewhere what the "parent" of the application being deployed is.

One way to do this is to edit oracle.10.1.3.serverdef file and add an additional property field that is shown in the server configuration dialog:
<property id="application.parent"
label="Parent Application:"
default="default" />
This addition results in the new property appearing on the OC4J server definition page:

The "Parent Application" property specified on the server defintion is then passed through to the Ant build file that performs the deployment.

Now by simply editing the oracle.10.1.3.xml file (which contains the deployment targets that are called by the plugin) the appplication.parent property can be appended to the deployment operation:
<target name="deploy.j2ee.ear" depends="check.skip.ear.deploy" unless="skip.deploy">
<antcall target="package.module.ear"/>
Now when a deployment is performed using this OC4J server definition, the parent property of the deployed application will be set to the value specified as shown in this snippet from the oc4j server.xml configuration file.
<application name="otn-parent-deploy-ear"
parent="default" start="true" /
Its not the perfect solution since the parent value is specified at an OC4J server definition level and you can't specify the parent on an application-by-application basis. Which effectively means if you need to have different parent applications, you effecitvely need to create an OC4J server definition for each parent setting you need.

But if for some reason you really need to specify a specific parent value when deploying using the Eclipse WTP OC4J plugin, this is one way to accomodate it.

Test Code for OTN Question


    public void doGet(HttpServletRequest request,
HttpServletResponse response)
ServletException, IOException {


HttpSession session = request.getSession();
Date now = new Date(System.currentTimeMillis());
SimpleBean smb = null;

smb = (SimpleBean)session.getAttribute("when");
if (smb==null) {
smb = new SimpleBean();
session.setAttribute("when", smb);
request.getRequestDispatcher("/index.jsp").forward(request, response);
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
<%@ page contentType="text/html;charset=windows-1252"%>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"/>

Object o = session.getAttribute("when");
if(o !=null) {

When: <%=o%>

<a href="setsessionservlet">Access the Servlet</a>
package oracle.otn.example;

import java.sql.Date;
import java.text.DateFormat;

public class SimpleBean {
private Date when;
private String id;
DateFormat df = DateFormat.getDateTimeInstance(DateFormat.LONG, DateFormat.LONG);

public SimpleBean() {

public String getId() {
return id;

public void setId(String id) {
this.id = id;

public Date getWhen() {
return when;

public void setWhen(Date when) {
this.when = when;

public String toString() {
return id + "::" + df.format(when);
This produces output such as the following on a series of requests:
When: 0abb70c7231c61d925be0b52462a8f04cf9600f3cff7::23 November 2006 12:15:47
When: 0abb70c7231c61d925be0b52462a8f04cf9600f3cff7::23 November 2006 12:15:58
When: 0abb70c7231c61d925be0b52462a8f04cf9600f3cff7::23 November 2006 12:16:07

20 November 2006

OC4J Administrator Password

As of the OC4J 10.1.3 release, there is no longer a "default" or out-of-the-box administrator password.

The password to be used for the administation user (oc4jadmin) is set when OC4J is first started.

If you are using OC4J standalone, you will be prompted for the password the very first time you start the OC4J instance.

If you are using Oracle Application Server, you would have been prompted for the password during the installation process that would have then been set for the OC4J instance.

If you use the "Create Instance" button to create a new OC4J instance within Application Server Control, the password will be inherited from the initial OC4J instance.

The password for the instance is encrypted and stored in the system-jazn-data.xml file.

Changing OC4J Ports in Oracle Application Server

When OC4J is part of an Oracle Application Server environment, it is managed and monitored OPMN. OPMN is a core component of Oracle Application Server and basically provides centralized process management capability.

As such, when OC4J is being managed by OPMN, the ports is uses at runtime are supplied by OPMN when it starts the instance. The port settings in the OC4J configuration files are overidden by the OPMN supplied values.

If OC4J ports need to be changed in an Oracle Application Server enviromment, then they need to be changed at the source -- the opmn.xml file -- and not in the OC4J configuration files.

There are three ways I can think of to change OPMN port entries

1. Use Application Server Control and the new Runtime Ports page that was added in the release.

2. Use the opmnctl command

For example, to switch the default-web-site from using AJP to HTTP protocol, use this command:

>opmnctl config port update ias-component=OC4J process-type=home portid=default-web-site protocol=http

3. Manually edit opmn.xml and specify the port to use.

Now with that example, what needs to be kept in mind here is that for an Oracle Application Server installation, in most cases, the OC4J instance is running in AJP mode and Oracle HTTP Server is sitting in front of it and routing client requests.

If this is the case, and you want change the port to a value of 80, then you need to change the Oracle HTTP Server port since it is the server that is servicing end user requests and then routing them to OC4J. You don't change the OC4J port since it is servicing requests from Oracle HTTP Server.

Then just to make it a little confusing, the Oracle HTTP Server port is configured in $ORACLE_HOME/Apache/Apache/httpd.conf file and not in the opmn.xml file.

14 November 2006

Executing Scripts Using admin_client.jar

The command line utility admin_client.jar is used to perform deployment and other sorts of administrative operations against an OC4J instance.

Typically the operations are called from the command line on a one by one basis.

A little extra feature admin_client has is the ability to execute a script that contains a set of commands to perform.

Besides enabling scripts to be developed that capture a sequence of related (or common) operations, another benefit of this is that admin_client.jar establishes the connection once, and then executes the commands in the script using the same connection.

A script simply contains the list of admin_client commands to execute, in their normal form.

For example, to stop an application, then perform a redeployment, the script would contain:
  -stop  myApp
-redeploy -file d:\temp\myapp.ear -deploymentName myapp -bindAllWebApps

To execute the script, admin_client.jar is invoked as normal with the deployer_uri and the authentication details, but instead of providing a command to execute you specify the -script option and feed it the script to use.
C:\oc4j\j2ee\home>java -jar admin_client.jar
deployer:oc4j:localhost oc4jadmin welcome1 -script script.txt

06/11/15 20:53:00 Notification ==>Stopping manageable object:
06/11/15 20:53:00 Notification ==>Stop completed for state manageable object:
06/11/15 20:53:01 Notification ==>Uploading file myapp.ear ...
06/11/15 20:53:01 Notification ==>Application Deployer for myapp STARTS.

Related documentation.

13 November 2006

Starting and Stopping Applications On OC4J

A handy but little known feature with OC4J 10.1.3 is the ability to selectively start and stop applications that are deployed to an OC4J instance.

In previous releases, it was always possible to start/stop an OC4J instance, but it wasn't possible to start/stop the individual applications that are deployed to an OC4J instance.

The application start/stop operations are exposed in multiple places.

  1. Within Application Server Control

    This is relatively straight forward, so I'll leave it to you to play with.

  2. Within admin_client.jar

    Stop operation:
    >java -jar admin_client.jar
    deployer:oc4j:localhost oc4jadmin [password] -stop myApp

    Notification ==>Stopping manageable object:

    Notification ==>Stop completed for state manageable object:

    The new state of the application is written in the server.xml file:
    <application name="myApp" path="../applications/myApp.ear"
    parent="default" start="false" />

    Start operation:
    >java -jar admin_client.jar
    deployer:oc4j:localhost oc4jadmin [password] -start myApp

    Notification ==>Starting manageable object:

    Notification ==>Start completed for state manageable object:

    <application name="myApp" path="../applications/myApp.ear"
    parent="default" start="true" />

  3. Using the Oracle Ant tasks <oracle:stop> and <oracle:start>

    Stop operation:
    <target name="stopapp">
    <echo message="-----> Stopping application" />
    userid="oc4jadmin" password="welcome1"

    Buildfile: build.xml

    [echo] -----> Stopping application
    [oracle:stop] Stopping application testpermgen.
    [oracle:stop] 06/11/14 15:42:45 Notification ==>
    Stop completed for state manageable object:

    And the same pattern for the start operation.
    <target name="startapp">
    <echo message="-----> Starting application" />
    userid="oc4jadmin" password="welcome1"

    Buildfile: build.xml

    [echo] -----> startping application
    [oracle:start] Starting application myApp.

    [oracle:start] 06/11/14 15:47:48 Notification ==>
    Starting manageable object:

    [oracle:start] 06/11/14 15:47:48 Notification ==>
    Start completed for state manageable object:

    [oracle:start] Application myApp started.
You can now have multiple applications all deployed to an OC4J instance and only start those applications you need at any point in time.

Tip on Deploying to Oracle Application Server Using admin_client.jar

When using admin_client.jar to operate against an Oracle Application Server instance, the deployer_uri takes the form:


which commonly translates into something like


or even


Note that in the last realized form, the opmn-request-port is left off, so the port will default to 6003.

When its operating against Oracle Application Server, admin_client.jar uses the OPMN request port to determine what the exact network location is for the OC4J instance that is specified.

If you find you are running into an error that states "Failed at Could not get DeploymentManager", then its well worth double checking what the actual OPMN request port actually is.

This can be done in three ways I can think of:

1. From the command line using the opmnctl command

C:\oracleas\opmn\bin>opmnctl status -port

2. By looking at the $ORACLE_HOME/opmn/conf/opmn.xml and looking for the value of the defined request attribute in the port tag:

3. And finally, with the release, you can use Application Server Control (ASC) to display the port values of the OPMN service. On the Cluster Topology page, scroll down to the bottom and click the Runtime Ports link. This will display all of the ports currently in use by the server, including the OPMN service.

Once you have the OPMN request port, if it differs from 6003 then ensure that you use the correct value with the deployer_uri so that admin_client can connect to the OPMN service.

For example, given the information above, a valid deployer URL would be:


Which can be validated as accurate:

C:\oracleas\j2ee\home>java -jar admin_client.jar
deployer:oc4j:opmn://localhost:6005/admin oc4jadmin welcome1 -validateURI

URI deployer:oc4j:opmn://localhost:6005/admin is valid and connected

10 November 2006

How to Set Java Options For OC4J

OC4J runs in two different environments -- OC4J standalone and Oracle Application Server -- it's the same OC4J, but how it's started is different.

Setting Java properties for the OC4J instance is therefore done in a slightly different way.

1. An OC4J standalone environment is created by extracting the contents of the oc4j_extended.zip file. This gives you an simple yet complete OC4J environment.

To start OC4J standalone, you call the Java executable yourself and run the oc4j.jar file.

Thus in this sort of environment, you provide the Java properties (-X, -D) on the command line

>java -Xmx256m -Ddebug.log=true -jar oc4j.jar

2. In an Oracle Application Server environment, an OC4J instance is launched (and monitored/stopped) by the OPMN service.

The OPMN service reads a configuration file $ORACLE_HOME/opmn/conf/opmn.xml that defines what processes OPMN needs to start, and also what environment needs to be supplied to the process.

The Java properties for an OC4J instance are defined within its start-parameters/java-options tag in its opmn.xml definition.
<process-type id="admin" module-id="OC4J" status="enabled">
<category id="start-parameters">
<data id="java-options"
value="-Xrs -server -XX:MaxPermSize=128M
-ms512M -mx1024M -XX:AppendRatio=3
<category id="stop-parameters">
<data id="java-options"
value="-Djava.awt.headless=true -Dhttp.webdir.enable=false"/>
<start timeout="600" retry="2"/>
<stop timeout="120"/>
<restart timeout="720" retry="2"/>
<port id="default-web-site" range="12501-12600" protocol="ajp"/>
<port id="rmi" range="12401-12500"/>
<port id="rmis" range="12701-12800"/>
<port id="jms" range="12601-12700"/>
<process-set id="default_group" numprocs="1"/>
To add extra Java options, this opmn.xml file can be modified to set the additional property values required. Don't forget to take a backup first.

Once you change the file, execute the command below to request OPMN to reload the configuration file into memory:

>$ORACLE_HOME/opmn/bin/opmnctl reload

and then start the OC4J instance.

As of the Oracle Application Server 10g R3 ( release, the Java options for an Oc4J instance can be set directly from Application Server Control console.

No need to manually edit the opmn.xml file.

The Start Parameters:Java Options settings can be accessed using the Server Properties page of the OC4J instance you wish to configure.

Deploying a WAR File to OC4J From the Command Line

Building on the previous posting on deploying an EAR file to OC4J from the command line, this posting shows how to deploy a WAR file to an OC4J instance from the command line.

  1. Verify that you have the correct details to connect to the OC4J instance using the validateURI command.

    >java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin -validateURI

    URI deployer:oc4j:localhost is valid and connected

  2. Use the deploy command to deploy the WAR file and bind it with a context-root path to the default web site.

    >java -jar admin_client.jar deployer:oc4j:localhost
    oc4jadmin <password>
    -deploy -file <path-to-war-file>
    -deploymentName <application name>
    -contextRoot </path>

For example:

>java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin <password> -deploy -file d:\temp\testit.war -deploymentName testit -bindAllWebApps -contextRoot "/testit"

06/11/13 11:39:20 Notification ==>Uploading file testit.war ...
06/11/13 11:39:20 Notification ==>Application Deployer for testit STARTS.
06/11/13 11:39:20 Notification ==>Undeploy previous deployment
06/11/13 11:39:21 Notification ==>Initialize C:\oc4j\j2ee\home\applications\testit.ear begins...
06/11/13 11:39:21 Notification ==>Initialize C:\oc4j\j2ee\home\applications\testit.ear ends...
06/11/13 11:39:21 Notification ==>Starting application : testit
06/11/13 11:39:21 Notification ==>Initializing ClassLoader(s)
06/11/13 11:39:21 Notification ==>Initializing EJB container
06/11/13 11:39:21 Notification ==>Loading connector(s)
06/11/13 11:39:21 Notification ==>Starting up resource adapters
06/11/13 11:39:21 Notification ==>Initializing EJB sessions
06/11/13 11:39:21 Notification ==>Committing ClassLoader(s)
06/11/13 11:39:21 Notification ==>Initialize testit begins...
06/11/13 11:39:21 Notification ==>Initialize testit ends...
06/11/13 11:39:21 Notification ==>Started application : testit
06/11/13 11:39:21 Notification ==>Binding web application(s) to site default-web-site begins...
06/11/13 11:39:21 Notification ==>Binding web application(s) to site default-web-site ends...
06/11/13 11:39:21 Notification ==>Application Deployer for testit COMPLETES.
Operation time: 1101 msecs

If you don't specify the -contextRoot switch, the WAR file will be bound to the default web site using the deploymentName that was specified.

Deploying an EAR File to OC4J From the Command Line

This is a posting which covers a very basic, but frequent operation with OC4J -- deploying an EAR file and automatically binding the web modules it contains to the default web site.

To do this, you use the OC4J command line utility admin_client.jar.
  1. Open a shell/command window

  2. Navigate to the $ORACLE_HOME/j2ee/home directory

  3. Make sure you can run the Java executable, either with it in the $PATH or via an absolute reference

    >java -version

    java version "1.5.0_07"
    Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-b03)
    Java HotSpot(TM) Client VM (build 1.5.0_07-b03, mixed mode)

  4. Calculate the Deployer URI you need to use.

    The target OC4J instance is specified using a Deployment URI.

    For an OC4J standalone instance this takes the form:



    It defaults to using a port value 23791 so that can be omitted if the target port is 23791.

    For an Oracle Application Server OC4J instance, this takes form:



    This pattern defaults to using an OPMN request port value of 6003 so that can be omitted if the target port is 6003

    For an Oracle Application Server Cluster Group this takes form:



    Again this pattern defaults to using an OPMN request port value of 6003 so that can be omitted if the target port is 6003

  5. Verify that you have the correct details to connect to the OC4J instance using the validateURI command.

    >java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin -validateURI

    URI deployer:oc4j:localhost is valid and connected

  6. Use the deploy command to deploy the EAR file and bind the web modules it contains to the default web site.

    >java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin -deploy -file -deploymentName -bindAllWebApps

    For example:

    >java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1
    -deploy -file d:\temp\archer.ear -deploymentName archer -bindAllWebApps

    06/11/10 14:54:49 Notification ==>Uploading file archer.ear ...
    06/11/10 14:54:49 Notification ==>Application Deployer for archer STARTS.
    06/11/10 14:54:49 Notification ==>Copy the archive to c:\oc4j\j2ee\home\applications\archer.ear
    06/11/10 14:54:49 Notification ==>Initialize C:\oc4j\j2ee\home\applications\archer.ear begins...
    06/11/10 14:54:49 Notification ==>Unpacking archer.ear
    06/11/10 14:54:49 Notification ==>Done unpacking archer.ear
    06/11/10 14:54:49 Notification ==>Unpacking archer_web.war
    06/11/10 14:54:49 Notification ==>Done unpacking archer_web.war
    06/11/10 14:54:49 Notification ==>Initialize C:\oc4j\j2ee\home\applications\archer.ear ends...
    06/11/10 14:54:49 Notification ==>Starting application : archer
    06/11/10 14:54:49 Notification ==>Initializing ClassLoader(s)
    06/11/10 14:54:49 Notification ==>Initializing EJB container
    06/11/10 14:54:51 Notification ==>Loading connector(s)
    06/11/10 14:54:51 Notification ==>Starting up resource adapters
    06/11/10 14:54:51 Notification ==>Initializing EJB sessions
    06/11/10 14:54:51 Notification ==>Committing ClassLoader(s)
    06/11/10 14:54:51 Notification ==>Initialize archer_web begins...
    06/11/10 14:54:51 Notification ==>Initialize archer_web ends...
    06/11/10 14:54:51 Notification ==>Started application : archer
    06/11/10 14:54:51 Notification ==>Binding web application(s) to site default-web-site begins...
    06/11/10 14:54:51 Notification ==>Binding archer_web web-module for application archer to site default-web-site under context root /archer
    06/11/10 14:54:51 Notification ==>Binding web application(s) to site default-web-site ends...
    06/11/10 14:54:51 Notification ==>Application Deployer for archer COMPLETES.
    Operation time: 1933 msecs

And that is the most basic deployment operation in action.

You can do a lot more with this command, explore all its options using

>java -jar admin_client.jar -usage deploy

08 November 2006

Viewing JSP Stack Traces with OC4J

You may notice a slight change in the behaviour of OC4J with the JSP engine.

In previous releases, when an error occurs in the translation or runtime execution of a JSP page, the container would return the exception, message and a stacktrace to the client. It even included the line in the JSP page where the error occurred.

When developing, this rock'd. What more could you want -- error, stacktrace, offending line in JSP.

In the release, the behaviour has changed so that instead of returning all the gory details to the client, a generic error message is presented. The details are now written into the log file for the application.

When running a production app, this is better -- clients don't need to see that level of detail.

The good news for developers is that the behaviour can be modified so that the error details are again reported to the client by configuring the web module to be in development mode.

This is done using the orion-web.xml of the application by setting the developer attribute of the orion-web-app element to true.

This can be done in several ways.

First off, you can put an orion-web.xml file into the WEB-INF directory of the Web module, and provide this setting in the file.

If you don't want to do that, and deploy the application using Application Server Control (ASC) then you can edit the deployment plan when the application is deployed and configure the development mode . Choose to edit the deployment plan, locate the Web module in question and set developer attribute to true.

If you are using JDeveloper and deploying the application to an external OC4J instance (ie not its embedded server), then you can use the Deployment Plan editor that it invokes to do the exact same thing. It's actually a really sweet capability.

When the deployment plan editor appear, locate for the Web module for which you want to enable development mode, then click in the "development" field and set the value to true.

Continue with the deployment.

This deployment plan setting will be applied to the application when it is deployed to the OC4J instance.

Now when the application is accessed and an error occurs, OC4J will determine that the Web module is running in development mode and return all the gory details to the client.

From the JDeveloper Deployment Plan editor, you can even choose to save the settings after you configure them so they can be loaded next time.

EAR File Packaging Got Better With JDeveloper

I'll admit it. I've been using Eclipse a lot more lately than JDeveloper. The main reason is that I find I struggle with the project and packaging model JDeveloper uses. For example, if I am building an example of using MBeans for an application, I've struggled to get it all packaged up nicely with JDeveloper in the past.

It could well be my fault by being a bit lazy and not really taking the time to understand the way it works. It just seemed easier to use Eclipse and built exactly what I wanted in Ant.

To cut a long story even remotely short, I just downloaded the new JDeveloper distribution to verify a bug someone had pointed me at relating to defining MBeans in the orion-application.xml file.

As I started to use it, I noticed that it had improved quite a bit in the area of packaging EAR files. Certainly in the way I'd wanted to use it in the past.

One very nice thing is that it's now possible to specify in an EAR deployment-profile where a JAR file should be located within the EAR file. This is particularly helpful with the new JEE5 /lib classloading feature we've added.

For example, lets say you are building an application that consists of a Web application and an MBean. Typically you'd build the MBean as one project, and the Web module as another project.

Then assemble them into an EAR file using the EAR file deployment descriptor.

You may choose to create a specific project just to contain the EAR/application level artifacts such as application.xml -- there's a nice JDeveloper feature (that I think is new) here too where the entries in application.xml are automatically provided based on the J2EE modules selected to be in the application using the Application Assembly dialog page.

The example on the left shows an application called "example" that contains three projects: mbean, webapp and application.

The mbean and webapp projects contains the code and resources that relate to their needs. They both contain their own deployment profile to package the project into its required archive form. The application project is used to assemble the application from the separate projects using an EAR deployment profile.

The EAR deployment profile lets the individual projects within the application to be assembled into the EAR file. The nice discovery I found in the release is that the target directory within the EAR file can be specified now for each project.

Why is this exciting. Does Buttso have no life at all?

Well what I liked about it, is that you can use this new facility to make use of the JEE5 library-directory classloading addition. By specifying that the mbeans-library jar file should be placed within a /lib directory in the EAR file, the MBeans classes are automatically made avaialble to the other modules within the EAR file.

In reality to do this, you must also add an explicit J2EE deployment descriptor application.xml file inside of your EAR file instead of relying on the implicit application.xml file JDeveloper inserts into the EAR file.

Add a J2EE deployment descriptor application.xml file to the application project and either set the version to be "5" or if you leave it as a 1.4 version, insert the /lib tags into the file.

It's only a little feature for sure, but its certainly something that makes me more productive in JDeveloper than before. I'm hoping to discover a few other little things like this as I start to use it a little more often now.

07 November 2006

Using EAR Level Libraries with

In the classloading area, we've quietly added a new feature I think is pretty handy.

For a long while now, adding a library at the EAR file level, which is available to all the modules within the application has required the provision of a proprietary deployment descriptor.

To do it, you put the library into the EAR file, then declare it as a library by using an orion-application.xml file.

And in the orion-application.xml you'd have to put:
<library path="commonstuff.jar"/>

OK, it's not so much of a demanding task that its going to throw development schedules way out of kilter, but its just one of the little things you'd like to try and make a bit easier.

Well in we have. The JEE5 specification calls for support for the inclusion of EAR level libraries. So we basically implement that with

Given the example situation above, you can make commonstuff.jar automatically available to all the modules by simply putting it in a root level /lib directory of the EAR file and setting the version in the application.xml file to be "5".

<application version="5">

If you want to use another directory name (instead of lib) then that can be specified using the <library-directory> tag.

<application version="5">

In which case, the container will look for a /libraries directory inside of the EAR file for code sources to make available to the application.

It's not a massive feature change, but a nice little subtle one that helps to simplify the development and deployment cycle by removing the need to provide an orion-application.xml file with an application to share common libraries within the application itself.

Creating New OC4J Instances With

In the recently published OracleAS release, you may notice that we've reintroduced support for a "Create Instance" operation within Application Server Control.

The "Create Instance" operation lets you create a new OC4J instance, give it a name and allocate it to a group. No surprises.

What may suprise you is that by default, the new OC4J instance is configured to run its default-web-site in AJP mode. What this means is that if you have performed the Basic Installation type and don't have Oracle HTTP Server in the mix, you can't access the new instance from a browser.

You can observe this using the command $ORACLE_HOME/opmn/bin/opmnctl status -l which outputs all the current ports in use for an Oracle Application Server home.

Processes in Instance: oow_http_admin.localhost
ias-component | process-type | pid | status |
uid | memused | uptime | ports
OC4JGroup:colors | OC4J:red | 3728 | Alive | 18
7892744 | 68052 | 0:09:09 | jms:12601,ajp:12502,rmis:12702,rmi:12402

But no worries, it's easy to change.

In the release, we also added another new Adminstration Task to ASC to modify the "Server Properties" of an Oc4J instance. Using the "Server Properties" page you can change the protocol and port used by the default-web-site.

So what you want to do is to access the "Server Properties" page of the new OC4J instance and adjust the details of the default-web-suite so that it runs in HTTP mode using a known fixed (and free!) port.

After restarting the instance using OPMN or ASC, the new OC4J instance and applications deployed to it will be able to be accessed directly using a browser.

The "opmnctl status -l" show also now show the port being used as http:5000.

Processes in Instance: oow_http_admin.localhost
ias-component | process-type | pid | status |
uid | memused | uptime | ports
OC4JGroup:colors | OC4J:red | 6052 | Alive | 18
7892746 | 23260 | 0:00:34 | jms:12603,http:5000,rmis:12703,rmi:12403

28 August 2006

OTN Doc Search for Mozilla

Here's a search I use in Mozilla that enables me to do quick and easy searches of the Oracle Application Server 10.1.3 documentation set.

Create a new file in the $MOZILLA_HOME/searchplugins directory, paste in this text, and restart Mozilla.

You'll then see a new "OTN 10.1.3 Doc Search" box added to your search engines.

Type in a keyword press enter.


Go on, search yourself silly.

OTN Doc Search
name="OTN 10.1.3 Doc Search"
description="OTN 10.1.3 Doc"
method="GET" >

<input name="word" user>
<input name="remark" value="">
<input name="book" value="">
<input name="preference" value="">
<input name="method" value="TEXT">

resultListStart="<!-- RESULT LIST START -->"
resultListEnd="<!-- RESULT LIST END -->"
resultItemStart="<!-- RESULT ITEM START -->"
resultItemEnd="<!-- RESULT ITEM END -->"

25 August 2006

Accessing Environment Variables from Oracle Application Server

Question of the day:

"We access and use standard environment variables in our Java code. It works with other vendors products, but when we deploy it to OC4J running within Oracle Application Server, the code no longer works. How can we use environment variables?"


In the Oracle Application Server architecture, the OC4J process is started by the OPMN process. The model that is employed results in no environment variables that are set when OPMN is launched being passed to the processes that OPMN starts.

If you want to set specific environment variables for OPMN managed processes to use, then you must do it by setting the environment variable name and value in the opmn.xml file. OPMN will then pass the environment variable to the process(es) it starts.
  <ias-instanceid="ias-instance-id" ... ">
<variableid="id" value="value" append="boolean"/>
<ias-component id="ias-component-id">>
</ias-component id="ias-component-id">>
It's worth noting that the <environment> tag can be used in multiple places within the opmn.xml file to allow the correct scope (or additive effect) to be defined.

Once the environment variable has been set, it can be accessed from within an applictation running within an OPMN managed OC4J instance using the standard Java API: System.getenv("envvar");

01 August 2006

My Ant Discovery for the Day

I love it when I discover or learn something new. Or discover something I should probably already know.

I wanted to make an Ant build file conditional on the O/S on which is was executing - so a target copies either the .bat or .sh scripts into a runtime directory.

I started out thinking of using the inbuilt property ${os.name} -- which returns the O/S name. But with Windows having more flavours than Ben and Jerry, I was finding it hard just to deal with all the Windows flavours in their own right. In a neat manner anyway.

So Google with various keywords related to what I wanted to do returned this Gem of a task which has been added to Ant in recent times -- <os family="windows" /> -- when combined with a condition, it can be used to set a property if the O/S is any flavour of Windows. And then that can be used with the <target> conditional attributes.

Exactly what I wanted!

<!-- Set IsWindows property IF the OS is from the Windows family -->
<condition property="IsWindows" value="true">
<os family="windows" />

And then use this in the O/S specific targets

<target name="copy-windows-scripts"if="IsWindows">
<echo message="Copying Windows scripts"/>

<target name="copy-linux-unix-scripts" unless="IsWindows">
<echo message="Copying Linux/Unix Scripts"/>

And then use these in the main task and they will be conditionally executed.

<!-- Either the .bat or .sh scripts will be copied based on the os family -->
<antcall target="copy-windows-scripts"/>
<antcall target="copy-linux-unix-scripts"/>

28 July 2006

Adding Oracle Ant Tasks to Eclipse

Whoa, a month since I last wrote anything. I'm not sure if that concerns me more from the point of view that I've not done anything interesting in a month which I thought was worth sharing, or that a month has flashed by so quickly.

Eclipse -> Ant -> OC4J

Mucking around with Eclipse lately, I wanted to use the <oracle:> Ant tasks from the IDE.

OC4J comes with its own standard Ant distribution which has the <oracle:> Ant tasks already seeded within it. One option therefore was to swap the distribution of Ant being used by Eclipse with the one in the OC4J distribution.

But that seemed a little severe -- how about we add the <oracle:> tasks to Eclipse instead.

After a bit of trial and a bit more of error, I have it working.

In the end, the steps required to make it work are quite simple, with one major consideration: it's necessary to have an OC4J environment local to the Eclipse IDE.

The <oracle:> Ant tasks are packaged to run within the context of OC4J. The Manifest.mf file of the JAR files contain Class-Path entries which define the other required libraries. So take it as a given, that as a minimum you need an OC4J environment on the client. This can be from the oc4j_extended.zip or from the result of performing an Oracle Application Server installation.

The two JAR files of interest from OC4J that we need to add to Eclipse are:

  1. ant/ant-oracle.jar
  2. j2ee/utilities/ant-oracle-classes.jar

Now when I say add, I mean configure the Eclipse Ant class-path to be aware of these JAR files in their original locations -- not copying them into the Ant directories within Eclipse. The JAR files have relative Class-Path links in their Manifest.mf files, so copying them around into different directories will break them.

Once you have a Project, open the Windows -> Prefences dialog from the Menubar.

Select the Ant > Runtime node in the tree

Select the Classpath tab and the "Global Entries" node.

Click the "Add External JARS" button and add the two JAR files from the OC4J distribution.

That's it!

You can now define and use the <oracle*> Ant tasks within the Eclipse environment.

Here is an n example of using the <oracle:deploy> task to deploy an archive to an local OC4J instance.
<target name="deploy" depends="compile" description="--> description">
<oracle:deploy debug="true"
deploymentname="testit" contextroot="/testit"
Executing this target from the Eclipse Ant runner results in the application being deployed to the specified OC4J instance.

Eclipse Content Assistance

Once the <oracle> Ant tasks have been added, Eclipse can help you included them within build your Ant build files using its Content Assistance capability.

To see the list of <oracle> Ant tasks, simply type:

<ora> and press ctrl+space.

Eclipse will then display a list of all the <oracle:> tasks, which can be inserted into the build file by selecting the desired task.

Once the task has been inserted, the attributes for the task can be viewed using the same content assistance mechanism.

Note: I found that the Content Assistance would not show the <oracle:> tags until I added one manually. This seems to force Eclipse to load the JAR file and become aware of the rest of the tasks. This could just be my experience, but if the <oracle:> are not showing up in the IDE as described, try manually seeding it with the example I showed above.

29 June 2006

Client setup for connecting to OC4J using JSR160

When connecting from remote JMX clients to OC4J using JSR160, there's a couple of things to keep in mind.

  1. For OC4J, the Service URL specifies the use of the RMI protocol


  2. For OracleAS, the Service URL additionally specifies the use of the OPMN mechanism to obtain the ORMI port of the specified OC4J instance


  3. The client needs to be told where to locate the RMI implementation.

    For programatic clients, this is done using the environment passed to the JMXConnectorFactory

    Hashtable env= new Hashtable();


    Hashtable credentials= new Hashtable();


    env.put(JMXConnector.CREDENTIALS, credentials);

    jmxCon = JMXConnectorFactory.newJMXConnector(serviceUrl, env);

    For pre-built clients, this is done using a System property:


  4. The client classpath needs to include the $ORACLE_HOME/j2ee/home/admin_client.jar library. This library contains references to all the libraries needed to establish remote JMX connections in its Manifest.mf Class-Path entry. It's a nice one-stop shop.
This combination of things usually solves most of the problems I get asked about in this area.

The OC4J J2EE Developer's Guide has a good section on remote connections.

23 June 2006

Go the Socceroos

Could it be bandwagon jumping? Never! Well maybe but I'll watch Australia play just about anything.

But what an effort by the Australian team at the World Cup! I was leaping off my couch this morning watching their effort against Croatia -- go you Socceroos!

While I'm on the Soccer theme -- ever wondered what your Brazilian soccer name would be?


DataSource lookup using java:comp/env

Helped someone out this week where the claim was OC4J doesn't support the same standards they are used to developing with on Tomcat.

The reported problem was that the developer was trying to lookup a DataSource using the standard ENC approach -- java:comp/env/jdbc/DataSource from within a Servlet.

"It doesn't work with OC4J, I must change all my code to lookup the datasource using its actual name!"

OK, lets take a look at it -- that's not quite true.

Yes, we do enable a direct datasource lookup to be done using just the jndiLocation value of the DataSource in need. For example, if there is an actual physical datasource defined on the J2EE container with a location of "jdbc/OracleDS" then it can be looked up using the actual name:
  DataSource ds = (DataSource)ic.lookup("jdbc/OracleDS");

But this is a convenience mechanism only. It's not something I'd recommend or use other than for something quick and dirty. It hardcodes the application code so that it requires a physical datasource to be defined on the J2EE container.

If I was developing I'd opt for the standard, portable approach so that the application makes no assumptions about its target environments.

Which basically means using the ENC (Environment Naming Context) model which is implemented by J2EE servers to abstract application resources away from their physical manifestations. I've always wanted to use that word somewhere ...

To use the ENC model you need to do two things.

1. Do the Logical

In the application, you define a logical representation of the resources you need to use. This is done using resource-ref definitions in the standard J2EE deployment descriptor files. Whenever you need to get hold of the resource, you look it up from the JNDI ENC and use it.

This means the application is free from using anything specific to a physical environment in the code. So it becomes portable.

Here's an example. Lets say I have a Servlet which needs to connect to a database and execute a query. I want the Servlet to be portable so it can be deployed anywhere.

What I do is to first define a resource-ref element in the web.xml file which identifes the logical datasource name to be used:

This says to the J2EE container when the app is deployed that a DataSource should be mapped to the jndiLocation "bing/Bang".

To get hold of this DataSource in the Servlet code, it is looked up like this:
  InitialContext ic = new InitialContext();
DataSource bingBang = (DataSource)ic.lookup("java:comp/env/bing/Bang");
Connection con = bingBang.getConnection();

OK -- all standards stuff. Note the use of the java:comp/env prefix here when looking up the resource. This is needed because resource-ref declarations are bound by the J2EE container into the ENC and this java:comp/env is the way to reach into the ENC.

But how does this logical "bing/Bang" actually get married up to a database to connect to?

2. Do the Physical

A physical datasource is configured at the J2EE container with details such as which database to connect to, the username password combination and any other special properties. It is given a unique name so it can be identified and used -- for example "jdbc/MyXEDatabase"

Once the application has been packaged, its time for deployment. And its at deployment time that the person doing the deployment makes the decision on how to map the logical resource-ref entries to their physical counterparts on the server.

What this means in this specific case during the deployment process, the deployment manager will extract the list of logical references it finds in the standard deployment descriptors (DataSource - bing/Bang) and allow you to specify which of the physical datasources it should be be mapped to -- in this case "jdbc/MyXEDatabase".

This gets automatically generated into a deployment descriptor which is read by OC4J:
<resource-ref-mapping location="bing/Bang" name="jdbc/MyXEDatabase"/>

So that when an application looks up bing/Bang it really gets given jdbc/MyXEDatabase

And there you have it.

14 June 2006

Adding a Mozilla Search Engine

Gee, I'm a bit of a lazy bugger.

We have an internal application we use to enter/view/manage bugs. Not that we have any bugs of course. A bug is identified by a bug number, which can be supplied to our bugdb application and the relevant bug text displayed. Of course you can perform many more complex and combined forms of queries but the simple 'can you check this bug please' usually results in the simple bug number type of query.

It struck me that it'd be cool to somehow add our bugdb application as a search engine for Mozilla. So I could just enter the bug number in the search field and press enter, without needing to go to the actual bug application first.

Yes, I know. I must be really, really lazy.

I thought it'd be hard. I thought wrong. Those Mozilla people, what enablers!

If you look in the $MOZILLA_HOME/searchplugins directory, you'll probably see a bunch of files. The files ending with .src define a search plugin.

Looking at one of the .src examples, you can pretty easily see how it works.

For my bugdb search I really just needed to specify the URL of the bugdb application and specify the name of the query parameter it uses.

name="Oracle Bug DB"
description="Oracle Bug DB"

<input name="c_rptno" user>


You then save this as a .src file into the searchplugins directory, restart Mozilla and bango! you have a new search option.

How easy can it be!

I then hunted around and found some doc off the Mozilla website which actually explains how it all works. Good job Mozilla folks.

Even better, it shows how you can remotely install these things using a bit of JavaScript, which will add the .src file and an accompanying icon (16x16) to a client browser.

See http://mycroft.mozdev.org/deepdocs/installing.html#server which has a working example of the JavaScript calls:
"http://localhost.localdomain/plugins directory/"+name+".src",
"http://localhost.localdomain/plugins directory/"+name+"."+ext,
cat );

Now of course this is for our internal application, so it won't for you folks out there. But if you ever wanted to add a new option to the Mozilla search engine list, then try it out. No code required!

07 June 2006

Parsing XSDs

When things are little quiet on the blog front usually means its hot on the work front. I don't want to say the inverse is true since that could say something about my daily acitivities.

So this is just a short and sweet post today.

I've been tackling a task this week which required me to provide some details about the OC4J configuration parameters. To make it easy, I thought I'd derive the data I wanted directly from the OC4J schema files -- after all they pretty much define what our config files can contain.

Besides the drudgery of writing the parsing routines by hand, the biggest thing I discovered was that in order to parse an XSD file you have to set the namespaceAware property to true.

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder parser = factory.newDocumentBuilder();
Document document = parser.parse(fis);

Until I did that, the document returned was basically null.

As I was working on this short term task -- my mind kept thinking back to what would the good practices for working with XSD files themselves? Could/should I have spent a little more time checking into using Castor/JAXB/commons-digester/etc. instead of crufting something manually? Would that have been worth the effort?

I ended up doing what I knew would work to get the job done, but it's code I'll never let off my laptop, I promise.

01 June 2006

More info on remote jconsole connections

[update] the bug has now been fixed in our code line so this will work out of the box in the coming release.

It turns out that jconsole (which I never found the src to!) supplies the jmx credentials as a String array, such as:

String s5 = userNameUrl.getText().trim();
String s7 = passwordUrl.getText();
String as[] = { s5, s7 };
connectionparameters.map.put("jmx.remote.credentials", as);

whereas we were expecting the credentials to be in a Map.

I don't like to leave things hanging ... so I made some changes to the effected classes in an isolated view just to see if I could get it to work -- fear not, Product Managers don't touch production code!

With the changes in place, I was then able to get jconsole to connect remotely to both a OC4J standalone and an Oracle Application Server instance using their respective URL forms:
  • service:jmx:rmi://[oc4j-host]:[oc4j-port]
  • service:jmx:rmi:///opmn://[opmn-host]:[opmn-port]/[oc4j-name]
I've logged a bug and try and work this fix into the release.

I also found once I'd connected that I needed a couple of extra libraries on the client side to make jconsole work fully -- javax77.jar to get the Stats classes and dms.jar.

Here's the set of Oracle libraries required:
  • ${ORACLE_HOME}/j2ee/home/oc4jclient.jar
  • ${ORACLE_HOME}/j2ee/home/lib/adminclient.jar
  • ${ORACLE_HOME}/j2ee/home/lib/javax77.jar
  • ${ORACLE_HOME}/dms/lib/dms.jar

31 May 2006

Establishing remote connections to OC4J with jconsole

I'm struggling with this task at the moment.

What I'm trying to do is to use the jconsole utility provided in JDK5 and establish a remote connection to an OC4J instance.

It works a treat when connecting using its local model -- just start OC4J with the following command:

java -Dcom.sun.management.jmxremote=true -jar oc4j.jar The JVM process running oc4j.jar will appear in the local connection tab and can be connected to.

However the remote connection model is presenting more of a challenge at the moment. Using the advanced tab, you can specify the direct JMX Service URL to connect the remote OC4J instance.

Now since OC4J uses its ORMI protocol for remote JMX connections, jconsole needs to be configured with the appropriate libraries and property settintgs to allow it to work over ORMI.

After a bit of trial and error, I captured what I think is the required command to launch jconsole and allow it to work as a remote OC4J client. The OC4J specific settings



Using the advanced connection tab, you can specify the direct JMX Service URL to identify the target server.

To connect remotely to an OC4J process the URL is of the form


So all systems go .... except pressing the connect button results in an exception being thrown on the command line and the connection failing.

Exception in thread "JConsole.addUrl" java.lang.ClassCastException:[Ljava.lang.String;
at oracle.oc4j.admin.jmx.remote.rmi.RMIJMXConnectorImpl.getDomain(RMIJMXConnectorImpl.java:83)
at oracle.oc4j.admin.jmx.remote.JMXConnectorImpl.connect(JMXConnectorImpl.java:363)
at javax.management.remote.JMXConnectorFactory.connect(JMXConnectorFactory.java:248)
at sun.tools.jconsole.ProxyClient.(ProxyClient.java:117)
at sun.tools.jconsole.ProxyClient.getProxyClient(ProxyClient.java:87)
at sun.tools.jconsole.JConsole$2.run(JConsole.java:410)

Which at least when looking at the sunny side, shows that the client side configuration being used here must be close to the mark as OC4J client is being used and the exceptions are coming from OC4J JMX classes.

On the bummer side, it doesn't work!

I wanted to then see what is being passed into our RMIJMXConnector from jconsole and compare it with what we're expecting.

I hunted around for the source code for the JDK5/jconsole but couldn't seem to find it anywhere. Has anyone seen the source for jconsole?

The Mustang (JDK6) source snapshot release looks to include it, but I'm not using Mustang here.

Anyway, I'll keep digging and see how this can be made to work.

30 May 2006

Multicast Checker

I still get email comments from time-to-time on this utility to verify the availability of multicast on a network.

So I thought I'd post the link on this blog as well.

The OC4J admin_client distribution

With the OC4J 10.1.3 release, we now provide a separate client side administration distribution:


The distribution is approximately 5.5MB in side and contains the admin_client.jar utility and all the necessary libraries to perform command line administration of a remote OC4J instance.

Using this distribution, the admin_client.jar utility can connect to a remote OC4J 10.1.3 or Oracle Application Server 10.1.3 instance and execute any of its management commands.

As a simple example of using this distribution, I can use it to view the list of shared-libraries installed in the OC4J Home instance in an Oracle Application Server 10.1.3 server running at HQ in Redwood shores from my desktop PC here in Australia.
>mkdir oc4j_admin_client
>cd oc4J_admin_client
>jar xf d:\downloads\oc4j_admin_client_101300.zip
>cd j2ee
>cd home
>java -jar admin_client.jar deployer:oc4j:opmn://stadp57.us.oracle.com/home
oc4jadmin welcome1 -listSharedLibraries

Found 23 shared libraries:

Modifiable libraries:
global.libraries version 1.0
global.tag.libraries version 1.0
oracle.persistence version 1.0
oracle.expression-evaluator version 10.1.3
adf.oracle.domain version 10.1.3
adf.generic.domain version 10.1.3

Non-modifiable (system) libraries:
oracle.dms version 3.0
oracle.gdk version 10.1.0_2
oracle.jdbc version 10.1.0_2
oracle.xml version 10.1.0_2
oracle.cache version 10.1.3
oracle.sqlj version 10.1.3
oracle.http.client version 10.1.3
soap version 10.1.3
oracle.jwsdl version 10.1.3
oracle.ws.client version 10.1.3
oracle.xml.security version 10.1.3
oracle.ws.security version 10.1.3
oracle.toplink version 10.1.3
oracle.ws.reliability version 10.1.3
oracle.ws.testpage version 10.1.3
oracle.ws.core version 10.1.3
oracle.wsm version 10.1.3
Any of the commands available in admin_client.jar can be used -- deploy/undeploy/start/stop applications, bind Web modules to web-sites, install/publish/modify shared-libraries.

Using the variants of the Deployer URI available, admin_client.jar can be executed against any of the OC4J 10.1.3 models.

Oc4J Standalone

  • deployer:[oc4j-host]:[ormi-port]

  • deployer:oc4j:duraace.au.oracle.com:23791

Oracle Application Server OC4J single instance

  • deployer:oc4j:opmn://[opmn-host]:[opmn-port]/[oc4j-name]

  • deployer:oc4j:opmn://stadp57.us.oracle.com:6003/home

Oracle Application Server OC4J Group

  • deployer:oc4j:opmn://[opmn-host]:[opmn-port]/[group-name]

  • deployer:oc4j:opmn://stadp57.us.oracle.com:6003/colors