|
Role(s):
Service Provider, Customer
Component(s):
Notification Provider
Infrastructure Sensor
License:
Apache 2.0
Usage Instructions
Installation
Software Installation
Notification Support Toolkit
API
The Notification
Provider toolkit is in charge of the distribution of topic based
events within the constraints of a Virtual Organisation (or another
form of collaboration). The notification support thereby allows for
multiplexing of messages, as well as aggregation of sources. It
supports both push and pull models to satisfy firewall constraints.
Topics can be easily registered and extended, and changes in
producers/subscribers are maintained in the collaborative scope.
Notifications can be sent to both Web Service based and Agent based
Consumers.
A set of topics are
defined which classify the different events that may occur in the
system. Consumers are subscribed to the topics they are interested
in, while publishers publish notifications belonging to different
topics.
The components included
in this toolkit are infrastructure components, as such they are
basically used by other components in order to send and receive
notifications. The Notification Provider manages the different
topics, and it associates these topics with their respective
publishers and consumers. In addition, the Notification Provider
routes the notifications from their producers to the final
consumers. This can be done directly if the consumer is a Web
Service (Notification WS Consumer), or through the Infrastructure
Sensor if the consumer is an agent (Agent Consumer). Next
figure presents a deployment diagram of the Notification Support toolkit
where its dependencies with other toolkits and components are
depicted. The different deployments of the Notification Provider can
communicate directly or through the Gateway component included in
the Messaging Infrastructure toolkit.
Notification Support Installation
Installation Requirements
·
All components require Linux OS
(the Notification Provider is also available for Mac OS), concretely
Ubuntu has been chosen as reference distribution (so this
distribution is recommended as base OS).
·
The Notification Provider requires
OpenSSL 0.97 or higher for security, libXML 2.4.0 or higher to parse
XML, unixODBC 2.2.0 or iODBC 3.0.0 or higher versions for databe
access, postgreSQL / mySql as database management system, and
gSOAP_2.7.12 as middleware for Web Services.
·
The Infrastructure Sensor requires
Java 1.5, WSIT as its Web Service implementation, Jade 3.5. as the
agent platform.
Deployment Tips
There are two
alternative deployment options for the Notification Support toolkit,
depending on which kind of traffic is allowed between the
Notification Provider and the Notification Consumers. If only HTTP
traffic is allowed, then the Notification Provider and the
Infrastructure Sensor should be installed in the same computer, in
this way the communication between the Notification Provider and the
Notification WS Consumer would rely on Web Services, and
communication between the Notification Provider and the
Infrastructure Sensor would rely on HTTP (since the HTTP MTP would
be used). If the communications are based only on Web Services (i.e.
SOAP traffic), then the Infrastructure Sensor should be deployed in
the Notification Customer side so all the communications between the
two sides will rely on Web Services. The final deployment should
consider the different security restrictions, concretely allowed
traffic, in order to select the most suitable option.
The fully distributed
deployment configuration of the toolkit, independently on where the
Infrastructure Sensor is allocated is shown in REF _Ref226869202 \h
Figure 17.
Deployment
Prerequisites:
1.All components are always necessary.
2.There are no grouping restrictions. Components
can be deployed together on a single machine as well as in different
machines which can be reachable through the internet.
3.Deployment on the same machine at the
Notification Provider is recommended if HTTP traffic is allowed with
the notification consumers.
4.Deployment on different machines (the
Notification Provider at the Notification Provider side, and the
Infrastructure Sensor at the Notification Consumer side) is
recommended if only Web Service traffic is allowed with the
notification consumers
Software Installation
The installer of this
toolkit can be any of the standard package managers included in an
Ubuntu distribution. In the REF _Ref2268687891 \h Figure 18
the Synaptic package manager is shown, with a search of all the
packages where the keyword 'BREIN' is included in the description.
The results of the search are all the Linux packages distributed
through the public repository of the BREIN project. The packages
related to the IS and NP components, as well as the one related to
the Notification Support toolkit, can be found in the repository,
they are the following:
NotificationSupport_2.0.i386.deb (Main package)
InfrastructureSensor_2.0_all.deb
InfrastructureSensorMTP_2.0_all.deb
NotificationProvider_1.0_i386.deb
In order to install the
toolkit, the 'NotificationSupport' package must be selected, then
marked to install, and finally the 'apply' action executed. This
will install all the components included in the toolkit. If just a
single component is going to be installed it just has to be selected
and market in the same way than the toolkit. These packages can be
market to be updated, removed or re-installed whenever it will be
necessary.
These directories are
explained in more detail in the following subsections.
Usage Instructions
Notification Provider with Infrastructure Sensor
Inside the toolkit the
Notification Provider and the Infrastructure Sensor must be deployed
together in order to have notifications, once deployed the different
publishers and consumers may be introduced into the scene.
The different
interactions and the data exchanged and needed them is explained
next.
Figure 22
presents the interactions performed internally between the
components of the Notification Support toolkit. Initially the
Infrastructure Sensor (IS) subscribes as consumer of all topics in a
concrete domain. From this moment, the Notification Provider sends
the Infrastructure Sensor all the notifications related with the
topics it subscribed to.
Notification Support Toolkit API
|
Method |
SubscribeResponse resp Subscribe(Subscribe
req) |
|
Arguments |
Subscribe req
-
A struct containing:
- Notification Consumer's address
- TopicExpression expressed in a specified Dialect
- An initial termination time for Subscription |
|
Return Value[s] |
SubscribeResponse resp
– A struct containing:
- Subscription ID |
|
Description |
Subscribe is sent by Subscriber. The message should
contain information about Notification Consumer and an
expression defining Topic or Topics that this
Subscription affects. If a message processing is
successful, Subscription is created. It is possible to
create many equal Subscriptions by sending numerously
the same SubscribeRequest message. Response message -
SubscribeResponse delivers Subscription ID. |
|
Method |
RenewResponse resp Renew(Renew req) |
|
Arguments |
Renew req
–
A struct containing:
- Subscription ID
- A new termination time for Subscription |
|
Return Value[s] |
RenewResponse resp
–
A struct containing:
- The termination time which was set by Notification
Broker
- Notification Broker's current time |
|
Description |
When Subscriber wants to renew
Subscription, it can send a RenewRequest message. A
message should contain Subscription ID and a new
termination time suggestion for Subscription. |
|
Method |
UnsubscribeResponse resp Unsubscribe(Unsubscribe
req) |
|
Arguments |
Unsubscribe
req – A struct containing:
- Subscription ID |
|
Return Value[s] |
UnsubscribeResponse
resp – A struct without a content |
|
Description |
When Subscriber wants to
terminate Subscription, it has to send an
UnsubscribeRequest message. This message has to contain
Subscription ID. |
|
Method |
RegisterPublisherResponse resp
RegisterPublisher(RegisterPublisher req) |
|
Arguments |
RegisterPublisher
req – A struct containing:
- An initial termination time for Publisher Registration |
|
Return Value[s] |
RegisterPublisherResponse
resp – A struct containing:
- Publisher Registration ID |
|
Description |
Before Publisher starts
sending Notifications, it has to register himself. It
sends a RegisterPublisherRequest message to Notification
Broker. At this time a registration process is
anonymous-style and no authorization is proceeded. At
the response to the successful Publisher's registration
process, Notification Broker sends
RegisterPublisherResponse with Registration ID. |
|
Method |
void Notify(Notify req) |
|
Arguments |
Notify
req – A struct containing:
- Publisher's Registration ID
- Notification message(s) consists of:
- TopicExpression defining single Topic
- Notification content |
|
Return Value[s] |
None |
|
Description |
Notify consists of one or many
NotificationMessages. Each of them is an individual
Notification message. NotificationMessage should define
single Topic that this message concerns. Publisher's
Registration ID has to be attached to Notify messages.
Notify is a one-way message. |
|
Method |
DestroyRegistrationResponse resp
DestroyRegistration(DestroyRegistration req) |
|
Arguments |
DestroyRegistration
req – A struct containing:
- Publisher's Registration ID |
|
Return Value[s] |
DestroyRegistrationResponse
resp – A struct without a content |
|
Description |
Publisher can terminate
Registration by sending a DestroyRegistrationRequest
message to Notification Broker. The parameter attached
to this request is Publisher's Registration ID. |
|
Method |
GetCurrentMessageResponse resp
GetCurrentMessage(GetCurrentMessage req) |
|
Arguments |
GetCurrentMessage
req – A struct containing:
- TopicExpression defining single Topic |
|
Return Value[s] |
DestroyRegistrationResponse
resp – A struct containing:
- Notification content |
|
Description |
GetCurrentMessage
is a kind of expansion of the
standard Notification concept and it is sending when
object wants to receive NotificationMessage besides a
publicizing procedure. It is useful for example when new
NotificationConsumer is connecting and wants to get the
last published NotificationMessage. Single
GetCurrentMessage
should refer exactly one Topic. In a response to
GetCurrentMessageRequest
Notification Broker prepares
GetCurrentMessageResponse.
This message includes content of the last Notification
that
GetCurrentMessageRequest
refers to |
The
application programming interface that the Sensor provides to an
Agent is described in the following tables:
Notification Agent Interface
|
Method |
boolean ack notify(Notify notification,
int sequenceID) |
|
Arguments |
Notify notification –
A notify object containing notification's topic,
message and publisher identifier |
|
int sequenceID –
An integer that represents the number of notifications
received before the current by this Agent |
|
Return Value[s] |
boolean ack
– true if the reception of the notification in the Agent
is alright, else false |
|
Description |
Through this method an Agent receives a notification
with its sequence number, the return value tells if the
reception in the Agent has succeed |
Notification Helper Interface
|
Method |
int subscriptionID subscribeToConsumer(String
aid, String topic) |
|
Arguments |
String aid – Agent Identifier string |
|
String topic – Topic expression string |
|
Return Value[s] |
int subscriptionID – Subscription identifier
integer |
|
Description |
This method lets an Agent to be subscribed to a desired
topic, the return value identifies the subscription |
|
Method |
void unSubscribeToConsumer(int subscriptionID) |
|
Arguments |
int subscriptionID -
Subscription identifier integer |
|
Return Value[s] |
None |
|
Description |
Method that
unsubscribes an Agent from the subscription identifier |
|
Method |
List subscriptions getCurrentSubscriptions(String
aid) |
|
Arguments |
String aid – Agent Identifier string |
|
Return Value[s] |
List subscriptions – A list containing all the
subscription identifiers for the Agent |
|
Description |
This method gets a list of the current subscriptions of
an Agent |
|
Method |
List notifications getLostNotifications(String
topic, int lastSequenceID) |
|
Arguments |
String topic – Topic expression string |
|
|
int lastSequenceID – Sequence identifier integer
that represents the last notification received about
this topic |
|
Return Value[s] |
List notifications – A list of notifications that
begins with the notification with sequence identifier
greater than the last sequence identifier received as
input |
|
Description |
Returns a list of lost notifications |
|
