siena.h

发布/订阅系统中间件

// -*- C++ -*-
//
//  This file is part of Siena, a wide-area event notification system.
//  See http://www.cs.colorado.edu/serl/dot/siena.html
//
//  Author: Antonio Carzaniga <[e-mail]>
//  See the file AUTHORS for full details. 
//
//  Copyright (C) 1998-1999 University of Colorado
//
//  This program is free software; you can redistribute it and/or
//  modify it under the terms of the GNU General Public License
//  as published by the Free Software Foundation; either version 2
//  of the License, or (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
//  USA, or send email to [e-mail].
//
//
// $Id: Siena.h,v 1.2 2002/11/22 17:52:34 carzanig Exp $
// 
#ifndef _Siena_h
#define _Siena_h

#include <iostream>
#include <string>
#include <map>
#include <list>
#include <exception>

using namespace std;

#ifdef HAVE_CXX_NAMESPACE
namespace Siena {
#endif

class Siena;
class Notifiable;
class Request;
class AttributeValue;
class Event;
class AttributeConstraint;
class Filter;
class Pattern;

/** @memo Interface of the event service.
    @author <a href="mailto:[e-mail]">Antonio Carzaniga</a>
    @version 3.1415
    @see SimpleSiena
    @doc
    A <code>Siena</code> object represents the access point to the
    <em>Siena</em> event service. Clients can publish and subscribe
    by calling the corresponding methods on a <code>Siena</code>
    object. 
    <p>
    <i>Example</i>:
    <pre>
    Siena * S = new SimpleSiena();

    Event e;

    e["price"] = 500;
    e["airline"] = "UA";
    e["dest"] = "MXP";

    S->publish(e);
    </pre>
*/
class Siena {
 public:
    /** @memo Version identifier for the Siena interface */ 
    static const char * Version;

    /** @memo publish an event
	@param e event to be published
	@exception SienaException
	@doc 
	injects event <code>e</code> into the event service. 
	A copy of <code>e</code> will be delivered to all those 
	interested parties that subscribed for matching filters. 
	<p>
	<i>Example</i>:
	<pre>
	Siena * S;
	// ...
        Event e;
	
	e["price"] = 500;
	e["airline"] = "UA";
	e["dest"] = "MXP";
	
	S->publish(e);
	</pre>
    */
    virtual void	publish(const Event &e)				= 0;
    /** @memo subscribes for a given <em>filter</em>.
	@see unsubscribe
	@param f filter that matches events of interest
	@param n subscriber
	@exception SienaException
	@doc
	subscribes for a given <em>filter</em>.  interested party
	<code>n</code> will receive notifications matching filter
	<code>f</code>. 
	<p>
	<i>Example</i>:
	<pre>
	Siena * S;
	Notifiable * n;
	// ...
	Filter f;
	f.add_constraint("price", Siena_lt, 700); 
	f.add_constraint("dest", Siena_eq, "MXP"); 
	
	S->subscribe(f,n);
	</pre>
    */
    virtual void	subscribe(const Filter &f, Notifiable *n)	= 0;
    /** @memo subscribes for a given <em>pattern</em>.
	@see unsubscribe
	@param p pattern of sequences of events of interest
	@param n subscriber */
    virtual void	subscribe(const Pattern &p, Notifiable *n)	= 0;
    /** @memo cancels previous subcriptions.
	@param f expresses filters to be cancelled
	@param n subscriber
	@see subscribe
	@doc
	cancel all previous subscriptions from interested party
	<code>n</code> with a filter <em>g</em> that is <em>covered</em>
	by filter <code>f</code>.
	<p>
	<i>Example</i>:
	<pre>
	Siena * S;
	Notifiable * n;
	// ...
	Filter f;
	
	f.add_constraint("dest", Siena_xx, 0);
	
	S->unsubscribe(f,n);
	</pre>

	Note that a filter [dest <i>any</i>] covers the filter of the
	previous example [price &lt; 700, dest == "MXP"] */
    virtual void	unsubscribe(const Filter &f, Notifiable *n)	= 0;
    /** @memo cancels previous subcriptions.
	@param p expresses patterns to be cancelled
	@param n subscriber

	@doc
	cancel all previous subscriptions from interested party
	<code>n</code> with a pattern <em>q</em> that is <em>covered</em>
	by pattern <code>p</code>.
    */
    virtual void	unsubscribe(const Pattern &p, Notifiable *n)	= 0;

    /** @memo announces the intention to notify a class of events
	@doc
	<b>not yet implemented!</b>
    */
    virtual void	advertise(const Filter &f)			= 0;
    /** @memo cancels previous advertisements
	@doc
	<b>not yet implemented!</b>
    */
    virtual void	unadvertise(const Filter &)			= 0;

    /** @memo cancels all previous subcriptions from a given subscriber.
	@param n subscriber
	@doc
	cancel all previous subscriptions from interested party
	<code>n</code>.
    */
    virtual void	disconnect(Notifiable *)			= 0;

    /** @memo temporarily suspend the delivery of notifications 
	to a given subscriber.
	@param n subscriber 
	@doc
	<b>not yet implemented!</b>
    */
    virtual void	suspend(Notifiable *n)				= 0;
    /** @memo resume the delivery of notifications to a previously suspended subscriber.
	@param n subscriber 
	@doc
	<b>not yet implemented!</b>
    */
    virtual void	resume(Notifiable *)				= 0;
};

/** @memo Interested party
    @doc 

    A <code>Notifiable</code> represents an event consumer.  Events
    are delivered to a <code>Notifiable</code> by calling their
    <code>notify</code> method.  A <code>Notifiable</code> must
    specialize <code>notify</code> to implement its specific response
    to event notifications.
    <i>Example</i>:
    <pre>
    class Ticker : public Notifiable {
    virtual void notify(Event &e) { cout << e["price"].int_value() << endl; };
    }
    // ...
    Filter f;
    Ticker t;
    f.add_constraint("price", Siena_lt, 500);
    S->subscribe(f, t);
    // ...
    </pre>
*/
class Notifiable {
 public:
    /** @memo response to a notification
	@param e notified event
	@doc
	The event service calls this method to notify the interested
	party. The interested party specializes this method to
	implement its response to the event notification.
    */
    virtual void	notify(Event &e)				= 0;
};

/** @memo Type identifier for <em>Siena</em>
    @doc
    <em>Siena</em> has some of the most common data
    types. <code>SienaType</code> enumerates the available types in
    <em>Siena</em>.
    <p>
    <i>Example</i>:
    <pre>
    Event e;
    // ...
    SienaType t;
    t = e["quantity"].type();
    switch(t) {
    case Siena_integer: 
    // ...
    case Siena_string:
    // ...
    }
    </pre>
*/
enum SienaType {
//
// It might
// be better to program this as a class. This class would implement
// part of the ``matching'' functions as (possibly polymorphic)
// methods. The textual description would also be included in the
// ``type'' class.
//
// ...design choice...
// 

    /** undefined null type */
    Siena_null		= 0,
    /** string */
    Siena_string	= 1,
    /** signed integer number  */
    Siena_integer	= 2,
    /** boolean value */
    Siena_bool		= 3,
    /** time/date (<b><em>not yet implemented!</em></b>) */
    Siena_date		= 4,
    /** floating point number */
    Siena_double 	= 5,
    /** binary object (<b><em>not yet implemented!</em></b>) */
    Siena_binary	= 6
};

/** @memo Textual representation of <em>Siena</em> types identifiers 
    @doc
    strings representing type identifiers. Its values are
    <code>null</code>, <code>string</code>, <code>integer</code>,
    <code>boolean</code>, <code>data</code>, <code>float</code>, and
    <code>binary</code>. The mappings are obvious with respect to the
    values of <code>SienaType</code>, for example
    <code>SienaTypeDescription[Siena_bool] == "boolean"</code>.  */
extern const string	SienaTypeDescription[];

/** @memo value of an attribute in a notification
    @see Event SienaType

    @doc
    An <code>AttributeValue</code> stores the value of an
    attribute. Attributes can be of a pre-defined set of types
    (SienaType).  <code>AttributeValue</code> provides methods for
    accessing and assigning values in the form of C++ types.  In
    particular, an <code>AttributeValue</code> of type
    <code>Siena_integer</code> can be assigned to and from an
    <code>int</code>, an <code>AttributeValue</code> of type
    <code>Siena_string</code> can be assigned to and from a C++
    standard <code>string</code>, etc. 
    <p>

    <i>Example</i>:
    <pre>
    AttributeValue x, y;
    //
    // now x.type() == y.type() == Siena_null
    //
    x = true;
    y = x;
    //
    // now x.type() == y.type() == Siena_bool
    //
    int i = 10;
    if (x.bool_value()) y = i + 10;
    x = i + 20;
    cout &lt;&lt; x.int_value() + y.int_value() &lt;&lt; endl;
    i = x;
    y = "ciao";
    cout &lt;&lt; y.string_value() &lt;&lt; endl;
    </pre>
*/
class AttributeValue {
 public:
    
    /**@name Constructors */
    //@{
    /** <em>null</em> value */
			AttributeValue();
    /** copy constructor */
			AttributeValue(const AttributeValue &v);
    /** construct from a string */
			AttributeValue(const string &);
    /** construct from a C-style string */
			AttributeValue(const char *);
    /** construct from an <code>int</code> */
			AttributeValue(int);
    /** construct from a <code>bool</code> */
			AttributeValue(bool);
    /** construct from a <code>double</code> */
			AttributeValue(double);
    //@}
    //
    // more constructors here with the specific types
    // ... work in progress ... 
    //
		~AttributeValue();
    /**@name Access functions */
    //@{
    /** returns the actual type of this value */
    SienaType		type()					const;

    /** @memo returns a reference to the value as an integer
	@exception BadType exception is generated when
	           <code>type() != Siena_integer</code> 
	@doc 

	returns a reference to the value as an integer
	<p>
	<i>Example</i>:
	<pre>
	AttributeValue x = 20;
	cout << x.int_value();
	x.int_value()++;
	cout << x.int_value();
	</pre>
    */
    int	&		int_value();

    /** @memo returns a reference to the value as a boolean 
	@doc returns a reference to the value as a boolean 
	@exception BadType exception is generated when
	           <code>type() != Siena_bool</code> */
    bool &		bool_value();

    /** @memo returns a reference to the value as a string 
	@exception BadType exception is generated when
	           <code>type() != Siena_string</code>
		   
        @doc 
	returns a reference to the value as a string 
	<p>
	<i>Example</i>:
	<pre>
	AttributeValue x = "ciao";
	cout << x.string_value();
	x.string_value() += " ciao";
	cout << x.string_value();
	</pre>
    */
    string &		string_value();

    /** @memo returns a reference to the value as a double 
	@doc returns a reference to the value as a double 
	@exception BadType exception is generated when
	           <code>type() != Siena_double</code> */
    double &		double_value();
    /** @memo returns a reference to the value as an integer
	@doc returns a reference to the value as an integer
	@exception BadType exception is generated when
	           <code>type() != Siena_integer</code> */
    const int &		int_value()				const;
    /** @memo returns a copy of the value as a boolean 
	@doc returns a copy of the value as a boolean 
        @exception BadType exception is generated when
	           <code>type() != Siena_bool</code>  */
    const bool &	bool_value()				const;
    /** @memo returns a copy of the value as a boolean 
	@doc returns a copy of the value as a boolean 
        @exception BadType exception is generated when
	           <code>type() != Siena_bool</code>  */
    const string &	string_value()				const;
    /** @memo returns a copy of the value as a boolean 
	@doc returns a copy of the value as a boolean 
        @exception BadType exception is generated when
	           <code>type() != Siena_bool</code>  */
    const double &	double_value()				const;

    /** @memo conversion operator to <code>int</code>
        @exception BadType exception is generated when
	           <code>type() != Siena_int</code> 

	@doc 

	returns a copy of the value as an integer whenever the
	<code>AttributeValue</code> is used in place of an