Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Related Pages

## Implementation Repository User's Guide

In order for a server to make use of the Implementation Repository, it must communicate with the ImR to keep it up to date on such things as the server's running status. These functions now are contained within the POA, so when a Persistent POA is used on a server that has -ORBUseImR specified, it will communicate with an Implementation Repository, if one is available.

### How is the ImR used?

The main steps for the lifetime of a server that uses the ImR are generally the following:

1. Register name and startup commands with the ImR using tao_ImR
   Example:`` `tao_ImR -ORBInitRef ImplRepoService=file://implrepo.ior add plane -c "airplane_server -i -ORBInitRef ImplRepoService=file://implrepo.ior"
   `
   Note that the name used to register the server is the name of the POA which the objects are created in. So in this example, the airplane_server creates a POA called "plane" and activates its servants under it.
2. Start the server once to generate an ImR-ified IOR
3. Start clients and pass them the above IOR
4. Clients will use the IOR, which will automatically go through the ImR
5. The ImR will start the server if it is not already running
6. At any time when the server is not currently in use by a client, it can be shut down using tao_ImR
   Example:`tao_ImR -ORBInitRef ImplRepoService=file://implrepo.ior shutdown plane
   `
7. After the server isn't needed anymore, it can be removed from the ImR database using tao_ImR
   Example:`` tao_ImR -ORBInitRef ImplRepoService=file://implrepo.ior remove plane

### So what does the server need to do?

As of TAO 1.0.9, the Implementation Repository support on the server-side has been integrated into the POA. Previously, the IR_Helper class needed to be used explicitly. Now only the "-ORBUseImR 1" command line argument needs to be used.

There are a couple of restrictions on the server though. Only objects within a persistent POA will be supported by the ImR. Also the Implementation Repository will key its entries on POA name. What this means for the server is that each server must have unique persistent POA names.

### Use of -ORBDefaultInitRef with the ImR

As mentioned in the INS documentation (in TAO/docs/INS.html), a base IOR can be passed to the ORB. Then when resolve_initial_reference is called, the ORB can append the service name to the base IOR to form a full IOR.

When used with the ImR, this can be a powerful feature. If the ImR's endpoint is used as the base IOR, then the ImR can be used to provide many services via the resolve_initial_reference functionality.

For example, let's say the ImR service is running on doriath on port 5555 and the Name Service is already registered with the ImR (in that the ImR knows how to start the Name Service).

Now we should be able to run some client that uses the Name Service like this:

`client -ORBDefaultInitRef corbaloc:iiop:doriath:5555/`

When the client calls resolve_initial_reference("NameService"), the ORB will resolve that to "corbaloc:iiop:doriath:5555/NameService". The ImR recognizes this IOR as a pointer to the NameService, and will then start it up if necessary. Finally, it will forward the client to the Name Service.

Services used in this way have two requirements:

- The server must be registered as the request_initial_reference name. For example, the Name Service is registered as the "NameService", and thus also contains a POA with the name "NameService".
- The server must also be able to handle the INS name "corbaloc:iiop:machine:port/poa_name", where the poa_name is the same name as above.

### What are activation modes

Each server can have one of three different types of activation modes:

- NORMAL is the default. The server can be started via tao_ImR, the command line, and with client requests.
- MANUAL specifies that the server shouldn't be activated with a client request but can be activated through tao_ImR or via the command line.
- PER_CLIENT specifies that each request to the ImplRepo will result in a new server process started up. Because clients cache the forwarded reference, there is one server per client (more or less). There are some exceptions, such as if the original IOR is used in different threads (each thread would get a different server). Note: The Implementation Repository doesn't store any information about the started servers in this mode, so it cannot be used to shut down the servers. So the servers must have an alternative way of shutting down.
- AUTO_START specifies that a server should be activated when the Implementation Repository is started. tao_ImR also has an autostart command to activate all servers marked AUTO_START.

### Using the tao_ImR ior command

First, some background.

For the longest time, there was no way with TAO's Implementation Repository to register a server and then start using the client immediately. The server had to be started once just for the purpose of creating an IOR for the client to use. The problem was that it was very difficult to create an IOR without running the server.

It would be nice to be able to generate a valid IOR without requiring the program to be run. A valid IOR in this case requires two major things. First it requires the endpoint of the ImR. This is relatively easy to get, since it is encoded in the ImR's IOR. Second it also requires an object key. At the least, this involves both the POA hierarchy and the object name.

So if we knew the POA and object names, then we should be able to create an IOR for the server. One possibility would be to have tao_ImR ask for both the POA and the object, and then create the POA hierarchy to generate an IOR. Doing the generation is this manner (letting the POA create the reference) shields us from changes in the IOR generation schemes. Since we are using the same code that the server would use, our IORs would be up to date.

It ends up there is an easier way to do this. The Interoperable Naming Service is intended to be used in situations where an IOR could be created by hand. Using the same information as above, it is not difficult to take the endpoint information from the ImR and attach the POA name. For example, let's say that we are running the ImR on ringil.ece.uci.edu at port 5000. The endpoint would be "corbaloc:iiop:1.2@ringil.ece.uci.edu:5000". If we are creating an IOR for the nestea server, we'd just need to attach "/nestea_server" to the end of the endpoint. Now we have an IOR.

So what does this mean for the server?

The main issue here is that the server must be changed to support the simplified name. This can be done by using the IORTable like this:

`CORBA::Object_var table_object = this->orb_->resolve_initial_references ("IORTable", ACE_TRY_ENV); ACE_TRY_CHECK;`

IORTable::Table_var adapter = IORTable::Table::_narrow (table_object.in (), ACE_TRY_ENV); ACE_TRY_CHECK; if (CORBA::is_nil (adapter.in ())) { ACE_ERROR ((LM_ERROR, "Nil IORTable
")); } else { adapter->bind (poa_name, server_str.in (), ACE_TRY_ENV); ACE_TRY_CHECK; }

These lines, as taken from the nestea_server example, just uses the same poa_name as registered with the ImR and associates it with the server_obj object in the IOR table. Because the ImR will be able to handle the simplified name (if it uses the POA name scheme) then this IOR will work.

Just one more thing, each object that needs an IOR needs to be registered with the IOR table. But this raises the problem of uniqueness; they all can't have the same name. The ImR will actually only look at the name part of the simplified IOR up to the first "/". So both "corbaloc:iiop:1.2@ringil:5000/nestea_server/foo" and "corbaloc:iiop:1.2@ringil:5000/nestea_server/bar" will be treated by the ImR as objects in the "nestea_server" server.

### Persistent Implementation Repository

Tao's Implementation Repository can be made persistent by doing two things:

- Always start up the Implementation Repository on the same port. This ensures that the Implementation Repository will not have to re-ImR-ify the IORs of every server registered to it each time it starts up. The way to accomplish this is to add
  -ORBEndpoint iiop://(hostname):(portnumber)

  to the ImR's startup command line. The host name can be obtained portably in C++ code with the lines

  ACE_INET_addr ad;
  char *hostname = ad.get_host_name ();

  or in a Perl script by adding

  use Sys::Hostname;
  $hostname = hostname();

  There are even specific port numbers, assigned to the OMG by the IANA, which can be used for this purpose. They are 683 (for IIOP) and 684 (for IIOP over SSL). For more information about this, see http://www.iana.org/ and http://www.isi.edu/in-notes/iana/assignments/port-numbers.

- Pass the ImR a filename to use for the backing store, specified by the command line option

  -p (filename)

  This option must be used the first and every subsequent time the persistent ImR is started up.