--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/corba/src/share/classes/org/omg/DynamicAny/package.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,220 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+
+ Copyright 2000-2006 Sun Microsystems, Inc. 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. Sun designates this
+ particular file as subject to the "Classpath" exception as provided
+ by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ CA 95054 USA or visit www.sun.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>