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