path: root/TAO/orbsvcs/orbsvcs/PortableGroup.idl

// -*- IDL -*-

//=============================================================================
/**
 *  @file    PortableGroup.idl
 *
 *  $Id$
 */
//=============================================================================

#ifndef _PORTABLEGROUP_IDL_
#define _PORTABLEGROUP_IDL_

#include <orbsvcs/CosNaming.idl>
#include <tao/IOP.pidl>
#include <tao/GIOP.pidl>
#include <orb.idl>

module PortableGroup
{
  typeprefix PortableGroup "omg.org";

  /// MembershipStyle
  const string PG_MEMBERSHIP_STYLE = "org.omg.PortableGroup.MembershipStyle";

  /// InitialNumberReplicas
  const string PG_INITIAL_NUMBER_REPLICAS = "org.omg.PortableGroup.InitialNumberReplicas";

  /// MinimumNumberReplicas
  const string PG_MINIMUM_NUMBER_REPLICAS = "org.omg.PortableGroup.MinimumNumberReplicas";

  /// Factories
  const string PG_FACTORIES = "org.omg.PortableGroup.Factories";

  // Specification for Interoperable Object Group References
  typedef string GroupDomainId;
  typedef unsigned long long ObjectGroupId;
  typedef unsigned long ObjectGroupRefVersion;

  struct TagGroupTaggedComponent { // tag = TAG_GROUP;
    GIOP::Version component_version;
    GroupDomainId group_domain_id;
    ObjectGroupId object_group_id;
    ObjectGroupRefVersion object_group_ref_version;
  };
  typedef sequence <octet> GroupIIOPProfile; // tag = TAG_GROUP_IIOP

  // Specification of Common Types and Exceptions for Group Management
  interface GenericFactory;

  typedef CORBA::RepositoryId _TypeId;
  typedef Object ObjectGroup;
  typedef sequence<ObjectGroup> ObjectGroups;
  typedef CosNaming::Name Name;
  typedef any Value;

  struct Property {
    Name nam;
    Value val;
  };

  typedef sequence<Property> Properties;
  typedef Name Location;
  typedef sequence<Location> Locations;
  typedef Properties Criteria;

  struct FactoryInfo {
    GenericFactory the_factory;
    Location the_location;
    Criteria the_criteria;
  };
  typedef sequence<FactoryInfo> FactoryInfos;

  typedef long MembershipStyleValue;
  const MembershipStyleValue MEMB_APP_CTRL = 0;
  const MembershipStyleValue MEMB_INF_CTRL = 1;

  typedef FactoryInfos FactoriesValue;
  typedef unsigned short InitialNumberReplicasValue;
  typedef unsigned short MinimumNumberReplicasValue;

  exception InterfaceNotFound {};
  exception ObjectGroupNotFound {};
  exception MemberNotFound {};
  exception ObjectNotFound {};
  exception MemberAlreadyPresent {};
  exception ObjectNotCreated {};
  exception ObjectNotAdded {};
  exception UnsupportedProperty {
    Name nam;
    Value val;
  };

  exception InvalidProperty {
    Name nam;
    Value val;
  };

  exception NoFactory {
    Location the_location;
    _TypeId type_id;
  };

  exception InvalidCriteria {
    Criteria invalid_criteria;
  };

  exception CannotMeetCriteria {
    Criteria unmet_criteria;
  };

  // Specification of PropertyManager Interface
  interface PropertyManager {

    void set_default_properties (in Properties props)
      raises (InvalidProperty, UnsupportedProperty);

    Properties get_default_properties();

    void remove_default_properties (in Properties props)
      raises (InvalidProperty, UnsupportedProperty);

    void set_type_properties (in _TypeId type_id, in Properties overrides)
      raises (InvalidProperty, UnsupportedProperty);

    Properties get_type_properties(in _TypeId type_id);

    void remove_type_properties (in _TypeId type_id, in Properties props)
      raises (InvalidProperty, UnsupportedProperty);

    void set_properties_dynamically
      (in ObjectGroup object_group, in Properties overrides)
      raises (ObjectGroupNotFound,
              InvalidProperty,
              UnsupportedProperty);

    Properties get_properties (in ObjectGroup object_group)
      raises (ObjectGroupNotFound);
  }; // endPropertyManager


  // Specification of ObjectGroupManager Interface
  interface ObjectGroupManager {
    ObjectGroup create_member (in ObjectGroup object_group,
                               in Location the_location,
                               in _TypeId type_id,
                               in Criteria the_criteria)
      raises (ObjectGroupNotFound,
              MemberAlreadyPresent,
              NoFactory,
              ObjectNotCreated,
              InvalidCriteria,
              CannotMeetCriteria);

    ObjectGroup add_member (in ObjectGroup object_group,
                            in Location the_location,
                            in Object member)
      raises (ObjectGroupNotFound,
              MemberAlreadyPresent,
              ObjectNotAdded);

    ObjectGroup remove_member (in ObjectGroup object_group,
                               in Location the_location)
      raises (ObjectGroupNotFound, MemberNotFound);

    Locations locations_of_members (in ObjectGroup object_group)
      raises (ObjectGroupNotFound);

    ObjectGroups groups_at_location (in Location the_location);

    ObjectGroupId get_object_group_id (in ObjectGroup object_group)
      raises (ObjectGroupNotFound);

    ObjectGroup get_object_group_ref (in ObjectGroup object_group)
      raises (ObjectGroupNotFound);

    Object get_member_ref (in ObjectGroup object_group,
                           in Location loc)
      raises (ObjectGroupNotFound, MemberNotFound);

  }; // end ObjectGroupManager


  // Specification of GenericFactory Interface
  interface GenericFactory {
    typedef any FactoryCreationId;

    Object create_object (in _TypeId type_id,
                          in Criteria the_criteria,
                          out FactoryCreationId factory_creation_id)
      raises (NoFactory,
              ObjectNotCreated,
              InvalidCriteria,
              InvalidProperty,
              CannotMeetCriteria);

    void delete_object (in FactoryCreationId factory_creation_id)
      raises (ObjectNotFound);

  }; // end GenericFactory

  ///////////////////////
  // The following FactoryRegistry interface is not included in the OMG PortableGroup IDL.
  // It's an extension needed as part of implementing the FT CORBA specification.

  /**
   * Interface to allow generic factories for replicas to register themselves.
   * Factories are distinguished by the type of object created (TypeId) and the
   * location at which they create the object (FactoryInfo.the_location)
   */
  interface FactoryRegistry
  {
    /**
     * register a factory to create objects of the given type
     * at the location given in the FactoryInfo.
     * @param type_id the type of object to be created.
     * @param factory_info information about the factory including its location.
     * @throws MemberAlreadyPresent if there is already a factory for this type of object
     *         at this location.
     */
    void register_factory(in _TypeId type_id, in FactoryInfo factory_info)
      raises (MemberAlreadyPresent);

    /**
     * Remove the registration of a factory.
     * @param type_id the type of object formerly created by this factory.
     * @param location where the factory formerly created objects.
     * @throws MemberNotPresent if no factory is available for the given type at this location.
     */
    void unregister_factory(in _TypeId type_id, in Location location)
      raises (MemberNotFound);

    /**
     * Remove the registration of all factories that create a particular type of object.
     * If no factories exist for the given type, the registry is unchanged.
     * This is not an error.
     * @param type_id the type of object formerly created by the factories to be unregistered.
     */
    void unregister_factory_by_type(in _TypeId type_id);

    /**
     * Remove the registration of all factories that create objects at a particular location.
     * If the location is unknown the registry is unchanged.
     * This is not an error.
     * @param location where the factories formerly created objects.
     */
    void unregister_factory_by_location(in Location location);

    /**
     * List all the factories that create a given type of object.
     * If the type is unknown, an empty list is returned.  This is not an error.
     * @param type_id the type of object the factories create.
     */
    FactoryInfos list_factories_by_type(in _TypeId type_id);

    /**
     * List all the factories that create a objects at a given location.
     * If no factories are registered for this location, an empty list is returned.
     * This is not an error.
     * @param location where the factories create objects.
     */
    FactoryInfos list_factories_by_location(in Location location);

  }; // end of FactoryRegistry

}; // end PortableGroup

#endif  /* _PORTABLEGROUP_IDL_ */