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

src/share/classes/org/omg/DynamicAny/package.html@65a52284d8a3

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

Tue, 16 Jan 2018 22:52:07 -0800

author
asaha
date
Tue, 16 Jan 2018 22:52:07 -0800
changeset 1662
65a52284d8a3
parent 158
91006f157c46
child 748
6845b95cba6b
permissions
-rw-r--r--

Merge

     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