CosNotifyFilter.idl
Go to the documentation of this file.
00001 /** 00002 * @file CosNotifyFilter.idl 00003 * 00004 * @brief Defines the CosNotifyFilter module 00005 * 00006 * $Id: CosNotifyFilter.idl 41671 2001-09-17 20:50:34Z coryan $ 00007 * 00008 * This module is taken from the standard CORBA Notification Service 00009 * 1.0, as described in: 00010 * 00011 * http://www.omg.org/technology/documents/formal/notification_service.htm 00012 * 00013 * In particular the following two documents were used: 00014 * formal/2000-06-20 00015 * formal/01-03-03 00016 * 00017 * @author Pradeep Gore <pradeep@cs.wustl.edu> 00018 */ 00019 00020 #ifndef _COS_NOTIFY_FILTER_IDL_ 00021 #define _COS_NOTIFY_FILTER_IDL_ 00022 00023 #include <orb.idl> 00024 00025 #include "CosNotifyComm.idl" 00026 00027 #pragma prefix "omg.org" 00028 00029 /** 00030 * @namespace CosNotifyFilter 00031 * 00032 * @brief Defines the interfaces used in Event Filtering 00033 */ 00034 module CosNotifyFilter 00035 { 00036 /// Constraints are assigned IDs by each Filter object, and can be 00037 /// modified using those IDs. 00038 typedef long ConstraintID; 00039 00040 /** 00041 * @struct ConstraintExp 00042 * 00043 * @brief Defines a constraint expression. 00044 */ 00045 struct ConstraintExp { 00046 /// The list of event types accepted 00047 CosNotification::EventTypeSeq event_types; 00048 /// A constraint (or filtering) expression 00049 string constraint_expr; 00050 }; 00051 00052 /// A sequence of constraint IDs 00053 typedef sequence<ConstraintID> ConstraintIDSeq; 00054 00055 /// A sequence of constraint expressions 00056 typedef sequence<ConstraintExp> ConstraintExpSeq; 00057 00058 /** 00059 * @struct ConstraintInfo 00060 * 00061 * @brief Helper data structure to modify a constraint expression. 00062 */ 00063 struct ConstraintInfo { 00064 /// New constraint expression 00065 ConstraintExp constraint_expression; 00066 /// ID of the expression modified 00067 ConstraintID constraint_id; 00068 }; 00069 00070 /// Sequence of Constraint infos, modify multiple constraints. 00071 typedef sequence<ConstraintInfo> ConstraintInfoSeq; 00072 00073 /** 00074 * @struct MappingConstraintPair 00075 * 00076 * @brief Helper structure used to modify a mapping constraint 00077 * expression. 00078 */ 00079 struct MappingConstraintPair { 00080 /// Constraint expression 00081 ConstraintExp constraint_expression; 00082 /// Value to set in the property if the constraint expression 00083 /// matches 00084 any result_to_set; 00085 }; 00086 00087 /// Sequence of mapping constraint pairs 00088 typedef sequence<MappingConstraintPair> MappingConstraintPairSeq; 00089 00090 /** 00091 * @struct MappingConstraintInfo 00092 * 00093 * @brief Helper structure used to represent a mapping constraint, 00094 * its property value and the ID assigned to it in a MappingFilter. 00095 */ 00096 struct MappingConstraintInfo { 00097 ConstraintExp constraint_expression; 00098 ConstraintID constraint_id; 00099 any value; 00100 }; 00101 /// A list of MappingConstraintInfo 00102 typedef sequence<MappingConstraintInfo> MappingConstraintInfoSeq; 00103 00104 /// Each callback object receives a unique ID when it is attached to 00105 /// a Filter 00106 typedef long CallbackID; 00107 00108 /// Batch management of callback objects in the Filter interface 00109 typedef sequence<CallbackID> CallbackIDSeq; 00110 00111 /** 00112 * @exception UnsupportedFilterableData 00113 * 00114 * @brief Exception raised when an event with unsupported filtered 00115 * data is tested against a Filter. 00116 */ 00117 exception UnsupportedFilterableData {}; 00118 00119 /** 00120 * @exception InvalidGrammar 00121 * 00122 * @brief Exception raised if the filtering expression is using an 00123 * invalid grammar. 00124 */ 00125 exception InvalidGrammar {}; 00126 00127 /** 00128 * @exception InvalidConstraint 00129 * 00130 * @brief Exception raised if a constraint's grammar does not match 00131 * the Filter grammar. 00132 * 00133 * The constraint that is deemed invalid is returned as part of the 00134 * exception. 00135 */ 00136 exception InvalidConstraint { 00137 /// Constraint that caused the problem 00138 ConstraintExp constr; 00139 }; 00140 00141 /** 00142 * @exception DuplicateConstraintID 00143 * 00144 * @brief Exception raised if a duplicate ID is used while modifying 00145 * or removing multiple constraints. 00146 */ 00147 exception DuplicateConstraintID { 00148 /// ID causing the problem 00149 ConstraintID id; 00150 }; 00151 00152 /** 00153 * @exception ConstraintNotFound 00154 * 00155 * @brief Exception raised if a constraint ID is not found while 00156 * modifying or removing multiple constraints. 00157 */ 00158 exception ConstraintNotFound { 00159 /// ID causing the problem 00160 ConstraintID id; 00161 }; 00162 00163 /** 00164 * @exception CallbackNotFound 00165 * 00166 * @brief Exception raised if the application tries to remove a 00167 * Filter callback that does not exists. 00168 */ 00169 exception CallbackNotFound {}; 00170 00171 /** 00172 * @exception InvalidValue 00173 * 00174 * @brief Exception raised if a modification or addition of a 00175 * mapping constraint does not matches the mapping filter type. 00176 */ 00177 exception InvalidValue { 00178 /// Constraint expression that cause the problem 00179 ConstraintExp constr; 00180 /// Value that caused the problem 00181 any value; 00182 }; 00183 00184 /** 00185 * @interface Filter 00186 * 00187 * @brief Interface used to manipulate and evaluate filters. 00188 * 00189 * An event filter posseses multiple constraints, each constraint 00190 * applies to a limited range of event types, the filter is accepted 00191 * if it matches one or more constraint expressions that apply to 00192 * its event type. 00193 */ 00194 interface Filter { 00195 /// Constraint grammar used in this filter 00196 /** 00197 * All filtering expressions in the filter should use this 00198 * grammar. 00199 */ 00200 readonly attribute string constraint_grammar; 00201 00202 /// Add constraints to a filter 00203 /** 00204 * Return the constraints and their IDs. 00205 * 00206 * @throws InvalidConstraint if one or more constraints contain 00207 * invalid an invalid expression in the Filter constraint 00208 * grammar. 00209 */ 00210 ConstraintInfoSeq add_constraints ( 00211 in ConstraintExpSeq constraint_list) 00212 raises (InvalidConstraint); 00213 00214 /// Modify and/or remove multiple constraints in the Filter 00215 /** 00216 * The operation can raise InvalidConstraint if one or more 00217 * constraints contain invalid expressions in the constraint 00218 * grammar. 00219 * 00220 * @param del_list List of constraint IDs to be removed 00221 * @param modify_list List of constrained modified 00222 * 00223 * @throws ConstraintNotFound If one or more of the ConstraintID 00224 * supplied are not found. 00225 */ 00226 void modify_constraints ( 00227 in ConstraintIDSeq del_list, 00228 in ConstraintInfoSeq modify_list) 00229 raises (InvalidConstraint, ConstraintNotFound); 00230 00231 /// Obtain the one or more constraints given their IDs 00232 /** 00233 * @param id_list List of IDs queried 00234 * 00235 * @throws ConstraintNotFound if one or more of 00236 * the ConstraintID supplied are not found. 00237 */ 00238 ConstraintInfoSeq get_constraints( 00239 in ConstraintIDSeq id_list) 00240 raises (ConstraintNotFound); 00241 00242 /// The all the constraints in the Filter 00243 ConstraintInfoSeq get_all_constraints(); 00244 00245 /// Remove all the constraints from the Filter 00246 void remove_all_constraints(); 00247 00248 /// Destroy the Filter 00249 void destroy(); 00250 00251 /// Match a regular event against the constraints in the filter 00252 /** 00253 * @param filterable_data The Notification Service event to be 00254 * tested against the constraints in this Filter 00255 * @return TRUE if at least one constraint evaluates to TRUE for 00256 * the event. 00257 * @throws UnsupportedFilterableData if the event contents do not 00258 * match the filtering expression, for example, if the 00259 * expression for a filterable field expects a string, but the 00260 * actual value is a number. 00261 */ 00262 boolean match ( in any filterable_data ) 00263 raises (UnsupportedFilterableData); 00264 00265 /// Match a structured event against the constraints in the filter 00266 /** 00267 * @param filterable_data The Notification Service event to be 00268 * tested against the constraints in this Filter 00269 * @return TRUE if at least one constraint expression evaluates 00270 * to TRUE for the event. 00271 * @throws UnsupportedFilterableData if the event contents do not 00272 * match the filtering expression, for example, if the 00273 * expression for a filterable field expects a string, but the 00274 * actual value is a number. 00275 */ 00276 boolean match_structured ( 00277 in CosNotification::StructuredEvent filterable_data ) 00278 raises (UnsupportedFilterableData); 00279 00280 /// Match a typed event against the constraints in the filter 00281 /** 00282 * @param filterable_data The sequence of properties that make the 00283 * filterable portion of the Typed event. 00284 * @return TRUE if at least one constraint expression evaluates 00285 * to TRUE for the event. 00286 * @throws UnsupportedFilterableData if the event contents do not 00287 * match the filtering expression, for example, if the 00288 * expression for a filterable field expects a string, but the 00289 * actual value is a number. 00290 */ 00291 boolean match_typed ( 00292 in CosNotification::PropertySeq filterable_data ) 00293 raises (UnsupportedFilterableData); 00294 00295 /// Add a callback interface to the filter 00296 /** 00297 * Filters can communicate changes in the list of event types they 00298 * potentially accept. 00299 * 00300 * @param callback the object interested about changes in the 00301 * Filter event type list. 00302 * @return A unique ID attached to the callback interface. 00303 */ 00304 CallbackID attach_callback ( 00305 in CosNotifyComm::NotifySubscribe callback); 00306 00307 /// Remove a callback interface from the filter 00308 /** 00309 * @param callback The ID of the callback removed 00310 * 00311 * @throws CallbackNotFound if the callback id supplied is not 00312 * found in the internal list of callbacks. 00313 */ 00314 void detach_callback ( in CallbackID callback) 00315 raises ( CallbackNotFound ); 00316 00317 /// Return all the callback IDs in the Filter object 00318 CallbackIDSeq get_callbacks(); 00319 }; 00320 00321 /** 00322 * @interface MappingFilter 00323 * 00324 * @brief Mapping filters can be used to change properties of an 00325 * event as it traverses the Notification Service. 00326 */ 00327 interface MappingFilter { 00328 /// Return the constraint grammar used in the mapping filter 00329 readonly attribute string constraint_grammar; 00330 00331 /// Return the type code for the property affected by this mapping 00332 /// filter 00333 readonly attribute CORBA::TypeCode value_type; 00334 00335 /// Return the default value set by this mapping filter 00336 /** 00337 * The default value is used if there are no mapping constraint 00338 * expressions matching the event. 00339 */ 00340 readonly attribute any default_value; 00341 00342 /// Add multiple mapping constraints to the filter 00343 /** 00344 * @param pair_list List of constraint expressions and the 00345 * corresponding property value 00346 * 00347 * @return The list of constraint expressions, their values, and 00348 * the IDs assigned to them in this Filter. 00349 * 00350 * @throws InvalidConstraint if one or more constraint expressions 00351 * do not match the constraint grammar of this mapping filter 00352 * @throws InvalidValue if the value in one or more mapping 00353 * constraint pairs does not match the type code for this 00354 * mapping filter. 00355 */ 00356 MappingConstraintInfoSeq add_mapping_constraints ( 00357 in MappingConstraintPairSeq pair_list) 00358 raises (InvalidConstraint, InvalidValue); 00359 00360 /// Modify and/or remove mapping constraints in the filter 00361 /** 00362 * @param del_list list of constraint IDs that should be removed 00363 * @param modify_list list of constraints that would be modified 00364 * 00365 * @throws InvalidConstraint if one or more constraint expressions 00366 * do not match the constraint grammar of this mapping filter 00367 * @throws InvalidValue if the value in one or more mapping 00368 * constraint pairs does not match the type code for this 00369 * mapping filter. 00370 * @throws ConstraintNotFound if one or more mapping constraint 00371 * IDs are not found in the filter 00372 */ 00373 void modify_mapping_constraints ( 00374 in ConstraintIDSeq del_list, 00375 in MappingConstraintInfoSeq modify_list) 00376 raises (InvalidConstraint, InvalidValue, ConstraintNotFound); 00377 00378 /// Retrieve multiple mapping constraints from the filter 00379 /** 00380 * @param id_list the list of mapping constraint IDs requested 00381 * @return The list of constraint expressions, their values and 00382 * IDs. 00383 * @throws ConstraintNotFound if one or more mapping constraint 00384 * IDs are not found in the filter 00385 */ 00386 MappingConstraintInfoSeq get_mapping_constraints ( 00387 in ConstraintIDSeq id_list) 00388 raises (ConstraintNotFound); 00389 00390 /// Get all the mapping constraints from the Filter 00391 MappingConstraintInfoSeq get_all_mapping_constraints(); 00392 00393 /// Remove all the mapping constraints in the Filter 00394 void remove_all_mapping_constraints(); 00395 00396 /// Destroy the mapping filter 00397 void destroy(); 00398 00399 /// Test an event against the mapping constraints 00400 boolean match ( in any filterable_data, 00401 out any result_to_set ) 00402 raises (UnsupportedFilterableData); 00403 00404 boolean match_structured ( 00405 in CosNotification::StructuredEvent filterable_data, 00406 out any result_to_set) 00407 raises (UnsupportedFilterableData); 00408 00409 boolean match_typed ( 00410 in CosNotification::PropertySeq filterable_data, 00411 out any result_to_set) 00412 raises (UnsupportedFilterableData); 00413 }; 00414 00415 /** 00416 * @interface FilterFactory 00417 * 00418 * @brief Create Filter and MappingFilter objects 00419 */ 00420 interface FilterFactory { 00421 /// Create a new Filter object 00422 /** 00423 * @param constraint_grammar The name of the grammar used for this 00424 * filter 00425 * @throws InvalidGrammar The grammar name provided is invalid or 00426 * unsupported 00427 */ 00428 Filter create_filter (in string constraint_grammar) 00429 raises (InvalidGrammar); 00430 00431 /// Create a new MappingFilter object 00432 /** 00433 * @param constraint_grammar The name of the grammar used for this 00434 * filter 00435 * @param default_value The default property value used if no 00436 * mapping constraint matches 00437 * @throws InvalidGrammar The grammar name provided is invalid or 00438 * unsupported 00439 */ 00440 MappingFilter create_mapping_filter ( 00441 in string constraint_grammar, 00442 in any default_value) 00443 raises(InvalidGrammar); 00444 }; 00445 00446 /// Each filter is assigned a unique ID 00447 typedef long FilterID; 00448 00449 /// List of filter IDs 00450 typedef sequence<FilterID> FilterIDSeq; 00451 00452 /** 00453 * @exception FilterNotFound 00454 * 00455 * @brief Exception raised if a filter ID is not found. 00456 */ 00457 exception FilterNotFound {}; 00458 00459 /** 00460 * @interface FilterAdmin 00461 * 00462 * @brief Interface used to modify the Filters attached to a 00463 * Notification Service component 00464 */ 00465 interface FilterAdmin { 00466 /// Add a filter 00467 /** 00468 * @param new_filter Filter to be added 00469 * @return The ID assigned to the new filter 00470 */ 00471 FilterID add_filter ( in Filter new_filter ); 00472 00473 /// Remove a filter 00474 /** 00475 * @param filter ID of the filter to be removed 00476 * @throws FilterNotFound if the filter ID is not found in this 00477 * FilterAdmin 00478 */ 00479 void remove_filter ( in FilterID filter ) 00480 raises ( FilterNotFound ); 00481 00482 /// Get a filter 00483 /** 00484 * @param filter ID of the filter returned 00485 * @return The filter 00486 * @throws FilterNotFound if the filter ID is not found in this 00487 * FilterAdmin 00488 */ 00489 Filter get_filter ( in FilterID filter ) 00490 raises ( FilterNotFound ); 00491 00492 /// Get the IDs of all the filters 00493 /** 00494 * @return The list of all filter IDs in this component 00495 */ 00496 FilterIDSeq get_all_filters(); 00497 00498 /// Remove all the filters from this component 00499 void remove_all_filters(); 00500 }; 00501 }; 00502 00503 #pragma prefix "" 00504 00505 #endif /* _COS_NOTIFY_FILTER_IDL_ */
