TAO/tests/Bug_3154_Regression/orbsvcs/CosNotification.idl

   1 /**
   2  * @file CosNotification.idl
   3  *
   4  * @brief Define the CosNotification module
   5  *
   6  * CosNotification.idl,v 1.3 2002/07/01 14:13:59 parsons Exp
   7  *
   8  * @author Pradeep Gore <pradeep@cs.wustl.edu>
   9  */
  10
  11 #ifndef _COS_NOTIFICATION_IDL_
  12 #define _COS_NOTIFICATION_IDL_
  13
  14 #pragma prefix "omg.org"
  15
  16 /**
  17  * @namespace CosNotification
  18  *
  19  * @brief Define basic data structures used by the Notification
  20  *        Service
  21  */
  22 module CosNotification
  23 {
  24   /// Dummy typedef for strings, if the intent was to support I18N
  25   /// strings the spec should have used wstring
  26   typedef string Istring;
  27
  28   /// Properties are named using a string
  29   typedef Istring PropertyName;
  30
  31   /// Property values are stored using anys
  32   typedef any PropertyValue;
  33
  34   /**
  35    * @struct Property
  36    *
  37    * @brief Define a name/value pair.
  38    *
  39    * Events are described using named/value sequences, this structure
  40    * defines the name/value pair.
  41    */
  42   struct Property {
  43     /// The name
  44     PropertyName name;
  45     /// The value
  46     PropertyValue value;
  47   };
  48
  49   /// Define a sequence of properties.
  50   typedef sequence<Property> PropertySeq;
  51
  52   //@{
  53   /**
  54    * @name Different kinds of property sequences
  55    *
  56    * @brief The following are all sequences of Property, but
  57    * serve different purposes.
  58    */
  59   /// Property sequence used for optional header fields
  60   typedef PropertySeq OptionalHeaderFields;
  61
  62   /// Property sequence used for the event body that can be used
  63   /// in filtering
  64   typedef PropertySeq FilterableEventBody;
  65
  66   /// Specify quality of service properties
  67   typedef PropertySeq QoSProperties;
  68
  69   /// Specify administrative properties
  70   typedef PropertySeq AdminProperties;
  71   //@}
  72
  73   /**
  74    * @struct _EventType
  75    *
  76    * @brief Define event type names.
  77    *
  78    * Different vertical industries (domains) can define well-known
  79    * events (event_types).  This structure is used for that purpose
  80    */
  81   struct _EventType {
  82     /// The name of the vertical industry defining the event type.
  83     string domain_name;
  84     /// The type of event.
  85     string type_name;
  86   };
  87   /// A sequence of event types
  88   typedef sequence<_EventType> EventTypeSeq;
  89
  90   /**
  91    * @struct PropertyRange
  92    *
  93    * @brief A structure to define property ranges.
  94    *
  95    */
  96   struct PropertyRange {
  97     /// Lower end of the range
  98     PropertyValue low_val;
  99     /// High end of the range
 100     PropertyValue high_val;
 101   };
 102
 103   /**
 104    * @struct NamedPropertyRange
 105    *
 106    * @brief A named property range
 107    */
 108   struct NamedPropertyRange {
 109     /// The name
 110     PropertyName name;
 111     /// The range
 112     PropertyRange range;
 113   };
 114   /// A sequence of named property ranges
 115   typedef sequence<NamedPropertyRange> NamedPropertyRangeSeq;
 116
 117   /**
 118    * @enum QoSError_code
 119    *
 120    * @brief Describe QoS errors.
 121    */
 122   enum QoSError_code {
 123     /// The application has requested an unsupported QoS property
 124     UNSUPPORTED_PROPERTY,
 125     /// The application has requested a QoS property that, though
 126     /// supported, cannot be set in the requested scope.
 127     UNAVAILABLE_PROPERTY,
 128     /// The application has requested a QoS property with an
 129     /// unsupported value.
 130     UNSUPPORTED_VALUE,
 131     /// The application has requested a QoS property with a supported
 132     /// value, but unavailable at the requested scope.
 133     UNAVAILABLE_VALUE,
 134     /// The property name is unknown or not recognized.
 135     BAD_PROPERTY,
 136     /// The value type for the requested property is invalid
 137     BAD_TYPE,
 138     /// The value for the requested property is illegal
 139     BAD_VALUE
 140   };
 141
 142   /**
 143    * @struct PropertyError
 144    *
 145    * @brief Describe the problems detected with an application
 146    * requested QoS.
 147    *
 148    * If there are any problems with an application request for QoS the
 149    * problems are raised using an exception that contains all the
 150    * problems, and a description of the valid values (if they apply).
 151    */
 152   struct PropertyError {
 153     /// Property error description
 154     QoSError_code code;
 155     /// Property name with a problem
 156     PropertyName name;
 157     /// Valid range for that property in the Notification Service
 158     /// implementation
 159     PropertyRange available_range;
 160   };
 161   /// List of property errors.
 162   typedef sequence<PropertyError> PropertyErrorSeq;
 163
 164   /**
 165    * @exception UnsupportedQoS
 166    *
 167    * @brief Exception used to describe problems with one or more QoS
 168    * requests
 169    *
 170    */
 171   exception UnsupportedQoS {
 172     /// Complete description of the properties in error
 173     PropertyErrorSeq qos_err;
 174   };
 175
 176   /**
 177    * @exception UnsupportedAdmin
 178    *
 179    * @brief Exception used to describe problems with one or more Admin
 180    * properties
 181    */
 182   exception UnsupportedAdmin {
 183     /// The complete description of the invalid properties.
 184     PropertyErrorSeq admin_err;
 185   };
 186
 187   /**
 188    * @struct FixedEventHeader
 189    *
 190    * @brief Define the 'fixed' part of the event header
 191    */
 192   struct FixedEventHeader {
 193     /// The event type
 194     _EventType event_type;
 195     /// A (possibly unique) name for the particular event
 196     string event_name;
 197   };
 198
 199   /**
 200    * @struct EventHeader
 201    *
 202    * @brief Complete event header
 203    */
 204   struct EventHeader {
 205     /// The fixed part of the event header
 206     FixedEventHeader fixed_header;
 207     /// The optional part
 208     OptionalHeaderFields variable_header;
 209   };
 210
 211   /**
 212    * @struct StructuredEvent
 213    *
 214    * @brief Define structured events
 215    */
 216   struct StructuredEvent {
 217     /// The header
 218     EventHeader header;
 219     /// The part of the body used for filtering
 220     FilterableEventBody filterable_data;
 221     /// The part of the body not used for filtering
 222     any remainder_of_body;
 223   };
 224   /// Sequence of events, for batch processing
 225   typedef sequence<StructuredEvent> EventBatch;
 226
 227   //@{
 228   /**
 229    * @name Constants for QoS Properties
 230    *
 231    * The following constant declarations define the standard QoS
 232    * property names and the associated values each property can take
 233    * on. The name/value pairs for each standard property are grouped,
 234    * beginning with a string constant defined for the property name,
 235    * followed by the values the property can take on.
 236    */
 237
 238   const string EventReliability = "EventReliability";
 239   const short BestEffort = 0;
 240   const short Persistent = 1;
 241
 242   /// Can take on the same values as EventReliability
 243   const string ConnectionReliability = "ConnectionReliability";
 244
 245   const string Priority = "Priority";
 246   const short LowestPriority = -32767;
 247   const short HighestPriority = 32767;
 248   const short DefaultPriority = 0;
 249
 250   /// StartTime takes a value of type TimeBase::UtcT.
 251   const string StartTime = "StartTime";
 252
 253   /// StopTime takes a value of type TimeBase::UtcT.
 254   const string StopTime = "StopTime";
 255
 256   /// Timeout takes on a value of type TimeBase::TimeT
 257   const string Timeout = "Timeout";
 258
 259   const string OrderPolicy = "OrderPolicy";
 260   const short AnyOrder = 0;
 261   const short FifoOrder = 1;
 262   const short PriorityOrder = 2;
 263   const short DeadlineOrder = 3;
 264
 265   /// DiscardPolicy takes on the same values as OrderPolicy, plus
 266   const string DiscardPolicy = "DiscardPolicy";
 267   const short LifoOrder = 4;
 268
 269   /// MaximumBatchSize takes on a value of type long
 270   const string MaximumBatchSize = "MaximumBatchSize";
 271
 272   /// PacingInterval takes on a value of type TimeBase::TimeT
 273   const string PacingInterval = "PacingInterval";
 274
 275   /// StartTimeSupported takes on a boolean value
 276   const string StartTimeSupported = "StartTimeSupported";
 277
 278   /// StopTimeSupported takes on a boolean value
 279   const string StopTimeSupported = "StopTimeSupported";
 280
 281   /// MaxEventsPerConsumer takes on a value of type long
 282   const string MaxEventsPerConsumer = "MaxEventsPerConsumer";
 283
 284   //@}
 285
 286   /**
 287    * @interface QoSAdmin
 288    *
 289    * @brief Interface used to control the QoS properties of an Event
 290    * Service components (Channel, Proxy, etc.)
 291    *
 292    * QoS properties of a channel can be set at different levels,
 293    * including the proxies, the ConsumerAdmin and the SupplierAdmin
 294    * objects.  Each one of those components offers this interface to
 295    * allow control over the properties.
 296    */
 297   interface QoSAdmin {
 298     /// Get the current QoS properties
 299     /**
 300      * The operation returns the properties set:
 301      * - At the level queried
 302      * - Not set at the level queried but set at a higher-level
 303      * - Not set at all but having a default value.
 304      */
 305     QoSProperties get_qos();
 306
 307     /// Set the QoS properties
 308     /**
 309      * @param qos The requested QoS properties
 310      * @throws UnsupportedQoS if the requested QoS cannot be
 311      *   implemented or is invalid.  The exception contents describe
 312      *   the problem(s) in detail.
 313      */
 314     void set_qos (in QoSProperties qos)
 315       raises (UnsupportedQoS);
 316
 317     /// Validate a set of QoS properties
 318     /**
 319      * @param required_qos the list of properties requested by the
 320      *        application
 321      * @param available_qos If the properties are supported this
 322      *        argument returns a list of any other properties that
 323      *        could also be set.
 324      * @throws UnsupportedQoS if the requested QoS cannot be
 325      *   implemented or is invalid.  The exception contents describe
 326      *   the problem(s) in detail.
 327      */
 328     void validate_qos (in QoSProperties required_qos,
 329                        out NamedPropertyRangeSeq available_qos )
 330       raises (UnsupportedQoS);
 331   };
 332
 333   //@{
 334   /**
 335    * @name Constants for Admin Properties
 336    *
 337    * Admin properties are defined in similar manner as QoS
 338    * properties. The only difference is that these properties are
 339    * related to channel administration policies, as opposed message
 340    * quality of service
 341    */
 342   /// MaxQueueLength takes on a value of type long
 343   const string MaxQueueLength = "MaxQueueLength";
 344
 345   /// MaxConsumers takes on a value of type long
 346   const string MaxConsumers = "MaxConsumers";
 347
 348   /// MaxSuppliers takes on a value of type long
 349   const string MaxSuppliers = "MaxSuppliers";
 350
 351   /// RejectNewEvents takes on a value of type Boolean
 352   const string RejectNewEvents = "RejectNewEvents";
 353   //@}
 354
 355   /**
 356    * @interface AdminPropertiesAdmin
 357    *
 358    * @brief Define the interface to manipulate the Admin properties of
 359    *   a Notification Service components
 360    *
 361    * Several Notification Service components have Admin properties,
 362    * including the Event Channel, its ConsumerAdmin and SupplierAdmin
 363    * objects as well as the proxies.  This interface is used to
 364    * control the Admin properties of each one of those components.
 365    */
 366   interface AdminPropertiesAdmin {
 367     /// Get the Admin properties
 368     /**
 369      * The operation returns the properties set:
 370      * - At the level queried
 371      * - Not set at the level queried but set at a higher-level
 372      * - Not set at all but having a default value.
 373      */
 374     AdminProperties get_admin();
 375
 376     /// Set the Admin properities
 377     /**
 378      * @param admin The list of Admin properties requested
 379      * @throws UnsupportedAdmin if the requested admin properties
 380      *   cannot be implemented or are invalid
 381      */
 382     void set_admin (in AdminProperties admin)
 383       raises (UnsupportedAdmin);
 384   };
 385
 386 };
 387
 388 #pragma prefix ""
 389
 390 #endif /* _COS_NOTIFICATION_IDL_ */