Java(TM) 2 Platform, Standard Edition, v1.2.2 API Specification: Interface DynAny

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Java^TM 2 Platform
Standard Edition

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynAny

All Known Subinterfaces:: DynArray, DynEnum, DynFixed, DynSequence, DynStruct, DynUnion, DynValue

public interface DynAny
extends Object

An object that enables the dynamic management of Any values. A DynAny object allows a program to use an Any object when the program has no static information about the type of the Any object. The DynAny interface provides methods for traversing the data value associated with an Any object at run time and for extracting the primitive constituents of the data value.

A DynAny object is associated with a data value that may correspond to a copy of the value inserted into an Any object. The DynAny object may be seen as owning a pointer to an external buffer that holds some representation of the data value.

For data values that are constructed types (IDL struct, sequence, array, union, and so on), the DynAny object also can be thought of as holding a pointer to a buffer offset where the current component of the constructed type is being represented. The buffer pointer effectively points to the space used to represent the first component of the data value when the programmer creates the DynAny object. Calling the DynAny method next will move the pointer to the next component, making it possible to iterate through the components of a constructed data value. The buffer pointer is moved back to the first component each time the method rewind is called.

DynAny methods make it possible to do the following:

Obtain the type code associated with a DynAny object
Initialize a DynAny object from another DynAny object
Initialize a DynAny object from an Any value
Generate an Any value from a DynAny object
Destroy a DynAny object
Create a copy of a DynAny object
Access a value of some basic type in a DynAny object
Iterate through components of a DynAny object

Inserting a basic data type value into a constructed DynAny object implies initializing the next component of the constructed data value associated with the DynAny object. For example, invoking the method insert_boolean in a DynStruct implies inserting a boolean data value as the next member of the associated struct data value.

Creating a DynAny object can be done by:

invoking a method on an existing DynAny object
invoking an org.omg.CORBA.ORB method (create_dyn_any, create_dyn_struct, create_dyn_sequence, and so on)

Dynamic creation of an Any object containing a value of a basic data type typically involves the following:

Creating a DynAny object using ORB.create_basic_dyn_any, passing it the type code associated with the basic data type value to be created
Initializing the value by means of invoking methods on the resulting DynAny object (insert_boolean if the DynAny is of type boolean, for example)
Creating the Any object by invoking the method to_any on the initialized DynAny object

Dynamic creation of an Any object containing a value of a constructed data type typically involves the following:

Creating a DynAny object using the appropriate ORB method (for example, ORB.create_dyn_struct for an IDL struct), passing it the type code associated with the constructed data type value to be created
Initializing components of the value by means of:
- invoking methods on the resulting DynStruct (or other constructed type) object
  - call the method current_component to get a DynAny object for that component
  - call the appropriate insert method on the DynAny object returned by the method current_component to initialize the component
  - call the method next to move to the next component and continue to get the current component, initialize it, and move to the next component until there are no more components (the method next returns false)
- or invoking methods on the DynAny objects generated for each member of the constructed type
Creating the Any object by invoking the method to_any on the initialized DynAny object

DynAny objects are intended to be local to the process in which they are created and used. Any method that attempts to export references to DynAny objects to other processes or to externalize them with the method org.omg.CORBA.ORB.object_to_string will throw a MARSHAL exception. Also, even though DynAny objects are derived from the interface Object, invoking methods from Object will throw the NO_IMPLEMENT exception. An attempt to use a DynAny object with the DII (Dynamic Invocation Interface) may throw a NO_IMPLEMENT exception.

The following classes are derived from DynAny and define additional methods relevant to their particular IDL type: DynFixed, DynStruct, DynSequence, DynArray, DynUnion, DynEnum, DynAny, and DynValue.

Method Summary

void assign(DynAny dyn_any)
          Initializes the value associated with this DynAny object with the value associated with the given DynAny object.

DynAny copy()
          Clone this DnyAny.

DynAny current_component()
          Returns a DynAny object reference that can be used to get/set the value of the component currently accessed.

void destroy()
          Destroys this DynAny object and frees any resources used to represent the data value associated with it.

void from_any(Any value)
          Initializes the value associated with this DynAny object with the value associated with the given Any object.

Any get_any()
          Retrieves the org.omg.CORBA.Any contained in this DynAny object.

boolean get_boolean()
          Retrieves the boolean contained in this DynAny object.

char get_char()
          Retrieves the char contained in this DynAny object.

double get_double()
          Retrieves the double contained in this DynAny object.

float get_float()
          Retrieves the float contained in this DynAny object.

int get_long()
          Retrieves the int contained in this DynAny object.

long get_longlong()
          Retrieves the long contained in this DynAny object.

byte get_octet()
          Retrieves the byte contained in this DynAny object.

Object get_reference()
          Retrieves the org.omg.CORBA.Other contained in this DynAny object.

short get_short()
          Retrieves the short contained in this DynAny object.

String get_string()
          Retrieves the String contained in this DynAny object.

TypeCode get_typecode()
          Retrieves the org.omg.CORBA.TypeCode contained in this DynAny object.

int get_ulong()
          Retrieves the int contained in this DynAny object.

long get_ulonglong()
          Retrieves the long contained in this DynAny object.

short get_ushort()
          Retrieves the short contained in this DynAny object.

Serializable get_val()
          Retrieves the java.io.Serializable object contained in this DynAny object.

char get_wchar()
          Retrieves the char contained in this DynAny object.

String get_wstring()
          Retrieves the String contained in this DynAny object.

void insert_any(Any value)
          Inserts the given org.omg.CORBA.Any object as the value for this DynAny object.

void insert_boolean(boolean value)
          Inserts the given boolean as the value for this DynAny object.

void insert_char(char value)
          Inserts the given char as the value for this DynAny object.

void insert_double(double value)
          Inserts the given double as the value for this DynAny object.

void insert_float(float value)
          Inserts the given float as the value for this DynAny object.

void insert_long(int value)
          Inserts the given int as the value for this DynAny object.

void insert_longlong(long value)
          Inserts the given long as the value for this DynAny object.

void insert_octet(byte value)
          Inserts the given byte as the value for this DynAny object.

void insert_reference(Object value)
          Inserts the given org.omg.CORBA.Object as the value for this DynAny object.

void insert_short(short value)
          Inserts the given short as the value for this DynAny object.

void insert_string(String value)
          Inserts the given String object as the value for this DynAny object.

void insert_typecode(TypeCode value)
          Inserts the given org.omg.CORBA.TypeCode as the value for this DynAny object.

void insert_ulong(int value)
          Inserts the given int as the value for this DynAny object.

void insert_ulonglong(long value)
          Inserts the given long as the value for this DynAny object.

void insert_ushort(short value)
          Inserts the given short as the value for this DynAny object.

void insert_val(Serializable value)
          Inserts the given java.io.Serializable object as the value for this DynAny object.

void insert_wchar(char value)
          Inserts the given char as the value for this DynAny object.

void insert_wstring(String value)
          Inserts the given String as the value for this DynAny object.

boolean next()
          Moves to the next component of this DynAny object.

void rewind()
          Moves the internal pointer to the first component.

boolean seek(int index)
          Moves the internal pointer to the given index.

Any to_any()
          Creates an Any object from this DynAny object.

TypeCode type()
          Retrieves the TypeCode object contained in this DynAny object.

Methods inherited from interface org.omg.CORBA.Object

_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

type

public TypeCode type()

Retrieves the TypeCode object contained in this DynAny object. Note that the type code associated with a DynAny object is initialized at the time DynAny is created and cannot be changed during the lifetime of the DynAny object.

Returns:: the TypeCode object describing the value contained in this DynAny object

assign

public void assign(DynAny dyn_any)
            throws Invalid

Initializes the value associated with this DynAny object with the value associated with the given DynAny object.

Parameters:: dyn_any - the DynAny object whose value will be used to initialize this DynAny object
Throws:: org.omg.CORBA.DynAnyPackage.Invalid - if the given DynAny object has a type code that is not equivalent or has not been assigned a value

from_any

public void from_any(Any value)
              throws Invalid

Initializes the value associated with this DynAny object with the value associated with the given Any object.

Parameters:: value - the Any object whose value will be used to initialize this DynAny object
Throws:: org.omg.CORBA.DynAnyPackage.Invalid - if the given Any object has a type code that is not equivalent or has not been assigned a value

to_any

public Any to_any()
           throws Invalid

Creates an Any object from this DynAny object. The type code and value of this DynAny object are copied into the newly-created Any object.

Returns:: the newly-created Any object
Throws:: org.omg.CORBA.DynAnyPackage.Invalid - if this DynAny object has not been correctly created or does not contain a meaningful value

destroy

public void destroy()

Destroys this DynAny object and frees any resources used to represent the data value associated with it. This method also destroys all DynAny objects obtained from it.

Destruction of DynAny objects should be handled with care, taking into account issues dealing with the representation of data values associated with DynAny objects. A programmer who wants to destroy a DynAny object but still be able to manipulate some component of the data value associated with it, should first create a DynAny object for the component and then make a copy of the created DynAny object.

copy

public DynAny copy()

Clone this DnyAny.

Returns:: the DynAny.