Merge pull request #2303 from jwillemsen/jwi-803
[ACE_TAO.git] / TAO / tests / Bug_3154_Regression / orbsvcs / CosNotification.idl
bloba067f40a6071e0c9c7cd3de19a0ec3138630ca10
1 /**
2 * @file CosNotification.idl
4 * @brief Define the CosNotification module
6 * CosNotification.idl,v 1.3 2002/07/01 14:13:59 parsons Exp
8 * @author Pradeep Gore <pradeep@cs.wustl.edu>
9 */
11 #ifndef _COS_NOTIFICATION_IDL_
12 #define _COS_NOTIFICATION_IDL_
14 #pragma prefix "omg.org"
16 /**
17 * @namespace CosNotification
19 * @brief Define basic data structures used by the Notification
20 * Service
22 module CosNotification
24 /// Dummy typedef for strings, if the intent was to support I18N
25 /// strings the spec should have used wstring
26 typedef string Istring;
28 /// Properties are named using a string
29 typedef Istring PropertyName;
31 /// Property values are stored using anys
32 typedef any PropertyValue;
34 /**
35 * @struct Property
37 * @brief Define a name/value pair.
39 * Events are described using named/value sequences, this structure
40 * defines the name/value pair.
42 struct Property {
43 /// The name
44 PropertyName name;
45 /// The value
46 PropertyValue value;
49 /// Define a sequence of properties.
50 typedef sequence<Property> PropertySeq;
52 //@{
53 /**
54 * @name Different kinds of property sequences
56 * @brief The following are all sequences of Property, but
57 * serve different purposes.
59 /// Property sequence used for optional header fields
60 typedef PropertySeq OptionalHeaderFields;
62 /// Property sequence used for the event body that can be used
63 /// in filtering
64 typedef PropertySeq FilterableEventBody;
66 /// Specify quality of service properties
67 typedef PropertySeq QoSProperties;
69 /// Specify administrative properties
70 typedef PropertySeq AdminProperties;
71 //@}
73 /**
74 * @struct _EventType
76 * @brief Define event type names.
78 * Different vertical industries (domains) can define well-known
79 * events (event_types). This structure is used for that purpose
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;
87 /// A sequence of event types
88 typedef sequence<_EventType> EventTypeSeq;
90 /**
91 * @struct PropertyRange
93 * @brief A structure to define property ranges.
96 struct PropertyRange {
97 /// Lower end of the range
98 PropertyValue low_val;
99 /// High end of the range
100 PropertyValue high_val;
104 * @struct NamedPropertyRange
106 * @brief A named property range
108 struct NamedPropertyRange {
109 /// The name
110 PropertyName name;
111 /// The range
112 PropertyRange range;
114 /// A sequence of named property ranges
115 typedef sequence<NamedPropertyRange> NamedPropertyRangeSeq;
118 * @enum QoSError_code
120 * @brief Describe QoS errors.
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
143 * @struct PropertyError
145 * @brief Describe the problems detected with an application
146 * requested QoS.
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).
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;
161 /// List of property errors.
162 typedef sequence<PropertyError> PropertyErrorSeq;
165 * @exception UnsupportedQoS
167 * @brief Exception used to describe problems with one or more QoS
168 * requests
171 exception UnsupportedQoS {
172 /// Complete description of the properties in error
173 PropertyErrorSeq qos_err;
177 * @exception UnsupportedAdmin
179 * @brief Exception used to describe problems with one or more Admin
180 * properties
182 exception UnsupportedAdmin {
183 /// The complete description of the invalid properties.
184 PropertyErrorSeq admin_err;
188 * @struct FixedEventHeader
190 * @brief Define the 'fixed' part of the event header
192 struct FixedEventHeader {
193 /// The event type
194 _EventType event_type;
195 /// A (possibly unique) name for the particular event
196 string event_name;
200 * @struct EventHeader
202 * @brief Complete event header
204 struct EventHeader {
205 /// The fixed part of the event header
206 FixedEventHeader fixed_header;
207 /// The optional part
208 OptionalHeaderFields variable_header;
212 * @struct StructuredEvent
214 * @brief Define structured events
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;
224 /// Sequence of events, for batch processing
225 typedef sequence<StructuredEvent> EventBatch;
227 //@{
229 * @name Constants for QoS Properties
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.
238 const string EventReliability = "EventReliability";
239 const short BestEffort = 0;
240 const short Persistent = 1;
242 /// Can take on the same values as EventReliability
243 const string ConnectionReliability = "ConnectionReliability";
245 const string Priority = "Priority";
246 const short LowestPriority = -32767;
247 const short HighestPriority = 32767;
248 const short DefaultPriority = 0;
250 /// StartTime takes a value of type TimeBase::UtcT.
251 const string StartTime = "StartTime";
253 /// StopTime takes a value of type TimeBase::UtcT.
254 const string StopTime = "StopTime";
256 /// Timeout takes on a value of type TimeBase::TimeT
257 const string Timeout = "Timeout";
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;
265 /// DiscardPolicy takes on the same values as OrderPolicy, plus
266 const string DiscardPolicy = "DiscardPolicy";
267 const short LifoOrder = 4;
269 /// MaximumBatchSize takes on a value of type long
270 const string MaximumBatchSize = "MaximumBatchSize";
272 /// PacingInterval takes on a value of type TimeBase::TimeT
273 const string PacingInterval = "PacingInterval";
275 /// StartTimeSupported takes on a boolean value
276 const string StartTimeSupported = "StartTimeSupported";
278 /// StopTimeSupported takes on a boolean value
279 const string StopTimeSupported = "StopTimeSupported";
281 /// MaxEventsPerConsumer takes on a value of type long
282 const string MaxEventsPerConsumer = "MaxEventsPerConsumer";
284 //@}
287 * @interface QoSAdmin
289 * @brief Interface used to control the QoS properties of an Event
290 * Service components (Channel, Proxy, etc.)
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.
297 interface QoSAdmin {
298 /// Get the current QoS properties
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.
305 QoSProperties get_qos();
307 /// Set the QoS properties
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.
314 void set_qos (in QoSProperties qos)
315 raises (UnsupportedQoS);
317 /// Validate a set of QoS properties
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.
328 void validate_qos (in QoSProperties required_qos,
329 out NamedPropertyRangeSeq available_qos )
330 raises (UnsupportedQoS);
333 //@{
335 * @name Constants for Admin Properties
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
342 /// MaxQueueLength takes on a value of type long
343 const string MaxQueueLength = "MaxQueueLength";
345 /// MaxConsumers takes on a value of type long
346 const string MaxConsumers = "MaxConsumers";
348 /// MaxSuppliers takes on a value of type long
349 const string MaxSuppliers = "MaxSuppliers";
351 /// RejectNewEvents takes on a value of type Boolean
352 const string RejectNewEvents = "RejectNewEvents";
353 //@}
356 * @interface AdminPropertiesAdmin
358 * @brief Define the interface to manipulate the Admin properties of
359 * a Notification Service components
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.
366 interface AdminPropertiesAdmin {
367 /// Get the Admin properties
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.
374 AdminProperties get_admin();
376 /// Set the Admin properities
378 * @param admin The list of Admin properties requested
379 * @throws UnsupportedAdmin if the requested admin properties
380 * cannot be implemented or are invalid
382 void set_admin (in AdminProperties admin)
383 raises (UnsupportedAdmin);
388 #pragma prefix ""
390 #endif /* _COS_NOTIFICATION_IDL_ */