| <!doctype html> |
| <HTML> |
| <HEAD> |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> |
| <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en]C-gatewaynet (WinNT; U) |
| [Netscape]"> |
| <TITLE>package</TITLE> |
| <!-- |
| /* |
| * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 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 |
| * questions. |
| */ |
| --> |
| </HEAD> |
| <BODY> |
| Provides the mapping of the OMG CORBA APIs to the Java™ |
| programming language, including the class <code>ORB</code>, which is implemented |
| so that a programmer can use it as a fully-functional Object Request Broker |
| (ORB). |
| |
| <P>For a precise list of supported sections of official CORBA specifications with which |
| the Java[TM] Platform, Standard Edition 6 complies, see <A |
| HREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in |
| Java[TM] SE 6</em></A>. |
| |
| |
| <H1>General Information</H1> |
| The information in this section is information relevant to someone who |
| compiles Interface Definition Language (IDL) files and uses the |
| ORB to write clients and servers. |
| |
| <P>The classes and interfaces described in this section can be put into |
| four groups: <code>ORB classes</code>, Exceptions, <code>Helper</code> classes, |
| and <code>Holder</code> classes. |
| |
| <H2> |
| The <code>ORB</code> Class</H2> |
| |
| <P>An ORB handles (or brokers) method invocations between a client and |
| the method's implementation on a server. Because the client and server |
| may be anywhere on a network, and because the invocation and implementation |
| may be written in different programming languages, an ORB does a great |
| deal of work behind the scenes to accomplish this communication. |
| |
| <P>Most of what an ORB does is completely transparent to the user, and a major |
| portion of the <code>CORBA</code> package consists of classes used by the ORB |
| behind the scenes. The result is that most programmers will use only a |
| small part of this package directly. In fact, most programmers will use |
| only a few methods from the <code>ORB</code> class, some exceptions, and |
| occasionally, |
| a holder class. |
| <H3> |
| <code>ORB</code> Methods</H3> |
| |
| <P>Before an application can enter the CORBA environment, it must first: |
| <UL> |
| <LI>Be initialized into the ORB and possibly the object adapter (POA) environments. |
| <LI>Get references to ORB object (for use in future ORB operations) |
| and perhaps other objects (including the root POA or some Object Adapter objects). |
| </UL> |
| <P>The following operations are provided to initialize applications and obtain |
| the appropriate object references: |
| <UL> |
| <LI>Operations providing access to the ORB, which are discussed in this |
| section. |
| <LI>Operations providing access to Object Adapters, Interface Repository, |
| Naming Service, and other Object Services. These operations are described |
| in <a href="#adv"><em>Other Classes</em></a>. |
| </UL> |
| <P> |
| When an application requires a CORBA environment it needs a mechanism to |
| get an ORB object reference and possibly an OA object reference |
| (such as the root POA). This serves two purposes. First, it initializes |
| an application into the ORB and OA environments. Second, it returns the |
| ORB object reference and the OA object reference to the application |
| for use in future ORB and OA operations. |
| |
| <P>In order to obtain an ORB object reference, applications call |
| the <code>ORB.init</code> operation. The parameters to the call can comprise an |
| identifier for the ORB for which the object reference is required, |
| and an arg_list, which is used to allow environment-specific data to be |
| passed into the call. |
| |
| <P>These are the <code>ORB</code> methods |
| that provide access to the ORB: |
| <UL> |
| <LI> |
| <code><b>init</b>()</code> |
| |
| <LI> |
| <code><b>init</b>(String [] args, Properties props)</code> |
| |
| <LI> |
| <code><b>init</b>(Applet app, Properties props)</code> |
| </UL> |
| |
| <P>Using the <code>init()</code> method without parameters initiates |
| a singleton ORB, which can only |
| give typecode creation <code>any</code>s needed in code generated |
| in Helper classes by <code>idlj</code>. |
| |
| <P>Applications require a portable means by which to obtain their |
| initial object references. References are required for the root |
| POA, POA Current, Interface Repository, and various Object Services |
| instances. The functionality required by the application is similar |
| to that provided by the Naming Service. However, the OMG does not |
| want to mandate that the Naming Service be made available to all |
| applications in order that they may be portably initialized. |
| Consequently, the operations shown in this section provide a |
| simplified, local version of the Naming Service that applications |
| can use to obtain a small, defined set of object references which |
| are essential to its operation. Because only a small well-defined |
| set of objects are expected with this mechanism, the naming context |
| can be flattened to be a single-level name space. This simplification |
| results in only two operations being defined to achieve the functionality |
| required. |
| |
| <P>Initial references are obtained via two operations provided in |
| the ORB object interface, providing facilities to list and |
| resolve initial object references. These are: |
| <UL> |
| <LI> |
| <code><b>resolve_initial_references</b>(String name)</code> |
| <LI> |
| <code><b>list_initial_services</b>()</code> |
| <LI> |
| <code><b>register_initial_reference</b>(String id, org.omg.CORBA.Object obj)</code> |
| </UL> |
| |
| <P>An example that uses some of these methods is {@extLink idl_getting_started Getting Started with Java IDL}. |
| |
| <H2> |
| Exceptions</H2> |
| Exceptions in Java IDL are similar to those in any code written in the |
| Java programming language. If a method is defined to throw an exception, |
| then any code using that method must have a <code>try</code>/<code>catch</code> |
| block and handle that exception when it is thrown. |
| |
| <P>The documentation on {@extLink jidlexception Java IDL exceptions } |
| has more information and explains the difference between |
| system exceptions and user-defined exceptions. |
| |
| <P>The following is a list of the system exceptions (which are unchecked |
| exceptions inheriting through <code><a href="SystemException.html"> |
| org.omg.CORBA.SystemException</a></code> from |
| <code>java.lang.RuntimeException</code>) that are defined in the package |
| <code>org.omg.CORBA</code>: |
| <PRE><code> |
| BAD_CONTEXT |
| BAD_INV_ORDER |
| BAD_OPERATION |
| BAD_PARAM |
| BAD_TYPECODE |
| COMM_FAILURE |
| DATA_CONVERSION |
| FREE_MEM |
| IMP_LIMIT |
| INITIALIZE |
| INTERNAL |
| INTF_REPOS |
| INVALID_TRANSACTION |
| INV_FLAG |
| INV_IDENT |
| INV_OBJREF |
| INV_POLICY |
| MARSHAL |
| <a href="#NO_IMPLEMENT">NO_IMPLEMENT</a> |
| NO_MEMORY |
| NO_PERMISSION |
| NO_RESOURCES |
| NO_RESPONSE |
| OBJECT_NOT_EXIST |
| OBJ_ADAPTER |
| PERSIST_STORE |
| TRANSACTION_REQUIRED |
| TRANSACTION_ROLLEDBACK |
| TRANSIENT |
| UNKNOWN |
| </code></PRE> |
| <P> |
| The following is a list of user-defined exceptions defined in the package |
| <code>org.omg.CORBA</code>. |
| <PRE><code> |
| Bounds |
| UnknownUserException |
| WrongTransaction |
| PolicyError |
| </code></PRE> |
| |
| <H2>Subpackages</H2> |
| There are some packages inside the <code>CORBA</code> package with |
| "Package" as part of their names. These packages are generally quite small |
| because all they do is provide exceptions or classes for use by interfaces |
| and classes in the <code>CORBA</code> package. |
| |
| <P>For example, the package <code><a href="TypeCodePackage/package-summary.html"> |
| org.omg.CORBA.TypeCodePackage</a></code> contains |
| two exceptions thrown by methods in the class <code>TypeCode</code>. These |
| exceptions are: |
| <UL> |
| <LI> |
| <code>BadKind</code> |
| |
| <LI> |
| <code>Bounds</code> |
| </UL> |
| The package <code><a href="ORBPackage/package-summary.html"> |
| org.omg.CORBA.ORBPackage</a></code> contains two exceptions: |
| <UL> |
| <LI> |
| <code>InvalidName</code> |
| |
| <LI> |
| <code>InconsistentTypeCode</code> |
| </UL> |
| |
| <P>Another package that is a subpackage of <code>CORBA</code> is the |
| <code><a href="portable/package-summary.html">portable</a></code> |
| package. It provides a set of ORB APIs that makes it |
| possible for code generated by one vendor's IDL compiler to run |
| on another vendor's ORB. |
| |
| |
| |
| |
| <H2> |
| Holder classes</H2> |
| |
| |
| <P>Support for out and inout parameter passing modes requires the use of |
| additional <em><a href="doc-files/generatedfiles.html#holder">holder |
| classes</a></em>. 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. To support portable stubs and skeletons, |
| holder classes also implement the |
| <code><a href="portable/Streamable.html">org.omg.CORBA.portable.Streamable</a></code> |
| interface. |
| |
| <P>Holder classes are named by appending "Holder" to the name of the type. |
| The name of the type refers to its name in the Java programming language. For |
| example, a holder class for the interface named <code>Account</code> |
| in the Java programming |
| language would be named <code>AccountHolder</code>. |
| |
| |
| <P>Holder classes are available for all of the basic IDL |
| datatypes in the <code>org.omg.CORBA</code> package. So, for example, |
| there are already-defined classes for <code>LongHolder</code>, <code>ShortHolder</code>, |
| <code>FloatHolder</code>, and so on. Classes are also generated for |
| all named user-defined IDL types except those defined by <code>typedefs</code>. |
| (Note that in this context user defined includes types that are |
| defined in OMG specifications such as those for the Interface |
| Repository, and other OMG services.) |
| |
| |
| <P>Each holder class has: |
| <UL> |
| <LI>a constructor from an instance |
| <LI>a default constructor |
| <LI>a public instance member, <code>value</code> which is 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 typecode of the type |
| </UL> |
| |
| <P>The default constructor sets the value field to the default value for the |
| type as defined by the Java language: |
| <UL> |
| <LI><code>false</code> for boolean |
| <LI><code>0</code> for numeric and char types |
| <LI><code>null</code> for strings and 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> |
| public final class AccountHolder implements |
| org.omg.CORBA.portable.Streamable |
| { |
| // field that holds an Account object |
| public Account value = null; |
| |
| // default constructor |
| public AccountHolder () |
| { |
| } |
| |
| // creates a new AccountHolder from initialValue |
| public AccountHolder (Account initialValue) |
| { |
| value = initialValue; |
| } |
| |
| // reads the contents of i and assigns the contents to value |
| public void _read (org.omg.CORBA.portable.InputStream i) |
| { |
| value = AccountHelper.read (i); |
| } |
| |
| // writes value to o |
| public void _write (org.omg.CORBA.portable.OutputStream o) |
| { |
| AccountHelper.write (o, value); |
| } |
| |
| // returns the typecode for Account |
| public org.omg.CORBA.TypeCode _type () |
| { |
| return AccountHelper.type (); |
| } |
| |
| } |
| </PRE> |
| |
| <P>For more information on Holder classes, see Chapter 1.4, <em>Mapping for |
| Basic Types</em> in the <a href="http://www.omg.org/cgi-bin/doc?ptc/00-01-08"> |
| <em>OMG IDL to Java Language Mapping</em></a>. The Holder classes defined |
| in the package <code>org.omg.CORBA</code> are: |
| <PRE><code> |
| AnyHolder |
| AnySeqHolder |
| BooleanHolder |
| BooleanSeqHolder |
| ByteHolder |
| CharHolder |
| CharSeqHolder |
| CurrentHolder |
| DoubleHolder |
| DoubleSeqHolder |
| FixedHolder |
| FloatHolder |
| FloatSeqHolder |
| IntHolder |
| LongHolder |
| LongLongSeqHolder |
| LongSeqHolder |
| ObjectHolder |
| OctetSeqHolder |
| ParameterModeHolder |
| PolicyErrorHolder |
| PolicyListHolder |
| PrincipalHolder |
| ServiceInformationHolder |
| ShortHolder |
| ShortSeqHolder |
| StringHolder |
| StringSeqHolder |
| TypeCodeHolder |
| ULongLongSeqHolder |
| ULongSeqHolder |
| UnknownUserExceptionHolder |
| UShortSeqHolder |
| ValueBaseHolder |
| WCharSeqHolder |
| WrongTransactionHolder |
| WStringSeqHolder |
| </code></PRE> |
| |
| <h2>Helper Classes </h2> |
| <P>Helper files supply several static methods needed to manipulate the type. |
| These include: |
| <UL> |
| <LI><code>Any</code> insert and extract operations for the type |
| <LI>getting the repository id |
| <LI>getting the typecode |
| <LI>reading and writing the type from and to a stream |
| <LI>implement the <code>ValueHelper</code> interface (if it is a user-defined |
| value type) |
| </UL> |
| |
| <P>The helper class for a mapped IDL interface or abstract interface |
| also include narrow operation(s). The static narrow method allows |
| an <code>org.omg.CORBA.Object</code> to be narrowed to the object reference |
| of a more specific type. The IDL exception <code>CORBA.BAD_PARAM</code> |
| is thrown if the narrow fails because the object reference does not |
| support the requested type. A different system exception is raised |
| to indicate other kinds of errors. Trying to narrow a <code>null</code> will always |
| succeed with a return value of <code>null</code>. |
| 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>Helper classes |
| fall into two broad categories, <a href="#value">helpers for value types</a> and |
| <a href="#basic">helpers for non value types</a>. 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> |
| 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>idlj</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. |
| |
| |
| <a id="narrow"></a> |
| <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>The {@extLink idl_guides Hello World tutorial} |
| uses a <code>narrow</code> method that looks like this: |
| <PRE> |
| // create and initialize the ORB |
| ORB orb = ORB.init(args, null); |
| |
| // get the root naming context |
| org.omg.CORBA.Object objRef = |
| orb.resolve_initial_references("NameService"); |
| // Use NamingContextExt instead of NamingContext. This is |
| // part of latest Inter-Operable naming Service. |
| NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef); |
| |
| // resolve the Object Reference in Naming |
| String name = "Hello"; |
| helloImpl = HelloHelper.narrow(ncRef.resolve_str(name)); |
| </PRE> |
| |
| <a id="basic"></a> |
| <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 look |
| like this: |
| <PRE> |
| abstract public class AccountHelper |
| { |
| private static String _id = "IDL:Account:1.0"; |
| |
| // inserts an Account object into an Any object |
| public static void insert (org.omg.CORBA.Any a, Account that) |
| { |
| org.omg.CORBA.portable.OutputStream out = a.create_output_stream (); |
| a.type (type ()); |
| write (out, that); |
| a.read_value (out.create_input_stream (), type ()); |
| } |
| |
| // extracts an Account object from an Any object |
| public static Account extract (org.omg.CORBA.Any a) |
| { |
| return read (a.create_input_stream ()); |
| } |
| |
| |
| private static org.omg.CORBA.TypeCode __typeCode = null; |
| // gets the typecode for this type |
| synchronized public static org.omg.CORBA.TypeCode type () |
| { |
| if (__typeCode == null) |
| { |
| __typeCode = org.omg.CORBA.ORB.init ().create_interface_tc (AccountHelper.id (), "Account"); |
| } |
| return __typeCode; |
| } |
| |
| // gets the repository id for this type |
| public static String id () |
| { |
| return _id; |
| } |
| |
| // reads an Account object from an input stream |
| public static Account read (org.omg.CORBA.portable.InputStream istream) |
| { |
| return narrow (istream.read_Object (_AccountStub.class)); |
| } |
| |
| // writes an Account object to an outputstream |
| public static void write (org.omg.CORBA.portable.OutputStream ostream, Account value) |
| { |
| ostream.write_Object ((org.omg.CORBA.Object) value); |
| } |
| |
| // converts (narrows) an Object to an Account object |
| public static Account narrow (org.omg.CORBA.Object obj) |
| { |
| if (obj == null) |
| return null; |
| else if (obj instanceof Account) |
| return (Account)obj; |
| else if (!obj._is_a (id ())) |
| throw new org.omg.CORBA.BAD_PARAM (); |
| else |
| { |
| org.omg.CORBA.portable.Delegate delegate = ((org.omg.CORBA.portable.ObjectImpl)obj)._get_delegate (); |
| _AccountStub stub = new _AccountStub (); |
| stub._set_delegate(delegate); |
| return stub; |
| } |
| } |
| |
| } |
| </PRE> |
| |
| <a id="value"></a> |
| <h3>Value Type Helper Classes</h3> |
| A helper class for a value type includes different renderings of |
| the same methods generated for non-value type methods. 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 look like this: |
| <pre> |
| abstract public class AddressHelper |
| { |
| private static String _id = "IDL:Address:1.0"; |
| |
| // same as for non-value type |
| public static void insert (org.omg.CORBA.Any a, Address that) |
| { |
| org.omg.CORBA.portable.OutputStream out = a.create_output_stream (); |
| a.type (type ()); |
| write (out, that); |
| a.read_value (out.create_input_stream (), type ()); |
| } |
| |
| // same as for non-value type |
| public static Address extract (org.omg.CORBA.Any a) |
| { |
| return read (a.create_input_stream ()); |
| } |
| |
| private static org.omg.CORBA.TypeCode __typeCode = null; |
| private static boolean __active = false; |
| |
| // getting the typecode for the type |
| synchronized public static org.omg.CORBA.TypeCode type () |
| { |
| if (__typeCode == null) |
| { |
| synchronized (org.omg.CORBA.TypeCode.class) |
| { |
| if (__typeCode == null) |
| { |
| if (__active) |
| { |
| return org.omg.CORBA.ORB.init().create_recursive_tc ( _id ); |
| } |
| __active = true; |
| org.omg.CORBA.ValueMember[] _members0 = new org.omg.CORBA.ValueMember[0]; |
| org.omg.CORBA.TypeCode _tcOf_members0 = null; |
| __typeCode = org.omg.CORBA.ORB.init ().create_value_tc (_id, "Address", org.omg.CORBA.VM_NONE.value, null, _members0); |
| __active = false; |
| } |
| } |
| } |
| return __typeCode; |
| } |
| |
| // same as for non-value type |
| public static String id () |
| { |
| return _id; |
| } |
| |
| // reads a serializable instance of Address from the given input stream |
| public static Address read (org.omg.CORBA.portable.InputStream istream) |
| { |
| return (Address)((org.omg.CORBA_2_3.portable.InputStream) istream).read_value (id ()); |
| } |
| |
| // writes a serializable instance of Address to the given output stream |
| public static void write (org.omg.CORBA.portable.OutputStream ostream, Address value) |
| { |
| ((org.omg.CORBA_2_3.portable.OutputStream) ostream).write_value (value, id ()); |
| } |
| |
| |
| } |
| </pre> |
| |
| <P>The Helper classes defined in the package <code>org.omg.CORBA</code> are: |
| <PRE><code> |
| AnySeqHelper |
| BooleanSeqHelper |
| CharSeqHelper |
| CompletionStatusHelper |
| CurrentHelper |
| DefinitionKindHelper |
| DoubleSeqHelper |
| FieldNameHelper |
| FloatSeqHelper |
| IdentifierHelper |
| IDLTypeHelper |
| LongLongSeqHelper |
| LongSeqHelper |
| NameValuePairHelper |
| ObjectHelper |
| OctetSeqHelper |
| ParameterModeHelper |
| PolicyErrorCodeHelper |
| PolicyErrorHelper |
| PolicyHelper |
| PolicyListHelper |
| PolicyTypeHelper |
| RepositoryIdHelper |
| ServiceDetailHelper |
| ServiceInformationHelper |
| SetOverrideTypeHelper |
| ShortSeqHelper |
| StringSeqHelper |
| StringValueHelper |
| StructMemberHelper |
| ULongLongSeqHelper |
| ULongSeqHelper |
| UnionMemberHelper |
| UnknownUserExceptionHelper |
| UShortSeqHelper |
| ValueBaseHelper |
| ValueMemberHelper |
| VersionSpecHelper |
| VisibilityHelper |
| WCharSeqHelper |
| WrongTransactionHelper |
| WStringSeqHelper |
| WStringValueHelper |
| </code></PRE> |
| <a id="adv"></a> |
| <H1> |
| Other Classes</H1> |
| The other classes and interfaces in the <code>CORBA</code> package, which are |
| used behind the scenes, can be put into four groups. Three of the groups |
| are used with requests in some capacity, and the fourth group, concerning |
| the Interface Repository, is a category by itself. |
| <H2> |
| Classes Created by an ORB</H2> |
| The first group contains classes that are created by an ORB and contain |
| information used in request operations. |
| <UL> |
| <LI> |
| <code>TCKind</code> -- indicates the kind (datatype) for a <code>TypeCode</code> |
| object |
| |
| <LI> |
| <code>TypeCode</code> -- indicates a datatype and possibly other information |
| |
| <LI> |
| <code>Any</code> -- contains a value and its typecode |
| |
| <LI> |
| <code>NamedValue</code> -- contains a name, an <code>Any</code> object, and an |
| argument mode flag. <code>NamedValue</code> objects contain information about |
| method arguments, method return values, or a context. |
| |
| <LI> |
| <code>ContextList</code> -- a list of strings that describe the contexts that |
| need to be resolved and sent with an invocation |
| |
| <LI> |
| <code>ExceptionList</code> -- a list of <code>TypeCode</code>s for exceptions that |
| may be thrown by a method |
| |
| <LI> |
| <code>Environment</code> -- a container for the exception thrown during a method |
| invocation |
| |
| <LI> |
| <code>Context</code> -- a list of <code>NamedValue</code> objects used to pass |
| auxiliary information from client to server |
| |
| <LI> |
| <code>NVList</code> -- a list of <code>NamedValue</code> objects, used to pass |
| arguments or get results |
| </UL> |
| |
| <H2> |
| Classes That Deal with Requests</H2> |
| The second group of classes deals with requests: |
| <UL> |
| <LI> |
| <code>Object</code> -- the base class for all CORBA object references |
| |
| <LI> |
| <code>Request</code> -- the main class in the DII, which contains methods for |
| adding arguments to the request, for accessing information about the method |
| being invoked (the method name, its arguments, exceptions it throws, and |
| so on), and for making invocations on the request |
| |
| <LI> |
| <code>DynamicImplementation</code> -- the base class for server implementations |
| using the DSI. It has the method <code>invoke</code>, which is used by an |
| implementation |
| of this class to determine the state of a <code>ServerRequest</code> object |
| and to set its result or exception |
| |
| <LI> |
| <code>ServerRequest</code> -- captures the explicit state of a request for |
| the Dynamic Skeleton Interface |
| </UL> |
| |
| <H2> |
| Interfaces That Serve as Constants</H2> |
| The third group contains interfaces that serve as constants. The IDL-to-Java |
| mapping mandates that IDL enums are mapped to a Java class with the enumerated |
| values represented as public static final fields in that class (e.g. |
| DefinitionKind). |
| On the other hand IDL constants defined outside of an IDL interface are |
| mapped to a Java interface for each constant. |
| |
| <P>This is why several interfaces in the <code>org.omg.CORBA</code> package |
| consist of a single field, <code>value</code>, which is a <code>short</code>. This |
| field is a constant used for such things as an error code or value modifier. |
| For example, the <code>value</code> field of the interface <code>BAD_POLICY</code> |
| is one of the possible reasons for the exception <code>PolicyError</code> to |
| be thrown. To specify this error code, you would use <code>BAD_POLICY.value</code>. |
| |
| <P>The exception <code>PolicyError</code> uses the <code>value</code> field of |
| the following interfaces as its possible error codes. |
| <UL> |
| <LI> |
| <code>BAD_POLICY</code> |
| |
| <LI> |
| <code>BAD_POLICY_TYPE</code> |
| |
| <LI> |
| <code>BAD_POLICY_VALUE</code> |
| |
| <LI> |
| <code>UNSUPPORTED_POLICY</code> |
| |
| <LI> |
| <code>UNSUPPORTED_POLICY_VALUE</code> |
| </UL> |
| The method <code>TypeCode.type_modifier</code> returns the <code>value</code> field |
| of one of the following interfaces. The <code>VM</code> in the names of these |
| interfaces stands for "value modifier." |
| <UL> |
| <LI> |
| <code>VM_NONE</code> |
| |
| <LI> |
| <code>VM_ABSTRACT</code> |
| |
| <LI> |
| <code>VM_CUSTOM</code> |
| |
| <LI> |
| <code>VM_TRUNCATABLE</code> |
| </UL> |
| The following constants are returned by a <code>ValueMember</code> object's |
| access method to denote the visibility of the <code>ValueMember</code> object. |
| <UL> |
| <LI> |
| <code>PRIVATE_MEMBER</code> |
| |
| <LI> |
| <code>PUBLIC_MEMBER</code> |
| </UL> |
| These flags, used in <code>NamedValue</code> objects or as parameters to methods, |
| are defined in the following interfaces: |
| <UL> |
| <LI> |
| <code>ARG_IN</code> |
| |
| <LI> |
| <code>ARG_INOUT</code> |
| |
| <LI> |
| <code>ARG_OUT</code> |
| |
| <LI> |
| <code>CTX_RESTRICT_SCOPE</code> |
| </UL> |
| |
| <H2> |
| Interface Repository Interfaces and Classes</H2> |
| A fourth group contains the Interface Repository interfaces and classes, |
| which are generated by the <code>idlj</code> compiler from the OMG IDL |
| interface <code>ir.idl</code>. The purpose of the Interface Repository is to |
| identify the interfaces stored in it so that they can be accessed by an |
| ORB. Each module, type, interface, attribute, operation, parameter, exception, |
| constant, and so on is described completely by the Interface Repository |
| API. |
| |
| <P>An ORB does not require that there be an interface repository, and Java |
| IDL does not include one. Even though this release does not include an |
| implementation of an interface repository, the following IR classes and |
| interfaces have been included for the purpose of creating typecodes (see |
| create_value_tc, create_struct_tc, create_union_tc and create_exception_tc |
| methods in interface org.omg.CORBA.ORB): |
| <BR> |
| <UL> |
| <LI> |
| IRObject |
| |
| <LI> |
| IDLType |
| |
| <LI> |
| DefinitionKind |
| |
| <LI> |
| StructMember |
| |
| <LI> |
| UnionMember |
| |
| <LI> |
| ValueMember |
| </UL> |
| <!-- End Page Data --> |
| <HR> |
| <H1> |
| Related Documentation</H1> |
| For overviews, guides, and a tutorial, please see: |
| <UL> |
| <LI> {@extLink idl_guides Java IDL tutorial page}.</LI> |
| <LI> {@extLink rmi_iiop_guides RMI-IIOP developer's guide}.</LI> |
| </UL> |
| |
| |
| |
| |
| <P><A id="unimpl"></A> |
| <H1> |
| CORBA Features Not Implemented in Java IDL</H1> |
| |
| <P>Some of the API included in <code>org.omg</code> subpackages is provided for |
| conformance with the current OMG CORBA specification but is not implemented |
| in Sun's release of the JDK™. This enables |
| other JDK licensees to provide implementations of this API in standard |
| extensions and products. |
| |
| <P><A id="NO_IMPLEMENT"></A> |
| <h2>Features That Throw NO_IMPLEMENT</h2> |
| |
| <P>Some of the API included in <code>org.omg</code> subpackages throw |
| <code>NO_IMPLEMENT</code> exceptions for various reasons. Among these reasons |
| are: |
| <UL> |
| <LI>In some cases, for example <code>LocalObject</code>, the complete |
| implementation according to the specification indicates that |
| these API should throw <code>NO_IMPLEMENT</code>. |
| |
| <LI>In most cases, for example methods in <code>ORB.java</code>, |
| methods that throw |
| <code>NO_IMPLEMENT</code> are actually implemented in subclasses |
| elsewhere in the ORB code. |
| |
| <LI>In some cases, for example <code>_get_interface_def()</code> |
| and <code>_get_interface</code>, API are really not yet implemented. |
| </UL> |
| |
| |
| |
| |
| <H2> |
| General Summary of Features or API Not Implemented in This Release:</H2> |
| |
| <UL> |
| <LI> |
| Interface Repository. An Interface Repository is not required for normal |
| operation of Java IDL. |
| |
| <LI> |
| Java IDL does not support <code>long double</code>. |
| |
| |
| <LI> |
| Policies (<code><a href="Policy.html">org.omg.CORBA.Policy</a></code>) |
| and methods for getting them are not implemented. |
| |
| <LI> |
| Domain managers (<code><a href="DomainManager.html">org.omg.CORBA.DomainManager</a></code>) and methods for |
| getting them are not implemented. |
| |
| <LI> |
| Service Information <code><a href="ServiceInformation.html">org.omg.CORBA.ServiceInformation</a></code> |
| and ORB method |
| <code>public boolean get_service_information(short service_type, ServiceInformationHolder service_info)</code> |
| are not implemented. |
| |
| <LI>ORB methods for supporting single-threading |
| (<code>perform_work</code>, <code>work_pending</code>) are not implemented. |
| |
| <LI>IDL contexts. |
| </UL> |
| |
| <HR> |
| <H2> |
| Specific List of Unimplemented Features in Package <code>org.omg.CORBA</code></H2> |
| |
| |
| <H3> |
| Unimplemented Methods in package <code>org.omg.CORBA</code>:</H3> |
| |
| <UL> |
| <LI> |
| <code>ORB</code> |
| |
| <UL> |
| <LI> |
| <code>public org.omg.CORBA.Policy create_policy(int type, org.omg.CORBA.Any val)</code> |
| |
| |
| |
| <LI> |
| <code>public void perform_work()</code> |
| |
| <LI> |
| <code>public boolean work_pending()</code> |
| |
| <LI> |
| <code>public org.omg.CORBA.Current get_current()</code> |
| |
| <LI> |
| <code>create_operation_list</code> |
| |
| <LI> |
| <code>get_default_context</code> |
| |
| <LI> |
| <code>get_service_information</code> |
| |
| <LI> |
| obsolete <code>DynAnys</code> (deprecated in favor of <code>DynamicAny</code> package) |
| |
| |
| </UL> |
| |
| |
| |
| </UL> |
| @since JDK1.2 |
| @serial exclude |
| </BODY> |
| </HTML> |