SHAFT Tutorial

The API for SHAFT consists of the following classes:

• The Shaft class encapsulates an instance of the client. It exports public methods that can be used to make the client connect with a broker, send publications, subscriptions and unsubscriptions, make the broker open/close notification connections, accept notification connections and notifications from a broker.
• The ConnectInfo, PubInfo, SubInfo, UnsubInfo and NotInfo classes are used to pass arguments and return results to/from the public methods of Shaft. For example a ConnectInfo object is used to pass arguments to the public method of Shaft that opens a connection with the broker. Similarly a PubInfo object is used to pass arguments to the method that sends a publication to the broker and a NotInfo object is used to return the notification received from a broker and so on.

A Shaft object can be in three possible modes. In the client mode it is connected to a broker and capable of sending publications, subscriptions and unsubscription requests. It can also request the broker to open notification connections and receive notifications from a broker. In the server mode it encapsulates a server socket to which brokers can open notification connections. In the passive mode it is not connected to any broker and can either connect to a broker or accept a notification connections from a broker. A freshly created Shaft object is in passive mode. The following methods should be invoked on a passive Shaft object:

• int Connect(const ConnectInfo &connectInfo) - This opens a connection with a broker. The information about the IP address and port of the broker are contained in the argument. After a successful call to this method (denoted by a 0 return value) the Shaft object moves to client mode.
• bool Open(const ConnectInfo &connectInfo) - This opens a server socket for receiving notification connections from brokers. The port number and backlog of the socket are contained in the argument. After a successful call to this method  (denoted by a return value true) the Shaft object moves to server mode.
• bool AcceptNotConnect(Shaft &srvShaft) - This accepts a notification connection from a broker. The Shaft object passed as argument must be in server mode and the server socket to which the broker was attempting to connect must be encapsulated by it. After a successful call to this method (indicated by a true return value) the Shaft object moves to client mode.

The following methods should be invoked on a Shaft object in client mode:

• bool Publish(PubInfo &pubInfo) - This sends a publication to the broker with which the Shaft object is connected. The details of the publication are contained in the argument.
• bool Subscribe(SubInfo &subInfo) - This sends a subscription to the broker with which the Shaft object is connected. The details of the subscription are contained in the argument.
• bool Unsubscribe(UnsubInfo &unsubInfo) - This sends an unsubscription to the broker with which the Shaft object is connected. The details of the unsubscription are contained in the argument.
• int StartNotConnect(Shaft &srvShaft,Shaft &newShaft,const ConnectInfo &connectInfo) - This causes the broker to establish a notification connection. The first argument encapsulates a server socket with which the broker establishes the notification connection. The second argument contains a Shaft object that is connected to the broker by the notification connection. The third argument contains information about the IP address and port of the server socket encapsulated by the first argument.
• int StartNotConnect(const ConnectInfo &connectInfo) - This causes the broker to establish a notification connection with a server socket whose IP address and port are supplied through the argument. With the previous method the same thread can request the broker to open the notification connection and also accept the notification connection. With this method the request to open a notification connection and acceptance of the connection must be done by separate threads.
• int QueryNotConnect(const ConnectInfo &connectInfo) - This queries the broker as to whether a notification connection exists or not. The details of the connection are supplied through the argument.
• int CloseNotConnect(const ConnectInfo &connectInfo) - This requests the broker to terminate a notification connection. The details of the connection are supplied through the argument.
• bool GetNotification(NotInfo &notInfo) - This receives a notification from the broker. The notification received is returned in the argument.

The following methods should be invoked on a Shaft object in client or server mode:

• void Disconnect() - This closes any sockets - either a normal socket opened with the Connect or AcceptNotConnect method or a server socket opened with the Open method. On completion of a call to this method the Shaft object moves to passive mode.

The following methods can be invoked on any Shaft object:

• int GetStatus() const - This returns the current mode of the Shaft object.

The ConnectInfo class encapsulates a socket connection. It contains an IP address, a port number and a backlog (for server sockets). The following methods can be used to view and modify its data members:

• string GetIPAddress() const
• unsigned short GetPort() const
• int GetBacklog() const
• void SetIPAddress(const string i)
• void SetPort(const unsigned short p)
• void SetBacklog(const int b)

The PubInfo class encapsulates a publication to be sent to a broker. It contains three data members - the publication pub, the id to be assigned to the publication id and a flag indicating whether the broker should acknowledge the receipt of the publication ack . These data members can be viewed and modified by the following methods:

• string GetPub() const
• string GetId() const
• bool GetAck() const
• void SetPub(const string p)
• void SetId(const string i)
• void SetAck(const bool a)

The SubInfo class encapsulates a subscription to be sent to a broker. It contains six data members - the subscription sub, the id to be assigned to the subscription id, the IP address and port to which any notification for this subscription should be sent ipAddress and port, the number of seconds after which the subscription should expire validity , and a flag indicating whether the broker should acknowledge the receipt of the subscription ack. These data members can be viewed and modified by the following methods:

• string GetSub() const
• string GetId() const
• string GetIPAddress() const
• int GetPort() const
• unsigned long GetValidity() const
• bool GetAck() const
• void SetSub(const string s)
• void SetId(const string i)
• void SetIPAddress(const string i)
• void SetPort(const int p)
• void SetValidity(const unsigned int v)
• void SetAck(const bool a)

The UnsubInfo class encapsulates an unsubscription request to be sent to a broker. It contains two data members - the id of the subscription to be removed subId and a flag indicating whether the broker should acknowledge the receipt of the subscription ack. These data members can be viewed and modified by the following methods:

• void SetSubId(const string s)
• void SetAck(const bool a)
• string GetSubId() const
• bool GetAck() const

The NotInfo class encapsulates a notification received from a broker. It has two data members - the id of the subscription for which this is a notification subId and the publication which matched the subscription pub. These data members can be viewed and modified by the following methods:

• void SetSubId(const string s)
• void SetPub(const string p)
• string GetPub() const
• string GetSubId() const

A publication is just an alternating sequence of variables and constants separated by whitespace and beginning with a variable. A publication of the form "V1 C1 V2 C2 ... Vn Cn" where V1, V2, ..., Vn are variables and C1, C2, ..., Cn are constants assigns value Ci to variable Vi for i = 1,2, ..., n. For example the publication "name 'John Smith' age 30" assigns value 'John Smith' to the variable name and the value 30 to the variable age. The definition of a variable and a constant is the same as that for the BLADE query language described in the BLADE tutorial .

The following program demonstrates most of what has been described above. It depicts a client that opens a connection with a broker (that is assumed to be listening at IP address 100.100.100.100 and port 9999). The client itself is running on IP address 101.101.101.101. After connecting to the broker the client establishes a notification connection at port 10000. It then sends a subscription and a publication such that a notification will be generated. It receives the notification and closes the notification connection. Then it unsubscribes the subscription. Finally it disconnects from the broker and quits.

#include "Shaft.h"

Assuming that the program was saved to shaft.cpp it can be compiled on Linux as follows:

On Windows the compilation can be done as follows:

$ cl -DBLADE_OS_WIN32 shaft.cpp libshaft.lib libspear.lib -link -NODEFAULTLIB:LIBC.lib

If you wish to write a broker please read the BLADE and JBLADE tutorials.