Chapter 7: Integrating ColdFusion MX with Other Platforms

ColdFusion MX applications can connect to a wide range of platforms. You can access databases; communicate with various types of servers, such as FTP (File Transfer Protocol), HTTP (Hypertext Transfer Protocol), SMTP (Simple Mail Transfer Protocol), and POP (Post Office Protocol); include command-line programs; and access external objects, such as COM/DCOM objects, CORBA objects, Java classes, and Java servlets. In addition, Macromedia Flash Remoting features allow you to use ColdFusion MX functionality in your Macromedia Flash movies using the Flash syntax and objects.

This chapter first discusses the ColdFusion connectivity through various tags. You'll learn how to use these tags to communicate with external objects and programs. Finally, you'll be introduced to using the ColdFusion features in other environments.

Using External Objects in ColdFusion

There are four major types of external objects that you can use from ColdFusion MX applications. These external objects are as follows:

COM objects. COM (Component Object Model) is a specification and a set of services defined by Microsoft to enable component portability, reusability, and versioning. DCOM (Distributed Component Object Model) is an implementation of COM for distributed services, allowing access to components residing on a network.
CFX tags. CFX tags are custom tags written in C++ or Java using the ColdFusion Application Programming Interface (CFAPI). These tags can be used just like any other ColdFusion tags once they're registered in the ColdFusion Administrator.
CORBA objects. CORBA (Common Object Request Broker Architecture) is a specification for a distributed component object system defined by the Object Management Group (OMG). In this model, an object is an encapsulated entity whose services are accessed only through well-defined interfaces. The location and implementation of each object is hidden from the client requesting the services.
Java objects. Java objects include the Java classes available in the class path specified on the ColdFusion Administrator JVM and Java Settings page.

You can use the <CFOBJECT> tag to create an instance of an object. You can use other ColdFusion tags, including <CFSET> and <CFOUTPUT>, to invoke properties (or attributes) and methods (or operations) on the object. An object created by the <CFOBJECT> tag or returned by other objects is implicitly released at the end of the ColdFusion page execution.

Using COM Objects

ColdFusion is an automation (late-binding) COM client. As a result, the COM object must support the IDispatch interface, and arguments for methods and properties must be standard automation types. The IDispatch interface exposes objects, methods, and properties to automation programming tools and other applications. Because ColdFusion is a typeless language, it uses the type information of objects to correctly set up the arguments when the objects are called. Any ambiguity in the object's datatypes can lead to unexpected behavior.

Caution

In ColdFusion applications, you should use only those server-side COM objects that don't have a graphical user interface. If your ColdFusion application invokes an object with a graphical interface in a window, the component might appear on the Web server desktop, but not on the user's desktop. This can take up ColdFusion Server threads, which, in turn, may lead to other Web server requests not being serviced.

You can call in process (Inproc), local, or remote COM objects from ColdFusion applications. The attributes specified in the <CFOBJECT> tag determine which type of object is called.

After you acquire the object you want to use, you must register it with Windows so that ColdFusion can find it. Certain objects might be deployed with their own setup programs that register objects automatically, while others might require manual registration.

You can register Inproc object servers (which include DLL and OCX objects) manually by running the regsvr32.exe utility using the following syntax:

 regsvr32 c:\path\servername.dll

To start local objects, which include EXE objects, either start them or specify the command-line parameters as follows:

 C:\pathname\servername.exe -register

Caution

After you install a COM object, you should register it using the regsvr32.exe utility. Otherwise, you cannot find the object in the Object Viewer. The Object Viewer retrieves all COM objects and controls from the registry and presents the information in a simple format, sorted into groups for easy viewing.

In the Object Viewer, select the category and then the component to see the program ID of the COM object you want to use. The Object Viewer also gives you access to options for the operation of the object.

After a COM object is registered, use the <CFOBJECT> tag to call the COM object. You can use this tag to call an object located on the same computer as the ColdFusion server or on other computers on the network. The <CFOBJECT> tag can also be used for objects placed anywhere on the network using DCOM.

The syntax of the <CFOBJECT> tag is as follows:

 CFOBJECT TYPE = "COM"      ACTION = "action"      CLASS = "program_ID"      NAME = "text"      CONTEXT = "context"      SERVER = "server_name">

The attributes used with <CFOBJECT> are as follows:

ACTION. This is used to create an instance of the COM object before using it.
CLASS. This is a required attribute and is used to specify the component ProgID for the object to invoke services.
NAME. This is the name of the COM object to be invoked. It's also a required attribute.
CONTEXT. This is used to specify the type of the COM object and can be InProc, Local, or Remote. This is an optional attribute. If this attribute isn't specified, registry settings are used.
SERVER. This is a required attribute when the CONTEXT attribute is set to Remote. This is used to specify the valid server name using UNC (Universal Naming Convention) or DNS (Domain Name Server) conventions, in one of the following forms:
```
 server = "\\lanserver" server = "lanserver" server = "http://www.servername.com" server = "www.servername.com" server = "127.0.0.1" 
```

The following example uses the <CFOBJECT> tag to create the Collaborative Data Objects (CDO) for NTS SampleMail object to send mail:

 <CFOBJECT TYPE="COM"      ACTION="Create"      NAME="Mailer"      >

You must create an instance of the component in ColdFusion before your application pages can invoke any methods or assign any properties to the component. This sample CDO for NTS SampleMail component includes a number of methods and properties to perform a wide range of mail-handling tasks.

The CDO for NTS NewMail object includes the following properties:

 Body [ string ] Cc  [ String ] From  [ String ] Importance  [ Long ] Subject  [ String ] To  [ String ]

As mentioned, the ACTION attribute of <CFOBJECT> provides two ways to connect to COM objects:

Create method. The Create method (ACTION= "Create") takes a COM object, typically a DLL, and instantiates it prior to invoking methods and assigning properties.
Connect method The Connect method (ACTION=" Connect") links to an object that's already running on the server, typically an executable.

You can also use the CONTEXT attribute to specify the object context. If you don't specify a context, ColdFusion uses the setting in the registry. The different object contexts are

INPROC. This refers to an in-process server object—typically a DLL—that runs in the same process space as the calling process, such as ColdFusion.
LOCAL. This refers to an out-of-process server object, typically an EXE file, that's running outside the ColdFusion process space but running locally on the same server.
REMOTE. This refers to an out-of-process server object, typically an EXE file, that's running remotely on the network. If you specify the Context attribute as remote, you must also use the server attribute to identify where the object resides.

The following code illustrates the creation and use of a COM object:

 <!--- Create the object ---> <CFOBJECT type="COM"    ACTION="Create"    NAME="Mailer"    > <!--- Use the form variables from the user entry form to   populate a number of properties necessary to create and send the   message. ---> <CFSET Mailer.From = "#Form.fromName#"> <CFSET Mailer.To = "#Form.to#"> <CFSET Mailer.Subject = "#Form.subject#"> <CFSET Mailer.Importance = 1> <CFSET Mailer.Body = "#Form.body#"> <CFSET Mailer.Cc = "#Form.cc#"> <!--- Last, use the Send() method to send the message.   Invoking the Send() method destroys the object.---> <CFSET Mailer.Send()>

Using CORBA Objects

Common Object Request Broker Architecture (CORBA) is an open, vendor-independent infrastructure that allows computer applications to work together over a network. CORBA-based applications can interoperate regardless of the vendor, computer, operating system, or programming language. These applications use the standard protocol IIOP for this type of interoperability.

ColdFusion MX comes integrated with VisiBroker 3.2 ORB (Object Request Broker) for C++ runtime libraries. This library provides access to the CORBA objects through ColdFusion applications. You use the <CFOBJECT> tag to access CORBA objects through ORB.

The <CFOBJECT> tag supports CORBA through the Dynamic Invocation Interface (DII). As with COM, the object's type information should be available to ColdFusion. This requirement implies that an IIOP-compliant Interface Repository (IR) should be running on the network, and that the object's Interface Definition Language (IDL) specification must be registered in the IR.

The syntax of the <CFOBJECT> tag for using CORBA is as follows:

 <CFOBJECT TYPE="CORBA"          NAME="name"          CONTEXT="IOR|NameService"                    LOCALE="-type_value_pair_1 -type_value_pair_n">

Set the following attributes for the <CFOBJECT> tag to access a CORBA object:

Set the TYPE attribute to CORBA. The default value for this attribute is COM.
The CONTEXT attribute shows how the object reference is obtained. ColdFusion uses the Interoperable Object reference (IOR) or NAMESERVICE to access the CORBA objects. Set CONTEXT to IOR, for a file containing the object's unique Interoperable Object Reference, or to NAMESERVICE.
If you set the CONTEXT attribute to IOR set the CLASS attribute to the file containing the stringified version of the IOR. ColdFusion must be able to read this IOR file at all times. Therefore, make it local to the server or on the network in an accessible location.
If you set the CONTEXT attribute to NAMESERVICE, the CLASS attribute must include a period-delimited name. Currently, ColdFusion can only resolve objects registered in a CORBA 3.0-compliant naming service. You should ensure that the naming service (NS) is brought up with a default naming CONTEXT. The server implementing the object should bind to the default CONTEXT and register the appropriate name. ColdFusion also binds to the default CONTEXT to resolve the name.
Set the NAME attribute to the name that your application uses to call the object's operations and attributes.

After you create the object, you can invoke attributes and operations on the object using the syntax outlined in the previous section. ColdFusion also supports the use of complex types, such as structures and sequences. For structures, use ColdFusion structures; for sequences, use ColdFusion arrays.

Using Java Objects

ColdFusion MX offers a very high level of interoperability between the Java language, J2EE elements, and ColdFusion applications. This interoperability is possible because of the Java 2 Enterprise Edition (J2EE) technology platform. ColdFusion MX also simplifies the collaboration between Java developers and CFML developers, who can partition application logic more easily between components written in the two languages.

Once 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 various Java elements, including servlets, JavaServer Pages (JSPs), JSP custom tags, and Enterprise JavaBeans (EJBs). The integration of J2EE elements in ColdFusion MX applications is more flexible because ColdFusion MX applications themselves are Java applications.

There are many advantages of using JSPs and servlets within a CFML application. Some of these advantages are as follows:

If the project team is multiskilled, Java developers can create those parts of the application that use servlets and JSP. At the same time, ColdFusion developers can focus on coding CFML. Then, the work from both types of developers can be combined into a single application.
You can reuse JSP applications in your ColdFusion applications.
If you have an application that's completely written as a set of servlets, you can enhance its functionality by adding CFML pages to it.

There are many ways of interoperating ColdFusion MX applications and Java objects:

A ColdFusion application can include a mix of CFML pages, servlets, and JSPs.
ColdFusion pages can include servlets or JSPs and can forward control to servlets or JSPs.
Servlets and JSPs can include CFML pages, and can forward control to ColdFusion pages.
ColdFusion pages can import and use tags from a JSP custom tag library.
CFML pages and JSPs can share data in persistent scopes.

ColdFusion MX offers the ability to include JSPs and servlets in your ColdFusion applications. Therefore, ColdFusion pages, servlets, and JSPs can share data using JSP includes and forwards, using URL or FORM variables to POST or GET data between pages, and through persistent variable scopes.

Note

ColdFusion pages aren't JSPs. Therefore, you cannot use JSP syntax inside CFML pages. Also, you cannot embed pure Java code in the middle of a CFML page.

ColdFusion provides access from CFML to a PageContext object, which is a JSP-compatible object. This object provides a number of methods and properties that are useful in J2EE integration. It contains the include() and forward() methods to include or forward to a servlet or JSP template from a ColdFusion page.

JSPs can also include or forward to ColdFusion pages using the jsp:include directive. Java developers can use the JSP custom tag library. When you're creating a custom tag in CFML, you build it using CFML tag syntax. When you're creating a custom tag in JSP, you create it using Java. ColdFusion MX enables you to access JSP custom tags from within CFML syntax.

For example, you can use JSP custom tag libraries by performing the following steps:

Include the JSP custom tag library, consisting of a taglibname.jar file and a taglibname.tld file in the web_root/WEB-INF/lib directory.
Use the <cfimport> tag to import the custom tag library into a CFML template. When you import a JSP custom tag library, specify a namespace to import the tag to avoid having same name for the tags from the two sources.
Call tags from the library with any required attributes or bodies, just as you would call any other tag.

Applications that consist of CFML pages, servlets, and JSPs can share data in the Request, Session, and Application scopes. This is useful when you have data in a JSP Application scope that you need 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 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 doesn't have its own definition of special CFML scopes, such as CLIENT or FORM scopes. These are the only three scopes that CFML, JSP, and servlets have in common.

Now that you've had an overview of the Java objects and their integration with ColdFusion applications, let's take a look at the different ways you can call Java from ColdFusion:

Calling Java classes using CFX tags
Calling and creating Java components using the <CFOBJECT> tag
Calling Java applets using the <CFAPPLET> tag

Calling Java Classes Using CFX Tags

CFX tags differ from the CFM custom tags because they can be created in Visual C++, Java, or Delphi. They need to be compiled (.class for Java) and registered in the ColdFusion Administrator before they can be used. For more information on custom tags, refer to Appendix A, "Creating ColdFusion MX Custom Tags."

To call Java functions from ColdFusion, you need to use the CFX_Java tag. You can call and use CFX_Java just like any other ColdFusion tag, except that it's invoking Java code.

To use CFX_Java, you need to perform the following steps:

Set up the Java Virtual Machine (JVM) in ColdFusion.
Write the Java class.
Set up the tag in ColdFusion Administrator.
Call the tag in ColdFusion.

The JVM in ColdFusion is set up using the following steps:

The JVM you specify in the ColdFusion Administrator actually creates a running JVM within ColdFusion, either at startup or when first accessed.
The class path specifies the location of all your Java classes that ColdFusion can access and call.

The custom tag can be set up as follows:

When creating a CFX tag in ColdFusion Administrator, choose the Java type.
Specify the tag.
Name the CF references and then specify the Java class.
Name the .class file. The class must be on the same ColdFusion server.

The following code calls the custom tag, which returns data to be displayed in the browser:

 <html> <head> <title>Java Custom Tag Sample</title> </head> <body> <CFX_HelloColdFusion name="ColdFusion"> </body> </html>

Calling and Creating Java Components Using the <CFOBJECT> Tag

ColdFusion can call Java class files and Enterprise JavaBeans (EJBs) using the <CFOBJECT> tag.

To invoke a class, Java provides two basic kinds of methods: instance methods and static (or class) methods. The instance methods require an instance of the class before they can be invoked, whereas static methods do not. Instance methods use dynamic binding, whereas static methods use static binding.

The <CFOBJECT> tag can call any Java class that's available on the class path specified on the ColdFusion Administrator JVM and Java Settings page. For example:

 <CFOBJECT TYPE="Java"  NAME="MyObject">

Although the <CFOBJECT> tag loads the class, it doesn't create an instance object. Static methods and fields are accessible after the call to <CFOBJECT>.

To call the class constructors explicitly, you need to use the init () method with the appropriate arguments, as follows:

 <CFSET RET=MyObject.init(arg1, arg2)>

If you call a public method on the object without first calling the init () method, the result is an implicit call to the default constructor.

Arguments and return values can be any valid Java type, such as simple arrays and objects. ColdFusion does the appropriate conversions when strings are passed as arguments, but not when they're received as return values.

Java classes can be called directly from ColdFusion using the <CFOBJECT> tag. The following example calls a Java class to add two numbers:

 <CFOBJECT ACTION="Create" TYPE="Java" NAME="javaobject"> <CFSET A="5"> <CFSET B="50"> <CFSET Status = javaobject.add( "A", "B", 'Result' ) <CFOUTPUT>The Result of #A# plus #B# is #Result#.</CFOUTPUT>

The following code snippet calls a JRun EJB from ColdFusion:

 <!--This creates the Context object to get at the static fields. --->  <CFOBJECT      ACTION=create      NAME=ctx      TYPE="JAVA"      > <!-- Create the Properties object and call explicit constructor ---> <CFOBJECT      ACTION=create      NAME=prop type="JAVA"      > <!--- Call a method in the entity bean.---> <CFSET book.save(500)>

Caution

The Java class name is case-sensitive, but Java method and field names aren't. Neither are ColdFusion variables. As a result, the preceding sample code works even though the CFML uses emp.firstname and emp.lastname, while the Java source code uses FirstName and LastName for these fields.

ColdFusion is a typeless scripting language, while Java is strongly typed. In most situations, when the method names aren't ambiguous, ColdFusion can determine the required types. For example, ColdFusion strings are converted to the Java String type implicitly. Similarly, if a Java object contains a method named doIt that expects a parameter of type int, and CFML is issuing a doIt call with a CFML variable x, ColdFusion will convert the variable x to the Java int type. However, ambiguous situations, such as incorrect conversion of a variable to a Java datatype, can result from Java method overloading, where a class has multiple implementations of the same method that differ only in their parameter types.

Table 7.1 describes the Java datatypes that match the ColdFusion types. ColdFusion doesn't support direct conversion of date/time variables and structures.

Table 7.1: Conversion of Java to ColdFusion Datatypes
CFML	Java
Character	String.
Numeric	Int, long, float, or double, depending on the JavaCast function.
Boolean	Bool.
Array of character	Array of string.
Array of numeric	Array of Java int, long, float, or double. The conversion rule depends on the Java Method Signature.
Array of Java objects	Array of Java objects.

You can overload Java methods so that a class can have several methods with identical names. At runtime, the JVM resolves the specific method to use based on the parameters passed in the call.

Method overloading is a technique in which you define a number of different methods with the same name but different parameters or different return types. In this manner, you can use the same method name for different datatypes.

To indicate the datatype conversion of a ColdFusion variable to a Java variable, the JavaCast function is used. The syntax of this function is as follows:

 JavaCast(type, variable)

The arguments are as follows:

TYPE. This refers to the datatype to which the ColdFusion variable should be converted before being passed to the Java method. The possible datatypes are Boolean, int, long, double, or String.
VARIABLES. This refers to a ColdFusion variable that holds a scalar or string type.

The JavaCast function can be used after creating the Java object using <CFOBJECT>, but prior to calling one of its methods. If the method takes more than one overloaded argument, you need to call JavaCast for each argument that's overloaded. The JavaCast function should be used only when a method is overloaded, because its arguments can take more than one datatype.

JavaCast cannot be used to cast between complex objects, or to cast to a superclass. The result of this function should be used on calls to Java objects only. Also, there's no one-to-one correspondence between internally stored ColdFusion types and Java scalar types. Therefore, not all conversions can be performed. For example, suppose that a class has two implementations for the ManagerGrade method. One method takes a string variable, the other an integer. Look at the following code:

Here, "5" could be interpreted as a string or as a number. Therefore, there's no way to know which method implementation to use. You can use the JavaCast function to resolve such issues by specifying the Java type of a variable, as in the following line:

 <CFSET empl.ManagerGrade(JavaCast("int", "5")>

Calling Java Applets Using the <CFAPPLET> Tag

Applets can be stored on a server. Whenever a page that contains applets is requested from the server, the client downloads them. You can write your own applets or include existing applets in your Web pages. ColdFusion supports Java applets using the <CFAPPLET> tag.

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>. You can use the <CFAPPLET> tag to invoke applets, and 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.

The applet section of the Administrator contains the following settings:

AppletName. Specifies the name of the applet to be called.
Codebase. Specifies the URL (from the server root) to the directory containing the applet class file.
Code. Specifies the name of the applet class file.
Archive. This attribute is optional and is simply passed through by <CFAPPLET> to the applet. Internet Explorer does not support it. 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.
Method. This is an optional attribute and specifies the name of a method of the applet that returns a value. If you're not sure of this value, leave it blank.
Height. Specifies the default height in pixels of the applet on the Web page.
Width. Specifies the default width in pixels of the applet on the Web page.
VSpace. This is an optional attribute that specifies the vertical space.
HSpace. This is an optional attribute that specifies the horizontal space.
Align. Determines how the area defined for the applet is aligned with content on the Web page.
Java Not Supported Message. Specifies the message you want the applet to display if the browser rendering the Web page doesn't support applets.

The syntax of the <CFAPPLET> tag is as follows:

 <CFAPPLET appletSource = "applet_name"    NAME = "form_variable_name"    HEIGHT = "height_in_pixels"    WIDTH = "width_in_pixels"    VSPACE = "space_above_and_below_in_pixels"    HSPACE = "space_on_each_side_in_pixels"    ALIGN = "Left" or "Right" or "Bottom" or "Top" or "TextTop" or "Middle"              or "AbsMiddle" or "Baseline" or "AbsBottom"    NOTSUPPORTED = "message_to_display_for_nonJava_browser"    PARAM_1 = "applet_parameter_name"    PARAM_2 = "applet_parameter_name"    PARAM_N = "applet_parameter_name">

The attributes are as follows:

Appletsource. This is a required attribute. It's the name you specified to your applet when you registered it in the ColdFusion Administrator.
Name. This is a required attribute that 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 attributes override the same settings in the ColdFusion Administrator.
Applet parameters. Most applets require parameters and have default values defined so that they'll run even if you don't specify any parameters.