Mercurial > jdk8-mips64-public > corba / file comparison

comparison: src/share/classes/org/omg/DynamicAny/package.html

src/share/classes/org/omg/DynamicAny/package.html

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

Mercurial Repository: jdk8-mips64-public/corba

mercurial