siena.h

发布/订阅系统中间件

	<code>int</code>. 
	<p>
	<i>Example</i>:
	<pre>
	AttributeValue x = 20;
	int i = x;
	</pre>
    */
			operator int ()				const;
    /** @memo conversion operator to <code>int</code>
        @exception BadType exception is generated when
	           <code>type() != Siena_string</code> 

	@doc 

	returns a copy of the value as a boolean whenever the
	<code>AttributeValue</code> is used in place of an
	<code>int</code>. 
	<p>
	<i>Example</i>:
	<pre>
	AttributeValue x = "Siena";
	string s = x;
	</pre>
    */
			operator string ()			const;
    /** @memo conversion operator to <code>bool</code>
        @exception BadType exception is generated when
	           <code>type() != Siena_bool</code> 

	@doc conversion operator to <code>bool</code>
    */
			operator bool ()			const;
    /** @memo conversion operator to <code>double</code>
        @exception BadType exception is generated when
	           <code>type() != Siena_double</code> 

	@doc conversion operator to <code>double</code>
    */
			operator double ()			const;
    //@}
    //
    // to be continued with other types ...
    //
    // usual operators implementing some or all of the operators defined
    // by the event service (subscription language)
    //
    /**@name Assignment operators */
    //@{
    /** copy */
    AttributeValue &	operator = (const AttributeValue &);
    /** from string */
    AttributeValue &	operator = (const string &);
    /** from C-style string */
    AttributeValue &	operator = (const char *);
    /** from int */
    AttributeValue &	operator = (int);
    /** from bool */
    AttributeValue &	operator = (bool);
    /** from double */
    AttributeValue &	operator = (double);
    //@}

    bool		operator == (const AttributeValue &)	const;
    bool		operator < (const AttributeValue &)	const;

 protected:
    SienaType		_type;
    union {
	string *	str;
	int		num;
	bool		bln;
	double		dbl;
	//
	// to be completed with all the `physical' representation of the
	// various data types defined by the event service, e.g.:
	// Date *	date;
	// ... work in progress ... 
	//
    };
};

//
// primitive representation of a notification and of a Siena
//
typedef map<string, AttributeValue> AttributeSet;

/** @memo service parameters for a Siena request
    @doc

    A <code>Request</code> serves as a specification of service
    parameters for subscriptions, publications etc.  Just like an
    <code>Event</code>, it is implemented as a set of named attributes
    (a standard C++ <code>map</code>). <p>

    <em>Siena</em> uses some well-known attributes from a
    <code>Request</code>. See SENP. */
class Request: public AttributeSet {
    //
    // this might include specific methods to set well-defined
    // parameters (such as priority, encryption, etc.). This stuff is
    // still future work. ...work in progress...
    //
};

/** @memo event notification
    @see AttributeSet
    @doc

    A notification in <em>Siena</em> is a set of named attributes.
    <code>Event</code> represents an event notification. Attribute
    <em>names</em> are standard C++ <code>string</code>s while
    attribute <em>values</em> are <code>AttributeValue</code>s. A
    <em>name</em> uniquely identifies an attribute in an
    <code>Event</code>.
    <p>

    An <code>Event</code> is implemented as a <code>map&lt;string,
    AttributeValue&gt;</code>, therefore All the functions of the
    standard <code>map</code> template can be used to manipulate an
    <code>Event</code>. For instance:
    
    <pre>
    Event e;
    // ...
    // prints out attribute names of e
    //
    for(Event::iterator i = e.begin(); i != e.end(); ++i) cout &lt;&lt; (*i).first;
    </pre>

    Of course, every operation on an <code>Event</code> can take
    advantage of the access functions and assignment operators of
    <code>AttributeValue</code>.

    <pre>
    Event e;

    e["stock"] = "XYZ";
    e["price"] = 12.34
    e["quantity"] = 567;

    int q = e["quantity"];
    </pre>

    The structure of names and types of an <code>Event</code> is
    completely arbitrary for <em>Siena</em>. In other words,
    <em>Siena</em> does not require any pre-defined attribute. It is
    up to applications to agree on sets of names, types, and semantics
    of attributes. */
class Event : public AttributeSet {
 public:
			Event();
			Event(const Event &);
};

/** @memo operator identifier for <em>Siena</em>

    @doc

    <em>Siena</em> defines some of the most common operators (or
    binary relations). <code>SienaOperator</code> is the type of
    operator identifiers.
*/
enum SienaOperator {
    /** equals */ 
    Siena_eq		= 1, 
    /** suffix
	@doc
	<em>x</em> <code>Siena_sf</code> <em>y</em> is true if <em>y</em> is a
	suffix of <em>x</em>.  For example, <code>"software" Siena_sf "ware" ==
	true</code>, while <code>"software" Siena_sf "w" ==
	false</code>. <code>Siena_sf</code> is defined for strings
	only. */
    Siena_sf		= 2,
    /** @memo prefix
	@doc prefix.
	<em>x</em> <code>Siena_pf</code> <em>y</em> is true if <em>y</em> is
	a prefix of <em>x</em>.  For example, <code>"software" Siena_pf
	"soft" == true</code>, while <code>"software" Siena_pf "of"
	== false</code>. <code>Siena_pf</code> is defined for strings
	only. */
    Siena_pf		= 3,
    /** @memo less than.
	@doc less than.
	Integers and doubles are ordered as usual, strings are sorted
	in lexicographical order. For booleans, <code>false</code>
	&lt; <code>true</code>.  */
    Siena_lt		= 4, 
    /** greater than */
    Siena_gt		= 5, 
    /** less or equal */
    Siena_le		= 6, 
    /** greater or equal */
    Siena_ge		= 7, 
    /** @memo <em>any</em> (don't care)
	@doc <em>any</em> (don't care) always <code>true</code>.
     */
    Siena_xx		= 8, 
    /** not equal */
    Siena_ne		= 9, 
    /** @memo contains substring
	@doc contains substring.
	<em>x</em> <code>Siena_ss</code> <em>y</em> is true if <em>y</em> is
	a substring of <em>x</em>.  For example, <code>"software"
	Siena_ss "war" == true</code>, while <code>"software"
	Siena_ss "hard" == false</code>. <code>Siena_ss</code> is
	defined for strings only. */
    Siena_ss		= 10 
};

extern const string	SienaOperatorDescription[];

/** @memo semantics of Siena operators: applies an operator to two values.

    @doc
    Applies an operator to two values.
    Note that Siena operators are all binary relations.
    Operands are applied in the given order, so
    <code>apply_operator(op, x, y)</code> evaluates <em>x op y</em>. For example:
    <code>apply_operator(Siena_lt, x, y)</code> corresponds to <em>x &lt; y</em>
    <p>

    This function implements some minimal type-conversion (or type
    compatibility). In practice, integers are always compatible to
    doubles.  The result in case of incompatible types does not depend
    on the actual values of <code>x</code> and <code>y</code>.
    Specifically, it is always <code>true</code> if <code>op ==
    Siena_xx</code> (don't care) or <code>op == Siena_ne</code> (not
    equal). Otherwise it's <code>false</code>. 

    Note also that some operators (relations) are defined over a
    limited set of types. In particular <code>Siena_pf</code>,
    <code>Siena_sf</code>, and <code>Siena_ss</code> are defined for
    strings (<code>Siena_string</code>) operators only.
 */
extern bool		apply_operator(SienaOperator op, 
				       const AttributeValue & x, 
				       const AttributeValue & y);

/** @memo attribute constraint
    @see AttributeValue
    @doc
    An <code>AttributeConstraint</code> represents a condition posed on
    an attribute value. It stores an operator plus a comparison value.  */
class AttributeConstraint: public AttributeValue {
 public:
    /** the constraint operator */
    SienaOperator	op;

    /** @memo default constructor

	@doc <code>op</code> defaults to <code>Siena_eq</code>, the
	comparison value is <em>null</em>. */
			AttributeConstraint();
    /** @memo construct from an <code>AttributeValue</code>
	@param v initializes the comparison value
	@doc <code>op</code> defaults to <code>Siena_eq</code>, the
	comparison value is initialized with <code>v</code>. 
    */
			AttributeConstraint(const AttributeValue & v);

    /** @memo construct from an <code>AttributeValue</code> and 
	a <code>SienaOperator</code>
	@param v initializes the comparison value
	@param o initializes the operator <code>op</code>
    */
			AttributeConstraint(const AttributeValue & v, 
					    SienaOperator o);
    /** copy constructor */
			AttributeConstraint(const AttributeConstraint & c);

    /** copy assignment */
    AttributeConstraint &	operator = (const AttributeConstraint & c);
    /** @memo assignment from an <code>AttributeValue</code> 
	@param v comparison value
	@doc assigns the comparison value using <code>Siena_eq</code>
	as the comparison operator */

    AttributeConstraint &	operator = (const AttributeValue & v);
    bool		operator == (const AttributeConstraint & c) const;

    /** @memo applies <code>this</code> constraint to an attribute value
	@param v value to verify against <code>this</code> constraint
	@doc applies <code>this</code> constraint to an attribute value
    */

    bool		apply_to(const AttributeValue & v);
};


/** @memo primitive representation of a filter */
typedef multimap<string, AttributeConstraint> ConstraintSet;

/** @memo expression filtering notifications
    @see AttributeConstraint
    @doc  

    A <code>Filter</code> represents a boolean expression to be
    evaluated against an <code>Event</code>. It consists of a set of
    constraints. Each constraint poses a condition on an attribute of
    the <code>Event</code>. A <code>Filter</code> can pose multiple
    constraints on the same attribute.
    <p>

    A <code>Filter</code> is implemented by means of a
    <code>multimap&lt;string, AttributeConstraint&gt;</code>,
    therefore a <code>Filter</code> can be manipulated using all the
    methods of a standard <code>multimap</code>. Two additional
    utility methods are provided to add constraints.  
*/
class Filter : public ConstraintSet {
 public:
			Filter();
			Filter(const Filter &);

			Filter &		reduce();

    Filter &		operator = (const Filter &);
    bool		operator == (const Filter &)		const;

    /** @memo adds a constraint to the <code>Filter</code> */
    iterator		add_constraint(const string &, 
				       SienaOperator, const AttributeValue &);

    /** @memo adds a constraint to the <code>Filter</code> */
    iterator		add_constraint(const string &, 
				       const AttributeConstraint &);
};

/** expression of filters matching a sequence of notifications 
    (<b>not yet implemented!</b>). */
class Pattern: public list<Filter> {
//
// a Pattern is simply a list of (event) filters. This might be
// changed in the future, requiring a more complex data structure
//
 public:
			Pattern();
			Pattern(const Pattern &);
};

/** generic exception */
class SienaException: public exception {
    /** C-style string representation of what went wrong */
    virtual const char *	what() const throw();
public:
    virtual ~SienaException() throw() {};
};

/** exception: service unavailable */
class ServiceUnavailable: public exception {
    /** C-style string representation of what went wrong */
    virtual const char *	what() const throw();
public:
    virtual ~ServiceUnavailable() throw() {};
};

/** model exception */
class EventModelException: public SienaException {
    /** C-style string representation of what went wrong */
    virtual const char *	what() const throw();
public:
    virtual ~EventModelException() throw() {};
};

/** exception: attribute type mismatch */
class BadType: public EventModelException {
public:
    virtual ~BadType() throw() {};
 public:
    /** wrong type */
    SienaType			type;

				BadType(SienaType);

    /** C-style string representation of what went wrong */
    virtual const char *	what() const throw();
    virtual ostream &		printout(ostream &)		const;
};

/** exception operator mismatch */
class BadOperator: virtual public EventModelException {
public:
    virtual ~BadOperator() throw() {};
public:
    /** wrong operator */
    SienaOperator		op;

				BadOperator(SienaOperator); 

    /** C-style string representation of what went wrong */
    virtual const char *	what() const throw();
    virtual ostream &		printout(ostream &)		const;
};

/** exception: false filter (defines an empty set of events) */
class NullFilter: virtual public EventModelException {
public:
    virtual ~NullFilter() throw() {};
public:
    /** attribute name */
    string			name;
    /** conflicting constraint */
    AttributeConstraint		af1;
    /** conflicting constraint */
    AttributeConstraint		af2;

				NullFilter(const AttributeConstraint &,
					   const AttributeConstraint &);
				NullFilter(const string &,
					   const AttributeConstraint &,
					   const AttributeConstraint &);
    /** C-style string representation of what went wrong */
    virtual const char *	what() const throw();
    virtual ostream &		printout(ostream &)		const;
};

#ifndef NO_INLINE
#include <siena/Siena.icc>
#endif

#ifdef HAVE_CXX_NAMESPACE
};
#endif

#endif