Chapter 18
Type any

18.1 Using Insertion Methods to Construct an Any
18.2 Using Extraction Methods to Interpret an Any
18.3 Inserting and Extracting Array Types
18.4 Any Constructors and Additional Methods
18.5 Any as a Parameter or Return Value

This chapter gives the details of the IDL type any, and the corresponding Java class Any (defined in package IE.Iona.Orbix2.CORBA), which is used to indicate that a value of an arbitrary type can be passed as a parameter or a return value.

Consider the following interface:

 // IDL
 interface Test {
 	void op (in any a);
 };

A client can construct an any to contain any type of value which can be specified in IDL and then pass this in a call to operation op(). An application receiving an any must determine what type of value it stores and then extract the value.

The IDL type any maps to the Java class Any. The full public specification of this class can be found in Part II, "Class and Interface Reference" in the OrbixWeb Reference Guide. Conceptually, this class contains two instance variables: type and value. The type is a TypeCode and indicates what the type the any is, and the value of the any is stored in a byte array format. Class Any provides two data accessor methods (type() and value()) which allow these values to be retrieved.

Note that the value() method returns an array of bytes and not an object of the actual type specified by method type(). A set of insertion and extraction methods are provided to allow applications to manipulate the any value with respect to its actual type. These methods will be described in full in this chapter.

18.1 Using Insertion Methods to Construct an Any

The Java class Any contains a number of insertion methods which can be used to assign a value to an any. An insertion method is provided for each of the basic IDL types such as long, unsigned long, float, double, and string. These insertion methods are named insertLong, insertULong, insertFloat, and so on.

A single-element insertion method simply takes the element value as a parameter. For example, the signature of Any.insertLong() is as follows:

 public void insertLong(int l) 
 			throws SystemException;

Class Any also provides an insert() method, which supports the assignment of user-defined types to the any. Java classes generated for user-defined types inherit from the OrbixWeb interface Marshalable, so the signature for insert() can be defined as:

 public void insert(Marshalable m) 
 			throws SystemException;

Enumerated IDL types map directly to Java type int and therefore present a special case of user-defined types. These are discussed in section 18.1.1.

It is important to note that a specific user-defined type can only be inserted into an any if the IDL compiler -A switch was specified during compilation of its IDL definition.

Consider the following IDL definition:

 // IDL
 typedef sequence<long, 10> longSeq;
 
 struct Foo {
 	string bar;
 	float number;
 };
 
 interface Flexible {
 	void doit (in any a);
 };

Let us assume that a client programmer wishes to pass an any containing an IDL short as the parameter to the doit() operation. The following insertion method, which is a member of class Any, may be used:

 // Java
 public void insertShort(short s) 
 			throws SystemException;

So the client programmer can write the following code:

 // Java
 // in file Client.java,
 // in class Client
 
 _FlexibleRef fRef;
 IE.Iona.Orbix2.CORBA.Any param;
 short toPass = 26;
 
 try {
 	fRef = Flexible._bind ();
 
 	param = new Any();
 	param.insertShort (toPass);
 
 	fRef.doit (param);
 }
 catch (SyetemException se) {
 	...
 }

If the client wishes to pass a more complex user-defined type, such as longSeq or Foo defined above, the generic insert() method can be used. For example, the client programmer might write:

 // Java
 // in file Client.java,
 // in class Client
 
 _FlexibleRef fRef;
 IE.Iona.Orbix2.CORBA.Any param;
 Foo toPass = new Foo ();
 
 toPass.bar = "Bar";
 toPass.number = (float) 34.5;
 
 try {
 	fRef = Flexible._bind ();
 
 	param = new IE.Iona.Orbix2.CORBA.Any();
 	param.insert (toPass);
 
 	fref.doit (param);
 }
 catch (SystemException se) {
 	...
 }

These insertion methods generally provide a type-safe mechanism for insertion into an any. Both the type and value of the Any are assigned at insertion. If an attempt is made to insert a value which has no corresponding IDL type, this will result in a compile-time error.

If a Any holds a previous value when an insertion method is called, the old type and value will be replaced by the new. Class Any also provides a reset() method, which allows the type and value to be cleared explicitly.

18.1.1 Insertion of IDL Enumerated Types

Enumerated IDL types map directly to Java type int, as described in section 5.11. As such, they cannot be inserted into an any using the generic insertion method for insertion of user-defined types.

Instead, the insertion must be carried out in two stages: first the enumeration value should be inserted as an IDL long, then the type of the any should be set to the automatically generated TypeCode constant for the enumerated type.

The enumeration value can be inserted using the standard insertion method for IDL type long:

 public void insertLong(int l) 
 			throws SystemException;

Type Any supports the method setTypeCode() which can be used to set the type after the insertion of the value:

 public void setTypeCode(TypeCode tc);

For example, consider the following IDL enumerated type:

 // IDL
 enum Colour { blue, green };

This maps to Java type int. The Java class Colour is generated, to support the assignment of the named enumeration values:

 // Java
 // Automatically generated
 // in file Colour.java
 public class Colour {
 	public static final int blue = 0;
 	public static final int green = 1;
 
 	...
 }

A client programmer who wishes to assign an enum of type Colour into an any could do the following:

 // Java
 // in file Client.java,
 // in class Client
 
 IE.Iona.Orbix2.CORBA.Any param = 
 	new IE.Iona.Orbix2.CORBA.Any ();
 int enumToPass = Colour.blue;
 
 try {
 	param.insertLong (enumToPass);
 	param.setTypeCode (Colour._tc_Colour);
 }
 catch (SystemException se) {
 	...
 }

18.2 Using Extraction Methods to Interpret an Any

The Java class Any contains a number of extraction methods which can be used to extract values from an any. These operators correspond to the basic IDL types such as long, unsigned long, float, double, and string. These extraction methods are named extractLong(), extractULong(), extractFloat(), and so on. Each extraction method simply returns a value of the appropriate type.

Class Any also provides an extract() method, which supports the extraction of all user-defined types from an any. Unlike the other extraction methods, extract() takes a single parameter which must hold a pre-allocated variable of the appropriate user-defined type. The signature of this method is as follows:

 public void extract(Marshalable m) 
 			throws SystemException;

As indicated in the previous section, such user-defined types may only be stored in an any if the IDL compiler -A switch is specified during the compilation of their IDL definitions.

The following example IDL can be used to illustrate the use of extraction methods:

 // IDL
 typedef sequence<long, 10> longSeq;
 
 interface Versatile {
 	any getit ();
 };

An OrbixWeb programmer can extract a simple type from an any as follows:

 // Java
 // in file Client.java,
 // in class Client
 
 _VersatileRef vRef;
 IE.Iona.Orbix2.CORBA.Any rv;
 short toReceive;
 
 try {
 	vRef = Versatile._bind ();
 
 	rv = vRef.getit ();
 
 	// extract a short value
 	if ((rv.type()).kind() == 
 		IE.Iona.Orbix2.CORBA.TCKind.tk_short) {
 		toReceive = rv.extractShort ();
 	}
 }
 catch (SystemException se) {
 	...
 }

A sequence of type longSeq could be extracted from an any in the following manner:

 // Java
 // in file Client.java,
 // in class Client
 
 _VersatileRef vRef;
 IE.Iona.Orbix2.CORBA.Any rv;
 longSeq toReceive;
 
 try {
 	vRef = Versatile._bind ();
 
 	rv = vRef.getit ();
 
 	// extract a sequence of longs
 	if ((rv.type()).equals(longSeq._tc_longSeq)) {
 		toReceive = new longSeq (10);
 		rv.extract (toReceive);
 	}
 }
 catch (Systemexception se) {
 	...
 }

OrbixWeb does not destroy the value of an any after extraction; a programmer may therefore extract the value of an any more than once. However, if the value of an any has been extracted (using one of the extraction methods) then the position of the extraction index into the any value must be reset before the value can be extracted a second time. This can be achieved by calling the method resetPosition() on the Any object.

18.3 Inserting and Extracting Array Types

To support the insertion of arrays of each IDL type into an any, a set of array insertion methods are supplied. The name of each array insertion method is similar to that of the equivalent single-element insert method, with the word Array appended. For example, the array insertion method for type long is named insertLongArray(), while the generic method for the insertion of arrays of user-defined types is insertArray().

An array insertion method takes the array value and array length as parameters. For example, the signature of insertLongArray() is as follows:

 public void insertLongArray(int l[], int length) 
 			throws SystemException;

The extraction of arrays of IDL types from an any is also supported. For this purpose, class Any includes a set of array extraction methods. These methods include extractLongArray(), whose signature can be described as:

 public int extractLongArray(int l[],int length)  
 			throws SystemException;

Note that each of the array extraction methods takes two parameters: an array of the appropriate type, and the length of the incoming array. The array parameter must be a pre-allocated array of sufficient length to hold the value of the any. If the length parameter is less than the length of the any array value, OrbixWeb will throw a system exception of type BAD_PARAM. The extraction method returns the actual length of the array extracted from the any.

18.4 Any Constructors and Additional Methods

In addition to the functionality already described, the Java class Any contains:

A default constructor.
A copy constructor.
A constructor which takes a single integer argument.
A copy constructor which takes an additional integer argument.
A copy() method.
A clone() method.
An equals() method.
A toString() method.

The default constructor creates a Any with a TypeCode of kind tk_null and no value.

The copy constructor calls makes a deep copy of the Any parameter.

The two constructors which each take an additional integer argument allow the programmer to specify the marshalling protocol for the Any during construction. Programmers who wish to pass Anys as parameters to operations using the CORBA Internet Inter-ORB Protocol (IIOP) should refer to section 9.2.4 for a detailed description of the functionality of these constructors.

The toString() method simply returns a string of the form:

 "Any with typecode <typecode>"

18.5 Any as a Parameter or Return Value

The mapping for IDL any operation parameters and return value are illustrated by the following IDL operation:

 // IDL
 any op1 (in any a1, out any a2, inout any a3);

maps to:

 // Java
 public IE.Iona.Orbix2.CORBA.Any op1 (
 	IE.Iona.Orbix2.CORBA.Any a1, 
 	IE.Iona.Orbix2.CORBA.Any a2, 
 	IE.Iona.Orbix2.CORBA.Any a3);

Both return values and parameters (of all parameter passing modes) map directly to type Any for reasons highlighted in section 5.21.

[Roadmap] [Introduction] [GS: Applications] [GS: Applets]
[IDL] [Mapping] [Programming OrbixWeb] [Publishing Objects] [Retrieving Objects] [IIOP]
[Running Clients] [Running Servers] [Exceptions] [Inheritance] [Callbacks] [Contexts]
[API Configuration] [TypeCode] [Any] [DII] [IR] [Filters] [Smart Proxies] [Loaders] [Locators]
[Index]

Chapter 18 Type any