Description

Converts the data type of a ColdFusion variable to a specified Java type to pass as an argument to Java or .NET object. Use only for scalar, string, and array arguments.

Returns

The variable, as type type.

Category

String functions

Function syntax

JavaCast(type, variable)

History

ColdFusion MX 8: Added support for bigdecimal, byte, char, and short data types and for casting Arrays.

ColdFusion MX 7: Added support for nulls.

See also

CreateObject, cfobject, "Converting between .NET and ColdFusion data types" in and"Resolving ambiguous data types with the JavaCast function" in the ColdFusion Developer's Guide

Parameters

Usage

Use this method to specify the Java type to use for a variable that you use when calling a Java or .NET method when the conversion between types is ambiguous; for example, if a method is overloaded and differs only in parameter type or a .NET method is declared as taking a System.Object class parameter.

Use after creating a Java object with the cfobject tag, before calling one of its methods. If the method takes more than one overloaded argument, you must call JavaCast for each one. Use JavaCast only when a method is overloaded (because its arguments can take more than one data type, not because the method can take a variable number of arguments).

JavaCast cannot be used to cast between complex objects, nor to cast to a super-class.

Because there is not a one-to-one correspondence between internally stored ColdFusion types and Java scalar types, some conversions cannot be performed.

Use the result of this function only on calls to Java or .NET objects. The following example shows the use when calling a Java method.

<cfscript>
     x = CreateObject("java", "test.Hello");
     x.init();
     ret = x.sayHello(JavaCast("null", ""));
</cfscript>

The format JavaCast(type[], variable) casts a ColdFusion Array variable to a single dimensional Array of the specified type. It cannot convert multi-dimensional arrays. You can specify a primitive type or the name of a Class as the type to cast to. For example, you can use the following format to cast a ColdFusion Array to an Array of vom.x.yMyClass objects.

javacast("vom.x.y.MyClass[]", myCFArr)

Use an array in the first JavaCast parameter in any of the following circumstances:

• You have two functions with signatures with the same number of parameters, and a parameter takes different types of Arrays in different signatures; for example, if you have both of the following functions: foo(int[] x) and foo(String[] strs).
• The method parameter requires a class array in its signature; for example, foo(com.x.y.MyClass[]).
• The method parameter requires an Object in its signature and you need to pass an array of any particular type.

The following example shows the use of the JavaCast cunction to cast arrays:

You might have a fooClass class that defines the following two methods, each with two arguments where the first argument differs in the type of the array:

public class fooClass {
 public fooClass () {
 }
 public String foo(long[] arg) {
return "Argument was a long array";
 }
 public String foo(int[] arg) {
return "Argument was an Integer array";
 }
}

To be able to use these functions in your CFML, you must use the JavaCast function to convert the ColdFusion Arrray to the array type required by one of the functions, as shown in the following code snippet:

<cfset arr = [1,2,4,20,10]>
<cfset fooObj = createObject("java", "fooClass")>

<cfset fooObj.foo(javacasr("int[]", arr))>
<cfset fooObj.foo(javacast("long[]", arr))>

Example

The method fooMethod in the class fooClass takes one overloaded argument. The fooClass class is defined as follows:

public class fooClass {
    public fooClass () {
    }
    public String fooMethod(String arg) {
        return "Argument was a String";
    }
    public String fooMethod(int arg) {
        return "Argument was an Integer";
    }

}

Within ColdFusion, you use the following code:

<cfobject
action="create"
type = "java"
class = "fooClass" 
name = obj>

<!--- ColdFusion can treat this as a string or a real number --->
<cfset x = 33>

Perform an explicit cast to an int and call fooMethod:<br>
<cfset myInt = JavaCast("int", x)> 
<cfoutput>#obj.fooMethod(myInt)#</cfoutput>
<br><br>
Perform an explicit cast to a string and call fooMethod:<br>
<cfset myString = javaCast("String", x)> 
<cfoutput>#obj.fooMethod(myString)#</cfoutput>