package-summary.html

API資料大全

<H3>
Holder classes</H3>
Holder classes are generated by the <code>idltojava</code> compiler as
support for out and inout parameter passing modes.  Because the Java
programming language does not support out or inout parameters, holder
classes are needed as a means of passing a parameter that can be modified.
Holder classes implement the <code>org.omg.CORBA.portable.Streamable</code>
interface in order to support portable stubs and skeletons.
<P>
Holder classes are named by appending "Holder" to the name of the type.
Note that the name of the type refers to its name in the Java programming langua
ge.
For example, a holder class for the interface named <code>Account</code> 
in the Java programming language would be named <code>AccountHolder</code>.
<P>
There are holder classes available for all of the basic IDL data types
in the <code>org.omg.CORBA</code> package. So, for instance, there are
classes already defined for
<code>IntHolder</code>, <code>ShortHolder</code>, <code>LongHolder</code>,
<code>FloatHolder</code>, <code>ByteHolder</code>, <code>CharHolder</code>,
and so on. New holder classes are generated
for all named user-defined IDL types except those defined by a
<code>typedef</code>.
<P>
Each holder class contains the following:
<UL>
<LI> a constructor from an instance
<LI> a default constructor
<LI> a public field, <code>value</code>, which contains an instance of the typed
 value
<LI> a method for reading an input stream and assigning the contents to the type
's
        <code>value</code> field
<LI> a method for writing the value of the <code>value</code> field to an output
 stream
<LI> a method for getting the type code of the type
</UL>
<P>
The default constructor for a holder class sets the <code>value</code>
field to the default value for the type as defined by the Java
programming language.  These default values are:
<UL>
<LI><code>false</code> for <code>boolean</code> types
<LI><code>0</code> for numeric and char types
<LI><code>null</code> for strings
<LI> null for object references
</UL>
<P>
As an example, if the interface <code>Account</code>, defined in OMG IDL,
were mapped to the Java programming language, the following holder class
would be generated:
<PRE><code>

final public class AccountHolder implements
          org.omg.CORBA.portable.Streamable {
    public Account value;
         // the field that holds an Account object
        public AccountHolder() {}
         // the default constructor
        public AccountHolder(Account initial) {...}
         // creates a new AccountHolder from initial
        public void _read(org.omg.CORBA.portable.InputStream is) {...}
         // reads the contents of is and assigns the contents to value
        public void _write(org.omg.CORBA.portable.OutputStream os) {...}
         // writes value to os
        public org.omg.CORBA.TypeCode _type() {...}
         // returns the type code for Account
}


</code></PRE>

<P>The Holder classes defined in the package <TT>org.omg.CORBA</TT> are:
<PRE><code>
&nbsp;&nbsp;&nbsp;&nbsp; <TT>AnyHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>AnySeqHelper
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>BooleanHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>BooleanSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ByteHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>CharHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>CharSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>DoubleHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>DoubleSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>FixedHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>FloatHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>FloatSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>IntHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>LongHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>LongLongSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>LongSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ObjectHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>OctetSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>PrincipalHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ServiceInformationHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ShortHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ShortSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>StringHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>TypeCodeHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ULongLongSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ULongSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>UShortSeqHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>ValueBaseHolder
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>WCharSeqHolder</TT>

</code></PRE>

<h2>Helper Classes </h2>
Some of the classes in this package are "helper" classes.  These classes
fall into two broad categories, helpers for value types and
helpers for non value types. Because all of the helper classes in one category
provide the same methods, one generic explanation of each 
category of helper classes is presented here.
<P>
Note that, generally, the only helper method an application programmer uses is
the <code>narrow</code> method.  The other methods are normally used behind
the scenes and are transparent to the programmer.
<P>
When OMG IDL is mapped to the Java programming language, 
a "helper" class is generated for each user-defined type.
This generated class will have the name of the user-defined type with
the suffix <code>Helper</code> appended.  For example, if the
interface <code>Account</code> is defined in OMG IDL, the
<code>idltojava</code> compiler will automatically generate a class named
<code>AccountHelper</code>.  The <code>AccountHelper</code> class
will contain the static methods needed for manipulating instances of the type,
in this case, <code>Account</code> objects. 
These methods provide the means to insert the
type into an <code>Any</code> object, extract the type from an <code>Any</code>
object, get the type code for the type, get the type's repository id, read the
type from an input stream, and write the type to an output stream. 
Every user-defined type's helper class will include these basic methods.
If a user-defined type is a value type IDL type, it's helper class also
has to implement the <code>ValueHelper</code> interface, so this category of
helper classes will contain additional methods.
<P>In addition,
if the IDL type maps to an interface in the Java programming language, the
helper class will also contain a method for casting an object (narrowing it)
to the type. 

<h3>The <code>narrow</code> Method</h3>
When an object is the return value for a method, it is returned in the
form of a generic object, either an <code>org.omg.CORBA.Object</code> object
or a <code>java.lang.Object</code> object. This object must be cast to its
more specific type before it can be operated on.  For example, an
<code>Account</code> object will be returned as a generic object and must
be narrowed to an <code>Account</code> object so that <code>Account</code>
methods may be called on it.
<P>
The <code>narrow</code> method has two forms, one that takes an
<code>org.omg.CORBA.Object</code> object and one that takes a
<code>java.lang.Object</code> object. Whether the interface is abstract or
not determines which <code>narrow</code> method its helper class will provide.
The helper class for an interface
that is not abstract will have a <code>narrow</code> method that takes a CORBA
object, whereas the <code>narrow</code> method for an interface that is abstract will
take an object in the Java programming language.  The helper class for a
non-abstract interface that has at least one abstract base interface will provide
both versions of the <code>narrow</code> method.
<P> 

<h3>Example of a Basic Helper Class</h3>
A basic helper class, for purposes of this explanation, is one with
the methods that are provided by every helper class, plus a <code>narrow</code> 
method if the type defined in OMG IDL maps to an interface in the Java
programming language.  Types that are not value types will have a basic
helper class generated for them.
<P>
For example, assuming that the interface <code>Account</code> is not a
value type IDL type and is also not an abstract interface and has no
abstract base interfaces, its <code>AccountHelper</code> class will include
the following methods:
<UL>
 <LI><code>public static void <B>insert(org.omg.CORBA.Any a, Account ac)</B></code><br>
Inserts an <code>Account</code> object into an <code>Any</code> object.
<PRE>
Parameters:
   a	the <code>Any</code> object into which the <code>Account</code>
		object will be inserted
   ac	the <code>Account</code> object to be inserted
</PRE>
 <LI><code>public static Account <B>extract(org.omg.CORBA.Any a)</B></code><br>
 Extracts an <code>Account</code> object from an <code>Any</code> object.
<PRE>
Parameters:
   a	the <code>Any</code> object from which the <code>Account</code>
		 object will be extracted
Returns:
   the <code>Account</code> object that is the value for the given <code>Any</code>
   object
</PRE>
 <LI><code>public static org.omg.CORBA.TypeCode <B>type()</B></code><br>
Gets the typecode for this type.
<PRE>
Returns:
   the typecode for an <code>Account</code> object
</PRE>
<LI><code>public static String <B>id()</B></code><br>
Gets the repository id for this type.
 <PRE>
Returns:
   the repository id of an <code>Account</code> object
</PRE>
 <LI><code>public static Account
   <B>read(org.omg.CORBA.portable.InputStream istream)</B></code><br>
Reads an <code>Account</code> object from an input stream.
 <PRE>
Parameters:
   istream	the input stream from which the <code>Account</code>
			 object will be read
Returns:
   the <code>Account</code> object that was contained in the input stream
 </PRE>
 <LI><code>public static void
   <B>write(org.omg.CORBA.portable.OutputStream ostream)</B></code><br>
Writes an <code>Account</code> object to an output stream.
<PRE>
Parameters:
   ostream	the output stream to which the <code>Account</code>
			 object will be written
 </PRE>
 <LI><code>public static Account <B>narrow(org.omg.CORBA.Object obj)</B></code><br>
Converts (narrows) an <code>Object</code> object to an <code>Account</code> object.
 <PRE>
Parameters:
   obj	the CORBA <code>Object</code> that will be narrowed to this type
Returns:
   the CORBA <code>Object</code> as an <code>Account</code> object
 </PRE>
</UL>
<P>

<h3>Additional Methods for Value Type Helper Classes</h3>
A helper class for a value type includes some additional methods because
it must implement the <code>org.omg.CORBA.portable.ValueHelper</code>
interface. The main difference is that value types are types that can be
passed by value as parameters or return values of a method, which means that
they must be serializable.
<P>Assuming that <code>Address</code> is a value type, the
<code>AddressHelper</code> class will include the following additional methods:
<UL>
 <LI><code>public static ValueHelper <B>get_instance()</B></code><BR>
 Gets an instance of <code>AddressHelper</code>, creating it if necessary.
 <PRE>
Returns:
   an <code>AddressHelper</code> object, which implements the interface
   <code>ValueHelper</code>
 </PRE>
 <LI><code>public java.io.Serializable
	<B>read_Value(org.omg.CORBA.portable.InputStream istream)</B></code><BR>
 Reads a serializable instance of <code>Address</code> from the given input stream.
 <PRE>
Parameters:
   istream	the input stream from which the <code>Address</code> object will
			 be read
Returns:
   the serialized <code>Address</code> object
 </PRE>
 <LI><code>public void <B>write_Value(org.omg.CORBA.portable.OutputStream os,
	 java.io.Serializable obj)</B></code><BR>
 Writes a serializable instance of <code>Address</code> to the given output stream.
 <PRE>
Parameters:
   ostream	the output stream to which the <code>Address</code> object will
       		be written
   obj		the serialized <code>Address</code> object that will be written
 </PRE>
 <LI><code>public Class <B>get_class()</B></code><BR>
	 Returns the class for an instance of <code>Address</code>.
 <PRE>
Returns:
   the <code>Class</code> object for this type
 </PRE>
 <LI><code>public String <B>get_id()</B></code><BR>
	 Gets the repository id for an instance of <code>Address</code>.
 <PRE>
Returns:
   the repository id for this type
 </PRE>
 <LI><code>public String [] <B>get_truncatable_base_ids()</B></code><BR>
	 Gets an array of the truncatable base repository ids for an
	 instance of <code>Address</code>.
 <PRE>
Returns:
   an array of <code>String</code> objects containing the truncatable base 
   repository ids for this type
 </PRE>
 <LI><code>public org.omg.CORBA.TypeCode <B>get_type()</B></code><BR>
	 Gets the typecode for the type <code>Address</code>.
 <PRE>
Returns:
   the <code>TypeCode</code> object indicating the type of an 
   <code>Address</code> object
 </PRE>
</UL>

<P>The Helper classes defined in the package <TT>org.omg.CORBA</TT> are:
<PRE><code>
&nbsp;&nbsp;&nbsp;&nbsp; <TT>AnySeqHelper
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>AttrDescriptionSeqHelper
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>AttributeDescriptionHelper
</TT>&nbsp;&nbsp;&nbsp;&nbsp; <TT>AttributeModeHelper
</T