Tue, 16 Jan 2018 22:52:07 -0800
Merge
duke@1 | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
duke@1 | 2 | <html> |
duke@1 | 3 | <head> |
duke@1 | 4 | <!-- |
duke@1 | 5 | |
ohair@158 | 6 | Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. |
duke@1 | 7 | DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
duke@1 | 8 | |
duke@1 | 9 | This code is free software; you can redistribute it and/or modify it |
duke@1 | 10 | under the terms of the GNU General Public License version 2 only, as |
ohair@158 | 11 | published by the Free Software Foundation. Oracle designates this |
duke@1 | 12 | particular file as subject to the "Classpath" exception as provided |
ohair@158 | 13 | by Oracle in the LICENSE file that accompanied this code. |
duke@1 | 14 | |
duke@1 | 15 | This code is distributed in the hope that it will be useful, but WITHOUT |
duke@1 | 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
duke@1 | 17 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
duke@1 | 18 | version 2 for more details (a copy is included in the LICENSE file that |
duke@1 | 19 | accompanied this code). |
duke@1 | 20 | |
duke@1 | 21 | You should have received a copy of the GNU General Public License version |
duke@1 | 22 | 2 along with this work; if not, write to the Free Software Foundation, |
duke@1 | 23 | Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
duke@1 | 24 | |
ohair@158 | 25 | Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
ohair@158 | 26 | or visit www.oracle.com if you need additional information or have any |
ohair@158 | 27 | questions. |
duke@1 | 28 | |
duke@1 | 29 | --> |
duke@1 | 30 | |
duke@1 | 31 | </head> |
duke@1 | 32 | <body bgcolor="white"> |
duke@1 | 33 | <P>Provides classes and interfaces that enable traversal of the data value |
duke@1 | 34 | associated with an <code>any</code> at |
duke@1 | 35 | runtime, and extraction of the primitive constituents of the data value. |
duke@1 | 36 | |
duke@1 | 37 | |
duke@1 | 38 | <P>An <code>any</code> can be passed to a program that doesn't have any static information |
duke@1 | 39 | for the type of the <code>any</code> (code generated for the type by an IDL compiler has not |
duke@1 | 40 | been compiled with the object implementation). As a result, the object receiving the |
duke@1 | 41 | <code>any</code> does not have a portable method of using it. |
duke@1 | 42 | |
duke@1 | 43 | <P><code>DynAny</code>s enable traversal of the data value associated with an |
duke@1 | 44 | <code>any</code> at runtime, and extraction of the primitive constituents of the data value. |
duke@1 | 45 | This is especially helpful for writing powerful generic servers (bridges, event channels |
duke@1 | 46 | supporting filtering). Similarly, this facility enables the construction of an |
duke@1 | 47 | <code>any</code> at runtime, without having static knowledge of its type. This is especially |
duke@1 | 48 | helpful for writing generic clients (bridges, browsers, debuggers, user interface tools). |
duke@1 | 49 | |
duke@1 | 50 | <P><code>Any</code> values can be dynamically interpreted (traversed) and constructed through |
duke@1 | 51 | <tt>DynAny</tt> objects. A <tt>DynAny</tt> object is associated with a data |
duke@1 | 52 | value which corresponds to a copy of the value inserted into an <tt>Any</tt>. A |
duke@1 | 53 | <tt>DynAny</tt> object may be viewed as an ordered collection of component |
duke@1 | 54 | <tt>DynAny</tt>s. For <tt>DynAny</tt>s representing a basic type, such as <code>long</code>, |
duke@1 | 55 | or a type without components, such as an empty exception, the ordered collection of |
duke@1 | 56 | components is empty. |
duke@1 | 57 | |
duke@1 | 58 | <P>Each <tt>DynAny</tt> object maintains the notion of a current position into its collection |
duke@1 | 59 | of component <tt>DynAny</tt>s. The current position is identified by an index value that runs |
duke@1 | 60 | from 0 to n-1, where <em>n</em> is the number of components. The special index value -1 |
duke@1 | 61 | indicates a current position that points nowhere. |
duke@1 | 62 | For values that cannot have a current position (such as an empty exception), |
duke@1 | 63 | the index value is fixed at -1. |
duke@1 | 64 | If a <code>DynAny</code> is initialized with a value that has components, the index is |
duke@1 | 65 | initialized to 0. |
duke@1 | 66 | After creation of an uninitialized <code>DynAny</code> (that is, a <code>DynAny</code> that |
duke@1 | 67 | has no value but a <code>TypeCode</code> |
duke@1 | 68 | that permits components), the current position depends on the type of value represented by |
duke@1 | 69 | the <code>DynAny</code>. (The current position is set to 0 or -1, depending on whether the |
duke@1 | 70 | new <code>DynAny</code> |
duke@1 | 71 | gets default values for its components.) |
duke@1 | 72 | |
duke@1 | 73 | |
duke@1 | 74 | <P>The iteration operations <code>rewind</code>, <code>seek</code>, and <code>next</code> |
duke@1 | 75 | can be used to change the current position |
duke@1 | 76 | and the <code>current_component</code> operation returns the component at the current |
duke@1 | 77 | position. |
duke@1 | 78 | The <code>component_count</code> operation returns the number of components of a |
duke@1 | 79 | <code>DynAny</code>. |
duke@1 | 80 | Collectively, these operations enable iteration over the components of a |
duke@1 | 81 | <code>DynAny</code>, for example, |
duke@1 | 82 | to (recursively) examine its contents. |
duke@1 | 83 | |
duke@1 | 84 | |
duke@1 | 85 | <P>A constructed <code>DynAny</code> object is a <code>DynAny</code> object associated with |
duke@1 | 86 | a constructed type. |
duke@1 | 87 | There is a different interface, inheriting from the <code>DynAny</code> interface, |
duke@1 | 88 | associated with |
duke@1 | 89 | each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, |
duke@1 | 90 | exception, and value type). A constructed <code>DynAny</code> object exports operations |
duke@1 | 91 | that enable the creation of new <code>DynAny</code> objects, |
duke@1 | 92 | each of them associated with a component of the constructed data value. |
duke@1 | 93 | As an example, a <code>DynStruct</code> is associated with a <code>struct</code> value. This |
duke@1 | 94 | means that the <code>DynStruct</code> |
duke@1 | 95 | may be seen as owning an ordered collection of components, one for each structure member. |
duke@1 | 96 | The <code>DynStruct</code> object exports operations that enable the creation of new |
duke@1 | 97 | <code>DynAny</code> objects, |
duke@1 | 98 | each of them associated with a member of the <code>struct</code>. |
duke@1 | 99 | |
duke@1 | 100 | |
duke@1 | 101 | <P>If a <code>DynAny</code> object has been obtained from another (constructed) |
duke@1 | 102 | <code>DynAny</code> object, |
duke@1 | 103 | such as a <code>DynAny</code> representing a structure member that was created from a |
duke@1 | 104 | <code>DynStruct</code>, |
duke@1 | 105 | the member <code>DynAny</code> is logically contained in the <code>DynStruct</code>. |
duke@1 | 106 | Calling an <code>insert</code> or <code>get</code> operation leaves the current position |
duke@1 | 107 | unchanged. |
duke@1 | 108 | Destroying a top-level <code>DynAny</code> object (one that was not obtained as a component |
duke@1 | 109 | of another <code>DynAny</code>) |
duke@1 | 110 | also destroys any component <code>DynAny</code> objects obtained from it. |
duke@1 | 111 | Destroying a non-top level <code>DynAny</code> object does nothing. |
duke@1 | 112 | Invoking operations on a destroyed top-level <code>DynAny</code> or any of its descendants |
duke@1 | 113 | raises OBJECT_NOT_EXIST. |
duke@1 | 114 | If the programmer wants to destroy a <code>DynAny</code> object but still wants to |
duke@1 | 115 | manipulate some component |
duke@1 | 116 | of the data value associated with it, then he or she should first create a |
duke@1 | 117 | <code>DynAny</code> for the component |
duke@1 | 118 | and, after that, make a copy of the created <code>DynAny</code> object. |
duke@1 | 119 | |
duke@1 | 120 | |
duke@1 | 121 | <P>The behavior of <code>DynAny</code> objects has been defined in order to enable efficient |
duke@1 | 122 | implementations |
duke@1 | 123 | in terms of allocated memory space and speed of access. <code>DynAny</code> objects are |
duke@1 | 124 | intended to be used |
duke@1 | 125 | for traversing values extracted from <code>any</code>s or constructing values of |
duke@1 | 126 | <code>any</code>s at runtime. |
duke@1 | 127 | Their use for other purposes is not recommended. |
duke@1 | 128 | |
duke@1 | 129 | |
duke@1 | 130 | |
duke@1 | 131 | <H2>Handling DynAny objects</H2> |
duke@1 | 132 | |
duke@1 | 133 | <P><code>Insert</code> and <code>get</code> operations are necessary to handle basic |
duke@1 | 134 | <code>DynAny</code> objects |
duke@1 | 135 | but are also helpful to handle constructed <code>DynAny</code> objects. |
duke@1 | 136 | Inserting a basic data type value into a constructed <code>DynAny</code> object |
duke@1 | 137 | implies initializing the current component of the constructed data value |
duke@1 | 138 | associated with the <code>DynAny</code> object. For example, invoking |
duke@1 | 139 | <code>insert_boolean</code> on a |
duke@1 | 140 | <code>DynStruct</code> implies inserting a <code>boolean</code> data value at the current |
duke@1 | 141 | position |
duke@1 | 142 | of the associated <code>struct</code> data value. |
duke@1 | 143 | A type is consistent for inserting or extracting a value if its <code>TypeCode</code> is |
duke@1 | 144 | equivalent to |
duke@1 | 145 | the <code>TypeCode</code> contained in the <code>DynAny</code> or, if the |
duke@1 | 146 | <code>DynAny</code> has components, is equivalent to the <code>TypeCode</code> |
duke@1 | 147 | of the <code>DynAny</code> at the current position. |
duke@1 | 148 | |
duke@1 | 149 | <P>Basic operations include: |
duke@1 | 150 | <P> |
duke@1 | 151 | <UL> |
duke@1 | 152 | <LI>insert_boolean, get_boolean |
duke@1 | 153 | <LI>insert_char, get_char |
duke@1 | 154 | <LI>insert_short, get_short |
duke@1 | 155 | <LI>insert_ushort, get_ushort |
duke@1 | 156 | <LI>insert_long, get_long |
duke@1 | 157 | <LI>insert_ulong, get_ulong |
duke@1 | 158 | <LI>insert_double, get_double |
duke@1 | 159 | <LI>insert_string, get_string |
duke@1 | 160 | <LI>insert_reference, get_reference |
duke@1 | 161 | <LI>insert_typecode, get_typecode |
duke@1 | 162 | <LI>insert_longlong, get_longlong |
duke@1 | 163 | <LI>insert_ulonglong, get_ulonglong |
duke@1 | 164 | <LI>insert_longdouble, get_longdouble |
duke@1 | 165 | <LI>insert_wchar, get_wchar |
duke@1 | 166 | <LI>insert_wstring, get_wstring |
duke@1 | 167 | <LI>insert_any, get_any |
duke@1 | 168 | <LI>insert_dyn_any, get_dyn_any |
duke@1 | 169 | <LI>insert_val, get_val |
duke@1 | 170 | <LI>insert_octet, get_octet |
duke@1 | 171 | <LI>insert_float, get_float |
duke@1 | 172 | <LI>get_value |
duke@1 | 173 | <LI>get_as_string |
duke@1 | 174 | <LI>get_as_ulong |
duke@1 | 175 | <LI>get_members |
duke@1 | 176 | <LI>get_members_as_dyn_any |
duke@1 | 177 | <LI>get_discriminator |
duke@1 | 178 | <LI>get_length |
duke@1 | 179 | <LI>get_elements |
duke@1 | 180 | <LI>get_elements_as_dyn_any |
duke@1 | 181 | <LI>get_boxed_value |
duke@1 | 182 | <LI>get_boxed_value_as_dyn_any |
duke@1 | 183 | </UL> |
duke@1 | 184 | |
duke@1 | 185 | |
duke@1 | 186 | <P><code>DynAny</code> and <code>DynAnyFactory</code> objects are intended to be local to |
duke@1 | 187 | the process in which they are |
duke@1 | 188 | created and used. This means that references to <code>DynAny</code> and |
duke@1 | 189 | <code>DynAnyFactory</code> objects cannot be exported |
duke@1 | 190 | to other processes, or externalized with <code>ORB.object_to_string()</code>. |
duke@1 | 191 | If any attempt is made to do so, the offending operation will raise a MARSHAL system |
duke@1 | 192 | exception. |
duke@1 | 193 | Since their interfaces are specified in IDL, <code>DynAny</code> objects export operations |
duke@1 | 194 | defined in the standard |
duke@1 | 195 | <code>org.omg.CORBA.Object</code> interface. However, any attempt to invoke operations |
duke@1 | 196 | exported through the <code>Object</code> |
duke@1 | 197 | interface may raise the standard NO_IMPLEMENT exception. |
duke@1 | 198 | An attempt to use a <code>DynAny</code> object with the DII may raise the NO_IMPLEMENT |
duke@1 | 199 | exception. |
duke@1 | 200 | |
duke@1 | 201 | |
duke@1 | 202 | |
duke@1 | 203 | |
duke@1 | 204 | |
duke@1 | 205 | |
duke@1 | 206 | <P> |
duke@1 | 207 | |
duke@1 | 208 | |
duke@1 | 209 | <H3>Package Specification</H3> |
duke@1 | 210 | |
duke@1 | 211 | <P>For a precise list of supported sections of official specifications with which |
duke@1 | 212 | the Java[tm] Platform, Standard Edition 6 ORB complies, see <A |
duke@1 | 213 | HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA |
duke@1 | 214 | support in Java[tm] SE 6</A>. |
duke@1 | 215 | <p> |
duke@1 | 216 | @since 1.4 |
duke@1 | 217 | <br> |
duke@1 | 218 | @serial exclude |
duke@1 | 219 | </body> |
duke@1 | 220 | </html> |