Chapter 8
Retrieving Object References in Clients

8.1 Binding to Objects in OrbixWeb Servers
8.2 Using Object Reference Strings to Create Proxy Objects
8.3 Resolving Names in the Naming Service

As described in Chapter 7, there are four main ways for a server to publish information about the objects it creates:

Using an OrbixWeb daemon to store information about the server.
Passing object references as parameters to IDL operations.
Publication of object reference strings.
Associating names with object references using the CORBA Naming Service.

In this chapter we will explain how clients can locate objects which are implemented in servers which are known to the OrbixWeb daemon (by binding to those objects), how object reference strings can be converted to object references and how clients can resolve Naming Service names to locate objects in any server.

The client functionality associated with passing object references as method parameters requires no detailed discussion. OrbixWeb automatically creates a proxy for an object reference which enters a client's address space as an operation parameter–so the operation invocation is the only functionality required to retrieve such an object reference.

8.1 Binding to Objects in OrbixWeb Servers

The OrbixWeb _bind() method provides a mechanism for creating proxies for objects which have been created in servers. A client which uses _bind() to create a proxy does not need to specify the entire object reference for the target object. Although _bind() can be invoked using either the Orbix communications protocol or CORBA IIOP, it can only succeed if the target object is implemented in an Orbix or OrbixWeb server–_bind() cannot be used with objects which are implemented using other ORBs.

The creation of a proxy in a client's address space allows operations to be invoked on the target object; when an operation is invoked on the proxy, OrbixWeb automatically transmits the request to the target object. The _bind() method may be used to specify the exact object required or, by using default parameters, OrbixWeb may be allowed some freedom when choosing the object.

In OrbixWeb, the _bind() method has been integrated with a locator which provides a basic service for finding objects when no host is specified. For details, see Chapter 24, "Locators".

8.1.1 The _bind() Method

The _bind() method is a static method automatically generated by the IDL compiler for each IDL Java class. For interface A, the full form of _bind() is declared in Java class A as follows:

 // Java
 public static final _ARef 
 	_bind(String markerServer, String host)
 	throws IE.Iona.Orbix2.CORBA.SystemException {
 	...
 }

As a result of overloading, _bind() can take the following sets of parameters:

markerServer, host
markerServer
No parameters.
A full object reference as returned by the method _CORBA.Orbix._object_to_string().

The _bind() method supports polymorphic binds: that is, a call to A._bind() can be made to an object of interface B, if interface A is a base interface of interface B.

The markerServer and host parameters will be explained in turn in section 8.1.2 and section 8.1.3. Section 8.1.5 contains a tabular summary of the parameters to _bind(), and section 8.1.6 describes how _bind() can raise an exception and how its performance can be optimised. Finally, section 8.2 describes methods of creating proxy objects from object reference information, including binding to a stringified object reference.

8.1.2 The markerServer parameter to _bind()

The markerServer parameter denotes a specific server name and object within that server. It can be a string of the form:

 marker  ':'  server_name

The marker identifies a specific object within the specified server.

The server_name is the name of a server, as registered in the OrbixWeb Implementation Repository at the server host. It is not necessarily the name of a class or an interface (although an OrbixWeb programmer is free to make a server name the same as that of a class or interface). The OrbixWeb Implementation Repository is described in detail in Chapter 11, "Registration and Activation of Servers".

If the server name is not given in the markerServer parameter, the server name defaults to the name of the Java class for _bind().¹ For example, in a parameterless call to Bank._bind(), the server name will default to "Bank";² that is, the target server must then have been registered with the name "Bank".

If the marker is not given, it defaults to any object, within the server, which implements the interface (or a derived interface) given by the Java class name specified. The chosen object may have been named explicitly by the programmer or assigned a default name by OrbixWeb.

If the string does not contain a `:' character then the string is understood to be just a marker with no explicit server name. Since colon (`:') is used as a separator, it is illegal for a marker or a server name to include a `:' character.

Examples of the markerServer parameter which could be used in a call to Bank._bind() are:

"College_Green:AIB"	The `College_Green` object at the `AIB` server.
`"College_Green"`	The `College_Green` object at the `Bank` server.
`"College_Green:"`	The `College_Green` object at the `Bank` server.
`""`	Any `Bank` object at the `Bank` server.
`"College_Green:myBank"`	The `College_Green` object at the `myBank` server.
`":myBank"`	Any `Bank` object at the `myBank` server.

Finally, if the markerServer parameter has at least two `:' characters within it, it will not be treated as a marker:server-name pair, but it will be assumed to be the string form of a full object reference. See section 8.2 for further details.

8.1.3 The host parameter to _bind()

The host parameter to _bind() specifies the internet host name or the internet address of a node on which to find the object. An internet address is (assumed to be) a string of the form xxx.xxx.xxx.xxx, where x is a decimal digit.

Where a null string is provided, OrbixWeb will use the default locator to find the object's server in the distributed system. OrbixWeb's default locator allows the locations of servers to be recorded, as is explained in Chapter 24, "Locators". This configuration information is then used during _bind(), provided that the host parameter is not explicitly given. Note that the locator must be configured before it can be used.

OrbixWeb also allows developers to override the default locator with an alternative location mechanism. The programming steps required to achieve this are described in Chapter 24.

8.1.4 Example calls to _bind()

This section shows a selection of sample calls to _bind().

 // Java
 import IE.Iona.Orbix2.CORBA.SystemException;
 ...
 
 _BankRef bRef;
 
 try {
 	// Bind to any Bank object in any "Bank" server.
 	// That object should implement the Bank IDL
 	// interface.
 	bRef = Bank._bind();
 
 	// Bind to any Bank object in the "Bank" server 
 	// at node alpha (in the current domain).
 	// That object should implement the Bank IDL
 	// interface.
 	bRef = Bank._bind("", "alpha");
 
 	// Bind to the "College Green" object within the 
 	// "Bank" server at node alpha (in the current 
 	// domain). That object should implement the
 	// Bank IDL interface.
 	bRef = Bank._bind("College_Green", "alpha");
 
 	// Bind to the "College Green" object (in server
 	// "Bank") somewhere within the network.
 	// College_Green should implement the Bank IDL
 	// interface.
 	bRef = Bank._bind("College_Green");
 
 	// Bind to the "College_Green" object in 
 	// the "AIB" server somewhere in the network.  
 	// That object must implement the Bank 
 	// IDL interface.
 	bRef = Bank._bind("College_Green:AIB");
 
 	// Bind to the "College_Green" object at 
 	// the "AIB" server at node beta, in the 
 	// internet domain "mc.ie".  That object should 
 	// implement the Bank IDL interface.
 	bRef = Bank._bind 
 		("College_Green:AIB", "beta.mc.ie");
 
 	// Bind to the "College_Green" object at 
 	// the "AIB" server at Internet 
 	// Address 123.456.789.012. That object should 
 	// implement the Bank IDL interface.
 	bRef = Bank._bind 
 		("College_Green:AIB", "123.456.789.012");
 }
 catch (SystemException se) {
 	...
 }

8.1.5 Tabular summary of _bind() parameters

Table 8.1 summarises the rules for a general-form call to _bind():







 // Java
 _T1Ref tRef;
 tRef = T2._bind("M:S", "H", C);

T1	`T1` must be the same or a base type of `T2`.
T2	`T2` is an IDL interface name (and also a Java class name). It is not the name of a server (unless a server is explicitly created with the same name). The object that is found must implement interface `T2` or a derived interface of this.
M	`M` is a marker name, that is the name of an object within the specified server. If `M` is left blank (that is, if the `markerServer` parameter to `_bind()` is the empty string, or begins with a "`:`" character), then `_bind()` is allowed to find any object in the specified server with a correct interface (`T2` or a derived interface).
S	`S` is a server name–a name used previously to register a server in the Implementation Repository. If `S` is left blank (that is, if the `markerServer` parameter to `_bind()` is the empty string, or has no "`:`" character, or terminates with a "`:`" character) then the name `T2` is used as the server name. In this case, a server must have been explicitly registered with the name `T2`.
H	This is an internet host name or (if the string is in the format `xxx.xxx.xxx.xxx`, where `x` is a decimal digit) an internet address. If `H` is the empty string, OrbixWeb will use its locator to try to find the required server.

Table 8.1: Summary of parameters to _bind()

To bind to an object with interface T2 and marker "aaa" in a server called "sss", known to be running on host "hhh", a programmer might write (ignoring exception handling):

 // Java
 _T2Ref tRef;
 tRef = T2._bind("aaa:sss","hhh");

Since a server can support objects of any number of interfaces, the following can be used to bind to an object of interface T3 and marker "bbb" in the same server:

 // Java
 _T3Ref tRef;
 tRef = T3._bind("bbb:sss","hhh");

8.1.6 Binding and Exceptions

By default, _bind() raises an exception if the desired object is unknown to OrbixWeb. Doing so requires OrbixWeb to ping that desired object in order to check its availability (the ping operation is defined by OrbixWeb and it has no effect on the target object). The pinging will cause the target OrbixWeb server process to be activated if necessary, and it will confirm that this server recognises the target object.

If a programmer wishes to improve efficiency by reducing the number of remote invocations, pinging can be disabled by calling the method pingDuringBind() (on the _CORBA.Orbix object) as follows:

 // Java
 import IE.Iona.Orbix2._CORBA;
 ...
 _CORBA.Orbix.pingDuringBind(false);

The previous setting is returned.

When pinging is disabled, binding to an unavailable object will not raise an exception at that time. Instead, an exception will be raised when the proxy object is first used.

A program should always check for exceptions when calling _bind(), whether or not pinging is enabled. Even when pinging is disabled, this method will raise an exception in some circumstances, including on some configuration errors.

8.2 Using Object Reference Strings to Create Proxy Objects

An OrbixWeb object is uniquely identified by an object reference. Given a stringified form of an OrbixWeb object reference, an OrbixWeb client can create a proxy for that object, by passing the string to the method string_to_object() on the _CORBA.Orbix object.

For example, given an object reference string which identifies a Bank object:

 // Java
 import IE.Iona.Orbix2._CORBA;
 import IE.Iona.Orbix2.CORBA.SystemException;
 ...
 
 String bStr = ... ; // Assign to object ref string.
 _BankRef bRef;
 
 try {
 	bRef = _CORBA.Orbix.string_to_object (bStr);
 }
 catch (SystemException se) {
 	...
 }

 // Java
 import IE.Iona.Orbix2.CORBA.SystemException;
 ...
 
 String bStr = ...; // Assign to object ref string.
 _BankRef bRef;
 
 try {
 	bRef = Bank._bind (bStr);
 }
 catch (SystemException se) {
 	...
 }

This has exactly the same functionality as calling string_to_object().

The method string_to_object() (of class ORB) is overloaded to allow the individual fields of a stringified object reference to be specified. The definition of this form of string_to_object() is as follows:

 // Java
 // In package IE.Iona.Orbix2.CORBA,
 // in class ORB.
 public IE.Iona.Orbix2.CORBA._ObjectRef string_to_object(
 		String host, String IR_host, 
 		String ServerName, String marker,
 		String IR_server, String interfaceMarker)
 		throws SystemException;

The ability to create proxy objects from object reference strings has several useful applications. For example, this approach to proxy creation is often used in conjunction with the OrbixWeb Dynamic Invocation Interface (DII).

8.3 Resolving Names in the Naming Service

As described in section 7.2.1, a server can use the CORBA Naming Service to associate an abstract name, which is defined within a naming context, with an object reference. For a client, a typical use of the Naming Service is to find the initial naming context and then to resolve a name to obtain an object reference.

Full details of the functionality supported by the Naming Service are given in the OrbixNames Guide. The OrbixNames implementation of the Naming Service runs as an Orbix (or OrbixWeb) server. Clients can access the functionality of the Naming Service through the standard IDL definitions for this service.

The following code segment illustrates how a client might resolve the name objects.bank.national to retrieve the object reference published by the server example in section 7.2.1.

 // Java
 // An OrbixWeb client
 // (of an OrbixWeb server and of a Naming Server).
 // In file Client.java.
 package idl_demo;
 
 import CosNaming._NamingContextRef;
 import CosNaming.Name;
 import IE.Iona.Orbix2._CORBA;
 import IE.Iona.Orbix2.CORBA.SystemException;
 import IE.Iona.Orbix2.CORBA._ObjectRef;
 
 public class Client {
 	public static void main (String args[]) {
 		_NamingContextRef initContext;
 		Name name;
 		_ObjectRef initRef, objRef;
 		_BankRef bankRef;
 
 		try {
 			// Find initial naming context.
 			initRef = 
 				_CORBA.Orbix.resolve_initial_references
 				("NameService");
 			initContext = NamingContext._narrow 
 				(initRef);
 
 			// Set up name and contexts.
 			name = new Name (3);
 			name.buffer[0].id = 
 				new String ("objects");
 			name.buffer[0].kind = new String ("");
 			name.buffer[1].id = new String ("banks");
 			name.buffer[1].kind = new String ("");
 			name.buffer[2].id =
 				new String ("national");
 			name.buffer[2].kind = new String ("");
 
 			// Resolve the name.
 			objRef = initContext.resolve (name);
 			bankRef = Bank._narrow (objRef);
 		}
 		catch (SystemException se) {
 			// Details omitted.
 		}
 
 		// Use bankRef as normal(not shown).
 		...
 	}
 }

¹ This is the only system recognised relationship between server names and interface names.

² OrbixWeb will choose the name of the Java class if a null string is specified for the server name. This can be done either by not passing a first parameter, or by passing one of the following as the first parameter: a null string; a string with no `:'; or a string which terminates with a `:'.

[Roadmap] [Introduction] [GS: Applications] [GS: Applets]
[IDL] [Mapping] [Programming OrbixWeb] [Publishing Objects] [Retrieving Objects] [IIOP]
[Running Clients] [Running Servers] [Exceptions] [Inheritance] [Callbacks] [Contexts]
[API Configuration] [TypeCode] [Any] [DII] [IR] [Filters] [Smart Proxies] [Loaders] [Locators]
[Index]

Chapter 8 Retrieving Object References in Clients

Contents