Developing ColdFusion MX Applications with CFML Previous Up One Level Next Home Search
Integrating COM and CORBA Objects in CFML Applications


Creating and using CORBA objects

The following sections describe how to create, or instantiate, a CORBA object and how to use it in your ColdFusion application.

Creating CORBA objects

The cfobject tag and CreateObject functions create in ColdFusion a stub, or proxy object, for the CORBA object on the remote server. You use this stub object to invoke the remote object.

The following table describes the attributes you use in the cfobject tag to create a CORBA object:
Attribute
Description
type
Must be CORBA. COM is the default.
context
Specifies the CORBA binding method, that is, how the object is obtained, as follows:
  • IOR Uses a file containing the object's unique Interoperable Object Reference.
  • NameService Uses a naming service.
class
Specifies the information required for the binding method to access the object.
If you set the context attribute to IOR, The class attribute must be to the full pathname of a file containing the string version of the IOR. ColdFusion must be able to read this IOR file at all times, so make it local to the server or put it on the network in an accessible location.
If you set the context attribute to NameService, The class attribute must be a name delimited by forward slashes (/), such as MyCompany/Department/Dev. You can use period-delimited "kind" identifiers as part of the class attribute; for example, Macromedia.current/Eng.current/CF"
name
Specifies the name (handle) that your application uses to call the object's interface.
locale
(Optional) Identifies the connector configuration. You can omit this option if ColdFusion Administrator has only one connector configuration, or if it has multiple connector configurations and you want to use the one that is currently selected in the Administrator. If you specify this attribute, it must be an ORB name you specified in the CORBA Connector ORB Name field when you configured a CORBA connector in ColdFusion Administrator; for example, Visibroker.

For example, use the following CFML to invoke a CORBA object specified by the tester.ior file if you configured your ORB name as Visibroker: 

<cfobject  action = "create" type = "CORBA" context = "IOR" 
class = "d:\temp\tester.ior" name = "handle" locale = "Visibroker">

When you use the CreateObject function to invoke this CORBA object, specify the name as the function return variable, and specify the type, class, context, and locale as arguments. For example, the following line creates the same object as the preceding cfobject tag: 

handle = CreateObject("CORBA", "d:\temp\tester.ior", "IOR", "Visibroker")

For the complete cfobject and CreatObject syntax, see CFML Reference.

Using a naming service

Currently, ColdFusion can only resolve objects registered in a CORBA 2.3-compliant naming service.

If you use a naming service, make sure that its naming context is identical to the naming context specified in the property file of the Connector configuration in use, as specified in the ColdFusion Administrator CORBA Connectors page. The property file must contain the line "SVCnameroot=name" where name is the naming context to be used. The server implementing the object must bind to this context, and register the appropriate name.

Using CORBA objects in ColdFusion

After you create the object, you can invoke attributes and operations on the object using the syntax described in "Creating and using objects". The following sections describe the rules for using CORBA objects in ColdFusion pages. They include information on using methods in ColdFusion, which IDL types you can access from ColdFusion, and the ColdFusion data types that correspond to the supported IDL data types.

Using CORBA interface methods in ColdFusion

When you use the cfobject tag or the CreateObject function to create a CORBA object, ColdFusion creates a handle to a CORBA interface, which is identified by the cfobject name attribute or the CreateObject function return variable. For example, the following CFML creates a handle named myHandle: 

<cfobject  action = "create" type = "CORBA" context = "IOR" 
class = "d:\temp\tester.ior" name = "myHandle" locale="visibroker">
<cfset myHandle = CreateObject("CORBA", "d:\temp\tester.ior", "IOR", "visibroker")

You use the handle name to invoke all of the interface methods, as in the following CFML: 

<cfset ret=myHandle.method(foo)>

The following sections describe how to call CORBA methods correctly in ColdFusion.

Method name case considerations

Method names in IDL are case-sensitive. However, ColdFusion is case-insensitive. Therefore, do no use methods that differ only in case in IDL.

For example, the following IDL method declarations correspond to two different methods: 

testCall(in string a); // method #1
TestCall(in string a); // method #2

However, ColdFusion cannot differentiate between the two methods. If you call either method, you cannot be sure which of the two will be invoked.

Passing parameters by value (in parameters)

CORBA in parameters are always passed by value. When calling a CORBA method with a variable in ColdFusion, specify the variable name without quotes, as shown in the following example:
IDL
 
void method(in string a);
CFML
 
<cfset foo="my string">
<cfset ret=handle.method(foo)>

Passing variables by reference (out and inout parameters)

CORBA out and inout parameters are always passed by reference. As a result, if the CORBA object modifies the value of the variable that you pass when you invoke the method, your ColdFusion page gets the modified value.

To pass a parameter by reference in ColdFusion, specify the variable name in double quotes in the CORBA method. The following example shows an IDL line that defines a method with a string variable, b, that is passed in and out of the method by reference. It also shows CFML that calls this method.
IDL
 
void method(in string a, inout string b);
CFML
 
<cfset foo = "My Initial String">
<cfset ret=handle.method(bar, "foo")>
<cfoutput>#foo#</cfoutput>

In this case, the ColdFusion variable foo corresponds to the inout parameter b. When the CFML executes, the following happens:

  1. ColdFusion calls the method, passing it the variable by reference.
  2. The CORBA method replaces the value passed in, "My Initial String", with some other value. Because the variable was passed by reference, this modifies the value of the ColdFusion variable.
  3. The cfoutput tag prints the new value of the foo variable.

Using methods with return values

Use CORBA methods that return values as you would any ColdFusion function; for example:
IDL
 
double method(out double a);
CFML
 
<cfset foo=3.1415>
<cfset ret=handle.method("foo")>
<cfoutput>#ret#</cfoutput>

Using IDL types with ColdFusion variables

The following sections describe how ColdFusion supports CORBA data types. They include a table of supported IDL types and information about how ColdFusion converts between CORBA types and ColdFusion data.

IDL Support

The following table shows which CORBA IDL types ColdFusion supports, and whether they can be used as parameters or return variables. (NA means not applicable.)
CORBA IDL type
General support
As parameters
As return value
constants
No
No
No
attributes
Yes (for properties)
NA
NA
enum
Yes (as an integer)
Yes
Yes
union
No
No
No
sequence
Yes
Yes
Yes
array
Yes
Yes
Yes
interface
Yes
Yes
Yes
typedef
Yes
NA
NA
struct
Yes
Yes
Yes
module
Yes
NA
NA
exception
Yes
NA
NA
any
No
No
No
boolean
Yes
Yes
Yes
char
Yes
Yes
Yes
wchar
Yes
Yes
Yes
string
Yes
Yes
Yes
wstring
Yes
Yes
Yes
octet
Yes
Yes
Yes
short
Yes
Yes
Yes
long
Yes
Yes
Yes
float
Yes
Yes
Yes
double
Yes
Yes
Yes
unsigned short
Yes
Yes
Yes
unsigned long
Yes
Yes
Yes
longlong
No
No
No
unsigned longlong
No
No
No
void
Yes
NA
Yes

Data type conversion

The following table lists IDL data types and the corresponding ColdFusion data types:
IDL type
ColdFusion type
boolean
Boolean
char
One-character string
wchar
One-character string
string
String
wstring
String
octet
One-character string
short
Integer
long
Integer
float
Real number
double
Real number
unsigned short
Integer
unsigned long
Integer
void
Not applicable (returned as an empty string)
struct
Structure
enum
Integer, where 0 corresponds to the first enumerator in the enum type
array
Array (must match the array size specified in the IDL)
sequence
Array
interface
An object reference
module
Not supported (cannot dereference by module name)
exception
ColdFusion throws an exception of type coldfusion.runtime.corba.CorbaUserException
attribute
Object reference using dot notation

Boolean data considerations

ColdFusion treats any of the following as Boolean values:
True
"yes", "true", or 1
False
"no", "false", or 0

You can use any of these values with CORBA methods that take Boolean parameters, as the following code shows:
IDL
 
module Tester
  {
  interface TManager
  {
    void testBoolean(in boolean a);
    void testOutBoolean(out boolean a);
    void testInoutBoolean(inout boolean a);
    boolean returnBoolean();
  }
}
CFML
 
<CFSET handle = CreateObject("CORBA", "d:\temp\tester.ior", "IOR", "") >
<cfset ret = handle.testboolean("yes")>
<cfset mybool = True>
<cfset ret = handle.testoutboolean("mybool")>
<cfoutput>#mybool#</cfoutput>

<cfset mybool = 0>
<cfset ret = handle.testinoutboolean("mybool")>
<cfoutput>#mybool#</cfoutput>

<cfset ret = handle.returnboolean()>
<cfoutput>#ret#</cfoutput>

Struct data type considerations

For IDL struct types, use ColdFusion structures. You can prevent errors by using the same case for structure key names in ColdFusion as you do for the corresponding IDL struct field names.

Enum type considerations

ColdFusion treats the enum IDL type as an integer with the index starting at 0. As a result, the first enumerator corresponds to 0, the second to 1, and so on. In the following example, the IDL enumerator a corresponds to 0, b to 1 and c to 2:
IDL
 
module Tester
{
  enum EnumType {a, b, c};
  interface TManager
  {
    void testEnum(in EnumType a);
    void testOutEnum(out EnumType a);
    void testInoutEnum(inout EnumType a);
    EnumType returnEnum();
  }
}
CFML
 
<CFSET handle = CreateObject("CORBA", "d:\temp\tester.ior", "IOR", "") >
<cfset ret = handle.testEnum(1)>

In this example, the CORBA object gets called with the second (not first) entry in the enumerator, a.

Double-byte character considerations

If you are using an ORB that supports CORBA later than version 2.0, you do not have to do anything to support double-byte characters. Strings and characters in ColdFusion will appropriately convert to wstring and wchar when they are used. However, the CORBA 2.0 IDL specification does not support the wchar and wstring types, and uses the 8-bit Latin-1 character set to represent string data. In this case, you cannot pass parameters containing those characters, however, you can call parameters with char and string types using ColdFusion string data.

Handling exceptions

Use the cftry and cfcatch tags to catch CORBA object method exceptions thrown by the remote server, as follows:

  1. Specify type="coldfusion.runtime.corba.CorbaUserException" in the cfcatch tag to catch CORBA exceptions.
  2. Use the cfcatch.getContents method to get the contents of the exception object.

The the cfcatch.getContents method returns a ColdFusion structure containing the data specified by the IDL for the exception.

The following code example shows the IDL for a CORBA object that raises an exception defined by the PrimitiveException exception type definition, and the CFML that catches the exception and displays the contents of the object.
IDL
 
interface myInterface
{
  exception PrimitiveException
  {
    long l; 
    string s; 
    float f;
  };
  void testPrimitiveException() raises (PrimitiveException);

}

CFML
 
<cftry> 
  <cfset ret0 = handle.testPrimitiveException()>
  <cfcatch type=coldfusion.runtime.corba.CorbaUserException>
    <cfset exceptStruct= cfcatch.getContents()>
    <cfdump var ="#exceptStruct#"> 
  </cfcatch>
</cftry>

Copyright © 2002, Macromedia Inc. All rights reserved. Previous Up Next Home Search

Comments