1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/org/omg/DynamicAny/package.html Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,220 @@
1.4 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.5 +<html>
1.6 +<head>
1.7 +<!--
1.8 +
1.9 + Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
1.10 + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.11 +
1.12 + This code is free software; you can redistribute it and/or modify it
1.13 + under the terms of the GNU General Public License version 2 only, as
1.14 + published by the Free Software Foundation. Sun designates this
1.15 + particular file as subject to the "Classpath" exception as provided
1.16 + by Sun in the LICENSE file that accompanied this code.
1.17 +
1.18 + This code is distributed in the hope that it will be useful, but WITHOUT
1.19 + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.20 + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.21 + version 2 for more details (a copy is included in the LICENSE file that
1.22 + accompanied this code).
1.23 +
1.24 + You should have received a copy of the GNU General Public License version
1.25 + 2 along with this work; if not, write to the Free Software Foundation,
1.26 + Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.27 +
1.28 + Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.29 + CA 95054 USA or visit www.sun.com if you need additional information or
1.30 + have any questions.
1.31 +
1.32 +-->
1.33 +
1.34 +</head>
1.35 +<body bgcolor="white">
1.36 +<P>Provides classes and interfaces that enable traversal of the data value
1.37 + associated with an <code>any</code> at
1.38 +runtime, and extraction of the primitive constituents of the data value.
1.39 +
1.40 +
1.41 +<P>An <code>any</code> can be passed to a program that doesn't have any static information
1.42 +for the type of the <code>any</code> (code generated for the type by an IDL compiler has not
1.43 +been compiled with the object implementation). As a result, the object receiving the
1.44 +<code>any</code> does not have a portable method of using it.
1.45 +
1.46 +<P><code>DynAny</code>s enable traversal of the data value associated with an
1.47 +<code>any</code> at runtime, and extraction of the primitive constituents of the data value.
1.48 +This is especially helpful for writing powerful generic servers (bridges, event channels
1.49 +supporting filtering). Similarly, this facility enables the construction of an
1.50 +<code>any</code> at runtime, without having static knowledge of its type. This is especially
1.51 +helpful for writing generic clients (bridges, browsers, debuggers, user interface tools).
1.52 +
1.53 +<P><code>Any</code> values can be dynamically interpreted (traversed) and constructed through
1.54 +<tt>DynAny</tt> objects. A <tt>DynAny</tt> object is associated with a data
1.55 +value which corresponds to a copy of the value inserted into an <tt>Any</tt>. A
1.56 +<tt>DynAny</tt> object may be viewed as an ordered collection of component
1.57 +<tt>DynAny</tt>s. For <tt>DynAny</tt>s representing a basic type, such as <code>long</code>,
1.58 +or a type without components, such as an empty exception, the ordered collection of
1.59 +components is empty.
1.60 +
1.61 +<P>Each <tt>DynAny</tt> object maintains the notion of a current position into its collection
1.62 +of component <tt>DynAny</tt>s. The current position is identified by an index value that runs
1.63 +from 0 to n-1, where <em>n</em> is the number of components. The special index value -1
1.64 +indicates a current position that points nowhere.
1.65 + For values that cannot have a current position (such as an empty exception),
1.66 + the index value is fixed at -1.
1.67 + If a <code>DynAny</code> is initialized with a value that has components, the index is
1.68 +initialized to 0.
1.69 + After creation of an uninitialized <code>DynAny</code> (that is, a <code>DynAny</code> that
1.70 +has no value but a <code>TypeCode</code>
1.71 + that permits components), the current position depends on the type of value represented by
1.72 + the <code>DynAny</code>. (The current position is set to 0 or -1, depending on whether the
1.73 +new <code>DynAny</code>
1.74 + gets default values for its components.)
1.75 +
1.76 +
1.77 + <P>The iteration operations <code>rewind</code>, <code>seek</code>, and <code>next</code>
1.78 +can be used to change the current position
1.79 + and the <code>current_component</code> operation returns the component at the current
1.80 +position.
1.81 + The <code>component_count</code> operation returns the number of components of a
1.82 +<code>DynAny</code>.
1.83 + Collectively, these operations enable iteration over the components of a
1.84 +<code>DynAny</code>, for example,
1.85 + to (recursively) examine its contents.
1.86 +
1.87 +
1.88 + <P>A constructed <code>DynAny</code> object is a <code>DynAny</code> object associated with
1.89 +a constructed type.
1.90 + There is a different interface, inheriting from the <code>DynAny</code> interface,
1.91 +associated with
1.92 + each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array,
1.93 + exception, and value type). A constructed <code>DynAny</code> object exports operations
1.94 +that enable the creation of new <code>DynAny</code> objects,
1.95 + each of them associated with a component of the constructed data value.
1.96 + As an example, a <code>DynStruct</code> is associated with a <code>struct</code> value. This
1.97 +means that the <code>DynStruct</code>
1.98 + may be seen as owning an ordered collection of components, one for each structure member.
1.99 + The <code>DynStruct</code> object exports operations that enable the creation of new
1.100 +<code>DynAny</code> objects,
1.101 + each of them associated with a member of the <code>struct</code>.
1.102 +
1.103 +
1.104 + <P>If a <code>DynAny</code> object has been obtained from another (constructed)
1.105 +<code>DynAny</code> object,
1.106 + such as a <code>DynAny</code> representing a structure member that was created from a
1.107 +<code>DynStruct</code>,
1.108 + the member <code>DynAny</code> is logically contained in the <code>DynStruct</code>.
1.109 + Calling an <code>insert</code> or <code>get</code> operation leaves the current position
1.110 +unchanged.
1.111 + Destroying a top-level <code>DynAny</code> object (one that was not obtained as a component
1.112 +of another <code>DynAny</code>)
1.113 + also destroys any component <code>DynAny</code> objects obtained from it.
1.114 + Destroying a non-top level <code>DynAny</code> object does nothing.
1.115 + Invoking operations on a destroyed top-level <code>DynAny</code> or any of its descendants
1.116 +raises OBJECT_NOT_EXIST.
1.117 + If the programmer wants to destroy a <code>DynAny</code> object but still wants to
1.118 +manipulate some component
1.119 + of the data value associated with it, then he or she should first create a
1.120 +<code>DynAny</code> for the component
1.121 + and, after that, make a copy of the created <code>DynAny</code> object.
1.122 +
1.123 +
1.124 + <P>The behavior of <code>DynAny</code> objects has been defined in order to enable efficient
1.125 +implementations
1.126 + in terms of allocated memory space and speed of access. <code>DynAny</code> objects are
1.127 +intended to be used
1.128 + for traversing values extracted from <code>any</code>s or constructing values of
1.129 +<code>any</code>s at runtime.
1.130 + Their use for other purposes is not recommended.
1.131 +
1.132 +
1.133 +
1.134 + <H2>Handling DynAny objects</H2>
1.135 +
1.136 + <P><code>Insert</code> and <code>get</code> operations are necessary to handle basic
1.137 +<code>DynAny</code> objects
1.138 + but are also helpful to handle constructed <code>DynAny</code> objects.
1.139 + Inserting a basic data type value into a constructed <code>DynAny</code> object
1.140 + implies initializing the current component of the constructed data value
1.141 + associated with the <code>DynAny</code> object. For example, invoking
1.142 +<code>insert_boolean</code> on a
1.143 + <code>DynStruct</code> implies inserting a <code>boolean</code> data value at the current
1.144 +position
1.145 + of the associated <code>struct</code> data value.
1.146 + A type is consistent for inserting or extracting a value if its <code>TypeCode</code> is
1.147 +equivalent to
1.148 + the <code>TypeCode</code> contained in the <code>DynAny</code> or, if the
1.149 +<code>DynAny</code> has components, is equivalent to the <code>TypeCode</code>
1.150 + of the <code>DynAny</code> at the current position.
1.151 +
1.152 + <P>Basic operations include:
1.153 + <P>
1.154 + <UL>
1.155 + <LI>insert_boolean, get_boolean
1.156 + <LI>insert_char, get_char
1.157 + <LI>insert_short, get_short
1.158 + <LI>insert_ushort, get_ushort
1.159 + <LI>insert_long, get_long
1.160 + <LI>insert_ulong, get_ulong
1.161 + <LI>insert_double, get_double
1.162 + <LI>insert_string, get_string
1.163 + <LI>insert_reference, get_reference
1.164 + <LI>insert_typecode, get_typecode
1.165 + <LI>insert_longlong, get_longlong
1.166 + <LI>insert_ulonglong, get_ulonglong
1.167 + <LI>insert_longdouble, get_longdouble
1.168 + <LI>insert_wchar, get_wchar
1.169 + <LI>insert_wstring, get_wstring
1.170 + <LI>insert_any, get_any
1.171 + <LI>insert_dyn_any, get_dyn_any
1.172 + <LI>insert_val, get_val
1.173 + <LI>insert_octet, get_octet
1.174 + <LI>insert_float, get_float
1.175 + <LI>get_value
1.176 + <LI>get_as_string
1.177 + <LI>get_as_ulong
1.178 + <LI>get_members
1.179 + <LI>get_members_as_dyn_any
1.180 + <LI>get_discriminator
1.181 + <LI>get_length
1.182 + <LI>get_elements
1.183 + <LI>get_elements_as_dyn_any
1.184 + <LI>get_boxed_value
1.185 + <LI>get_boxed_value_as_dyn_any
1.186 + </UL>
1.187 +
1.188 +
1.189 + <P><code>DynAny</code> and <code>DynAnyFactory</code> objects are intended to be local to
1.190 +the process in which they are
1.191 + created and used. This means that references to <code>DynAny</code> and
1.192 +<code>DynAnyFactory</code> objects cannot be exported
1.193 + to other processes, or externalized with <code>ORB.object_to_string()</code>.
1.194 + If any attempt is made to do so, the offending operation will raise a MARSHAL system
1.195 +exception.
1.196 + Since their interfaces are specified in IDL, <code>DynAny</code> objects export operations
1.197 +defined in the standard
1.198 + <code>org.omg.CORBA.Object</code> interface. However, any attempt to invoke operations
1.199 +exported through the <code>Object</code>
1.200 + interface may raise the standard NO_IMPLEMENT exception.
1.201 + An attempt to use a <code>DynAny</code> object with the DII may raise the NO_IMPLEMENT
1.202 +exception.
1.203 +
1.204 +
1.205 +
1.206 +
1.207 +
1.208 +
1.209 +<P>
1.210 +
1.211 +
1.212 +<H3>Package Specification</H3>
1.213 +
1.214 +<P>For a precise list of supported sections of official specifications with which
1.215 +the Java[tm] Platform, Standard Edition 6 ORB complies, see <A
1.216 +HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA
1.217 +support in Java[tm] SE 6</A>.
1.218 +<p>
1.219 +@since 1.4
1.220 +<br>
1.221 +@serial exclude
1.222 +</body>
1.223 +</html>
