0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
157N/A Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A This code is free software; you can redistribute it and/or modify it 0N/A under the terms of the GNU General Public License version 2 only, as 157N/A published by the Free Software Foundation. Oracle designates this 0N/A particular file as subject to the "Classpath" exception as provided 157N/A by Oracle in the LICENSE file that accompanied this code. 0N/A This code is distributed in the hope that it will be useful, but WITHOUT 0N/A ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A version 2 for more details (a copy is included in the LICENSE file that 0N/A accompanied this code). 0N/A You should have received a copy of the GNU General Public License version 0N/A 2 along with this work; if not, write to the Free Software Foundation, 0N/A Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 157N/A Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="white">
0N/A<
P>Provides classes and interfaces that enable traversal of the data value
0N/A associated with an <
code>any</
code> at
0N/Aruntime, and extraction of the primitive constituents of the data value.
0N/A<
P>An <
code>any</
code> can be passed to a program that doesn't have any static information
0N/Afor the type of the <
code>any</
code> (code generated for the type by an IDL compiler has not
0N/Abeen compiled with the object implementation). As a result, the object receiving the
0N/A<
code>any</
code> does not have a portable method of using it.
0N/A<
P><
code>DynAny</
code>s enable traversal of the data value associated with an
0N/A<
code>any</
code> at runtime, and extraction of the primitive constituents of the data value.
0N/AThis is especially helpful for writing powerful generic servers (bridges, event channels
0N/Asupporting filtering). Similarly, this facility enables the construction of an
0N/A<
code>any</
code> at runtime, without having static knowledge of its type. This is especially
0N/Ahelpful for writing generic clients (bridges, browsers, debuggers, user interface tools).
0N/A<
P><
code>Any</
code> values can be dynamically interpreted (traversed) and constructed through
0N/A<
tt>DynAny</
tt> objects. A <
tt>DynAny</
tt> object is associated with a data
0N/Avalue which corresponds to a copy of the value inserted into an <
tt>Any</
tt>. A
0N/A<
tt>DynAny</
tt> object may be viewed as an ordered collection of component
0N/A<
tt>DynAny</
tt>s. For <
tt>DynAny</
tt>s representing a basic type, such as <
code>long</
code>,
0N/Aor a type without components, such as an empty exception, the ordered collection of
0N/A<
P>Each <
tt>DynAny</
tt> object maintains the notion of a current position into its collection
0N/Aof component <
tt>DynAny</
tt>s. The current position is identified by an index value that runs
0N/Afrom 0 to n-1, where <
em>n</
em> is the number of components. The special index value -1
0N/Aindicates a current position that points nowhere.
0N/A For values that cannot have a current position (such as an empty exception),
0N/A the index value is fixed at -1.
0N/A If a <
code>DynAny</
code> is initialized with a value that has components, the index is
0N/A After creation of an uninitialized <
code>DynAny</
code> (that is, a <
code>DynAny</
code> that
0N/Ahas no value but a <
code>TypeCode</
code>
0N/A that permits components), the current position depends on the type of value represented by
0N/A the <
code>DynAny</
code>. (The current position is set to 0 or -1, depending on whether the
0N/Anew <
code>DynAny</
code>
0N/A gets default values for its components.)
0N/A <
P>The iteration operations <
code>rewind</
code>, <
code>seek</
code>, and <
code>next</
code>
0N/Acan be used to change the current position
0N/A and the <
code>current_component</
code> operation returns the component at the current
0N/A The <
code>component_count</
code> operation returns the number of components of a
0N/A Collectively, these operations enable iteration over the components of a
0N/A<
code>DynAny</
code>, for example,
0N/A to (recursively) examine its contents.
0N/A <
P>A constructed <
code>DynAny</
code> object is a <
code>DynAny</
code> object associated with
0N/A There is a different interface, inheriting from the <
code>DynAny</
code> interface,
0N/A each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array,
0N/A exception, and value type). A constructed <
code>DynAny</
code> object exports operations
0N/Athat enable the creation of new <
code>DynAny</
code> objects,
0N/A each of them associated with a component of the constructed data value.
0N/A As an example, a <
code>DynStruct</
code> is associated with a <
code>struct</
code> value. This
0N/Ameans that the <
code>DynStruct</
code>
0N/A may be seen as owning an ordered collection of components, one for each structure member.
0N/A The <
code>DynStruct</
code> object exports operations that enable the creation of new
0N/A<
code>DynAny</
code> objects,
0N/A each of them associated with a member of the <
code>struct</
code>.
0N/A <
P>If a <
code>DynAny</
code> object has been obtained from another (constructed)
0N/A<
code>DynAny</
code> object,
0N/A such as a <
code>DynAny</
code> representing a structure member that was created from a
0N/A<
code>DynStruct</
code>,
0N/A the member <
code>DynAny</
code> is logically contained in the <
code>DynStruct</
code>.
0N/A Calling an <
code>insert</
code> or <
code>get</
code> operation leaves the current position
0N/A Destroying a top-level <
code>DynAny</
code> object (one that was not obtained as a component
0N/Aof another <
code>DynAny</
code>)
0N/A also destroys any component <
code>DynAny</
code> objects obtained from it.
0N/A Destroying a non-top level <
code>DynAny</
code> object does nothing.
0N/A Invoking operations on a destroyed top-level <
code>DynAny</
code> or any of its descendants
0N/Araises OBJECT_NOT_EXIST.
0N/A If the programmer wants to destroy a <
code>DynAny</
code> object but still wants to
0N/Amanipulate some component
0N/A of the data value associated with it, then he or she should first create a
0N/A<
code>DynAny</
code> for the component
0N/A and, after that, make a copy of the created <
code>DynAny</
code> object.
0N/A <
P>The behavior of <
code>DynAny</
code> objects has been defined in order to enable efficient
0N/A in terms of allocated memory space and speed of access. <
code>DynAny</
code> objects are
0N/A for traversing values extracted from <
code>any</
code>s or constructing values of
0N/A<
code>any</
code>s at runtime.
0N/A Their use for other purposes is not recommended.
0N/A <
H2>Handling DynAny objects</
H2>
0N/A <
P><
code>Insert</
code> and <
code>get</
code> operations are necessary to handle basic
0N/A<
code>DynAny</
code> objects
0N/A but are also helpful to handle constructed <
code>DynAny</
code> objects.
0N/A Inserting a basic data type value into a constructed <
code>DynAny</
code> object
0N/A implies initializing the current component of the constructed data value
0N/A associated with the <
code>DynAny</
code> object. For example, invoking
0N/A<
code>insert_boolean</
code> on a
0N/A <
code>DynStruct</
code> implies inserting a <
code>boolean</
code> data value at the current
0N/A of the associated <
code>struct</
code> data value.
0N/A A type is consistent for inserting or extracting a value if its <
code>TypeCode</
code> is
0N/A the <
code>TypeCode</
code> contained in the <
code>DynAny</
code> or, if the
0N/A<
code>DynAny</
code> has components, is equivalent to the <
code>TypeCode</
code>
0N/A of the <
code>DynAny</
code> at the current position.
0N/A <
P>Basic operations include:
0N/A <
LI>insert_boolean, get_boolean
0N/A <
LI>insert_char, get_char
0N/A <
LI>insert_short, get_short
0N/A <
LI>insert_ushort, get_ushort
0N/A <
LI>insert_long, get_long
0N/A <
LI>insert_ulong, get_ulong
0N/A <
LI>insert_double, get_double
0N/A <
LI>insert_string, get_string
0N/A <
LI>insert_reference, get_reference
0N/A <
LI>insert_typecode, get_typecode
0N/A <
LI>insert_longlong, get_longlong
0N/A <
LI>insert_ulonglong, get_ulonglong
0N/A <
LI>insert_longdouble, get_longdouble
0N/A <
LI>insert_wchar, get_wchar
0N/A <
LI>insert_wstring, get_wstring
0N/A <
LI>insert_any, get_any
0N/A <
LI>insert_dyn_any, get_dyn_any
0N/A <
LI>insert_val, get_val
0N/A <
LI>insert_octet, get_octet
0N/A <
LI>insert_float, get_float
0N/A <
LI>get_members_as_dyn_any
0N/A <
LI>get_discriminator
0N/A <
LI>get_elements_as_dyn_any
0N/A <
LI>get_boxed_value_as_dyn_any
0N/A <
P><
code>DynAny</
code> and <
code>DynAnyFactory</
code> objects are intended to be local to
0N/Athe process in which they are
0N/A created and used. This means that references to <
code>DynAny</
code> and
0N/A<
code>DynAnyFactory</
code> objects cannot be exported
0N/A If any attempt is made to do so, the offending operation will raise a MARSHAL system
0N/A Since their interfaces are specified in IDL, <
code>DynAny</
code> objects export operations
0N/Adefined in the standard
0N/Aexported through the <
code>Object</
code>
0N/A interface may raise the standard NO_IMPLEMENT exception.
0N/A An attempt to use a <
code>DynAny</
code> object with the DII may raise the NO_IMPLEMENT
0N/A<
H3>Package Specification</
H3>
0N/A<
P>For a precise list of supported sections of official specifications with which
0N/Athe Java[tm] Platform, Standard Edition 6 ORB complies, see <
A 0N/Asupport in Java[tm] SE 6</
A>.