ColdFusion Article

Based on the powerful Java 2 Enterprise Edition (J2EE) technology platform, Macromedia ColdFusion MX takes Java interoperability support to the next level, exposing unparalleled interoperability between the Java language, J2EE elements and ColdFusion applications. ColdFusion MX also simplifies the collaboration between Java developers and CFML developers, enabling them to partition application logic more easily between components written in CFML and those written in Java.

By building ColdFusion MX on the J2EE Java technology platform, Macromedia allows you to use the ColdFusion programming environment to harness the power of the J2EE platform in the following ways:

After the CFML compiler compiles ColdFusion pages into Java classes, the ColdFusion application server executes them in the ColdFusion MX runtime with the help of application service libraries in the J2EE engine. This architecture lets ColdFusion MX applications integrate with Java elements such as servlets, JavaServer Pages (JSPs), JSP custom tags, and Enterprise JavaBeans (EJBs). Because ColdFusion MX applications themselves are Java applications, the integration of J2EE elements in ColdFusion MX applications is a lot more robust, natural and flexible than ever before. This tighter integration with the Java platform technology enables ColdFusion MX to take advantage of the integration services offered by third-party application servers, including legacy connectors and messaging middleware.

This article provides an overview of some of the integration methods and offers a high-level outline of how you can take advantage of these methods. For detailed implementation examples, refer to the documentation in "Integrating J2EE and Java Elements in CFML Applications," a chapter in the Developing ColdFusion MX Applications documentation.

Interoperating with Java servlets, JSPs, and JSP custom tags
A ColdFusion MX application can consist of any combination of CFML pages, ColdFusion components, JSPs, and servlets. You can therefore use JSPs and servlets within a CFML application in many interesting ways:

I describe each of these scenarios in the following sections.

Working with a mix of CFML pages, servlets and JSPs
Because ColdFusion MX offers the ability to include JSPs and servlets in your ColdFusion applications, ColdFusion pages, servlets and JSPs can share data using JSP includes and forwards, URL or FORM variables to POST or GET data between pages, and through persistent variable scopes. Using a combination of servlets, JSPs, and ColdFusion pages offers you more flexibility than ever before in developing an application and leverages the talents of your development team through code reuse.

Note: ColdFusion pages are not JSPs, however, so you cannot use most JSP syntax inside CFML pages. Nor can you embed pure Java code in the middle of a CFML page. See below for more specific examples on integrating of JSPs and ColdFusion pages.

Including or forwarding to servlets/JSPs
ColdFusion MX provides access from CFML to a PageContext object that is JSP-compatible. This object exposes a number of methods and properties useful in J2EE integration. In particular, it includes the include() and forward() methods that provide the equivalent of the corresponding standard JSP tags. Use these methods to include or forward to a servlet or JSP template from a ColdFusion page.

For example, to include a "hello world" JSP page in your ColdFusion application, you would use the following in your CFML page:

<CFSCRIPT>

     GetPageContext().include(“hello.jsp”);

</CFSCRIPT>

or alternatively:

<CFSET GetPageContext().include(“hello.jsp”)>

To pass parameters to the JSP, include the parameters in the page URL.

Note: The cfservlet tag has been deprecated in ColdFusion MX; in its place you are encouraged to use these new J2EE constructs to handle page includes.

Including or forwarding to ColdFusion pages
JSPs can include or forward to ColdFusion pages using the jsp:include directive. This is the converse of the previous scenario.

For example, the following JSP sets Request, Session and Application variables, and calls a ColdFusion page by passing it a name parameter:

<%@page import = "java.util.*" %>

<% request.setAttribute("myvariable","This"); %>
<% ((Map)Session.getAttribute("myApp")).put("myvariable", "is a"); %>
<% application.setAttribute("myApp.myvariable","test."); %>

<jsp:include page="hello.cfm">
<jsp:param name="name" value="Robert" />
</jsp:include> 

In addition, using JSP custom tags in applications allows you to take advantage of even more resources in the Java community. There are a number of Java websites (such as JSPTags.com [http://jsptags.com/]) whose JSP custom tags you can use in an instant within applications.

JSP custom tags are normally grouped together and contained in JSP custom tag libraries. These libraries usually appear as a Java JAR file and contain a tag library descriptor file (TLD) and a set of tag handler classes, each of which provides the Java implementation for a particular tag in that library.

Here's how you use JSP custom tag libraries:

<!--- import the custom tag library so that this template can see it --->
<CFIMPORT taglib = "/WEB-INF/lib/random.jar" prefix="myrand">

<!--- execute a custom tag from this library --->
<myrand:number id="randpass" range="000000 - 999999"
algorithm="SHA1PRNG" provider="SUN"/>

Sharing data in persistent scopes
Applications comprised of CFML pages, servlets, and JSPs can share data in the Request, Session and Application scopes. This is useful if you have data in a JSP application scope that you wish to access from a CFML page in the same application. You can avoid passing data with the CGI scope by taking advantage of shared scopes. Simply setting a session variable in a JSP page, as you normally would, makes it immediately visible from a CFML page as a CFML SESSION variable, and vice-versa.

ColdFusion MX integrates with only the Request, Session and Application scopes because JSP does not have its own definition of special CFML scopes, such as CLIENT or FORM scopes. These three are the only scopes that CFML, JSP and servlets have in common.

One example of Session variable sharing occurs when you put a customer order structure into the Session scope in a CFML template. Because Session is a shared scope, you don't have to pass the order values as a set of parameters to a JSP. Instead, the JSP accesses the Session scope variables directly, and the ColdFusion page only requires a line without parameters, such as the following, to call the JSP:

GetPageContext().forward(URLEncodedFormat(“/responsegen/responsegen.jsp”));

The JSP accesses its Session scope and can see the data that the CFML page set.

In addition, CFML data types (structs, and so forth) are Serializable and therefore can leverage J2EE server-specific features (such as session failover).

Note: When you share data between ColdFusion pages and JSPs, be careful about data type conversion issues. For more information, refer to the documentation "Developing ColdFusion MX Applications with CFML."

Using Java Objects in ColdFusion Applications
Many developers use Java classes from existing projects or prefer to develop parts of web applications in Java. This means your ColdFusion pages can use public repositories of Java code, offering all sorts of useful functionality. For example, you could find and include Java classes in the public domain that perform specific mathematical algorithms or complex string manipulation. Whatever the reason, accessing and using Java objects in ColdFusion MX is easy.

Macromedia has improved support for using Java objects in ColdFusion applications in ColdFusion MX. Macromedia ColdFusion 5 was not built on a Java foundation and therefore did not interpret Java objects in a native manner. ColdFusion MX, on the other hand, interprets Java objects natively, offering significantly better performance, some new enhancements and better stability.

Working with Java objects
To use a Java object in a ColdFusion page, follow these basic steps:

Importing objects
When working with Java objects, load a Java object onto which you will operate. ColdFusion MX uses the CreateObject() function to import an object.  Alternatively, use the cfobject tag to get a Java class, as in the following example: 

<CFOBJECT type=”java” class=”MyClass” name=”myObj”>

Creating an object instance
Create an instance of a Java object in ColdFusion MX with the special init function.  When you call this method, it creates a new instance of the class and executes the constructor.  See the following example:

            <CFSET ret = myObj.init(arg1, arg2) >

Note that this init method is not a method of the object, but a ColdFusion identifier that calls the new function on the class constructor.  So, if a Java object has a real init method, a name conflict exists and you will be unable to call the object’s init method.

To maintain persistent access to an object, first use the init function because it returns a reference to an instance of the object; the cfobject tag does not. When you use the cfobject tag to create an object, or other objects return it, the object is implicitly released at the end of the ColdFusion page execution.

Using methods and properties
To set a property, use this:

            <CFSET obj.property = “somevalue”>

To get a property, use this:

            <CFSET value = obj.property>

To call a method, use this:

            A method with no arguments:

            <CFSET retval = obj.Method1()>

            A method with arguments:

            <CFSET retval = obj.Method2(x,y,”hello”)>

Calling JavaBean get and set methods
ColdFusion MX can automatically invoke the getPropertyName() and setPropertyName(value)methods if a Java class conforms to the JavaBeans specification. As a result, you set or get the property by referencing it directly, without having to explicitly invoke a method.

For example, if the myFishTank class is a JavaBean, the following code returns the results of calling the getTotalFish() method on the myFish object:

      <CFOUTPUT>

          There are currently #myFish.TotalFish# fish in the tank.

     </CFOUTPUT>

The following example adds one guppy to a myFish object by implicitly calling the setGuppyCount(int number) method:

            <CFSET myFish.GuppyCount = myFish.GuppyCount + 1>

These shortcuts allow for easier JavaBean integration in ColdFusion MX than before.

Accessing a CFML page's PageContext object
The underlying J2EE engine treats a ColdFusion MX page as a servlet. ColdFusion MX dynamically generates the servlet functionality so it's not visible to the developer, but it provides CFML with the GetPageContext() function, which returns the underlying javax.servlet.jsp.PageContext object of a ColdFusion page.

While this object outside the case of JSP includes and forwards is not immediately useful to most developers, it gives you the flexibility to access low-level information that you may need while integrating with Java.

Some of the more interesting methods are:

You may find more detailed information on the Java PageContext class in JSP books or articles on the web. Sun's Java site also includes information on the Java PageContext class.

Adding JavaScript and client-side Java
ColdFusion pages, like HTML pages, can incorporate client-side JavaScript and Java applets, which are Java applications that run inside client browsers and are sometimes used to develop interactive client-side applications.

JavaScript allows browsers to make web pages more dynamic on the client side by scripting responses to user actions, such as mouse clicks, or updating portions of a page based on user actions. For example, you may want to take advantage of JavaScript in an application that has an interactive user interface.

Write the JavaScript code in a CFML template just as you would in any HTML page. The ColdFusion processing engine ignores the JavaScript and passes it directly to the client.

The CFML tag, cfapplet, simplifies using Java applets in an application. Register an applet in the ColdFusion administrator and then use the cfapplet tag to call the applet from within a CFML template.