IOGRManager

 

Introduction

Fault Tolerant CORBA specification introduces the Interoperable Object Group References in order to face the problem of addressing a group of replicated CORBA objects. An IOGR is a multiprofile IOR composed by IIOP profiles addressing object group members. Any of these profiles can be used by client ORBs to reach the server object group. A TAG_MULTIPLE_COMPONENTS profile must be present in an IOGR when it identifies an empty group, i.e. with no replicas currently belonging to the group.

Each profile must contain the TAG_FT_GROUP component, while the TAG_FT_PRIMARY component can be contained in at most one TAG_INTERNET_IOP profile.

The TAG_FT_GROUP component is a struct composed by four fields, namely: version, ft_domain_id, object_group_id and object_group_ref_version. These fields allow to uniquely identify an object group in the context of a fault tolerant domain and to associate version numbers to membership changes.

The TAG_FT_PRIMARY component of a IIOP profile, if present, informs to the client ORB that the containing IIOP profile probably is the primary member of a passively replicated object group.

We have implemented an object to allow CORBA clients to build, update and manage IOGRs, i.e. the IOGRManager CORBA object, available for download.

 

 

 

IOGRManager IDL Interface

 

interface IOGRManager{
ObjectGroup create_IOGR(in FT::FTDomainId ft_domain_id, in FT::ObjectGroupId obiect_group_id,

                                     in FT::ObjectGroupRefVersion object_group_ref_version,  

                                     in ObjectList obj_list) raises (IOGRException);
ObjectList extract_Object (in ObjectGroup object_group) raises (IOGRException);
ObjectGroup add_Member(in ObjectGroup object_group, in Object obj) raises (IOGRException); 
ObjectGroup remove_Member (in ObjectGroup object_group, in Object obj) raises (IOGRException);
ObjectGroup set_Primary_Member(in ObjectGroup object_group, in Object primary_object)

                                                  raises (IOGRException);
ObjectGroup set_Group_Version(in ObjectGroup object_group, in FT::ObjectGroupRefVersion version)

                                              raises (IOGRException);
FT::ObjectGroupRefVersion get_Group_Version(in ObjectGroup object_group) raises (IOGRException);
Object get_Primary_Member(in ObjectGroup object_group) raises (IOGRException);
boolean is_ObjectGroup (in Object object_group) raises (IOGRException);
boolean is_Equivalent (in Object object_a, in Object object_b) raises (IOGRException);
}

 

                                              

 

IOGRManager Operations

 

 

It allows to create IOGRs. It takes as input parameter the ids of the object group and of the fault tolerance domain, the object group version and an ObjectList object, which contains a (possibliy empty) list of references. If the list is empty, a simple IOGR containing a multiple components profile is returned. If the list is not empty, the returned reference will include all the IIOP profiles of the references belonging to the object_list.

In any case, the returned object group reference has no profile containing a TAG_FT_PRIMARY component. The primary member of a passively replicated object group can be set later using the set_Primary_Member operation.

A client will use this operation performing these steps:

  • Create the ObjectList with the Object References to insert in IOGR.

  • Invoke the create_IOGR operation on a servant of IOGRManager object, passing, as input parameters, the ObjectList and the values of TAG_FT_GROUP fields.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Create the Object List, with 2 Objects, registered into Naming Service with the names "name1" and "name2".

org.omg.CORBA.Object obj = nc.resolve(nc.to_name(name1));

org.omg.CORBA.Object[] _ObjList = new org.omg.CORBA.Object[2];
_ObjList[0] =obj;

obj = nc.resolve(nc.to_name(name2));

_ObjList[1] =obj;

try{

// Create IOGR, passing, as input parameter, the ObjectList and the values of TAG_FT_GROUP.

obj = iogr_manager.create_IOGR(ft_domain_id, object_group_id, object_group_ref_version, _ObjList)

// Bind the new IOGR into Naming Service with the name "IOGR_name".

nc.bind( nc.to_name(IOGR_name), obj);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

 

 

It allows to extract from an object group reference, passed as input parameter, a (possibly empty) list of object references, one for each profile of the IOGR addressing the object group.

If the object group reference has only a multiple components profile, it returns an empty list. 

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

  2. If the object group reference, passed as input parameter, contains a profile without TAG_FT_GROUP, returns an IOGRException with ExceptionMessage "TAG_FT_GROUP Not Found".

A client will use this operation performing these steps:

  • Get the object group reference to split.

  • Invoke the extract_Object operation on a servant of IOGRManager object, passing, as input parameter, the object group reference.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object group reference, registered into Naming Service with the name "iogr_name".

org.omg.CORBA.Object obj_iogr = nc.resolve(nc.to_name(iogr_name));

//Extract an ObjectList from the object group reference, passed as input parameter.

try{

ObjectList _ObjList = iogr_manager.extract_Object(obj_iogr);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

// Use the ObjectList

...

 

 

 

                    

 

 

It allows to insert a member into an object group reference. It extracts the IIOP profile from the obj input parameter, modifies it according to the Fault Tolerant CORBA specification and then inserts it into the object_group reference, that is finally returned as result.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

  2. If the object group reference, passed as input parameter, contains a profile without TAG_FT_GROUP, returns an IOGRException with ExceptionMessage "TAG_FT_GROUP Not Found".

  3. If the object to insert is already contained in IOGR, returns an IOGRException with ExceptionMessage "Duplicate Member".

  4. If the object reference and the object group reference, passed as input parameters, have different type_id, returns an IOGRException with ExceptionMessage "Wrong Type Id".

  5. If the object reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOR".

  6. If the object reference, passed as input parameter, is multi profile or has only a multiple components profile, returns an IOGRException with ExceptionMessage "Wrong IOR".

A client will use this operation performing these steps:

  • Get the object group reference of the Object Group to modify.

  • Get the object reference of the Object to add.

  • Invoke the add_Member operation on a servant of IOGRManager object, passing, as input parameters, the object group reference and the object reference.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object group reference of the object group to modify, registered into Naming Service with the name "iogr_name".

org.omg.CORBA.Object obj_iogr = nc.resolve(nc.to_name(iogr_name));

// Get the object reference of the object to add, registered into Naming Service with the name "ior_name".

org.omg.CORBA.Object obj_ior = nc.resolve(nc.to_name(ior_name));

//Add the object to the object group.

try{

org.omg.CORBA.Object obj =iogr_manager.add_Member(obj_iogr, obj_ior);

// Bind the new IOGR into Naming Service with the name "IOGR_name".

nc.bind( nc.to_name(IOGR_name), obj);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

 

 

It allows to remove a member from an object group reference. It extracts the IIOP profile from the obj input parameter, eliminates such profile from the object_group reference and then returns it as the result.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

  2. If the object group reference, passed as input parameter, contains a profile without TAG_FT_GROUP, returns an IOGRException with ExceptionMessage "TAG_FT_GROUP Not Found".

  3. If the object to remove is not found in IOGR, returns an IOGRException with ExceptionMessage "Object Not Found in Object Group".

  4. If the object reference and the object group reference, passed as input parameters, have different type_id, returns an IOGRException with ExceptionMessage "Wrong Type Id".

  5. If the object reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOR".

  6. If the object reference, passed as input parameter, is multi profile or has only a multiple components profile, returns an IOGRException with ExceptionMessage "Wrong IOR".

A client will use this operation performing these steps:

  • Get the object group reference of the Object Group to modify.

  • Get the object reference of the Object to remove.

  • Invoke the remove_Member operation on a servant of IOGRManager object, passing, as input parameters, the object group reference and the object reference.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object group reference of the object group to modify, registered into Naming Service with the name "iogr_name".

org.omg.CORBA.Object obj_iogr = nc.resolve(nc.to_name(iogr_name));

// Get the object reference of the object to remove, registered into Naming Service with the name "ior_name".

org.omg.CORBA.Object obj_ior = nc.resolve(nc.to_name(ior_name));

//Remove the object from the object group.

try{

org.omg.CORBA.Object obj =iogr_manager.remove_Member(obj_iogr, obj_ior);

// Bind the new IOGR into Naming Service with the name "IOGR_name".

nc.bind( nc.to_name(IOGR_name), obj);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

 

 

  • ObjectGroup set_Primary_Member(in ObjectGroup object_group, in Object primary_object)

                                                      raises (IOGRException);

It allows to set and to modify the primary IIOP profile of a passively replicated object group.

It returns an object group reference in which a TAG_FT_PRIMARY component appears only into the object group reference profile identified by the primary_object input parameter.

If another different profile with TAG_FT_PRIMARY is found in the object group reference, it is removed from the profile, according to FT_CORBA specification.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

  2. If the object group reference, passed as input parameter, contains a profile without TAG_FT_GROUP, returns an IOGRException with ExceptionMessage "TAG_FT_GROUP Not Found".

  3. If the object to set as primary is not found in IOGR, returns an IOGRException with ExceptionMessage "Object Not Found in Object Group".

  4. If the object reference and the object group reference, passed as input parameters, have different type_id, returns an IOGRException with ExceptionMessage "Wrong Type Id".

  5. If the object reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOR".

  6. If the object reference, passed as input parameter, is multi profile or has only a multiple components profile, returns an IOGRException with ExceptionMessage "Wrong IOR".

A client will use this operation performing these steps:

  • Get the object group reference of the ObjectGroup to modify.

  • Get the object reference of the Object to set as primary.

  • Invoke the set_Primary_Member operation on a servant of IOGRManager object, passing, as input parameters, the object group reference and the object reference.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object group reference of the object group to modify, registered into Naming Service with the name "iogr_name".

org.omg.CORBA.Object obj_iogr = nc.resolve(nc.to_name(iogr_name));

// Get the object reference of the object to set as primary, registered into Naming Service with the name "primary_name".

org.omg.CORBA.Object obj_ior = nc.resolve(nc.to_name(primary_name));

//Set the primary member into the object group.

try{

org.omg.CORBA.Object obj =iogr_manager.set_Primary_Member(obj_iogr, obj_ior);

// Bind the new IOGR into Naming Service with the name "IOGR_name".

nc.bind( nc.to_name(IOGR_name), obj);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

 

 

It accepts as input parameter an object group reference and returns the reference of the IIOP profile containing the TAG_FT_PRIMARY component, if present.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

  2. If the object group reference, passed as input parameter, contains a profile without TAG_FT_GROUP, returns an IOGRException with ExceptionMessage "TAG_FT_GROUP Not Found".

  3. If the object group reference has no profiles with TAG_FT_PRIMARY, returns an IOGRException with ExceptionMessage "Primary Not Found".

A client will use this operation performing these steps:

  • Get the object group reference of the ObjectGroup into which the primary is to be searched.

  • Invoke the get_Primary_Member operation on a servant of IOGRManager object, passing, as input parameter, the object group reference.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object group reference of the object group into which the primary is to be searched, registered into Naming Service with the name "iogr_name".

org.omg.CORBA.Object obj_ior = nc.resolve(nc.to_name(iogr_name));

//Get the primary member of the object group.

try{

org.omg.CORBA.Object obj =iogr_manager.get_Primary_Member(obj_iogr);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

It returns an object group reference obtained from the object_group input parameter by setting to the version value the ObjectGroupRefVersion field value of the TAG_FT_GROUP component of each profile.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

  2. If the object group reference, passed as input parameter, contains a profile without TAG_FT_GROUP, returns an IOGRException with ExceptionMessage "TAG_FT_GROUP Not Found".

 

A client will use this operation performing these steps:

  • Get the object group reference of the ObjectGroup into which the version is to be set.

  • Invoke the set_Group_Version operation on a servant of IOGRManager object, passing, as input parameters, the object group reference and the value of the version.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object group reference of the object group to modify, registered into Naming Service with the name "iogr_name".

org.omg.CORBA.Object obj_iogr = nc.resolve(nc.to_name(iogr_name));

//Set the ObjectGroupRefVersion into the object group.

try{

org.omg.CORBA.Object obj =iogr_manager.set_Group_Version(obj_iogr, version);

// Bind the new IOGR into Naming Service with the name "IOGR_name".

nc.bind( nc.to_name(IOGR_name), obj);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

 

It returns the value of the ObjectGroupRefVersion field of the TAG_FT_GROUP component of a profile of the object group reference passed as input parameter.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

  2. If the object group reference, passed as input parameter, contains a profile without TAG_FT_GROUP, returns an IOGRException with ExceptionMessage "TAG_FT_GROUP Not Found".

 

A client will use this operation performing these steps:

  • Get the object group reference of the ObjectGroup into which the version is to be searched.

  • Invoke the get_Group_Version operation on a servant of IOGRManager object, passing, as input parameter, the object group reference.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object group reference of the object group into which the version is to be searched, registered into Naming Service with the name "iogr_name".

org.omg.CORBA.Object obj_ior = nc.resolve(nc.to_name(iogr_name));

//Get the version of the object group.

try{

int version =iogr_manager.get_Group_Version(obj_iogr);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

 

  • boolean is_ObjectGroup (in Object object_group) raises (IOGRException);

It checks if an object reference is an object group reference.

It returns true if the reference passed as input parameter is an object group, i.e. it contains in each profile the TAG_FT_GROUP component, according to Fault Tolerant CORBA specification.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

 

A client will use this operation performing these steps:

  • Get the object reference to test.

  • Invoke the is_ObjectGroup operation on a servant of IOGRManager object, passing, as input parameter, the object reference.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the object reference to test, registered into Naming Service with the name "obj_name".

org.omg.CORBA.Object obj = nc.resolve(nc.to_name(obj_name));

// Test the object reference.

try{

boolean result = iogr_manager.is_ObjectGroup(obj);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);} 

 

 

 

                    

 

 

  • boolean is_Equivalent (in Object object_a, in Object object_b) raises (IOGRException);

It checks if two object references, passed as input parameters, are equivalent.

According to Fault Tolerant CORBA specification, there are three cases to consider for checking equivalence:

  1. Two non-object group references. In this case, this operation returns the result of the _is_equivalent operation defined for the object references.

  2. An object group reference and a non-object group reference. These references are not equivalent.

  3. Two object group references. In this case, this operation returns true if they have the same ft_domain_id and the same object_group_id fields.

It returns an IOGRException in the following cases:

  1. If the object group reference, passed as input parameter, is empty, i.e. without profiles, returns an IOGRException with ExceptionMessage "No Profiles in IOGR".

 

A client will use this operation performing these steps:

  • Get the object references to test.

  • Invoke the is_Equivalent operation on a servant of IOGRManager object, passing, as input parameters, the object references.

Example:

 

// Initialize the ORB

org.omg.CORBA.ORB orb =org.omg.CORBA.ORB.init(args,null); 

// Get a reference to the root_context
NamingContextExt nc=NamingContextExtHelper.narrow(orb.resolve_initial_references("NameService"));

// Create a servant, resolving the reference from Naming Service.
IOGRManager iogr_manager = IOGRManagerHelper.narrow(nc.resolve(nc.to_name("IOGRManager")));

 

// Get the first object reference to test, registered into Naming Service with the name "obj1_name".

org.omg.CORBA.Object obj1 = nc.resolve(nc.to_name(obj1_name));

// Get the second object reference to test, registered into Naming Service with the name "obj2_name".

org.omg.CORBA.Object obj2 = nc.resolve(nc.to_name(obj2_name));

// Test the object references.

try{

boolean result = iogr_manager.is_Equivalent(obj1, obj2);

}catch (IOGRException ex)

{ System.out.println (ex.ExceptionMessage);}