Contents

23.1 Specifying a Loader for an Object

23.2 Connection between Loaders and Object Naming

23.3 Loading Objects

23.4 Saving Objects

23.5 Aspects of Writing a Loader

23.6 Example Loader

23.7 Polymorphism

23.8 Approaches to Providing Persistent Objects

23.9 Disabling the Loaders

Loaders can provide support for persistent objects–long lived objects stored on disk in the file system or in a database.

Loaders are also called when an object reference enters an address space, and not just when a "missing object" is the target of a request. This can arise in a number of ways:

• When a call to either of the methods _bind() or string_to_object() is made from within a process.
  
• For a server: as an in parameter.
  
• For a client (or a server making an operation call): as an out or inout parameter, or a return value.
  

Overview of Creating a Loader

• load(): OrbixWeb uses this method to inform a loader of an object fault. The loader is given the marker of the missing object so that it can identify which object to load.
  
• save(): When a process terminates, the objects in its address space can be saved by its loaders. To allow this, OrbixWeb supplies a finalize() method, which should be called on the _CORBA.Orbix object before process termination. _CORBA.Orbix.finalize() makes an individual call to save() for each object managed by a loader. The save() method can also be explicitly called through the _ObjectRef._save() method, which all OrbixWeb objects implement.
  
• record() and rename(): These methods are used to control naming of objects, and they are explained in section 23.2.
  

The constructor of LoaderClass (the base class of all loaders) takes an optional boolean parameter. When creating a loader object, this parameter must be true if the load() method of the new loader is to be called by OrbixWeb.

Section 23.6 shows an example loader, but first the proceeding sections explain the different aspects of the loader mechanism in more detail.

23.1 Specifying a Loader for an Object

An object's loader can be specified as the object is being created, either by the TIE or by the BOAImpl approach.

In the TIE approach, this can be done by passing the loader object as the third parameter to a TIE object constructor. For example,

 // Java
 // myLoader is a loader object:
 
 _BankRef bRef = new _tie_Bank 
 	(new BankImplementation (), 
 	"College Green", myLoader);

 // Java
 import IE.Iona.Orbix2.CORBA.SystemException;
 import IE.Iona.Orbix2.CORBA.LoaderClass;
 
 class BankImplementation extends 
 	_boaimpl_Bank {
 	...
 	public BankImplementation 
 		(String marker, LoaderClass loader) 
 		throws SystemException {
 		super (marker, loader);
 		...
 	}
 }

An object's loader can be retrieved by calling:

 // Java
 // In package IE.Iona.Orbix2.CORBA,
 // in interface _ObjectRef.
 
 public LoaderClass _loader ()
 	throws SystemException;

Recall that objects can be named in a number of ways:

• By passing a marker name to a TIE object constructor, for example:
  

   _BankRef bRef = new _tie_Bank 
   	(new BankImplementation (), 
   	"College Green", myLoader);
  

• By passing the marker name to the BOAImpl constructor, for example:
  

   BankImplementation bImpl;
   
   try {
   	bImpl = new BankImplementation 
   		("College Green", myLoader);
   }
   ...
  

• By calling _ObjectRef._marker(String), for example:
  

   bRef._marker ("Foster Place");
  

OrbixWeb executes the following algorithm when an object is created, or an object's existing marker is changed:

• If the specified marker is not null, OrbixWeb checks whether the name is already in use within the process. If it is not in use, the name is suggested to the loader (by calling record() or rename()). The loader can accept the name by not changing it; alternatively, the loader can reject it by changing it to a new name. If the loader changes the name, OrbixWeb again checks that the new name is not already in use within the current process; if it is already in use, the object will not be correctly registered.
  
• If no name is specified or if the specified name is already in use within the current process, OrbixWeb will pass a null value to the loader (by calling record() or rename()) which must then choose a name. OrbixWeb will then check the chosen name; the object will not be correctly registered if this chosen name is already in use.
  

The implementations of rename() and record() in LoaderClass both return without changing the suggested name. (It's implementation of load() and save() carry out no actions.)

The default loader (which is associated with all objects which are not explicitly associated with another loader) is an instance of NullLoaderClass, a derived class of LoaderClass. This class inherits load(), save() and rename() from LoaderClass. It implements record() so that if no marker name is suggested it chooses one that is a string of decimal digits, different to any it generated before in the current process.

23.3 Loading Objects

The responsibilities of the load() method are:

• To determine if the required object is to be loaded by the current loader.
  
• If so, to re-create the object and assign the correct marker to it.
  

• The interface name.
  
• The target object's marker.
  
• A boolean value, set as follows depending on why the object fault occurred:
  
  

  true	Because of a call to _bind() or string_to_object() by the process that contains the loader.
  false	Because of an object fault on the target object of an incoming operation invocation, or on an in, out or inout parameter or return value.

  
  

• If an object fault occurs because of the call:
  

   p = I1._bind( <parameters> );
  

then the interface name in load() will be "I1".

(If the first parameter to the _bind() is a full object reference string, OrbixWeb will return an exception if the reference's interface field is not I1 or a derived interface of I1.).

• If an object fault occurs during the call
  

   p = _CORBA.Orbix.string_to_object
   	( <full object reference string> );
  

then the interface name in load() will be that extracted from the full object reference string.

• If a loader is called because of a reference entering an address space (as an in, out or inout parameter, a return value, or as the target object of an operation call), then the interface name in load() will be the interface name extracted from the object reference.
  

A programmer can also explicitly cause the save() method to be called by invoking an object's _save() method. The _save() method simply calls the save() method on the object's loader. _save() must be called in the same address space as the target object: calling it in a client process, that is, on a proxy, will have no effect.

The two alternative reasons for the invocation of save() are distinguished by its second parameter. This parameter is of type int, and takes one of the following values:

23.5 Aspects of Writing a Loader

• The load() method is redefined to do the main work of the loader, that is, to load the object on demand. The object's marker is normally used to find the object in the persistent store.
  
• The save() method is redefined so that it saves its objects on process termination, and also if _save() is called.
  
• The record() and rename() methods are normally redefined. Often, record() chooses the marker for a new object; and rename() is sometimes written to simply prevent an object's marker being changed. However, record() and rename() are sometimes not redefined in a simple application, where the code that chooses markers at the application level can be trusted to choose correct values.
  

Two interfaces are involved in the application:

 // IDL
 // In file bank.idl.
 
 interface Account {
 	readonly attribute float balance;
 	void makeDeposit(in float f);
 	void makeWithdrawal(in float f);
 };
 
 interface Bank {
 	Account newAccount(in string name);
 };

 idl -jP per_simp bank.idl

Interfaces Account and Bank are implemented by classes AccountImplementation and BankImplementation, respectively. Instances of class AccountImplementation are made persistent using a loader (of class Loader). The persistence mechanism used is very primitive because it uses one file per account object. Nevertheless, the example acts as a simple introduction to loaders. The implementation of class Loader is shown later, but first the implementations of classes AccountImplementation and BankImplementation are shown.

Class AccountImplementation is implemented as follows:

 // Java
 // In file AccountImplementation.java.
 package per_simp;
 
 import IE.Iona.Orbix2.CORBA._ObjectRef;
 import IE.Iona.Orbix2.CORBA.LoaderClass;
 import IE.Iona.Orbix2.CORBA.SystemException;
 
 public class AccountImplementation 
 	implements _AccountOperations {
 	protected String m_name;
 	protected float m_balance;
 	protected String m_accountNr;
 
 	public AccountImplementation 
 		(float initialBalance, String name, 
 		String nr) {
 		// Initialise member variable values.
 		// Details omitted.
 	}
 
 	// Methods to implement IDL operations:
 	public float get_balance () 
 		throws SystemException {
 		return m_balance;
 	}
 
 	public void makeLodgement (float f) 
 		throws SystemException {
 		m_balance += f;
 	}
 
 	public void makeWithdrawal (float f) 
 		throws SystemException {
 		m_balance -= f;
 	}
 
 	// Methods for supporting persistence.
 	public static _ObjectRef loadMe 
 		(String file_name, LoaderClass loader)
 		throws SystemException {
 		// Details shown later.
 	}
 
 	public void saveMe (String file_name) {
 		// Details shown later.
 	}
 };

 public static _ObjectRef loadMe 
 	(String file_name, LoaderClass loader)
 	throws SystemException {
 	...
 
 	RandomAccessFile file = null;
 	String name = null;
 	float bal = 0;
 
 	try {
 		file = new RandomAccessFile (file_name, "r"); 
 		name = file.readLine ();
 		bal = file.readFloat ();
 		file.close();
 	} 
 	catch (java.io.IOException ex) {
 		...
 		System.exit (1);
 	}
 
 	AccountImplementation aImpl = new 
 		AccountImplementation (bal, name, file_name);
 	_AccountRef aRef = new 
 		_tie_Account (aImpl, file_name, loader);
 
 	return aRef;
 }
 
 public void saveMe (String file_name) {
 	...
 
 	RandomAccessFile file = null;
 
 	try {
 		file = 
 			new RandomAccessFile (file_name, "rw"); 
 		file.seek (0);
 		file.writeBytes (m_name + "\n");
 		file.writeFloat (m_balance);
 		f.close();
 	} 
 	catch (java.io.IOException ex) {
 		...
 		System.exit(1);
 	}
 }

 _AccountRef aRef = 
 	new _tie_Account (aImpl, file_name, loader);

Class BankImplementation is implemented as follows:

 // Java
 // In file BankImplementation.java.
 package per_simp;
 
 import IE.Iona.Orbix2.CORBA.LoaderClass;
 import IE.Iona.Orbix2.CORBA.SystemException;
 
 public class BankImplementation
 	implements _BankOperations {
 	protected int m_sortCode;
 	protected int m_lastAc;
 	protected LoaderClass m_loader;
 
 	public BankImplementation (long sortCode,
 		LoaderClass loader) {
 		m_sortCode = sortCode;
 		m_loader = loader;
 		m_lastAc = 0; // Number of previous account.
 	}
 
 	// Method to implement IDL operation:
 	public _AccountRef newAccount (String name) 
 		throws SystemException {
 		String accountNr = new String ("a" 
 			+ m_sortCode + "-" + (++m_lastAc));
 
 		AccountImplementation aImpl = null;
 	
 		try {
 			aImpl = new AccountImplementation 
 				(100, name, accountNr);
 		}
 		catch (SystemException se) {
 			...
 		}
 
 		_AccountRef aRef = new 
 			_tie_Account (aImpl, accountNr, m_loader); 
 	
 		return aRef;
 	}
 }

The statement:

 _AccountRef aRef = 
 	new _tie_Account (aImpl, accountNr, m_loader);

The server application class must create a loader and a bank; for example:

 // Java
 // In file BankServer.java.
 package per_simp;
 
 import IE.Iona.Orbix2.CORBA.SystemException;
 import IE.Iona.Orbix2._CORBA;
 
 public class BankServer {
 	public static void main (String args[]) {
 		Loader myLoader = new Loader ();
 		BankImplementation bankImpl = 
 			new BankImplementation (1234, myLoader);
 		_BankRef bRef; 
 
 		try {
 			bRef = new _tie_Bank (bankImpl, "b1234");
 		}
 		catch (SystemException se) {
 			...
 		}
 
 		...
 	}
 }

 // Java
 // In file Loader.java.
 package per_simp;
 
 import IE.Iona.Orbix2._CORBA;
 import IE.Iona.Orbix2.CORBA.SystemException;
 import IE.Iona.Orbix2.CORBA.LoaderClass;
 import IE.Iona.Orbix2.CORBA._ObjectRef;
 
 class Loader extends LoaderClass {
 	public Loader() {
     super (true);
 	}
 
 	public _ObjectRef load (String interface, 
 		String marker, boolean isBind)
 		throws SystemException {
 		// We will always have an interface; 
 		// but the marker may be the null string.
 		if (marker!=null && !marker.equals ("") 
 			&& marker.charAt (0)=='a' && 
 			interface.equals ("Account"))
 			return AccountImplementation.loadMe 
 				(marker, this);
 
 		return null;
 	}
 
 	public void save (_ObjectRef obj, int reason) {
 		throws SystemException {
 		String marker = obj._marker ();
 
 		if (reason == _CORBA.processTermination) {
 			AccountImplementation aImpl = 
 				(AccountImplementation)(obj._deref());
 			aImpl.saveMe (marker);
 		}
 	}
 }

Note that the AccountImplementation.loadMe() method assigns the correct marker to the newly created object. If it failed to do this, then subsequent calls on the same object would result in further object faults and calls to the Loader.load() method.

It would have been possible for the Loader.load() method to have read the data itself, rather than calling the static method AccountImplementation.loadMe(). However, to construct the object, load() would be dependent on there being a constructor on class AccountImplementation that takes all of an account's state as parameters. Since this will not be the case for all classes, it is safer to introduce a method such as loadMe(). Equally, Loader.save() could have accessed the account's data and written it out, rather than calling AccountImplementation.saveMe(). However, it would then be dependent on AccountImplementation providing some means to access all of its state.

In any case, having loadMe() and saveMe() within class AccountImplementation provides a sensible split of functionality between the application level class, AccountImplementation, and the loader class.

Loaders are Transparent to Clients

 // Java
 	_BankRef bRef;
 	_AccountRef aRef;
 
 try {
 	// Find the bank somehow; for example, 
 	// using _bind():
 	bRef = Bank._bind (":per_simp", host);
 	
 	aRef = bRef.newAccount ("John");
 }
 catch (SystemException se) {
 	...
 }

 // Java
 // To access Account with account 
 // number "a1234-1".
 _AccountRef aRef;
 float bal;
 
 try {
 	aRef = Account._bind 
 		("a1234-1:per_simp", host);
 	bal = aRef.balance ();
 	aRef.makeWithdrawal (100.00);
 }
 catch (SystemException se) {
 	...
 }

23.7 Polymorphism

The class of the target object (and therefore how to load it) must therefore be determined either from the marker passed to the loader, or from the data used to load the target object. The demonstration code for loaders shows the marker names being used to distinguish the real interface of an object (using the first character of each marker). This is a simple approach, but it is probably better in a large system to use some information stored with the persistent data of each object.

It must also be remembered that distinguishing the real interface of an object may not be necessary in all applications and for all interfaces. If the correct interface name is always used in calls to _bind() (that is, I1._bind() is always used when binding to an object with interface I1) then handling polymorphism is not required. This will also be the case if _bind() is not used for a given interface: for example, all object references to accounts may be obtained by searching (say, using an owner name) in a bank, rather than using _bind().

It is however possible that, because of programmer error, the actual interface of the target object is not the same or a derived interface of correct one. This should be detected by a loader.

23.8 Approaches to Providing Persistent Objects

The information provided to a loader on an object fault comprises the object's marker and the interface name. The loader must be able to find the requested object using these two pieces of information. It must also be able to determine the implementation class of the target object–so that it can create an object of the correct class. Naturally, this implementation class must implement the required interface or one of its derived interfaces.

It is normal, therefore, to use the marker as a key to find the object, and either to encode the target object's implementation class in the marker, or to first find the object's persistent state and determine the implementation class from that data.

For example, a prefix of the marker could indicate the implementation class and the remainder of the marker (or indeed the whole marker) could be the name of the file that holds the object's persistent state.

The following are some of the choices available when using loaders to support persistent objects:

• Each object may be stored in its own file, or a record system may be used in which one or more records represent an object. Records may be stored, for example, in a relational database management system, or by using lines of a normal file.
  
• An object may be loaded when a request arrives for it; or all of the required objects may be loaded when the first request is made. For example, in our bank application, an account object may be loaded when an invocation is made on it, or all of the accounts controlled by a bank may be loaded when the bank, or any of its accounts, is first interacted with.
  
• An object may be saved to the persistent store at the termination of the process, or it may be saved before that time: for example, at the end of the method call that caused it to be loaded, or if the object has not been used for some period of time.
  

• A process may have a single loader to handle all of the interfaces that it supports. However, it is difficult to maintain such a loader for many interfaces.
  
• A process may have one loader to handle each interface (or each separate hierarchy of interfaces).
  

Another reason for having more than one loader is that a process may use objects from separate subsystems–each of which installs its own loader(s). These loaders must of course be able to distinguish requests to load their own objects. Confusion can be avoided if the subsystems handle disjoint interfaces (recall that the interface name is passed to a loader); however, some co-operation between the subsystems is required if they handle the same interfaces, or interfaces which have a common base interface.¹ Each subsystem must be able to distinguish its objects based on their markers or their persistent state.

In particular, the subsystems must choose disjoint markers.

23.9 Disabling the Loaders

The loaders can be disabled simply by calling the method:

 // Java
 // In package IE.Iona.Orbix2.CORBA,
 // in class BOA.
 public boolean enableLoaders (boolean b)
 	throws SystemException;