stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8040147: minor cleanup for docs

Browse Source 
Minor cleanup for docs

Reviewed-by: lancea
This commit is contained in:
Alexander Stepanov 2015-05-26 18:32:10 +04:00
parent 7a711fe858
commit f41f1b4c7a
1 changed files with 61 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
corba/src/java.corba/share/classes/org/omg/DynamicAny/package.html
View File

@ -25,7 +25,7 @@
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any or visit www.oracle.com if you need additional information or have any
questions. questions.
--> -->
</head> </head>
@ -40,97 +40,97 @@ for the type of the <code>any</code> (code generated for the type by an IDL comp
been compiled with the object implementation). As a result, the object receiving the been compiled with the object implementation). As a result, the object receiving the
<code>any</code> does not have a portable method of using it. <code>any</code> does not have a portable method of using it.
<P><code>DynAny</code>s enable traversal of the data value associated with an <P><code>DynAny</code>s enable traversal of the data value associated with an
<code>any</code> at runtime, and extraction of the primitive constituents of the data value. <code>any</code> at runtime, and extraction of the primitive constituents of the data value.
This is especially helpful for writing powerful generic servers (bridges, event channels This is especially helpful for writing powerful generic servers (bridges, event channels
supporting filtering). Similarly, this facility enables the construction of an supporting filtering). Similarly, this facility enables the construction of an
<code>any</code> at runtime, without having static knowledge of its type. This is especially <code>any</code> at runtime, without having static knowledge of its type. This is especially
helpful for writing generic clients (bridges, browsers, debuggers, user interface tools). helpful for writing generic clients (bridges, browsers, debuggers, user interface tools).
<P><code>Any</code> values can be dynamically interpreted (traversed) and constructed through <P><code>Any</code> values can be dynamically interpreted (traversed) and constructed through
<tt>DynAny</tt> objects. A <tt>DynAny</tt> object is associated with a data <tt>DynAny</tt> objects. A <tt>DynAny</tt> object is associated with a data
value which corresponds to a copy of the value inserted into an <tt>Any</tt>. A value which corresponds to a copy of the value inserted into an <tt>Any</tt>. A
<tt>DynAny</tt> object may be viewed as an ordered collection of component <tt>DynAny</tt> object may be viewed as an ordered collection of component
<tt>DynAny</tt>s. For <tt>DynAny</tt>s representing a basic type, such as <code>long</code>, <tt>DynAny</tt>s. For <tt>DynAny</tt>s representing a basic type, such as <code>long</code>,
or a type without components, such as an empty exception, the ordered collection of or a type without components, such as an empty exception, the ordered collection of
components is empty. components is empty.
<P>Each <tt>DynAny</tt> object maintains the notion of a current position into its collection <P>Each <tt>DynAny</tt> object maintains the notion of a current position into its collection
of component <tt>DynAny</tt>s. The current position is identified by an index value that runs of component <tt>DynAny</tt>s. The current position is identified by an index value that runs
from 0 to n-1, where <em>n</em> is the number of components. The special index value -1 from 0 to n-1, where <em>n</em> is the number of components. The special index value -1
indicates a current position that points nowhere. indicates a current position that points nowhere.
For values that cannot have a current position (such as an empty exception), For values that cannot have a current position (such as an empty exception),
the index value is fixed at -1. the index value is fixed at -1.
If a <code>DynAny</code> is initialized with a value that has components, the index is If a <code>DynAny</code> is initialized with a value that has components, the index is
initialized to 0. initialized to 0.
After creation of an uninitialized <code>DynAny</code> (that is, a <code>DynAny</code> that After creation of an uninitialized <code>DynAny</code> (that is, a <code>DynAny</code> that
has no value but a <code>TypeCode</code> has no value but a <code>TypeCode</code>
that permits components), the current position depends on the type of value represented by that permits components), the current position depends on the type of value represented by
the <code>DynAny</code>. (The current position is set to 0 or -1, depending on whether the the <code>DynAny</code>. (The current position is set to 0 or -1, depending on whether the
new <code>DynAny</code> new <code>DynAny</code>
gets default values for its components.) gets default values for its components.)
<P>The iteration operations <code>rewind</code>, <code>seek</code>, and <code>next</code> <P>The iteration operations <code>rewind</code>, <code>seek</code>, and <code>next</code>
can be used to change the current position can be used to change the current position
and the <code>current_component</code> operation returns the component at the current and the <code>current_component</code> operation returns the component at the current
position. position.
The <code>component_count</code> operation returns the number of components of a The <code>component_count</code> operation returns the number of components of a
<code>DynAny</code>. <code>DynAny</code>.
Collectively, these operations enable iteration over the components of a Collectively, these operations enable iteration over the components of a
<code>DynAny</code>, for example, <code>DynAny</code>, for example,
to (recursively) examine its contents. to (recursively) examine its contents.
<P>A constructed <code>DynAny</code> object is a <code>DynAny</code> object associated with <P>A constructed <code>DynAny</code> object is a <code>DynAny</code> object associated with
a constructed type. a constructed type.
There is a different interface, inheriting from the <code>DynAny</code> interface, There is a different interface, inheriting from the <code>DynAny</code> interface,
associated with associated with
each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array,
exception, and value type). A constructed <code>DynAny</code> object exports operations exception, and value type). A constructed <code>DynAny</code> object exports operations
that enable the creation of new <code>DynAny</code> objects, that enable the creation of new <code>DynAny</code> objects,
each of them associated with a component of the constructed data value. each of them associated with a component of the constructed data value.
As an example, a <code>DynStruct</code> is associated with a <code>struct</code> value. This As an example, a <code>DynStruct</code> is associated with a <code>struct</code> value. This
means that the <code>DynStruct</code> means that the <code>DynStruct</code>
may be seen as owning an ordered collection of components, one for each structure member. may be seen as owning an ordered collection of components, one for each structure member.
The <code>DynStruct</code> object exports operations that enable the creation of new The <code>DynStruct</code> object exports operations that enable the creation of new
<code>DynAny</code> objects, <code>DynAny</code> objects,
each of them associated with a member of the <code>struct</code>. each of them associated with a member of the <code>struct</code>.
<P>If a <code>DynAny</code> object has been obtained from another (constructed) <P>If a <code>DynAny</code> object has been obtained from another (constructed)
<code>DynAny</code> object, <code>DynAny</code> object,
such as a <code>DynAny</code> representing a structure member that was created from a such as a <code>DynAny</code> representing a structure member that was created from a
<code>DynStruct</code>, <code>DynStruct</code>,
the member <code>DynAny</code> is logically contained in the <code>DynStruct</code>. the member <code>DynAny</code> is logically contained in the <code>DynStruct</code>.
Calling an <code>insert</code> or <code>get</code> operation leaves the current position Calling an <code>insert</code> or <code>get</code> operation leaves the current position
unchanged. unchanged.
Destroying a top-level <code>DynAny</code> object (one that was not obtained as a component Destroying a top-level <code>DynAny</code> object (one that was not obtained as a component
of another <code>DynAny</code>) of another <code>DynAny</code>)
also destroys any component <code>DynAny</code> objects obtained from it. also destroys any component <code>DynAny</code> objects obtained from it.
Destroying a non-top level <code>DynAny</code> object does nothing. Destroying a non-top level <code>DynAny</code> object does nothing.
Invoking operations on a destroyed top-level <code>DynAny</code> or any of its descendants Invoking operations on a destroyed top-level <code>DynAny</code> or any of its descendants
raises OBJECT_NOT_EXIST. raises OBJECT_NOT_EXIST.
If the programmer wants to destroy a <code>DynAny</code> object but still wants to If the programmer wants to destroy a <code>DynAny</code> object but still wants to
manipulate some component manipulate some component
of the data value associated with it, then he or she should first create a of the data value associated with it, then he or she should first create a
<code>DynAny</code> for the component <code>DynAny</code> for the component
and, after that, make a copy of the created <code>DynAny</code> object. and, after that, make a copy of the created <code>DynAny</code> object.
<P>The behavior of <code>DynAny</code> objects has been defined in order to enable efficient <P>The behavior of <code>DynAny</code> objects has been defined in order to enable efficient
implementations implementations
in terms of allocated memory space and speed of access. <code>DynAny</code> objects are in terms of allocated memory space and speed of access. <code>DynAny</code> objects are
intended to be used intended to be used
for traversing values extracted from <code>any</code>s or constructing values of for traversing values extracted from <code>any</code>s or constructing values of
<code>any</code>s at runtime. <code>any</code>s at runtime.
Their use for other purposes is not recommended. Their use for other purposes is not recommended.
<H2>Handling DynAny objects</H2> <H2>Handling DynAny objects</H2>
<P><code>Insert</code> and <code>get</code> operations are necessary to handle basic <P><code>Insert</code> and <code>get</code> operations are necessary to handle basic
<code>DynAny</code> objects <code>DynAny</code> objects
but are also helpful to handle constructed <code>DynAny</code> objects. but are also helpful to handle constructed <code>DynAny</code> objects.
Inserting a basic data type value into a constructed <code>DynAny</code> object Inserting a basic data type value into a constructed <code>DynAny</code> object
@ -145,9 +145,8 @@ equivalent to
the <code>TypeCode</code> contained in the <code>DynAny</code> or, if the the <code>TypeCode</code> contained in the <code>DynAny</code> or, if the
<code>DynAny</code> has components, is equivalent to the <code>TypeCode</code> <code>DynAny</code> has components, is equivalent to the <code>TypeCode</code>
of the <code>DynAny</code> at the current position. of the <code>DynAny</code> at the current position.
<P>Basic operations include: <P>Basic operations include:
<P>
<UL> <UL>
<LI>insert_boolean, get_boolean <LI>insert_boolean, get_boolean
<LI>insert_char, get_char <LI>insert_char, get_char
@ -181,28 +180,28 @@ equivalent to
<LI>get_boxed_value <LI>get_boxed_value
<LI>get_boxed_value_as_dyn_any <LI>get_boxed_value_as_dyn_any
</UL> </UL>
<P><code>DynAny</code> and <code>DynAnyFactory</code> objects are intended to be local to <P><code>DynAny</code> and <code>DynAnyFactory</code> objects are intended to be local to
the process in which they are the process in which they are
created and used. This means that references to <code>DynAny</code> and created and used. This means that references to <code>DynAny</code> and
<code>DynAnyFactory</code> objects cannot be exported <code>DynAnyFactory</code> objects cannot be exported
to other processes, or externalized with <code>ORB.object_to_string()</code>. to other processes, or externalized with <code>ORB.object_to_string()</code>.
If any attempt is made to do so, the offending operation will raise a MARSHAL system If any attempt is made to do so, the offending operation will raise a MARSHAL system
exception. exception.
Since their interfaces are specified in IDL, <code>DynAny</code> objects export operations Since their interfaces are specified in IDL, <code>DynAny</code> objects export operations
defined in the standard defined in the standard
<code>org.omg.CORBA.Object</code> interface. However, any attempt to invoke operations <code>org.omg.CORBA.Object</code> interface. However, any attempt to invoke operations
exported through the <code>Object</code> exported through the <code>Object</code>
interface may raise the standard NO_IMPLEMENT exception. interface may raise the standard NO_IMPLEMENT exception.
An attempt to use a <code>DynAny</code> object with the DII may raise the NO_IMPLEMENT An attempt to use a <code>DynAny</code> object with the DII may raise the NO_IMPLEMENT
exception. exception.
<H3>Package Specification</H3> <H3>Package Specification</H3>
<P>For a precise list of supported sections of official specifications with which <P>For a precise list of supported sections of official specifications with which
the Java[tm] Platform, Standard Edition 6 ORB complies, see <A the Java[tm] Platform, Standard Edition 6 ORB complies, see <A
HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA
support in Java[tm] SE 6</A>. support in Java[tm] SE 6</A>.
@since 1.4 @since 1.4