Using basic object techniques



You can use ColdFusion to invoke Java objects and access object methods and properties.

Invoking objects

The cfobject tag makes Java objects available in ColdFusion. It can access any Java class that is available on the JVM classpath or in either of the following locations:

  • In a Java archive (.jar) file in web_root/WEB-INF/lib

  • In a class (.class) file in web_root/WEB-INF/classes

For example:

<cfobject type="Java" class="MyClass" name="myObj">

Although the cfobject tag loads the class, it does not create an instance object. Only static methods and fields are accessible immediately after the call to cfobject.

If you call a public non-static method on the object without first calling the init method, ColdFusion makes an implicit call to the default constructor.

To call an object constructor explicitly, use the special ColdFusion init method with the appropriate arguments after you use the cfobject tag; for example:

<cfobject type="Java" class="MyClass" name="myObj"> 
<cfset ret=myObj.init(arg1, arg2)>
Note: The 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 an init method, a name conflict exists and you cannot call the object init method.

To have persistent access to an object, use the init function, because it returns a reference to an instance of the object, and cfobject does not.

An object created using cfobject or returned by other objects is implicitly released at the end of the ColdFusion page execution.

Using properties

Use the following coding syntax to access properties if the object does either of the following actions:

  • Exposes the properties as public properties.

  • Does not make the properties public, but is a JavaBean that provides public getter and setter methods of the form getPropertyName() and setPropertyName(value). For more information, see Calling JavaBean get and set methods.

  • To set a property: <cfset obj.property = "somevalue">

  • To get a property: <cfset value = obj.property>

Note: ColdFusion does not require consistently capitalized property and method names. However, it is good programming practice to use the same case in ColdFusion as you do in Java to ensure consistency.

Calling methods

Object methods usually take zero or more arguments. Some methods return values, while others might not. Use the following techniques to call methods:

  1. If the method has no arguments, follow the method name with empty parentheses, as in the following cfset tag:

    <cfset retVal = obj.Method1()>

  2. If the method has one or more arguments, place the arguments in parentheses, separated by commas, as in the following example, which has one integer argument and one string argument:

    <cfset x = 23> 
<cfset retVal = obj.Method1(x, "a string literal")>
Note: When you invoke a Java method, the type of the data being used is important. For more information see Java and ColdFusion data type conversions.

Calling JavaBean get and set methods

ColdFusion can automatically invoke getPropertyName() and setPropertyName(value) methods if a Java class conforms to the JavaBeans pattern. As a result, you can 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>
Note: You can use the direct reference method to get or set values in some classes that have getProperty and setProperty methods but do not conform fully to the JavaBean pattern. However, you cannot use this technique for all classes that have getProperty and setProperty methods. For example, you cannot directly reference any of the following standard Java classes, or classes derived from them: Date, Boolean, Short, Integer, Long, Float, Double, Char, Byte, String, List, Array.

Calling nested objects

ColdFusion supports nested (scoped) object calls. For example, if an object method returns another object and you invoke a property or method on that object, you can use the following syntax:

<cfset prop = myObj.X.Property>.

Similarly, you can use code such as the following CFScript line:

GetPageContext().include("hello.jsp?name=Bobby");

In this code, the ColdFusion GetPageContext function returns a Java PageContext object, and the line invokes the include method of the PageContext object.