Creating CORBA Client Applications

 

This topic includes the following sections:

• The development process for CORBA C++ client applications

• The development process for CORBA Java client applications

• Obtaining the Object Management Group (OMG) Interface Definition Language (IDL) file

• Selecting the invocation type

• Compiling the OMG IDL file

• Writing the CORBA client application

• Building the CORBA client application

• Server applications acting as client applications

• Using Java2 Applets

 

---

Summary of the Development Process for CORBA C++ Client Applications

The steps for creating a CORBA C++ client application are as follows:

Step	Description
1	Obtain the OMG IDL file for the CORBA interfaces used by the CORBA C++ client application.
2	Select the invocation type.
3	Use the IDL compiler to compile the OMG IDL file. The client stubs are generated as a result of compiling the OMG IDL.
4	Write the CORBA C++ client application. This topic describes creating a basic client application. You can also implement security and transactions in your CORBA C++ client applications. For information about implementing security in your CORBA Java client application, see Using Security. For information about using transactions in your CORBA Java client application, see Using Transactions.
5	Build the CORBA C++ client application.

Each step in the process is explained in detail in the following sections.

The WebLogic Enterprise development environment for CORBA C++ client applications includes the following:

• The idl command, which compiles the OMG IDL file and generates the client stubs required for the CORBA interface.

• The buildobjclient command, which constructs a CORBA C++ client application executable.

• The C++ environmental objects, which provide access to CORBA objects in an WebLogic Enterprise domain and to the services provided by the CORBA objects.

 

---

Summary of the Development Process for CORBA Java Client Applications

The BEA WebLogic Enterprise software supports interoperability with the SUN Java Development Kit (JDK) Java client.

Note: See the BEA Weblogic Installation Guide for the specific versions of supported software

The steps for creating a CORBA Java client application are as follows:

Step	Description
1	Obtain the OMG IDL file for the CORBA interfaces used by the CORBA Java client application.
2	Select the invocation type.
3	Use the development tools provided by your CORBA Java Object Request Broker (ORB) to compile the OMG IDL file and generate client stubs.
4	Write the CORBA Java client application. This topic describes creating a basic client application. You can also implement security and transactions in your CORBA Java client applications. For information about implementing security in your CORBA Java client application, see Using Security. For information about using transactions in your CORBA Java client application, see Using Transactions.
5	Build the CORBA Java client application.

Each step in the process is explained in detail in the following sections.

You need to use the development tools provided by your CORBA Java ORB product to compile the OMG IDL file, generate the client stubs, and build the CORBA Java client application executable. You use the Java environmental objects, which provide access to CORBA objects in an WebLogic Enterprise domain and to the services provided by the CORBA objects.

 

---

Step 1: Obtaining the OMG IDL File

Generally, the OMG IDL files for the available interfaces and operations are provided to the client programmer by the application designer. This section contains the OMG IDL for the Basic sample application. Listing 2-1 shows the univb.idl file, which defines the following interfaces:

Interface	Description	Operations
Registrar	Obtains course information from the course database	get_courses_synopsis() get_courses_details()
RegistrarFactory	Creates object references to the Registrar object	find_registrar()
CourseSynopsisEnumerator	Gets a subset of the information from the course database, and iteratively returns portions of that subset to the client application	get_next_n() destroy()

Listing 2-1 OMG IDL File for the Basic Sample Application

---

#pragma prefix "beasys.com"

module UniversityB

{

   typedef unsigned long CourseNumber;
   typedef sequence<CourseNumber> CourseNumberList;

   struct CourseSynopsis
     {
        CourseNumber   course_number;
        string         title;
     };

   typedef sequence<CourseSynopsis> CourseSynopsisList;
   interface CourseSynopsisEnumerator
   {
        CourseSynopsisList get_next_n(
            in  unsigned long number_to_get, 
            out unsigned long number_remaining
   };
         void destroy();
   };

   typedef unsigned short Days;
   const Days MONDAY    =  1;
   const Days TUESDAY   =  2;
   const Days WEDNESDAY =  4;
   const Days THURSDAY  =  8;
   const Days FRIDAY    = 16;
  
   struct ClassSchedule
   {
       Days           class_days; // bitmask of days
       unsigned short start_hour; // whole hours in military time
       unsigned short duration;   // minutes
   };

   struct CourseDetails
   {
       CourseNumber   course_number;
       double         cost;
       unsigned short number_of_credits;
       ClassSchedule  class_schedule; 
       unsigned short number_of_seats;
       string         title;
       string         professor;
       string         description;
    };

   typedef sequence<CourseDetails> CourseDetailsList;

   interface Registrar
   {
       CourseSynopsisList
       get_courses_synopsis(
       in string                    search_criteria,
       in unsigned long             number_to_get, // 0 = all
       out unsigned long            number_remaining,
       out CourseSynopsisEnumerator rest
    );

    	CourseDetailsList get_courses_details(in CourseNumberList 
        courses);

   interface RegistrarFactory
   {
        Registrar find_registrar(
    );

  };

};

 

---

Step 2: Selecting the Invocation Type

Select the invocation type (static or dynamic) that you will use in the requests in the client application. You can use both types of invocation in a client application.

For an overview of static and dynamic invocation, see Client Application Development Concepts.

The remainder of this topic assumes that you chose to use static invocation in your CORBA client application. If you chose to use dynamic invocation, see Using the Dynamic Invocation Interface.

 

---

Step 3: Compiling the OMG IDL File

When creating CORBA C++ client applications, use the idl command to compile the OMG IDL file and generate the files required for the interface. The following is the syntax of the idl command:

idl idlfilename(s)

The IDL compiler generates a client stub (idlfilename_c.cpp) and a header file (idlfilename_c.h) that describe everything you need to have to use the client stub from the C++ programming language. You need to link these files into your client application.

In addition, the IDL compiler generates skeletons that contain the signatures of the CORBA object's operations. The generated skeleton information is placed in the idlfilename_s.cpp and idlfilename_s.h files. During development of the client application, it can be useful to look at the server header files and skeleton file.

Note: Do not modify the generated client stub or the skeleton.

For a complete description of the idl command and options, see WebLogic Enterprise Commands, System Processes, and MIB Reference.

When creating CORBA Java client applications:

• If you are using JDK version 1.2, you can use the idltojava command to compile the OMG IDL file. For more information about the idltojava command, see the documentation for the JDK version 1.2.

• If you are using Netscape version 3.0 and Java Development Kit (JDK) version 1.1.5, you need to use that product's IDL compiler to compile the OMG IDL.

The idltojava command or the IDL compiler generates the following:

• The client stubs for each interface (_interfaceStub.java)

• The CORBA helper class (interfaceHelper.java) and the CORBA holder class (interfaceHolder.java) that describe everything you need to use the client stub from the Java programming language.

Note that each OMG IDL defined exception defines an exception class and its helper and holder classes. The compiled .class files must be in the CLASSPATH of your client application.

In addition, the idltojava command or the IDL compiler generates skeletons that contain the signatures of the operations of the CORBA object. The generated skeleton information is placed in the _interfaceImplBase file.

 

---

Step 4: Writing the CORBA Client Application

To participate in a session with an WebLogic Enterprise server application, an WebLogic Enterprise client application must be able to get an object reference for a CORBA object and invoke operations on the object. To accomplish this, the CORBA client application code must do the following:

1. Initialize the WebLogic Enterprise ORB.

2. Establish communication with the WebLogic Enterprise domain.

3. Resolve initial references to the FactoryFinder object.

4. Use a factory to get an object reference for the desired CORBA object.

5. Invoke operations on the CORBA object.

The following sections use portions of the client applications in the Basic sample application to illustrate the steps. For information about the Basic sample application, see the Guide to University Sample Applications. The Basic sample application is located in the following directory on the WebLogic Enterprise software kit:

drive:\WLEdir\samples\corba\university\basic

Initializing the ORB

All CORBA client applications must first initialize the ORB.

Use the following code to initialize the ORB from a CORBA C++ client application:

C++

CORBA::ORB_var orb=CORBA::ORB_init(argc, argv, ORBid);

Typically, no ORBid is specified and the default ORBid specified during installation is used. However, when a client application is running on a machine that also has server applications running and the client application wants to access server applications in another WebLogic Enterprise domain, you need to override the default ORBid. This can be done by hard coding the ORBid as BEA_IIOP or by passing the ORBid in the command line as _ORBid BEA_IIOP.

Use the following code to initialize the ORB from a CORBA Java client application:

Java Application

org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init (args,props);

Use the following code to initialize the ORB from a CORBA Java client applet:

Java Applet

org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init (this,null);

where this is the name of the Java applet

Establishing Communication with the WebLogic Enterprise Domain

The client application creates a Bootstrap object. A list of IIOP Listener/Handlers can be supplied either as a parameter, via the TOBJADDR Java property or applet property. A single IIOP Listener/Handler is specified as follows:

//host:port

When the IIOP Listerner/Handler is provided via TOBJADDR, the second argument of the constructor can be null.

The host and port combination for the IIOP Listener/Handler is defined in the UBBCONFIG file. The host and port combination that is specified for the Bootstrap object must exactly match the ISL parameter in the WebLogic Enterprise domain's UBBCONFIG file. The format of the host and port combination, as well as the capitalization, must match. If the addresses do not match, the call to the Bootstrap object will fail and the following message appears in the log file:

Error: Unofficial connection from client at <tcp/ip adress>/<portnumber>

For example, if the network address is specified as //TRIXIE::3500 in the ISL parameter in the UBBCONFIG file, specifying either //192.12.4.6.:3500 or //trixie:3500 in the Bootstrap object will cause the connection attempt to fail.

On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Window NT, use the Network Control Panel to determine the capitalization.

The following C++ and Java examples show how to use the Bootstrap object:

C++

       Tobj_Bootstrap* bootstrap = new Tobj_Bootstrap(orb, "//host:port");

Java

Use the following commands to get the valid IIOP Listener/Handlers for the client application:

Native client applications

       Properties prop = Tobj_Bootstrap.getNativeProperties();

Remote client applications

       Properties prop = Tobj_Bootstrap.getRemoteProperties();

Use the IIOP Listerner/Handler in the following command:

       Tobj_Bootstrap bootstrap = new Tobj_Bootstrap(orb, "//host:port");

Java Applet

       Tobj_Bootstrap bootstrap = new Tobj_Bootstrap(orb, "//host:port", this); 

where this is the name of the Java applet

An WebLogic Enterprise domain can have multiple IIOP Listener/Handlers. If you are accessing an WebLogic Enterprise domain with multiple IIOP Listener/Handlers, you supply a list of Host:Port combinations to the Bootstrap object. If the second parameter of the Bootstrap command is an empty string, the Bootstrap object walks through the list until it connects to an WebLogic Enterprise domain. The list of IIOP Listener/Handlers can also be specified in TOBJADDR.

If you want to access multiple WebLogic Enterprise domains, you must create a Bootstrap object for each WebLogic Enterprise domain you want to access.

Resolving Initial References to the FactoryFinder Object

The client application must obtain initial references to the environmental objects that provide services for the application. The Bootstrap object's resolve_initial_references operation can be called to obtain references to the FactoryFinder, InterfaceRepository, SecurityCurrent, TransactionCurrent, NotificationService, and NameService environmental objects. The argument passed to the operation is a string containing the name of the desired object reference. You need to get initial references only for the environmental objects you plan to use in your client application.

The following C++ and Java examples show how to use the Bootstrap object to resolve initial references to the FactoryFinder object:

C++

//Resolve Factory Finder
CORBA::Object_var var_factory_finder_oref = bootstrap.resolve_initial_references
       ("FactoryFinder");
Tobj::FactoryFinder_var var_factory_finder_ref = Tobj::FactoryFinder::_narrow
      (factory_finder_oref.in());

Java

//Resolve Factory Finder
org.omg.CORBA.Object off = bootstrap.resolve_initial_references
      ("FactoryFinder");
FactoryFinder ff=FactoryFinderHelper.narrow(off);

For information about using security in client applications, see Using Security. For information about transactions in client applications, see Using Transactions.

Using the FactoryFinder Object to Get a Factory

CORBA client applications get object references to CORBA objects from factories. A factory is any CORBA object that returns an object reference to another CORBA object and registers itself as a factory. The client application invokes anoperation on a factory to obtain an object reference to a CORBA object of a specific type. To use factories, the client application must be able to locate the factory it needs. The FactoryFinder object serves this purpose. For information about the function of the FactoryFinder object, see Client Application Development Concepts.

The FactoryFinder object has the following methods:

• find_factories()

  Returns a sequence of factories that match the input key exactly.

• find_one_factory()

  Returns one factory that matches the input key exactly.

• find_factories_by_id()

  Returns a sequence of factories whose id field in the name component matches the input argument.

• find_one_factory_by_id()

  Returns one factory whose id field in the factory's CORBA name component matches the input argument.

The following C++ and Java examples show how to use the FactoryFinder find_one_factory_by_id method to get a factory for the Registrar object used in the client application for the Basic sample applications:

C++

CORBA::Object_var var_registrar_factory_oref = var_factory_finder_ref->
     find_one_factory_by_id(UniversityB::_tc_RegistrarFactory->id()
);
UniversityB::RegistrarFactory_var var_RegistrarFactory_ref =
     UniversityB::RegistrarFactory::_narrow(
          var_RegistrarFactory_oref.in()
     );

Java

org.omg.CORBA.Object of = FactoryFinder.find_one_factory_by_id
    (UniversityB.RegistrarFactoryHelper.id());
UniversityB.RegistrarFactory F = UniversityB.RegistrarFactoryHelper.narrow(of);

Using a Factory to Get a CORBA Object

Client applications call the factory to get an object reference to a CORBA object. The client applications then invoke operations on the CORBA object by passing it a pointer to the factory and any arguments that the operation requires.

The following C++ and Java examples illustrate getting the factory for the Registrar object and then invoking the get_courses_details() method on the Registrar object:

C++

UniversityB::Registrar_var var_Registrar = var_RegistrarFactory->
             find_Registrar();
UniversityB::CourseDetailsList_var course_details_list = Registrar_oref->
             get_course_details(CourseNumberList);

Java

UniversityB.Registrar gRegistrarObjRef = F.find_registrar();
gRegistrarObjRef.get_course_details(selected_course_numbers);

 

---

Step 5: Building the CORBA Client Application

The final step in the development of the CORBA client application is to produce the executable client application. To do this, you need to compile the code and link against the client stub.

When creating CORBA C++ client applications, use the buildobjclient command to construct an WebLogic Enterprise client application executable. The command combines the client stubs for interfaces that use static invocation, and the associated header files with the standard WebLogic Enterprise libraries to form a client executable. For the syntax of the buildobjclient command, see WebLogic Enterprise Commands, System Processes, and MIB Reference.

When compiling CORBA Java client applications, you need to include the Java Archive (JAR) file that contains the Java classes for the WebLogic Enterprise environmental objects in your CLASSPATH. If you are using JDK Version 1.2, the m3envobj.jar file is located in the following directory:

WLEdir/udataobj/java/jdk

 

---

Server Applications Acting as Client Applications

To process a request from a client application, the server application may need to request processing from another server application. In this situation, the server application is acting as a client application.

To act as a client application, the server application must obtain a Bootstrap object for the current WebLogic Enterprise domain. The Bootstrap object for the server application is already available via TP::Bootstrap (for CORBA C++ client applications) or TP.Bootstrap (for CORBA Java client applications). The server application then uses the FactoryFinder object to locate a factory for the CORBA object that can satisfy the request from the client application.

 

---

Using Java2 Applets

BEA WebLogic Enterprise supports Java2 applets. To run Java2 applets, you need to install the Java Plug-In product from Sun Microsystems, Inc. The Java Plug-in runs Java applets in an HTML page using Sun's Java Virtual Machine (JVM).

Before downloading the Java Plug-in kit from the Sun web site, verify whether or not the Java Plug-In is already installed on your machine.

Netscape Navigator

In Netscape Navigator, choose the About Plug-Ins option from the Help menu in the browser window. The following will appear if the Java Plug-In is installed:

application/x-java-applet;version 1.2

Internet Explorer

From the Start menu in Windows NT version 4.0, select the Programs option. If the Java Plug-In is installed, a Java Plug-In Control Panel option will appear.

If the Java Plug-In is not installed, you need to download and install the JDK1.2 plug-in (jre12-win32.exe) and the HTML Converter tool (htmlconv12.zip). You can obtain both these products from java.sun.com/products/plugin.

You also need to read the Java Plug-In HTML Specification located at java.sun.com/products/plugin/1.2/docs. This specification explains the changes Web page authors need to make to their existing HTML code to have existing JDK 1.2 applets run using the Java Plug-In rather that the brower's default Java run-time environment.

Write your Java applet. Use the following command to intialize the ORB from the Java applet:

org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init (this,null);

To automatically launch the Java Plug-In when Internet Explorer or Netscape Navigator browses the HTML page for your applet, use the OBJECT tag and the EMBED tag in the HTML specification. If you use the HTML Converter tool to convert your applet to HTML, these tags are automatically inserted. For more information about using the OBJECT and EMBED tags, see java.sun.com/products/plugin/1.2/docs/tags.html.