Developing an Application That Uses the CORBA Name Service

 

This topic includes the following sections:

• Development Steps

• Step 1: Obtain the OMG IDL for the CosNaming Interfaces

• Step 2: Include the Declarations and Prototypes for the CosNaming Interfaces

• Step 3: Connect to the BEA Tuxedo Namespace

• Step 4: Bind an Object to the BEA Tuxedo Namespace

• Step 5: Use a Name to Locate an Object in the BEA Tuxedo Namespace

 

---

Development Steps

Table 4-1 outlines the process for developing BEA Tuxedo CORBA applications that use the CORBA Name Service.

Table 4-1 Development Process

Step	Description
1	Obtain the OMG IDL for the CosNaming interfaces.
2	Include the declarations and prototypes for the CosNaming interfaces.
3	Connect to the BEA Tuxedo namespace.
4	Bind an object to the BEA Tuxedo namespace.
5	Use a name to locate an object in the BEA Tuxedo namespace.

 

Before performing the steps in this topic, you need to start the server process for the CORBA Name Service. For more information, see Starting the Server Process for the CORBA Name Service.

After performing the development steps in this topic, use the buildobjclient and buildobjserver commands to compile server and client applications that use the CORBA Name Service. For more information about the buildobjclient and buildobjserver commands, see the BEA Tuxedo Command Reference.

 

---

Step 1: Obtain the OMG IDL for the CosNaming Interfaces

A BEA Tuxedo CORBA application accesses the CORBA Name Service using the interfaces defined in CosNaming.idl. This Object Management Group (OMG) Interface Definition Language (IDL) file defines the interfaces, COSnaming data structures, and exceptions used by the CORBA Name Service. The CosNaming.idl file is located in the following directory locations:

Windows

drive:\%TUXDIR%\include\CosNaming.idl

UNIX

/usr/local/$TUXDIR/include/CosNaming.idl

Listing 4-1 shows the OMG IDL for CosNaming.idl. The same OMG IDL file is used by both CORBA C++ and Java applications.

Listing 4-1 CosNaming.idl

#ifndef _COSNAMING_IDL_
#define _COSNAMING_IDL_

module CosNaming {

#pragma prefix "omg.org/CosNaming"
	typedef string Istring;

	struct NameComponent {
		Istring id;
		Istring kind;
	};

    	typedef sequence<NameComponent> Name;

	enum BindingType { nobject, ncontext };

	struct Binding {
		Name        binding_name;
		BindingType binding_type;                   
	};

	typedef sequence <Binding> BindingList;                    

	interface BindingIterator;
	
	interface NamingContext {
		enum NotFoundReason { missing_node, 
					 not_context, 
					 not_object };

		exception NotFound { 
			NotFoundReason  why;
			Name            rest_of_name;
		};

		exception CannotProceed {
			NamingContext   cxt;
			Name            rest_of_name;
		};

		exception InvalidName{};                               
    
		exception AlreadyBound {};

		exception NotEmpty{};

		void    bind(in Name n, in Object obj)      
			 raises(NotFound, 
			       CannotProceed, 
				InvalidName, 
				AlreadyBound);

		void   rebind(in Name n, in Object obj)   
			raises(NotFound, 
				CannotProceed, 
				InvalidName);

		void    bind_context(in Name n, in NamingContext nc)        
			raises(NotFound, 
				CannotProceed, 
				InvalidName, 
				AlreadyBound);

		void    rebind_context(in Name n, in NamingContext nc)  
			raises(NotFound, 
				CannotProceed, 
				InvalidName);

		Object  resolve (in Name n)
			raises(NotFound, 
				CannotProceed, 
				InvalidName);

		void    unbind(in Name n)
			raises(NotFound, 
				CannotProceed, 
				InvalidName);

		NamingContext   new_context();
		NamingContext   bind_new_context(in Name n)
			raises(NotFound, 
				AlreadyBound,
				CannotProceed, 
				InvalidName);

        		void    destroy() raises(NotEmpty);
		void    list(in unsigned long    how_many,
			      out BindingList     bl,
			      out BindingIterator bi);

	};

	interface BindingIterator {
		boolean next_one(out Binding b);
		boolean next_n(in unsigned long how_many, 
			        out BindingList bl);
		void    destroy();
	};

	interface NamingContextExt:NamingContext {
		typedef string StringName;
		typedef string Address;
		typedef string URLString;

	StringName  to_string(in Name n) raises(InvalidName);
	Name        to_name(in StringName sn) 
				raises(InvalidName);
	exception InvalidAddress {};

	URLString   to_url(in Address addr, in StringName sn)
				raises(InvalidAddress, InvalidName);

	Object      resolve_str(in StringName n)
				raises(NotFound, 
					CannotProceed,
					InvalidName, 
					AlreadyBound
			);
		};
};

#pragma ID CosNaming "IDL:omg.org/CosNaming:1.0"
#endif // _COSNAMING_IDL_

 

---

Step 2: Include the Declarations and Prototypes for the CosNaming Interfaces

The declarations and prototypes for the CosNaming interfaces are provided as part of the software kit for the CORBA Name Service.

• For CORBA C++ client applications, include the declarations and prototypes for the naming interfaces by adding this statement to your BEA Tuxedo CORBA client application:

  #include "CosNaming_c.h"

  The include files for a BEA Tuxedo CORBA C++ client application are located in the $TUXDIR/include directory on UNIX systems and the %TUXDIR%\include directory on Windows systems.

• For CORBA Java client applications, include the declarations and prototypes for the interfaces by adding this statement to your BEA Tuxedo CORBA client application:

  import org.omg.CosNaming.*;

  The interfaces for the CORBA Name service are in the org.omg.CosNaming package.

  The Java packages for a BEA Tuxedo CORBA Java client application are located in the $TUXDIR/udataobj/java/jdk/m3envobj.jar file on UNIX systems and the %TUXDIR%\udataobj\java\jdk\m3envobj.jar file on Windows systems.

• If you are using a third-party Object Request Broker (ORB), you need to include or import the CosNaming interfaces in your client source stub programs before compiling.

 

---

Step 3: Connect to the BEA Tuxedo Namespace

The Bootstrap object supports a NameService environmental object for connecting to the root of the namespace. When using the NameService environmental object, the Object Request Broker (ORB) locates the root of the namespace. The object reference can then be narrowed to CosNaming::NamingContext or CosNamingContextExt. You need to connect to the BEA Tuxedo namespace before binding objects into the namespace and resolving names in the namespace.

Use the Bootstrap object or the CORBA Interoperable Naming Service (INS) bootstrapping mechanism to get an initial reference to the NameService environmental object. Use the BEA proprietary mechanism if you are using the BEA client ORB. Use the CORBA INS mechanism if you are using a client ORB from another vendor. For more information about bootstrapping the BEA Tuxedo domain see Chapter 4, "CORBA Bootstrapping Programming Reference," in the CORBA Programming Reference in the BEA Tuxedo online documentation.

Listing 4-2 and Listing 4-3 illustrate C++ and Java code that establishes communication with a BEA Tuxedo namespace.

Listing 4-2 C++ Example of Connecting to a Namespace

...
Tobj_Bootstrap * bootstrap = new Tobj_Bootstrap (v_orb.in(), "");
CORBA::Object_var var_nameservice_oref=
	bootstrap.resolve_initial_references("NameService");
root = CosNaming::NamingContext::_narrow (obj);
...

Listing 4-3 Java Example of Connecting to a Namespace

...
Tobj_Bootstrap bootstrap = new Tobj_Bootstrap(orb, "");
org.omg.CORBA.Object NameServiceobj = 
	gBootstrapObjRef.resolve_initial_references("NameService");
CosNaming.NamingCOntextExt ns_root = 
	CosNaming.NamingContextExtHelper.narrow (ns_obj);
...

A stringified object reference for the root of the namespace can also be used to connect to a namespace in a BEA Tuxedo domain. In order to use a stringified object reference, the -f command-line option must be specified when starting the server process for the CORBA Name Service. The -f command-line option writes the stringified object reference to the CNS_ROOT_FILE environment variable or to one of the following locations:

Windows

%APPDIR%\cnsroot.dat

UNIX

$APPDIR/cnsroot.dat

The stringified object reference for the root of the namespace does not change when the server process for the CORBA Name Service is started and stopped because stringified object reference is associated with a particular host machine rather than a particular server process. A stringified object reference that has been retrieved to communicate with one BEA Tuxedo namespace cannot be used to communicate with another BEA Tuxedo namespace.

Listing 4-4 and Listing 4-5 include C++ and Java code that establishes communication with a BEA Tuxedo namespace using a stringified object reference.

Listing 4-4 C++ Example of Using a Stringified Object Reference

...
Tobj_Bootstrap * bootstrap;
bootstrap = new Tobj_Bootstrap (v_orb.in(), "");
CORBA::Object_var obj = GetRefFromFile ("cnsroot.dat", v_orb);
root = CosNaming::NamingContext::_narrow (obj);
...

Listing 4-5 Java Example of Using a Stringified Object Reference

...
Tobj_Bootstrap bootstrap = new Tobj_Bootstrap(orb, "");
BufferedReader inFile = 
	newBufferedReader(new FileReader ("cnsroot.dat"));
String root_ior_string = inFile.readLine ();
org.omg.CORBA.Object ns_obj = 
	orb.string_to_objecet (root_ior_string);
CosNaming.NamingContextExt ns_root =
	CosNaming.NamingContextExtHelper.narrow (ns_obj);
...

If you choose to use a stringified object reference in a BEA Tuxedo CORBA application that also employs security and transactions, please note the following restrictions:

1. The BEA Tuxedo CORBA application must create a Bootstrap object and connect to the IIOP Listener/Handler before using the stringified object reference to connect to a BEA Tuxedo namespace. By calling the Bootstrap object first, the BEA Tuxedo application establishes an official connection to the IIOP Listener/Handler.

   If a BEA Tuxedo application does not first create a Bootstrap object, transactions and security cannot be used with any object retrieved from the namespace. Transactions and security require the use of an official connection.

2. If more than one IIOP Listener/Handler is defined in the UBBCONFIG file, the BEA Tuxedo CORBA application must use the first IIOP Listener/Handler defined in the UBBCONFIG file by the TOBJADDR environment variable.

   The CORBA Name Service creates the stringified object reference for the root of the namespace, using the default IIOP Listener/Handler's host and port. The first IIOP Listener/Handler defined in a UBBCONFIG file is considered the default IIOPListener/Handler. Using the default IIOP Listener/Handler causes all object references retrieved by the CORBA Name Service to be official connections. Transactions and security require the use of official connections.

 

---

Step 4: Bind an Object to the BEA Tuxedo Namespace

There are two ways to bind an object to the BEA Tuxedo namespace:

• The cnsbind command

• The bind() method of the CosNaming::NamingContext object

The cnsbind command can be used to bind application objects or naming context objects to the BEA Tuxedo namespace. The server process for the CORBA Name Service must be started before using the cnsbind command. For a complete description of the cnsbind command, see CORBA Name Service Reference.

Listing 4-6 and Listing 4-7 show the C++ and Java code implementations of the bind() method of the CosNaming::NamingContext object. The code examples accept two parameters, representing the id and kind fields for a Name. These parameters initialize a Name for the SimpleFactory object and bind the SimpleFactory object to the namespace.

Listing 4-6 C++ Example of Binding a Name to the BEA Tuxedo Namespace

...
//Establish the Name used to identify the SimpleFactory object
//in the namespace.

CosNaming::Name_var				factory_name = new CosNaming::Name(1);
	factory_name->length(1);
	factory_name[(CORBA::ULong) 0].id = 
					(const char * "simple_factory";
	factory_name[(CORBA::ULong) 0].kind = 
					(const char *) "";
//Create an object reference for the SimpleFactory object

s_v_factory_refer = TP::create_object_reference(
					_tc_SimpleFactory->id(),
					"simple_factory",
					CORBA::NVList::_nil()
);
//Get the NameService object reference. See Listing 4-2.
//Place the object reference for SimpleFactory in the namespace

root->bind(factory_name, s_v_fact_ref);
...

Listing 4-7 Java Example of Binding a Name to the BEA Tuxedo Namespace

...
//Create an object reference for the SimpleFactory object
org.omg.CORBA.object fact_ref = 
	TP.create_object_reference(
		SimpleFactoryHelper.id()	
		"simple_factory",
		null
	);

...
//Get the NameService object reference. See Listing 4-3.
//Place the object reference for SimpleFactory in the namespace
	CosNaming.NameComponent[] factName =
		ns_root.to_name("simple_factory");
	ns_root.bind(factName, fact_ref);

...

 

---

Step 5: Use a Name to Locate an Object in the BEA Tuxedo Namespace

Use the resolve() method of the CosNaming::NamingContext object to locate an object in a namespace in a BEA Tuxedo domain. Listing 4-8 and Listing 4-9 shows the C++ and Java code that accepts two parameters, representing the id and kind fields for a Name. The code example then binds to a naming context, resolves the name, and obtains an object reference for the specified object.

Listing 4-8 C++ Example of Locating a Name in the BEA Tuxedo Namespace

...
//Establish the Name used to identify the SimpleFactory object
//in the namespace.
CosNaming::Name_var				factory_name = new CosNaming::Name(1);
	factory_name->length(1);
	factory_name[(CORBA::ULong) 0].id = 
					(const char * "simple_factory";
	factory_name[(CORBA::ULong) 0].kind = 
					(const char *) "";

//Locate the SimpleFactory object in the namespace
CORBA::Object_var v_simple_factory_oref = 
		root->resolve( *factory_name);
SimpleFactory_var v_simple_factory_ref =
		SimpleFactory::_narrow(v_simple_factory_oref.in());

// Use the reference obtained from the BEA Tuxedo CORBA Name Service // to find the Simple object
Simple_var v_simple = v_simple_factory_ref->find_simple();
...

Listing 4-9 Java Example of Locating a Name in the BEA Tuxedo Namespace

...
//Find the SimpleFactory object in the namespace via a string name
org.omg.CORBA.Object simple_fact_oref =
	ns_root.resolve_str("simple_factory");
SimpleFactory simple_factory_ref =
	SimpleFactoryHelper.narrow(simple_fact_oref);

//Find the Simple object
Simple simple = simple_factory_ref.find_simple();
...