IIOP.NET - Custom mapping plugin mechanism

Custom mapping plugin mechanism

This tutorial explains the custom mapping plugin mechanism in IIOP.NET.

Purpose

The custom mapping plugin mechanism allows to specify a different mapping between a CLS type and an IDL type. This mechanism is most useful in connection with CORBA value types. If an implementation of the value type already exists on both platforms connected via CORBA, this mapping mechanism can map them on each other.

Example

An implementation of an ArrayList exists both in Java and in the .NET base class library. Using this custom mapping mechanism, java.util.ArrayList is mapped to System.Collections.ArrayList and vice versa.

Using the mapping plugin mechanism

This section describes, how to set up a custom mapping.
Setting up a custom mapping for a .NET client and for a .NET server is slighty different, because in the first case the IIOPChannel and the IDL to CLS compiler must be configured, whereas in the second case the IIOPChannel and the CLS to IDL generator must be configured.

Setting up a custom mapping for a .NET client

Setting up a custom mapping requires the following steps:

Create a custom mapping configuration file
Install mapping in the application
Implement needed InstanceMappers.
Implement CORBA value types
Use mapping file with the IDL to CLS compiler

Create a custom mapping configuration file

The mapping configuration file describes the custom mapping for the IIOPChannel and the IDL to CLS compiler. For convenience reasons, the same file can be used to configure the channel and the compiler.

The file contains a set of mapping descriptions of the following form:

    <mapping>
      <idlTypeName>type name<idlTypeName>
      <idlTypeAssembly>assembly name<idlTypeAssembly>
      <clsType>assembly qualified type name<clsType>
      <customMapper>assembly qualified type name<customMapper>
    <mapping>

The idlTypeName and the idlTypeAssembly entries specify, which type in which assembly represents the IDL type (in CLS) to which / from which should be mapped.
The clsType entry specifies the CLS type to which / from which should be mapped.
The optional customMapper part describes, which type maps instances from the IDL type to instances of the CLS type and vice versa.

Hint: The following XML schema's describes the format of this configuration file:
%IIOPNet%\IIOPChannel\MappingPluginSchema.xsd and %IDLToCLSCompiler%\IDLCompiler\MappingPluginSchema.xsd

Example:

    <?xml version='1.0'?>
    <mappings>

        <mapping>
            <idlTypeName>java.util.ArrayList<idlTypeName>
            <idlTypeAssembly>javaCollections<idlTypeAssembly>
            <clsType>System.Collections.ArrayList,mscorlib<clsType>
            <customMapper>
            Ch.Elca.Iiop.JavaCollectionMappers.ArrayListMapper,customCollectionMappings
            <customMapper>
        <mapping>
    
    <mappings>

Install mapping in the application

To take effect, the mapping must be installed together with the IIOPChannel in the application. The singleton CustomMapperRegistry allows to install a custom mapping from a file:

    CustomMapperRegistry reg = CustomMapperRegistry.GetSingleton();
    reg.AddMappingsFromFile(new FileInfo(fileName));

Implement needed InstanceMappers.

If instantiable types are mapped to each other, InstanceMappers are needed to map instances of one type to instances of the other type. During deserialisation, an instance of the CLS type representing the IDL type is created. This instance must be mapped to the target CLS type with an instance mapper. Just before serialisation, the instance of the CLS type must be mapped to an instance of the CLS type representing the IDL type.
The custom mapping plugin does the mapping with the help of a class implementing the ICustomMapper interface. This interfaces is defined as follows:

 
    public interface ICustomMapper {
         object CreateIdlForClsInstance(object clsObject);
         object CreateClsForIdlInstance(object idlObject);
     }

The CreateIdlForClsInstance method takes a CLS instance, and returns an instance of the CLS type representing the IDL type.
The CreateClsForIdlInstance method takes an instance of the CLS type representing the IDL type, and returns an instance of the CLS type.

The implementation of the instance mapper for the ArrayList example can be found in %IIOPNet%\MappingPlugin\java\InstanceMappers.cs.

Implement CORBA value types

If the IDL type in the custom mapping is a CORBA value type, this CORBA value type must be implemented in CLS. This implementation is needed to support serialisation / deserialisation.
Hint: For the methods, if present, only a dummy implementation is needed.

The implementation for the ArrayList example can be found in %IIOPNet%\MappingPlugin\java\CollectionsImpl.cs.

Use mapping file with the IDL to CLS compiler

The IDL to CLS compiler needs to replace the IDL type in the custom mapping with the target CLS type in method parameters, properties and fields.
The information, needed to accomplish this, is given to the compiler with the -c option:
IDLToCLSCompiler.exe -c mappingFile

A complete example can be found in:
%IIOPNet%\IntegrationTests\MappingPluginJava.

Setting up a mapping for a .NET server

Setting up such a mapping requires the following steps:

Create a custom mapping configuration file for the IIOPChannel
Create a custom mapping configuration file for the CLS to IDL generator
Install the mapping in the application
Implement needed InstanceMapper's.
Implement CORBA value types
Use mapping file with CLS to IDL generator

Steps 1, 3, 4 and 5 are the same as for a .NET client. For more information see section setting up a mapping for a .NET client.

Create a custom mapping configuration file for the CLS to IDL generator

This mapping configuration file describes the custom mapping for the CLS to IDL generator.

This file contains a set of mapping descriptions of the following form:

    <mapping>
        <clsType>assembly qualifies type name<clsType>
        <idlTypeName>type name<idlTypeName>
        <idlTypeAssembly>assembly name;idlTypeAssembly>
        <idlFile>(relative) path to idl file<idlFile>
    <mapping>

The clsType entry specifies the CLS type to which / from which should be mapped.
The idlTypeName and the idlTypeAssembly entries specify, which type in which assembly represents the idltype (in CLS) to which / from which should be mapped.
The idlFile specifies the location of the IDL file containing the IDL definition of the target IDL type.

Hint: The following XML schema describes the format of this configuration file:
%IIOPNet%\CLSToIDLGenerator\GeneratorMappingPluginSchema.xsd.

Example:

    <?xml version='1.0'?>
    <generatorMappings>

        <mapping>
            <clsType>System.Collections.ArrayList,mscorlib<clsType>
            <idlTypeName>java.util.ArrayList<idlTypeName>
            <idlTypeAssembly>javaCollections<idlTypeAssembly>
            <idlFile>java\util\ArrayList.idl<idlFile>
        <mapping>

     <generatorMappings>

Use mapping file with CLS to IDL generator

The CLS to IDL generator needs to replace the CLS type in the custom mapping with the target IDL type in methods parameters, properties and fields within the generated IDL files.
The information, needed to accomplish this, is given to the generator with the -c option:
CLSIDLGenerator.exe -c mappingFile

A complete example can be found in:
%IIOPNet%\IntegrationTests\MappingPluginJavaAsClient.

About this project

This project is maintained by Elca Informatique SA and was developed in collaboration with the Programming Languages and Runtime Systems Research Group of the ETH-Zurich as part of Dominic Ullmann's diploma thesis.

IIOP.NET Use Cases

Read the IIOP.NET success stories.

Custom mapping plugin mechanism

About this project

IIOP.NET Use Cases

News