In 1995 Allaire launched the ColdFusion Web Application Server. Since that launch, java has become an important language for the web, and Allaire has moved right along to combine the power of java with ColdFusion.

On June 15, 1999, Allaire purchased JRun, giving them a powerful java server that currently supports java servlets and Enterprise JavaBeans.

Allaire has a technology road map that will allow your CFML pages to execute directly on the next generation application server technology - a java engine code named Pharaoh.

Right now you can develop applications in java and run them with your JRun engine, and develop ColdFusion applications in CFML and run them on the ColdFusion Web Application Server. But how do you use ColdFusion and java to-gether?

Jeremy Allaire, in his IMHO, "Allaire ColdFusion, Java and JRun" (CFDJ, Vol. 1, issue 4), said that "ColdFusion and Java are perfect cousins." In this article I want to show how you can use Java with your ColdFusion applications right now. The good news is that you don't have to wait for Pharaoh or switch to JRun.

Java on the Server and the Client
When java first came out, many people thought it was going to be primarily useful on the client. Browser manufacturers started including Java Virtual Machines (JVM) in their products, and web sites started putting java applets in web pages. The browser downloads the applet, and the applet runs on the client machine. As java has matured, it's come to be seen more as a server-side language than a client-side language. On the server, software systems can be built from a combination of java servlets, java classes and/or applications, and Enterprise JavaBeans. You can make use of both client- and server-side java with ColdFusion.

There are five methods for calling java (both server- and client-side) from ColdFusion:

1. Calling Java servlets using CF-SERVLET
2. Calling Java servlets using CFHTTP
3. Calling and creating Java components with CFOBJECT
4. Calling Java applets with CF- APPLET
5. Calling Java classes with CFX tags

Calling Servlets with CFSERVLET
You can call java servlets from your ColdFusion pages using the CFSERVLET tag. This tag executes a servlet on the JRun engine. Note that in order to make use of CFSERVLET, the machine on which the servlet exists needs to have JRun installed. You don't need JRun on the same server as Cold-Fusion. You can, of course, make remote calls to other machines (both at your site and over the internet) as long as the remote machine is using JRun as its servlet engine (see Figure 1).

Let's say you want to call a servlet-based web site that's using JRun. You can call any of the servlets on that machine with CFSERVLET. All you have to do is specify the JRUNPROXY attribute to be the IP address of the server running JRun.

Depending on your web site, you might have JRun and Cold-Fusion on the same server or on the same network.

Sometimes you need to specify parameters for the servlet you're calling. To do this, specify CF-SERVLETPARAM tags within the CFSERVLET call.

For example:

<CFSERVLET CODE="ServletName"
JRUNPROXY="233.125.25.3:8083">
<CFSERVLETPARAM name="param1" value="35">
</CFSERVLET>

Note that when your ColdFusion page executes the CFSERVLET tag, it will wait for a response from the servlet you have called before continuing. The servlet you've called is executing on the JVM in the JRun engine.

Calling Servlets with CFHTTP
Sometimes you may need to call java servlets hosted on a web server that's not using JRun as its servlet engine. You can do this using CF-HTTP. Simply include the CFHTTP tag in your CFML page and make the URL you call point to the servlet you want to execute. If the servlet you're calling requires form input parameters, you'll need to specify the METHOD="POST" at-tribute in CFHTTP and include CHTTPPARAM tags for the form variables that your servlet requires (see Listing 1).

Calling Java Components with CFOBJECT
CFOBJECT provides a flexible way to call java components. You can create and use java objects and Enter-prise JavaBeans using CFOBJECT. (You need ColdFusion 4.5 or later to call java components this way.)

Setup in ColdFusion Administrator
To use CFOBJECT (and java CFXs) you need to set up the Java section of the ColdFusion Administrator. Example settings are as follows:

• Load JVM when starting Cold-Fusion: If you want to load the JVM in the ColdFusion process every time ColdFusion starts, check this box. If you want to load only the JVM when a java request is made, leave it unchecked.
• Java Virtual Machine path: This is the path to your JVM. For example, on Windows, it might be: "c:\ jdk1.2.2\jre\bin\classic\jvm.dll".
• Classpath: Your classpath should contain the paths of any java classes you want to use with CFOBJECT.

  For example:

  "c:;c:\jdk1.2.2;c:\jdk1.3\;c:\xerces\xerces.jar; c:\weblogic\lib\weblogic-aux.jar;c:\weblogic\classes".

  Initial heap size: Specifies the heap size that's allocated to the JVM when the JVM starts (typically 1K).
• Maximum heap size: Specifies the maximum size for the heap assigned to the JVM (typically 16K).
• System options: Specify any JVM command-line options here (name-value pairs separated by a semicolon).
• Implementation options: Specify any implementation-specific op-tions here (name-value pairs separated by a semicolon).
• CFX Jar path: Specify the location of the ColdFusion cfx.jar file that contains interfaces used by Java CFXs. For example:

"C:\CFUSION\JAVA\CLASSES"

Any java class in the classpath specified in the ColdFusion Admin-istrator can be loaded and used by ColdFusion. Note that classes execute on the JVM embedded in the ColdFusion process.

Your ColdFusion Administrator must also enable the CFOBJECT tag in the security section before you can use either CFOBJECT or the CreateObject function.

Calling Enterprise JavaBeans
You can also use CFOBJECT to call EJBs. EJBs can be deployed in any EJB server, such as JRun or BEA's weblogic Server.

To call EJBs, first configure the ColdFusion Administrator, as de-scribed above; second, create a java-bean and deploy it to your EJB server; third, create a java object that's running on the ColdFusion JVM, and then use that object to call your EJBs running on the EJB server. The results of the call are returned as a ColdFusion variable you can use in your CFML template.

You can create java objects in two ways:

• Using the <CFOBJECTACTION="- CREATE" ..> tag,
• Using the function CreateObject- ("JAVA", class)

Note that CFOBJECT supports COM, java, and CORBA objects. Solaris installations of ColdFusion support only CORBA objects at the time of writing, while Windows NT installations of ColdFusion support all three types.

For example, suppose you have written an entity bean that looks up an employee name given a unique key. In this example, we'll assume the bean has been deployed to BEA's weblogic Server.

We now need a ColdFusion page that will call our entity bean (see Listing 2).

Calling Java Applets with CFAPPLET
Client-Side Java
Java applets are supported by ColdFusion using the CFAPPLET tag. Applets are stored on your server. They're downloaded by the client whenever a page that contains applets is requested from the server. You can write your own applets or include existing applets in your Web pages. The advantage of registering applets in the Administrator and using CFAPPLET to invoke them is that you don't have to specify all the parameters the applet requires each time you use it. CFAPPLET will use the defaults you've registered in the Administrator unless you specifically override them.

Using Java Applets
To use a java applet in your CFML page, register the applet with the ColdFusion Administrator applets section. Once it's registered you can embed the applet in your CFML page using CFAPPLET. CFAPPLET must be used with CFFORM.

ColdFusion Administrator Settings
The applet section of the Admin-istrator has the following settings.

• AppletName: The name you'll use when you call the applet with CFAPPLET.
• Codebase: The URL (from the server root) to the directory containing the applet class file (e.g., /test/servlets/).
• Code The name of the applet class file (you should include the .class extension; e.g., "myapplet.class").
• Archive: Optional. This attribute is optional and simply passed through by CFAPPLET to the ap-plet. The actual meaning of the archive attribute varies between the HTML 4.0 specification and Netscape's implementation. It's not supported by Internet Ex-plorer. For Netscape, you can specify an archive (.zip or .jar) that packages multiple class files into a single archive. This makes it quicker for the browser to load all the required classes.

In HTML 4.0, the archive attribute allows you to specify a space-delimited list of URLs for additional classes or resource files. This is for compatibility with the OBJECT element, and allows required resources to be placed in several locations.

• Method: Optional. The name of a method of the applet that returns a value. Most applets don't return values. If you're not sure, leave it blank.
• Height: Default height of the applet on the web page in pixels.
• Width: Default width of the applet on the web page in pixels.
• VSpace: Optional.
• HSpace: Optional.
• Align: Determines how the area defined for the applet is aligned with content on the web page (e.g., "ABSMIDDLE").
• Java Not Supported Message: The message you want the applet to display if the browser rendering the web page does not support applets.

The CFAPPLET Tag
The CFAPPLET tag is simple to use. You specify the following at-tributes:

• Appletsource: Required. The value is the name you gave to your applet when you registered it in the ColdFusion Administrator.
• Name: Required. Specifies the name of the Form variable. If you specified a value for Method in the ColdFusion Administrator when registering the applet, this name should match the method name. This Form variable will contain the result of the method called in the applet.
• Height, Width, VSpace, HSpace, Align, Not Supported: These at-tributes override the same settings in the ColdFusion Admin-istrator.
• Applet parameters: Most applets require parameters, and will have default values defined so they'll run even if you don't specify any parameters. You can set up your own default values for the applet in the parameters section when you register the applet in the ColdFusion Administrator only if you want to override the defaults you have specified (or if you didn't specify any defaults and want to override the applet's own defaults).

Example applet call:

<CFAPPLET APPLETSOURCE="test" name="bob">

Calling Java Classes with CFX Tags
CFXs - or ColdFusion Extensions - allow you to extend ColdFusion with custom code written in C++ or java. You can write your own CFXs in java or just call existing java classes.

To call a java class this way, you need to do two things in the Cold-Fusion Administrator:

1. In the Java section set up the classpath and other information as described in the section above on CFOBJECT.
2. Register your custom extensions in the ColdFusion Administrator in the CFX tags section. Give the CFX a name, specify that it's a java extension, and then tell Cold-Fusion which java class the CFX will call.

For example, suppose you've registered a class "HelloWorld" in the ColdFusion Administrator CFX section that outputs "Hello Andrew" when it's called (see Listing 3).

In the Java section, you've included the path to your HelloWorld.class file in the classpath option, and now you want to create a sample Cold-Fusion page (see Listing 4).

You should see "HelloWorld" as the output when you call this page. If you get an error like this:

java.lang.ClassNotFoundException: HelloColdFusion. Java exception occurred in call to method

It's likely that you haven't correctly specified the path to your java class in the classpath setting of the Java section of ColdFusion Administrator. Another possibility is that you have not correctly specified the classname in the CFX Class attribute in the CFX section of the ColdFusion Administrator.

Note that if you're using Cold-Fusion Server version 4 or earlier, you need to use CFX_J. CFX_J has now been replaced with the CFX mechanism described above. But you can still download and install CFX_J if you have an older version of ColdFusion Server.

Summary
In this article we've covered five ways to call both client- and server-side java from ColdFusion. If you need to call JRun servlets, use CFSERVLET; if you need to make a simple call to java class, use CFXs; and if you need to call EJBs, use CFOBJECT .

• Figure 1
• Source Code