PSYC - Protocol for Synchronous Conferencing - Usage of the library.

Introduction - What is PSYC?

PSYC - The Protocol for Synchronous Conferencing - is a messaging protocol and can be used to message objects regardless of their physical location.

Especially the abstraction of the physical location is very helpful in the case of objects representing humans or distributed agents.

Using the library described through small examples

What is needed to contact an object via PSYC?

To contact an object via PSYC the object or its runtime environment - of course - needs to support the PSYC protocol. This will be done by instantiating an object of the class PSYCMessageCenter...
See constructor index of PSYCMessageCenter to find out how to do that.

Note: using a PSYCPacketManager to get all information is the "low level way" to communicate with the message center. In our examples we'll use an easier way.

Example: creating a PSYCMessageCenter that tries to listen at the PSYC well known port and if this fails, tries to listen at some random ports:

	PSYCMessageCenter center = new PSYCMessageCenter(null, true);

Now the runtime environment can be contacted via PSYC.

Note: at this moment, our object will get no information about received messages from the message center (it could send some using a "low level way" by using the PSYCMessageCenter API, but this will be not enough... normally).

How to tell the PSYCMessageCenter what informations we are interested to receive

To tell the PSYCMessageCenter what kind of information we want to get, we have to install so called packages in the PSYCMessageCenter environment. Packages provide a high level interface to subsections of the PSYC protocol. The API of every package can be different - only the way it communicates with the PSYCMessageCenter will be the same for every package.

Packages are installed within the PSYCMessageCenter environment by using the addPackage method by the PSYCMessageCenter.

Example: Making our PSYC environment able to react on "PING" requests:

	Echo echo; center.addPackage(echo = new Echo());

The Echo package provides a simple way to include it, acting self-sufficient. In this case it simply answers every incoming "ping" request by sending a "pong".

The Echo package also provides a more "intelligent" way to communicate with it: It accepts an EchoListener as constructor-parameter. This EchoListener is called every time the Echo package receives information about "ping"s and "pong"s. In this case, the EchoListener has to do the appropriate action (for example if it receives a "ping" request: sending a "pong" back).

To act as EchoListener, the application has to implement two interface methods echoPing and echoPong... see the EchoListener API documentation for details. These methods are called by the Echo package, if it receives the specific information.

The Echo package also provides a high level way to send "ping"s and "pong"s to peers. See the Echo API documentation for details.

There are some other packages acting similar to the Echo package, which are implementing some other basic parts of the PSYC protocol, for example the Trace and the Statistics package.

More complex packages

There are some other - a bit more complex - packages which cannot be installed "thumb", which cannot act self-sufficient. Examples are:

The Authentication package and its complement - the AuthenticationServer package. These packages provide a way to authenticate objects. An AuthenticationListener must be able to return an authentication password if requested and to deal with the fact that the password was invalid. An AuthenticationServerListener must be able to deal with the fact that someone sends an password to it. See the API documentation for Authentication, AuthenticationServer, AuthenticationLister and AuthenticationServerListener for details.
The LinkPeer package and its complement - the LinkServer package. These packages provide a way to "connect" one object to another for example to show dependancies between them. An UserListener must be able to deal with the information, that the object is connected to another and that it's disconnected from the other object. An UserServerListener must be able to deal with connection requests by other objects and with the fact, that an object gots disconnected. See the API documentation for User, UserServer, UserListener and UserServerListener for details.
The Notification package and its complement - the NotificationServer package. These packages provide a way to request a notification by an object, if - for example - there will be an user agent of this object. See the API documentation for Notification, NotificationServer, NotificationListener and NotificationServerListener for examples.

Implementing own packages

Because there are - at least at the moment - not so many packages and/or because some usage of PSYC will be very specific, it could be needed to implement own packages.

Packages are communicating to the PSYCMessageCenter via an interface specified in PSYCPackage. They implement methods to tell the PSYCMessageCenter what information they want and to get informed by the PSYCMessageCenter about received informations.

They are sending raw PSYC Messages via the methods provided by the PSYCMessageCenter. For example: assignVariable, augmentVariable and diminishVariable to assign, augment or diminish the specified variable for the specified target, send and sendChecked to send a message to the specified target - possibly only if the target supports them (sendChecked) and if wanted with a Hashtable of temporarily variables especially for that message.

They should have an API that allows high level Access to the functionalty they are supporting.

Generally...

Of course, every object is able to send raw PSYC messages to a target like modules do that, but this should be the not the normal way. PSYCDeliver.java does that for example, because it's only work to do is to send exactly one (user defined) PSYC message to exactly one target and it has not to wait for any reply.

[API-Documentation]