1 <HTML>
2 <HEAD>
3 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
4 <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en]C-gatewaynet (WinNT; U)
5 [Netscape]">
6 <TITLE>package</TITLE>
7 <!--
8 /*
9 * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.
10 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
11 *
12 * This code is free software; you can redistribute it and/or modify it
13 * under the terms of the GNU General Public License version 2 only, as
14 * published by the Free Software Foundation. Oracle designates this
15 * particular file as subject to the "Classpath" exception as provided
16 * by Oracle in the LICENSE file that accompanied this code.
17 *
18 * This code is distributed in the hope that it will be useful, but WITHOUT
19 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
20 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * version 2 for more details (a copy is included in the LICENSE file that
22 * accompanied this code).
23 *
24 * You should have received a copy of the GNU General Public License version
25 * 2 along with this work; if not, write to the Free Software Foundation,
26 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
27 *
28 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
29 * or visit www.oracle.com if you need additional information or have any
30 * questions.
31 */
32 -->
33 </HEAD>
34 <BODY BGCOLOR="#FFFFFF">
35 Provides the mapping of the OMG CORBA APIs to the Java<SUP><FONT
36 SIZE=-2>TM</FONT></SUP>
37 programming language, including the class <code>ORB</code>, which is implemented
38 so that a programmer can use it as a fully-functional Object Request Broker
39 (ORB).
40
41 <P>For a precise list of supported sections of official CORBA specifications with which
42 the Java[TM] Platform, Standard Edition 6 complies, see <A
43 HREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in
44 Java[TM] SE 6</em></A>.
45
46
47 <H1>General Information</H1>
48 The information in this section is information relevant to someone who
49 compiles Interface Definition Language (IDL) files and uses the
50 ORB to write clients and servers.
51
52 <P>The classes and interfaces described in this section can be put into
53 four groups: <code>ORB classes</code>, Exceptions, <code>Helper</code> classes,
54 and <code>Holder</code> classes.
55
56 <H2>
410
411 <P>Helper classes
412 fall into two broad categories, <a href="#value">helpers for value types</a> and
413 <a href="#basic">helpers for non value types</a>. Because all of the helper
414 classes in one category
415 provide the same methods, one generic explanation of each
416 category of helper classes is presented here.
417
418 <P>
419 When OMG IDL is mapped to the Java programming language,
420 a "helper" class is generated for each user-defined type.
421 This generated class will have the name of the user-defined type with
422 the suffix <code>Helper</code> appended. For example, if the
423 interface <code>Account</code> is defined in OMG IDL, the
424 <code>idlj</code> compiler will automatically generate a class named
425 <code>AccountHelper</code>. The <code>AccountHelper</code> class
426 will contain the static methods needed for manipulating instances of the type,
427 in this case, <code>Account</code> objects.
428
429
430 <a name="narrow"></a>
431 <h3>The <code>narrow</code> Method</h3>
432 When an object is the return value for a method, it is returned in the
433 form of a generic object, either an <code>org.omg.CORBA.Object</code> object
434 or a <code>java.lang.Object</code> object. This object must be cast to its
435 more specific type before it can be operated on. For example, an
436 <code>Account</code> object will be returned as a generic object and must
437 be narrowed to an <code>Account</code> object so that <code>Account</code>
438 methods may be called on it.
439 <P>
440 The <code>narrow</code> method has two forms, one that takes an
441 <code>org.omg.CORBA.Object</code> object and one that takes a
442 <code>java.lang.Object</code> object. Whether the interface is abstract or
443 not determines which <code>narrow</code> method its helper class will provide.
444 The helper class for an interface
445 that is not abstract will have a <code>narrow</code> method that takes a CORBA
446 object, whereas the <code>narrow</code> method for an interface that is abstract
447 will take an object in the Java programming language. The helper class for a
448 non-abstract interface that has at least one abstract base interface will provide
449 both versions of the <code>narrow</code> method.
450 <P>The <A HREF="{@docRoot}/../technotes/guides/idl/jidlExample.html"><em>Hello World</em></A>
451 tutorial uses a <code>narrow</code> method that looks like this:
452 <PRE>
453 // create and initialize the ORB
454 ORB orb = ORB.init(args, null);
455
456 // get the root naming context
457 org.omg.CORBA.Object objRef =
458 orb.resolve_initial_references("NameService");
459 // Use NamingContextExt instead of NamingContext. This is
460 // part of latest Inter-Operable naming Service.
461 NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);
462
463 // resolve the Object Reference in Naming
464 String name = "Hello";
465 helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));
466 </PRE>
467
468 <a name="basic"></a>
469 <h3>Example of a Basic Helper Class</h3>
470 A basic helper class, for purposes of this explanation, is one with
471 the methods that are provided by every helper class, plus a <code>narrow</code>
472 method if the type defined in OMG IDL maps to an interface in the Java
473 programming language. Types that are not value types will have a basic
474 helper class generated for them.
475 <P>
476 For example, assuming that the interface <code>Account</code> is not a
477 value type IDL type and is also not an abstract interface and has no
478 abstract base interfaces, its <code>AccountHelper</code> class will look
479 like this:
480 <PRE>
481 abstract public class AccountHelper
482 {
483 private static String _id = "IDL:Account:1.0";
484
485 // inserts an Account object into an Any object
486 public static void insert (org.omg.CORBA.Any a, Account that)
487 {
488 org.omg.CORBA.portable.OutputStream out = a.create_output_stream ();
654 ServiceInformationHelper
655 SetOverrideTypeHelper
656 ShortSeqHelper
657 StringSeqHelper
658 StringValueHelper
659 StructMemberHelper
660 ULongLongSeqHelper
661 ULongSeqHelper
662 UnionMemberHelper
663 UnknownUserExceptionHelper
664 UShortSeqHelper
665 ValueBaseHelper
666 ValueMemberHelper
667 VersionSpecHelper
668 VisibilityHelper
669 WCharSeqHelper
670 WrongTransactionHelper
671 WStringSeqHelper
672 WStringValueHelper
673 </code></PRE>
674 <a name="adv"></a>
675 <H1>
676 Other Classes</H1>
677 The other classes and interfaces in the <code>CORBA</code> package, which are
678 used behind the scenes, can be put into four groups. Three of the groups
679 are used with requests in some capacity, and the fourth group, concerning
680 the Interface Repository, is a category by itself.
681 <H2>
682 Classes Created by an ORB</H2>
683 The first group contains classes that are created by an ORB and contain
684 information used in request operations.
685 <UL>
686 <LI>
687 <code>TCKind</code> -- indicates the kind (datatype) for a <code>TypeCode</code>
688 object
689
690 <LI>
691 <code>TypeCode</code> -- indicates a datatype and possibly other information
692
693 <LI>
694 <code>Any</code> -- contains a value and its typecode
851
852 <LI>
853 UnionMember
854
855 <LI>
856 ValueMember
857 </UL>
858 <!-- End Page Data -->
859 <HR>
860 <H1>
861 Related Documentation</H1>
862 For overviews, guides, and a tutorial, please see:
863 <UL>
864 <LI>
865 <A HREF="{@docRoot}/../technotes/guides/idl/index.html">Java IDL home page</A>
866 </UL>
867
868
869
870
871 <P><A NAME="unimpl"></A>
872 <H1>
873 CORBA Features Not Implemented in Java IDL</H1>
874
875 <P>Some of the API included in <code>org.omg</code> subpackages is provided for
876 conformance with the current OMG CORBA specification but is not implemented
877 in Sun's release of the JDK<SUP><FONT SIZE=-2>TM</FONT></SUP>. This enables
878 other JDK licensees to provide implementations of this API in standard
879 extensions and products.
880
881 <P><A NAME="NO_IMPLEMENT"></A>
882 <h2>Features That Throw NO_IMPLEMENT</h2>
883
884 <P>Some of the API included in <code>org.omg</code> subpackages throw
885 <code>NO_IMPLEMENT</code> exceptions for various reasons. Among these reasons
886 are:
887 <UL>
888 <LI>In some cases, for example <code>LocalObject</code>, the complete
889 implementation according to the specification indicates that
890 these API should throw <code>NO_IMPLEMENT</code>.
891
892 <LI>In most cases, for example methods in <code>ORB.java</code>,
893 methods that throw
894 <code>NO_IMPLEMENT</code> are actually implemented in subclasses
895 elsewhere in the ORB code.
896
897 <LI>In some cases, for example <code>_get_interface_def()</code>
898 and <code>_get_interface</code>, API are really not yet implemented.
899 </UL>
900
901
|
1 <!doctype html>
2 <HTML>
3 <HEAD>
4 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
5 <META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en]C-gatewaynet (WinNT; U)
6 [Netscape]">
7 <TITLE>package</TITLE>
8 <!--
9 /*
10 * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.
11 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
12 *
13 * This code is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License version 2 only, as
15 * published by the Free Software Foundation. Oracle designates this
16 * particular file as subject to the "Classpath" exception as provided
17 * by Oracle in the LICENSE file that accompanied this code.
18 *
19 * This code is distributed in the hope that it will be useful, but WITHOUT
20 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
21 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22 * version 2 for more details (a copy is included in the LICENSE file that
23 * accompanied this code).
24 *
25 * You should have received a copy of the GNU General Public License version
26 * 2 along with this work; if not, write to the Free Software Foundation,
27 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
28 *
29 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
30 * or visit www.oracle.com if you need additional information or have any
31 * questions.
32 */
33 -->
34 </HEAD>
35 <BODY>
36 Provides the mapping of the OMG CORBA APIs to the Java™
37 programming language, including the class <code>ORB</code>, which is implemented
38 so that a programmer can use it as a fully-functional Object Request Broker
39 (ORB).
40
41 <P>For a precise list of supported sections of official CORBA specifications with which
42 the Java[TM] Platform, Standard Edition 6 complies, see <A
43 HREF="doc-files/compliance.html"><em>Official Specifications for CORBA support in
44 Java[TM] SE 6</em></A>.
45
46
47 <H1>General Information</H1>
48 The information in this section is information relevant to someone who
49 compiles Interface Definition Language (IDL) files and uses the
50 ORB to write clients and servers.
51
52 <P>The classes and interfaces described in this section can be put into
53 four groups: <code>ORB classes</code>, Exceptions, <code>Helper</code> classes,
54 and <code>Holder</code> classes.
55
56 <H2>
410
411 <P>Helper classes
412 fall into two broad categories, <a href="#value">helpers for value types</a> and
413 <a href="#basic">helpers for non value types</a>. Because all of the helper
414 classes in one category
415 provide the same methods, one generic explanation of each
416 category of helper classes is presented here.
417
418 <P>
419 When OMG IDL is mapped to the Java programming language,
420 a "helper" class is generated for each user-defined type.
421 This generated class will have the name of the user-defined type with
422 the suffix <code>Helper</code> appended. For example, if the
423 interface <code>Account</code> is defined in OMG IDL, the
424 <code>idlj</code> compiler will automatically generate a class named
425 <code>AccountHelper</code>. The <code>AccountHelper</code> class
426 will contain the static methods needed for manipulating instances of the type,
427 in this case, <code>Account</code> objects.
428
429
430 <a id="narrow"></a>
431 <h3>The <code>narrow</code> Method</h3>
432 When an object is the return value for a method, it is returned in the
433 form of a generic object, either an <code>org.omg.CORBA.Object</code> object
434 or a <code>java.lang.Object</code> object. This object must be cast to its
435 more specific type before it can be operated on. For example, an
436 <code>Account</code> object will be returned as a generic object and must
437 be narrowed to an <code>Account</code> object so that <code>Account</code>
438 methods may be called on it.
439 <P>
440 The <code>narrow</code> method has two forms, one that takes an
441 <code>org.omg.CORBA.Object</code> object and one that takes a
442 <code>java.lang.Object</code> object. Whether the interface is abstract or
443 not determines which <code>narrow</code> method its helper class will provide.
444 The helper class for an interface
445 that is not abstract will have a <code>narrow</code> method that takes a CORBA
446 object, whereas the <code>narrow</code> method for an interface that is abstract
447 will take an object in the Java programming language. The helper class for a
448 non-abstract interface that has at least one abstract base interface will provide
449 both versions of the <code>narrow</code> method.
450 <P>The <A HREF="{@docRoot}/../technotes/guides/idl/jidlExample.html"><em>Hello World</em></A>
451 tutorial uses a <code>narrow</code> method that looks like this:
452 <PRE>
453 // create and initialize the ORB
454 ORB orb = ORB.init(args, null);
455
456 // get the root naming context
457 org.omg.CORBA.Object objRef =
458 orb.resolve_initial_references("NameService");
459 // Use NamingContextExt instead of NamingContext. This is
460 // part of latest Inter-Operable naming Service.
461 NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);
462
463 // resolve the Object Reference in Naming
464 String name = "Hello";
465 helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));
466 </PRE>
467
468 <a id="basic"></a>
469 <h3>Example of a Basic Helper Class</h3>
470 A basic helper class, for purposes of this explanation, is one with
471 the methods that are provided by every helper class, plus a <code>narrow</code>
472 method if the type defined in OMG IDL maps to an interface in the Java
473 programming language. Types that are not value types will have a basic
474 helper class generated for them.
475 <P>
476 For example, assuming that the interface <code>Account</code> is not a
477 value type IDL type and is also not an abstract interface and has no
478 abstract base interfaces, its <code>AccountHelper</code> class will look
479 like this:
480 <PRE>
481 abstract public class AccountHelper
482 {
483 private static String _id = "IDL:Account:1.0";
484
485 // inserts an Account object into an Any object
486 public static void insert (org.omg.CORBA.Any a, Account that)
487 {
488 org.omg.CORBA.portable.OutputStream out = a.create_output_stream ();
654 ServiceInformationHelper
655 SetOverrideTypeHelper
656 ShortSeqHelper
657 StringSeqHelper
658 StringValueHelper
659 StructMemberHelper
660 ULongLongSeqHelper
661 ULongSeqHelper
662 UnionMemberHelper
663 UnknownUserExceptionHelper
664 UShortSeqHelper
665 ValueBaseHelper
666 ValueMemberHelper
667 VersionSpecHelper
668 VisibilityHelper
669 WCharSeqHelper
670 WrongTransactionHelper
671 WStringSeqHelper
672 WStringValueHelper
673 </code></PRE>
674 <a id="adv"></a>
675 <H1>
676 Other Classes</H1>
677 The other classes and interfaces in the <code>CORBA</code> package, which are
678 used behind the scenes, can be put into four groups. Three of the groups
679 are used with requests in some capacity, and the fourth group, concerning
680 the Interface Repository, is a category by itself.
681 <H2>
682 Classes Created by an ORB</H2>
683 The first group contains classes that are created by an ORB and contain
684 information used in request operations.
685 <UL>
686 <LI>
687 <code>TCKind</code> -- indicates the kind (datatype) for a <code>TypeCode</code>
688 object
689
690 <LI>
691 <code>TypeCode</code> -- indicates a datatype and possibly other information
692
693 <LI>
694 <code>Any</code> -- contains a value and its typecode
851
852 <LI>
853 UnionMember
854
855 <LI>
856 ValueMember
857 </UL>
858 <!-- End Page Data -->
859 <HR>
860 <H1>
861 Related Documentation</H1>
862 For overviews, guides, and a tutorial, please see:
863 <UL>
864 <LI>
865 <A HREF="{@docRoot}/../technotes/guides/idl/index.html">Java IDL home page</A>
866 </UL>
867
868
869
870
871 <P><A id="unimpl"></A>
872 <H1>
873 CORBA Features Not Implemented in Java IDL</H1>
874
875 <P>Some of the API included in <code>org.omg</code> subpackages is provided for
876 conformance with the current OMG CORBA specification but is not implemented
877 in Sun's release of the JDK™. This enables
878 other JDK licensees to provide implementations of this API in standard
879 extensions and products.
880
881 <P><A id="NO_IMPLEMENT"></A>
882 <h2>Features That Throw NO_IMPLEMENT</h2>
883
884 <P>Some of the API included in <code>org.omg</code> subpackages throw
885 <code>NO_IMPLEMENT</code> exceptions for various reasons. Among these reasons
886 are:
887 <UL>
888 <LI>In some cases, for example <code>LocalObject</code>, the complete
889 implementation according to the specification indicates that
890 these API should throw <code>NO_IMPLEMENT</code>.
891
892 <LI>In most cases, for example methods in <code>ORB.java</code>,
893 methods that throw
894 <code>NO_IMPLEMENT</code> are actually implemented in subclasses
895 elsewhere in the ORB code.
896
897 <LI>In some cases, for example <code>_get_interface_def()</code>
898 and <code>_get_interface</code>, API are really not yet implemented.
899 </UL>
900
901
|