package.html revision 608:7e06bf1dcb09
1176434Skaiw<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2176434Skaiw<html> 3176434Skaiw<head> 4176434Skaiw<!-- 5176434Skaiw 6176434Skaiw Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 7176434Skaiw DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 8176434Skaiw 9176434Skaiw This code is free software; you can redistribute it and/or modify it 10176434Skaiw under the terms of the GNU General Public License version 2 only, as 11176434Skaiw published by the Free Software Foundation. Oracle designates this 12176434Skaiw particular file as subject to the "Classpath" exception as provided 13176434Skaiw by Oracle in the LICENSE file that accompanied this code. 14176434Skaiw 15176434Skaiw This code is distributed in the hope that it will be useful, but WITHOUT 16176434Skaiw ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 17176434Skaiw FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 18176434Skaiw version 2 for more details (a copy is included in the LICENSE file that 19176434Skaiw accompanied this code). 20176434Skaiw 21176434Skaiw You should have received a copy of the GNU General Public License version 22176434Skaiw 2 along with this work; if not, write to the Free Software Foundation, 23176434Skaiw Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 24176434Skaiw 25176434Skaiw Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 26176434Skaiw or visit www.oracle.com if you need additional information or have any 27176434Skaiw questions. 28176434Skaiw 29176434Skaiw--> 30176434Skaiw 31176434Skaiw</head> 32176434Skaiw<body bgcolor="white"> 33176434Skaiw<P>Provides classes and interfaces that enable traversal of the data value 34176434Skaiw associated with an <code>any</code> at 35176434Skaiwruntime, and extraction of the primitive constituents of the data value. 36176434Skaiw 37176434Skaiw 38176434Skaiw<P>An <code>any</code> can be passed to a program that doesn't have any static information 39176434Skaiwfor the type of the <code>any</code> (code generated for the type by an IDL compiler has not 40176434Skaiwbeen compiled with the object implementation). As a result, the object receiving the 41176434Skaiw<code>any</code> does not have a portable method of using it. 42176434Skaiw 43176434Skaiw<P><code>DynAny</code>s enable traversal of the data value associated with an 44285224Semaste<code>any</code> at runtime, and extraction of the primitive constituents of the data value. 45176434SkaiwThis is especially helpful for writing powerful generic servers (bridges, event channels 46176434Skaiwsupporting filtering). Similarly, this facility enables the construction of an 47176434Skaiw<code>any</code> at runtime, without having static knowledge of its type. This is especially 48176434Skaiwhelpful for writing generic clients (bridges, browsers, debuggers, user interface tools). 49176434Skaiw 50176434Skaiw<P><code>Any</code> values can be dynamically interpreted (traversed) and constructed through 51176434Skaiw<tt>DynAny</tt> objects. A <tt>DynAny</tt> object is associated with a data 52176434Skaiwvalue which corresponds to a copy of the value inserted into an <tt>Any</tt>. A 53176434Skaiw<tt>DynAny</tt> object may be viewed as an ordered collection of component 54176434Skaiw<tt>DynAny</tt>s. For <tt>DynAny</tt>s representing a basic type, such as <code>long</code>, 55176434Skaiwor a type without components, such as an empty exception, the ordered collection of 56176434Skaiwcomponents is empty. 57176434Skaiw 58176434Skaiw<P>Each <tt>DynAny</tt> object maintains the notion of a current position into its collection 59176434Skaiwof component <tt>DynAny</tt>s. The current position is identified by an index value that runs 60176434Skaiwfrom 0 to n-1, where <em>n</em> is the number of components. The special index value -1 61176434Skaiwindicates a current position that points nowhere. 62224650Semaste For values that cannot have a current position (such as an empty exception), 63176434Skaiw the index value is fixed at -1. 64176434Skaiw If a <code>DynAny</code> is initialized with a value that has components, the index is 65285224Semasteinitialized to 0. 66183218Skaiw After creation of an uninitialized <code>DynAny</code> (that is, a <code>DynAny</code> that 67183218Skaiwhas no value but a <code>TypeCode</code> 68176434Skaiw that permits components), the current position depends on the type of value represented by 69176434Skaiw the <code>DynAny</code>. (The current position is set to 0 or -1, depending on whether the 70176434Skaiwnew <code>DynAny</code> 71176434Skaiw gets default values for its components.) 72176434Skaiw 73176434Skaiw 74176434Skaiw <P>The iteration operations <code>rewind</code>, <code>seek</code>, and <code>next</code> 75176434Skaiwcan be used to change the current position 76176434Skaiw and the <code>current_component</code> operation returns the component at the current 77176434Skaiwposition. 78176434Skaiw The <code>component_count</code> operation returns the number of components of a 79176434Skaiw<code>DynAny</code>. 80176434Skaiw Collectively, these operations enable iteration over the components of a 81176434Skaiw<code>DynAny</code>, for example, 82176434Skaiw to (recursively) examine its contents. 83176434Skaiw 84176434Skaiw 85176434Skaiw <P>A constructed <code>DynAny</code> object is a <code>DynAny</code> object associated with 86176434Skaiwa constructed type. 87176434Skaiw There is a different interface, inheriting from the <code>DynAny</code> interface, 88176434Skaiwassociated with 89177064Skaiw each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, 90177064Skaiw exception, and value type). A constructed <code>DynAny</code> object exports operations 91177064Skaiwthat enable the creation of new <code>DynAny</code> objects, 92177064Skaiw each of them associated with a component of the constructed data value. 93177064Skaiw As an example, a <code>DynStruct</code> is associated with a <code>struct</code> value. This 94177064Skaiwmeans that the <code>DynStruct</code> 95177064Skaiw may be seen as owning an ordered collection of components, one for each structure member. 96176434Skaiw The <code>DynStruct</code> object exports operations that enable the creation of new 97176434Skaiw<code>DynAny</code> objects, 98176434Skaiw each of them associated with a member of the <code>struct</code>. 99176434Skaiw 100176434Skaiw 101176434Skaiw <P>If a <code>DynAny</code> object has been obtained from another (constructed) 102176434Skaiw<code>DynAny</code> object, 103176434Skaiw such as a <code>DynAny</code> representing a structure member that was created from a 104176434Skaiw<code>DynStruct</code>, 105176434Skaiw the member <code>DynAny</code> is logically contained in the <code>DynStruct</code>. 106176434Skaiw Calling an <code>insert</code> or <code>get</code> operation leaves the current position 107176434Skaiwunchanged. 108176434Skaiw Destroying a top-level <code>DynAny</code> object (one that was not obtained as a component 109183218Skaiwof another <code>DynAny</code>) 110183218Skaiw also destroys any component <code>DynAny</code> objects obtained from it. 111183218Skaiw Destroying a non-top level <code>DynAny</code> object does nothing. 112183218Skaiw Invoking operations on a destroyed top-level <code>DynAny</code> or any of its descendants 113183218Skaiwraises OBJECT_NOT_EXIST. 114183218Skaiw If the programmer wants to destroy a <code>DynAny</code> object but still wants to 115183218Skaiwmanipulate some component 116176434Skaiw of the data value associated with it, then he or she should first create a 117176434Skaiw<code>DynAny</code> for the component 118176434Skaiw and, after that, make a copy of the created <code>DynAny</code> object. 119222122Sbcr 120176434Skaiw 121176434Skaiw <P>The behavior of <code>DynAny</code> objects has been defined in order to enable efficient 122176434Skaiwimplementations 123176434Skaiw in terms of allocated memory space and speed of access. <code>DynAny</code> objects are 124176434Skaiwintended to be used 125176434Skaiw for traversing values extracted from <code>any</code>s or constructing values of 126176434Skaiw<code>any</code>s at runtime. 127176434Skaiw Their use for other purposes is not recommended. 128176434Skaiw 129176528Skaiw 130176434Skaiw 131176434Skaiw <H2>Handling DynAny objects</H2> 132176434Skaiw 133176434Skaiw <P><code>Insert</code> and <code>get</code> operations are necessary to handle basic 134176434Skaiw<code>DynAny</code> objects 135176434Skaiw but are also helpful to handle constructed <code>DynAny</code> objects. 136176434Skaiw Inserting a basic data type value into a constructed <code>DynAny</code> object 137176528Skaiw implies initializing the current component of the constructed data value 138176434Skaiw associated with the <code>DynAny</code> object. For example, invoking 139176434Skaiw<code>insert_boolean</code> on a 140176434Skaiw <code>DynStruct</code> implies inserting a <code>boolean</code> data value at the current 141176434Skaiwposition 142176434Skaiw of the associated <code>struct</code> data value. 143176434Skaiw A type is consistent for inserting or extracting a value if its <code>TypeCode</code> is 144176434Skaiwequivalent to 145176434Skaiw the <code>TypeCode</code> contained in the <code>DynAny</code> or, if the 146176434Skaiw<code>DynAny</code> has components, is equivalent to the <code>TypeCode</code> 147176434Skaiw of the <code>DynAny</code> at the current position. 148176434Skaiw 149176434Skaiw <P>Basic operations include: 150176434Skaiw <P> 151176434Skaiw <UL> 152176434Skaiw <LI>insert_boolean, get_boolean 153176434Skaiw <LI>insert_char, get_char 154176434Skaiw <LI>insert_short, get_short 155176434Skaiw <LI>insert_ushort, get_ushort 156176434Skaiw <LI>insert_long, get_long 157176434Skaiw <LI>insert_ulong, get_ulong 158176434Skaiw <LI>insert_double, get_double 159176434Skaiw <LI>insert_string, get_string 160176434Skaiw <LI>insert_reference, get_reference 161176434Skaiw <LI>insert_typecode, get_typecode 162176434Skaiw <LI>insert_longlong, get_longlong 163176434Skaiw <LI>insert_ulonglong, get_ulonglong 164176434Skaiw <LI>insert_longdouble, get_longdouble 165176434Skaiw <LI>insert_wchar, get_wchar 166176434Skaiw <LI>insert_wstring, get_wstring 167176434Skaiw <LI>insert_any, get_any 168176434Skaiw <LI>insert_dyn_any, get_dyn_any 169213643Skientzle <LI>insert_val, get_val 170213643Skientzle <LI>insert_octet, get_octet 171213643Skientzle <LI>insert_float, get_float 172213643Skientzle <LI>get_value 173213643Skientzle <LI>get_as_string 174213643Skientzle <LI>get_as_ulong 175213643Skientzle <LI>get_members 176213643Skientzle <LI>get_members_as_dyn_any 177213643Skientzle <LI>get_discriminator 178213643Skientzle <LI>get_length 179213643Skientzle <LI>get_elements 180213643Skientzle <LI>get_elements_as_dyn_any 181213643Skientzle <LI>get_boxed_value 182213643Skientzle <LI>get_boxed_value_as_dyn_any 183213643Skientzle </UL> 184213643Skientzle 185213643Skientzle 186176434Skaiw <P><code>DynAny</code> and <code>DynAnyFactory</code> objects are intended to be local to 187176434Skaiwthe process in which they are 188176434Skaiw created and used. This means that references to <code>DynAny</code> and 189176525Skaiw<code>DynAnyFactory</code> objects cannot be exported 190176525Skaiw to other processes, or externalized with <code>ORB.object_to_string()</code>. 191176525Skaiw If any attempt is made to do so, the offending operation will raise a MARSHAL system 192176528Skaiwexception. 193176525Skaiw Since their interfaces are specified in IDL, <code>DynAny</code> objects export operations 194176525Skaiwdefined in the standard 195176434Skaiw <code>org.omg.CORBA.Object</code> interface. However, any attempt to invoke operations 196176434Skaiwexported through the <code>Object</code> 197176434Skaiw interface may raise the standard NO_IMPLEMENT exception. 198176434Skaiw An attempt to use a <code>DynAny</code> object with the DII may raise the NO_IMPLEMENT 199176434Skaiwexception. 200176434Skaiw 201176434Skaiw 202176434Skaiw 203176434Skaiw 204176528Skaiw 205176434Skaiw 206176434Skaiw<P> 207176434Skaiw 208176434Skaiw 209176434Skaiw<H3>Package Specification</H3> 210176434Skaiw 211176434Skaiw<P>For a precise list of supported sections of official specifications with which 212176528Skaiwthe Java[tm] Platform, Standard Edition 6 ORB complies, see <A 213176434SkaiwHREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA 214176434Skaiwsupport in Java[tm] SE 6</A>. 215176434Skaiw<p> 216224650Semaste@since 1.4 217224650Semaste<br> 218224650Semaste@serial exclude 219224650Semaste</body> 220224650Semaste</html> 221224650Semaste