|
4
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<!--
|
|
|
5 |
|
|
29827
|
6 |
Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
|
|
4
|
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
|
|
5555
|
11 |
published by the Free Software Foundation. Oracle designates this
|
|
4
|
12 |
particular file as subject to the "Classpath" exception as provided
|
|
5555
|
13 |
by Oracle in the LICENSE file that accompanied this code.
|
|
4
|
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 |
|
|
5555
|
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.
|
|
4
|
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 |
<H3>Package Specification</H3>
|
|
29827
|
202 |
|
|
4
|
203 |
<P>For a precise list of supported sections of official specifications with which
|
|
|
204 |
the Java[tm] Platform, Standard Edition 6 ORB complies, see <A
|
|
|
205 |
HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA
|
|
|
206 |
support in Java[tm] SE 6</A>.
|
|
29827
|
207 |
|
|
4
|
208 |
@since 1.4
|
|
|
209 |
<br>
|
|
|
210 |
@serial exclude
|
|
|
211 |
</body>
|
|
|
212 |
</html>
|