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

// -*- IDL -*-

//=============================================================================
/**
 *  @file    LoadBalancing.idl
 *
 *  $Id$
 *
 *  The "LoadBalancing" IDL module in this file is based heavily on
 *  the "FT" module defined in the OMG CORBA Fault Tolerance
 *  specification.
 *
 *  @author Ossama Othman <ossama@uci.edu>
 */
//=============================================================================


#ifndef TAO_LOADBALANCING_IDL
#define TAO_LOADBALANCING_IDL

#include "tao/PortableInterceptor.pidl"
#include "CosNaming.idl"
#include "orb.idl"

#pragma prefix "tao.lb"

/**
 * @class LoadBalancing
 *
 * @brief This module defines the interfaces and data types used in
 * TAO's Load Balancing service.
 * @par
 * TAO's Load Balancer manages distribution of requests to replicas of
 * a given Object in an effort to ensure that the  applications/hosts
 * pointed to by the Object reference are as equally loaded as
 * possible, i.e. load balanced.
 * @par
 * The definition of 'load' is application specific, for example, some
 * applications may choose to load balance access to multiple
 * dedicated lines, or separate network interfaces, as well as more
 * traditional load balancing metrics, such as CPU or power load.
 */
module LoadBalancing
{
  /// Types used for obtaining and/or reporting loads
  typedef unsigned long LoadId;
  struct Load {
    LoadId identifier;
    float value;
  };
  typedef sequence<Load> LoadList;

  /// Specification of Common Types and Exceptions for ReplicationManager
  interface GenericFactory;
  interface LoadNotifier;
  interface LoadMonitor;

  typedef unsigned long long ObjectGroupId;
  typedef unsigned long ObjectGroupRefVersion;

  typedef CORBA::RepositoryId TypeId;
  typedef Object ObjectGroup;
  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 unsigned short MembershipStyle;
  const MembershipStyle MEMB_APP_CTRL = 0;
  const MembershipStyle MEMB_INF_CTRL = 1;

  typedef unsigned short MonitoringStyle;
  const MonitoringStyle PULL = 0;
  const MonitoringStyle PUSH = 1;
  //  const MonitoringStyle NOT_MONITORED = 2;

  typedef unsigned short MonitoringGranularity;
  const MonitoringGranularity MEMB = 0;
  const MonitoringGranularity LOC = 1;
  const MonitoringGranularity LOC_AND_TYPE = 2;

  typedef unsigned short InitialNumberReplicas;
  typedef unsigned short MinimumNumberReplicas;

  typedef unsigned short ClientBinding;
  const ClientBinding PER_SESSION = 0;
  const ClientBinding PER_REQUEST = 1;
  const ClientBinding ON_DEMAND = 2;

  typedef unsigned short BalancingPolicy;
  const BalancingPolicy NON_ADAPTIVE = 0;
  const BalancingPolicy ADAPTIVE = 1;

  exception InterfaceNotFound {};
  exception ObjectGroupNotFound {};
  exception MemberNotFound {};
  exception ObjectNotFound {};
  exception MemberAlreadyPresent {};
  exception BadReplicationStyle {};
  exception ObjectNotCreated {};
  exception ObjectNotAdded {};
  exception PrimaryNotSet {};
  exception UnsupportedProperty {
    Name nam;
  };
  exception InvalidProperty {
    Name nam;
    Value val;
  };
  exception NoFactory {
    Location the_location;
    TypeId type_id;
  };
  exception InvalidCriteria {
    Criteria invalid_criteria;
  };
  exception CannotMeetCriteria {
    Criteria unmet_criteria;
  };
  exception MonitorAlreadyPresent {};
  exception LocationNotFound {};

  /// Specification of PropertyManager Interface which
  /// ReplicationManager Inherits
  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);
  };

  /// Specification of ObjectGroupManager Interface which
  /// ReplicationManager Inherits
  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,
              // CORBA::INV_OBJREF,  // @@ Missing declaration
              MemberAlreadyPresent,
              ObjectNotAdded);

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

//     ObjectGroup set_primary_member (in ObjectGroup object_group,
//                                     in Location the_location)
//       raises (ObjectGroupNotFound,
//               MemberNotFound,
//               PrimaryNotSet,
//               BadReplicationStyle);

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

    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);
  };

  /// Specification of GenericFactory Interface which
  /// ReplicationManager Inherits and Application Objects Implement
  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);
  };

  /// Specification of ReplicationManager Interface
  interface ReplicationManager : PropertyManager, ObjectGroupManager,
    GenericFactory {

    void register_load_notifier (in LoadNotifier load_notifier);

    LoadNotifier get_load_notifier ()
      raises (InterfaceNotFound);

    void register_load_monitor (in LoadMonitor load_monitor,
                                in Location the_location)
      raises (MonitorAlreadyPresent);

    LoadMonitor get_load_monitor (in Location the_location)
      raises (LocationNotFound);

    void remove_load_monitor (in Location the_location)
      raises (LocationNotFound);
  };

  /// It's not clear this interface is needed for the Load Balancer.
  interface LoadNotifier
  {
  };

  /// Interface that all load monitors must implement.
  interface LoadMonitor
  {
    /// Return the current load at the location the load monitor
    /// resides.
    readonly attribute LoadList current_load;

    /// Force redirection of requests for targets with the given
    /// RepositoryId to the target pointed to by the given object
    /// reference.
    void register_redirect (in string type_id,
                            in Object redirect_to);

    /// Remove the redirect for targets of the given RepositoryId.
    void remove_redirect (in string type_id);
  };

};

#pragma prefix ""

#endif /* TAO_LOADBALANCING_IDL */