duke@1: duke@1: duke@1:
duke@1: duke@1: duke@1: duke@1: duke@1:Provides classes and interfaces that enable traversal of the data value
duke@1: associated with an any
at
duke@1: runtime, and extraction of the primitive constituents of the data value.
duke@1:
duke@1:
duke@1:
An any
can be passed to a program that doesn't have any static information
duke@1: for the type of the any
(code generated for the type by an IDL compiler has not
duke@1: been compiled with the object implementation). As a result, the object receiving the
duke@1: any
does not have a portable method of using it.
duke@1:
duke@1:
DynAny
s enable traversal of the data value associated with an
duke@1: any
at runtime, and extraction of the primitive constituents of the data value.
duke@1: This is especially helpful for writing powerful generic servers (bridges, event channels
duke@1: supporting filtering). Similarly, this facility enables the construction of an
duke@1: any
at runtime, without having static knowledge of its type. This is especially
duke@1: helpful for writing generic clients (bridges, browsers, debuggers, user interface tools).
duke@1:
duke@1:
Any
values can be dynamically interpreted (traversed) and constructed through
duke@1: DynAny objects. A DynAny object is associated with a data
duke@1: value which corresponds to a copy of the value inserted into an Any. A
duke@1: DynAny object may be viewed as an ordered collection of component
duke@1: DynAnys. For DynAnys representing a basic type, such as long
,
duke@1: or a type without components, such as an empty exception, the ordered collection of
duke@1: components is empty.
duke@1:
duke@1:
Each DynAny object maintains the notion of a current position into its collection
duke@1: of component DynAnys. The current position is identified by an index value that runs
duke@1: from 0 to n-1, where n is the number of components. The special index value -1
duke@1: indicates a current position that points nowhere.
duke@1: For values that cannot have a current position (such as an empty exception),
duke@1: the index value is fixed at -1.
duke@1: If a DynAny
is initialized with a value that has components, the index is
duke@1: initialized to 0.
duke@1: After creation of an uninitialized DynAny
(that is, a DynAny
that
duke@1: has no value but a TypeCode
duke@1: that permits components), the current position depends on the type of value represented by
duke@1: the DynAny
. (The current position is set to 0 or -1, depending on whether the
duke@1: new DynAny
duke@1: gets default values for its components.)
duke@1:
duke@1:
duke@1:
The iteration operations rewind
, seek
, and next
duke@1: can be used to change the current position
duke@1: and the current_component
operation returns the component at the current
duke@1: position.
duke@1: The component_count
operation returns the number of components of a
duke@1: DynAny
.
duke@1: Collectively, these operations enable iteration over the components of a
duke@1: DynAny
, for example,
duke@1: to (recursively) examine its contents.
duke@1:
duke@1:
duke@1:
A constructed DynAny
object is a DynAny
object associated with
duke@1: a constructed type.
duke@1: There is a different interface, inheriting from the DynAny
interface,
duke@1: associated with
duke@1: each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array,
duke@1: exception, and value type). A constructed DynAny
object exports operations
duke@1: that enable the creation of new DynAny
objects,
duke@1: each of them associated with a component of the constructed data value.
duke@1: As an example, a DynStruct
is associated with a struct
value. This
duke@1: means that the DynStruct
duke@1: may be seen as owning an ordered collection of components, one for each structure member.
duke@1: The DynStruct
object exports operations that enable the creation of new
duke@1: DynAny
objects,
duke@1: each of them associated with a member of the struct
.
duke@1:
duke@1:
duke@1:
If a DynAny
object has been obtained from another (constructed)
duke@1: DynAny
object,
duke@1: such as a DynAny
representing a structure member that was created from a
duke@1: DynStruct
,
duke@1: the member DynAny
is logically contained in the DynStruct
.
duke@1: Calling an insert
or get
operation leaves the current position
duke@1: unchanged.
duke@1: Destroying a top-level DynAny
object (one that was not obtained as a component
duke@1: of another DynAny
)
duke@1: also destroys any component DynAny
objects obtained from it.
duke@1: Destroying a non-top level DynAny
object does nothing.
duke@1: Invoking operations on a destroyed top-level DynAny
or any of its descendants
duke@1: raises OBJECT_NOT_EXIST.
duke@1: If the programmer wants to destroy a DynAny
object but still wants to
duke@1: manipulate some component
duke@1: of the data value associated with it, then he or she should first create a
duke@1: DynAny
for the component
duke@1: and, after that, make a copy of the created DynAny
object.
duke@1:
duke@1:
duke@1:
The behavior of DynAny
objects has been defined in order to enable efficient
duke@1: implementations
duke@1: in terms of allocated memory space and speed of access. DynAny
objects are
duke@1: intended to be used
duke@1: for traversing values extracted from any
s or constructing values of
duke@1: any
s at runtime.
duke@1: Their use for other purposes is not recommended.
duke@1:
duke@1:
duke@1:
duke@1:
Insert
and get
operations are necessary to handle basic
duke@1: DynAny
objects
duke@1: but are also helpful to handle constructed DynAny
objects.
duke@1: Inserting a basic data type value into a constructed DynAny
object
duke@1: implies initializing the current component of the constructed data value
duke@1: associated with the DynAny
object. For example, invoking
duke@1: insert_boolean
on a
duke@1: DynStruct
implies inserting a boolean
data value at the current
duke@1: position
duke@1: of the associated struct
data value.
duke@1: A type is consistent for inserting or extracting a value if its TypeCode
is
duke@1: equivalent to
duke@1: the TypeCode
contained in the DynAny
or, if the
duke@1: DynAny
has components, is equivalent to the TypeCode
duke@1: of the DynAny
at the current position.
duke@1:
duke@1:
Basic operations include: duke@1:
duke@1:
DynAny
and DynAnyFactory
objects are intended to be local to
duke@1: the process in which they are
duke@1: created and used. This means that references to DynAny
and
duke@1: DynAnyFactory
objects cannot be exported
duke@1: to other processes, or externalized with ORB.object_to_string()
.
duke@1: If any attempt is made to do so, the offending operation will raise a MARSHAL system
duke@1: exception.
duke@1: Since their interfaces are specified in IDL, DynAny
objects export operations
duke@1: defined in the standard
duke@1: org.omg.CORBA.Object
interface. However, any attempt to invoke operations
duke@1: exported through the Object
duke@1: interface may raise the standard NO_IMPLEMENT exception.
duke@1: An attempt to use a DynAny
object with the DII may raise the NO_IMPLEMENT
duke@1: exception.
duke@1:
duke@1:
duke@1:
duke@1:
duke@1:
duke@1:
duke@1:
duke@1: duke@1: duke@1:
For a precise list of supported sections of official specifications with which duke@1: the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA duke@1: support in Java[tm] SE 6. duke@1:
duke@1: @since 1.4
duke@1:
duke@1: @serial exclude
duke@1:
duke@1: