Contents

20.1 Runtime Information on IDL Definitions

20.2 Using the Interface Repository

20.2.1 Installing the Interface Repository

20.2.2 Inserting Definitions into the Interface Repository

20.2.3 Retrieving Information from the Interface Repository

20.3 The Interface to the Interface Repository

20.3.1 Interface Contained

20.3.2 Interface Container

20.3.3 Repository

20.3.4 InterfaceDef

20.3.5 Using the Interface Repository

20.4 Standard Interfaces in the Interface Repository

20.1 Runtime Information on IDL Definitions

For example, given an object reference of type _ObjectRef or any derived interface,¹ an OrbixWeb program can determine the interface type of the object to which it points, and it can then use the Interface Repository to determine all of the information about that interface. In particular, it can determine:

• The module in which the interface was defined, if any.
  
• The name of the interface.
  
• The interface's attributes, and their definitions.
  
• The interface's operations, and their full definition, including parameter, context and exception definitions.
  
• The inheritance specification of the interface.
  

When the -R switch is used, the IDL file is copied to a file with the same name in the Interface Repository's storage system (as specified by IT_INT_REP_PATH in Orbix.cfg). If the -d<dir> switch is specified to the IDL compiler, then the file is copied relative to the dir sub-directory of IT_INT_REP_PATH.

Clients may retrieve the IDL information at runtime only if an Interface Repository server has been correctly registered on the host at which the definitions are stored, and this server will access the same IT_INT_REP_PATH directory as used in the compilation stage.

The overall requirements for storing IDL definitions in the Interface Repository by using the OrbixWeb IDL compiler are:

• The Interface Repository must be installed as explained in section 20.2.1.
  
• The IT_INT_REP_PATH in the OrbixWeb configuration file, or the IT_INT_REP_PATH environment variable must be set; and the corresponding directory must exist.
  
• The IT_INT_REP_PATH value accessed by the Interface Repository server must match the value used in the IDL compilation.
  
• The -R switch must be specified to the IDL compiler (for any IDL definitions that need to be dynamically visible.
  

Note that IDL definitions stored in the Interface Repository, but compiled with the Orbix IDL compiler will also be available to OrbixWeb clients (if the Interface Repository requirements, as described in the Orbix Programming Guide, have been satisfied).

20.2.1 Installing the Interface Repository

The Interface Repository's executable file can be explicitly run as a background process. This has the advantage that the Interface Repository can initialise itself before any other processes need to use it, especially if the -L switch is specified.

Note that the registration record in the Implementation Repository should be named "IR":

 putit IR <absolute path name and switches>

The Interface Repository process can be terminated using the killit utility.

20.2.2 Inserting Definitions into the Interface Repository

If the IDL file includes other IDL files (using the #include directive) then, by default, these included files are not copied into the Interface Repository's storage space. This default behaviour can be overridden by specifying the -N switch to the IDL compiler. The -N switch specifies that the IDL compiler is to compile and produce code for included files. In conjunction with the -R switch, -N copies the included files into the Interface Repository's storage space.

Note that when using the -N switch, the compilation must be invoked from the same directory as the root IDL file (that is, the file containing the #include directive(s)), in order to retain compatibility with the Interface Repository server.

Note also that if the -d<dir> switch is also specified to the IDL compiler, care should be taken to ensure that included IDL files (specified relative to the root file's directory) fit into the Interface Repository directory and do not overwrite existing IDL (and shadow) files. The subdirectory specified to the -d switch should be sufficiently deep within the Interface Repository to ensure this.

20.2.3 Retrieving Information from the Interface Repository

The overall nesting is as follows:

Repository

A Repository can contain:

 	ConstantDef
 	TypeDef
 	ExceptionDef
 	InterfaceDef
 	ModuleDef

 		ConstantDef
 		TypeDef
 		ExceptionDef
 		ModuleDef
 		InterfaceDef

 			ConstantDef
 			TypeDef
 			ExceptionDef
 			AttributeDef
 			OperationDef

Repository, ModuleDef, InterfaceDef, ConstantDef, TypeDef, ExceptionDef, AttributeDef, and OperationDef are types defined by the Interface Repository. Given an object of any of these types, full information on that definition can be determined. For example, an InterfaceDef, can be acquired by navigating through a Repository using the interface's name, or simply by browsing through a Repository.

There are two ways to retrieve information from the Interface Repository:

1. Given an object reference, find its interface name and from this find further information.


2. Obtain an object reference for the Interface Repository and navigate the Repository from this.

Using _ObjectRef._get_interface()

 // Java
 IE.Iona.Orbix2._InterfaceDefRef ifRef =
 	objRef._get_interface();

Note that for _get_interface() to work correctly, the -R switch must be specified to the IDL compiler when an interface is being compiled. Otherwise _get_interface() will raise an exception.

Binding to a Repository

 // Java
 IE.Iona.Orbix2.RepositoryRef repRef =
 	Repository._bind(":IR","");

20.3 The Interface to the Interface Repository

Notice that:

• A Repository can be a container for other items.
  
• An AttributeDef, OperationDef, ParameterDef, TypeDef, ConstantDef and ExceptionDef can be contained in other items.
  
• A ModuleDef and InterfaceDef can be a container for other items, and can themselves be contained in other items.
  

 // IDL
 typedef string Identifier;
 typedef string RepositoryId;
 typedef Identifier InterfaceName;

 // IDL
 interface Example {
 	long op();
 };

A RepositoryId is an identifier used to uniquely identify a module, interface, constant, typedef, exception, attribute or operation.

An InterfaceName is a string containing one of the following:

 "AttributeDef"
 "ConstantDef"
 "ExceptionDef"
 "InterfaceDef"
 "ModuleDef"
 "ParameterDef"
 "OperationDef"
 "TypeDef"
 "all"

20.3.1 Interface Contained

 // IDL
 interface Contained {
 	attribute Identifier name;
 	attribute RepositoryId id;
 	attribute RepositoryId defined_in;
 
 	sequence <Container>  within();
 
 	struct Description {
 		Identifier name; // Type of value.
 		any  value;
 	};
 	Description describe();
 };

The defined_in attribute of a Contained object gives the unique identifier of the Interface Repository object in which the object was defined. The defined_in attribute is nil for a definition given at the file level of an IDL file.

The operation within() returns the list of objects that contain the object. An Interface Repository object is contained in another if:

• It is defined within it (for example, an interface can be contained in a module because the interface is defined within that module).
  
• It is inherited by an interface (for example, an operation can be contained in an interface because the interface inherits the operation).
  

The operation describe() returns a Contained::Description structure, which contains a name and a value. The type of the latter is different for each Interface Repository object type: it can be one of the following types:

 ModuleDescription
 InterfaceDescription
 AttributeDescription
 OperationDescription
 ParameterDescription
 TypeDescription
 ConstantDescription
 ExceptionDescription

20.3.2 Interface Container

 // IDL
 interface Container {
 	sequence<Contained> contents (
 		in InterfaceName restrict_type,
 		in boolean  exclude_inherited
 	);    
 	sequence<Contained> lookup_name (
 		in Identifier search_name,
 		in long  levels_to_search,
 		in InterfaceName restrict_type,
 		in boolean  exclude_inherited
 	);    
 	struct Description {
 		Contained  contained_object;
 		Identifier  name;
 		any   value;
 	};    
 	sequence<Description> describe_contents (
 		in InterfaceName restrict_type,
 		in boolean  exclude_inherited,
 		in long  max_returned_objs
 	);
 };

The operation lookup_name() is used to return all of the objects within a given Interface Repository object which have the name specified by search_name.

The operation describe_contents() is a combination of the operation contents() and the operation describe() from interface Contained. It returns a sequence of structures each of which gives the object reference of a contained object, and its name and value (the last two are the same as in Contained::Description). Each of the Interface Repository types inherits from Contained or Container, or both. Each will be described now in detail.

Each of the search operations contents(), lookup_name() and describe_contents() takes a parameter restrict_type. If this parameter is set to a particular InterfaceName, for example OperationDef, then only contained operations are returned by the search operation. If set to "all", then all contained objects are returned. The parameter exclude_inherited indicates whether inherited objects should be returned by a search operation–it is meaningful only for interfaces.

20.3.3 Repository

 // IDL
 interface Repository : Container {
 	Contained lookup_id
 		(in RepositoryId search_id);    
 	// The following operations request the IR to
 	// load files immediately, rather than
 	// waiting for them to be used:
 	exception invalidLoad {};
 
 	void loadIDLAll(); // Similar to the -L switch.
 	void loadIDLFile(in string fileName)
    							raises (invalidLoad);
 };

A reference to a Repository object can be obtained by binding to it as follows:

 // Java
 IE.Iona.Orbix2.RepositoryRef repRef =
 	Repository._bind(":IR","");

On a Repository object, the inherited describe_contents() operation returns a sequence of Container::Description structures; one such structure for each top level item in the repository.

 // IDL
 struct Description {
 	Contained  contained_object;
 	Identifier  name;
 	any   value;
 };    

 // IDL
 struct RepositoryDescription {
  	Identifier name;
  	RepositoryId id;
 	RepositoryId defined_in;
 };

Regarding the operations loadIDLAll() and loadIDLFile(), note that the Interface Repository will load a file only once; attempts to re-load a file will be ignored.

20.3.4 InterfaceDef

 // IDL
 interface InterfaceDef: Container, Contained {
 	attribute sequence<RepositoryId>
 		base_interfaces;
 	struct FullInterfaceDescription {
 		Identifier name;
 		RepositoryId id;
 		RepositoryId defined_in;
 		sequence<OperationDescription>
 			operation;
 		sequence<AttributeDescription>
 			attributes;5
 };
 
 	FullInterfaceDescription describe_interface();
 };

The operation describe_interface() provides detailed information about an interface, including information about its operations and attributes. Alternatively, the inherited operation Container::describe_contents() can be used to iterate through the items declared directly in the interface. The operation describe_interface() is the most straightforward way to obtain a description of an interface's operations and attributes. These can be obtained by calling the function Container::describe_contents() (or a combination of Container::contents() and Contained::describe()).

The interface reference, of type InterfaceDef, of an object can be obtained by calling the function _get_interface() on a pointer to the object. Subsequently, the functions InterfaceDef::describe_interface() and/or Container::describe_contents() can be used to get detailed information about the interface.

The inherited operation Container::contents() returns a list of the constants, typedefs, exceptions, operations and attributes defined in the interface; these will include those inherited if exclude_inherited is false. Container::describe_contents() is a combination of the functions Container::contents() and Contained::describe().

The inherited operation Contained::describe() returns a structure of type Contained::Description. The value member, of type any, will have a TypeCode _tc_InterfaceDescription and a value which is a structure of type InterfaceDescription:

 // IDL
 struct InterfaceDescription {
 	Identifier name;
 	RepositoryId id;
 	RepositoryId defined_in;
 };

In this section, we show some example code that uses the types that have been described in this chapter.

The following code prints the list of operation names and attribute names defined on the interface of a given object:

 // Java
 // List the names of the operations valid on
 // the object referenced by objRef.
 
 IE.Iona.Orbix2._InterfaceDefRef interfaceRef;
 
 try {
 	// Get interface definition:
 	interfaceRef = objRef._get_interface();
 }
 catch ... // Handle any exceptions.
 
 IE.Iona.Orbix2.InterfaceDef.
 	FullInterfaceDescription full;
 
 try {
 	full = interfaceRef.describe_interface();
 }
 catch ... // Handle any exceptions.
 
 // Now print out the operation names:
 System.out.println ("The operation names are:");
 
 long i;
 
 for (i=0; i < full.operation.length; i++) {
 	System.out.println ("\t" + 
 		full.operation.buffer[i].name);
 
 // Now print out the attribute names:
 System.out.println ("The attribute names are:");
 
 for (i=0; i < full.attributes.length; i++) {
 	 System.out.println ("\t" + 
 		full.attributes.buffer[i].name);

 // Look up the operation doit() on the 
 // interface:
 try {
 	IE.Iona.Orbix2.ContainedSeq operations;
 
 	System.out.println (
 		"Looking up operation doit()");
 
 	operations = interfaceRef.lookup_name(
 					"doit", 1, "OperationDef", 0);
 
 	if (operations.length != 1)
 		System.out.println (
 			"Incorrect result lookup_name()");
 	}
 	else {
 		// Narrow the result to be an OperationDef:
 		IE.Iona.Orbix2._OperationDefRef doitOpRef;
 
 		doitOpRef = OperationDef.
 			_narrow(operations.buffer[0]);
 	}
 	...
 }
 catch ... // Handle any exceptions.

extension .sa

This is used if the -N switch is not specified. A file with the same base name but with extension .sa will be created in the Interface Repository's storage space to indicate that the -N switch was not specified.

extensions .rt and .inc

These are used if the -N switch is specified. For the root file being compiled, a file with the same base name but with extension .rt will be created in the Interface Repository's storage space to indicate that the -N switch was specified (this is in addition to copying the .idl file). In addition, each included file will be copied into the Interface Repository's storage space (using the normal .idl extension) and a .inc file will be created for each to indicate that its .idl file was copied because of inclusion in another file.