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