CASSIUS 1.9 Motivations, Installation, and Usage

TOC

1. Installation
2. Terminology Used
3. Understanding a CASS Awareness Environment
4. Instrumenting Information Sources
   1. FileMonitor sample program
   2. CassDAV the CASSIUS enabled WebDAV Server
5. Awareness Tools
   1. Sample Tools
   2. Using CASSandra Toolkit
   3. Modifying CASSandra Toolkit/Implementing your own Toolkit
   4. Building Awareness Tools Without CASSandra
6. Sample Perl Code
7. Full API
8. Utilities
9. Bugs

Installation

Install Tomcat Servlet Engine

Once it has been decompressed, there are two techniques by which Tomcat 4.0 can be started:

* Via an environment variable:
  - Set an environment variable CATALINA_HOME to the path of the directory
    into which you have installed Tomcat 4.0.
  - Execute the shell command:

      %CATALINA_HOME%\bin\startup             (Windows)

      $CATALINA_HOME/bin/startup.sh           (Unix)

* By modifying your current working directory:
  - Execute the following shell commands:

      cd %CATALINA_HOME%\bin                  (Windows)
      startup                                 (Windows)

      cd $CATALINA_HOME/bin                   (Unix)
      ./startup.sh                            (Unix)

After startup, the default web applications included with Tomcat 4.0 will be
available by browsing:

    http://localhost:8080/

Further information about configuring and running Tomcat 4.0 can be found in
the documentation included here, as well as on the Tomcat web site:

    http://jakarta.apache.org/tomcat/

Downlaod and Install mysql

Once it has been decompressed, follow the steps in INSTALL-BINARY to install it.

If you have difficulty getting permission for your non root user account to access all of the databases, try a command like this executed as root:

mysql -e "grant all privileges on * to mkantor@localhost"

Download the source code

Downloading the Java Servlet version of the CASSIUS server will downlaod the file cass.tar.gz. Move this file to your tomcat server's webapps directory, decompress and untar it. The directory "cassius" should be created, containing a properly configured servlet.

> tar -xzf cass.tar.gz

#!/bin/sh
CATALINA_HOME=/usr/local/jakarta-tomcat-4.0.4
export JAVA_HOME=/Library/Java/Home
$CATALINA_HOME/bin/startup.sh

> cd cassius/WEB-INF

> [path-to-mysql-bin]/mysqladmin create CASS
> [path-to-mysql-bin]/mysqladmin create TESTCASS

> [path-to-mysql-bin]/mysql -D CASS < InitializeGlobalTables
> [path-to-mysql-bin]/mysql -D TESTCASS < InitializeGlobalTables

Simple Test

http://localhost:8080/cassius/cass?Operation=Register&GlobalPassword=Spanikopizza&Account=Test&AccountClass=TestClass&ApplicationPassword=testpass3

The response should be:
0:Account {TestClass}.Test Registered

For any other response, see below for possible causes.

The complete test suite

> cd ../testing
> perl testsuite.pl TEST_INIT.data

Possible Problems

1. Is your mysql database running locally and does the tomcat server have permission to access the TESTCASS and CASS databases?
2. Is your tomcat installation running (is it accepting http requests)?
3. Most likely source of problems: Tomcat needs to be restarted so that it can find cassius. And on my development machine, it helps to wait 10 seconds after restarting it before trying to access it.
4. Look at your tomcat/log files to see what is going on. One of the log files will indicate that the servlet was not loaded, and will give reasons why. If the servlet is loading but not running, the problem is likely with mysql.
5. Make sure that the cassius folder created within the tomcat folder is correctly spelled and in all lowercase letters.
6. testsuite.pl was tested on Perl v5.6.0, but should work on any perl 5 interpreter. Perl errors can include incompatable perl versions, and the lack of the LWP::UserAgent module. This module can be found at www.cpan.org.
7. If all else fails, email me at mkantor@ics.uci.edu

Terminology Used Here

• CASS: CASS stands for Creating Awareness with Subscription Services. The CASS strategy presents a set of guidelines for providing users with useful and usable awareness tools and awareness information.
• CASSIUS: The CASS Information Update Server. A notification server that implements the CASS strategy for distributing awareness information.
• CASSandra: A toolkit for building software that work with CASSIUS. Currently supports Java.
• Information Source: Applications, servers, virtual environments, tools for monitoring the real world, print drivers, any software that has state or information that people (or other systems) can benefit from being aware of is a potential information source. It does not truely become an information source until it starts sending notifications to the notification server.
• Notification: A report describing an event such as a change in state, change in data, some type of event which the information source developer considered to be of potential significance to other users and systems.
• EventName: An EventName refers to the part of the notification which names the nature of the changes to the information source's state. For example, EventNames that might be sent out by a WebDAV server are "Get", "Post", "Rename", "Put", etc...
• Awareness Style: Awareness styles vary across a variety of dimensions in how they make users aware of new information. The style can have am important effect on what kinds of work environments and work practices an awareness tool can be used within. A tool that stridently beeps to let a person know that their spouse has returned home from work may not be an appropriate tool if you are an airforce pilot who might not be able to afford the interruption. Some dimensions include
  1. Intrusive vs. peripheral dimension: how intrusive/disruptive is the presentation of new awareness information? Highly intrusive would be a strident beeping, or popping up a modal dialog box and requiring that the user deal with the message containing new information before they move on with their work. Peripheral means that the presense of new information communicated using peripheral senses such as animations placed in a user's peripheral vision, or sounds that are non-disruptive but communicate the nature of the information that has arrived and in some cases even the nature of the event being reported upon.
  2. Mobility dimension: Can the awareness tool be moved from one computer to another as a person's work moves through a building? Can it use mobile devices, perhaps for when taking the train to work? Is this a style best used from an office while one is working, and using other styles when one is mobile?
  3. Information Representation dimension: What kinds of information does the representation of the information used by a style focus upon? Different types of graphs, animations, and other representations of information focus on illuminating certain aspects of information.
  4. Cognitive Effort dimension: How much effort is needed to interpret the representation? A highly abstract and general tool may require more interpretative effort from the user than a more focused, less general tool.
• Objects/ObjectID: An information source monitors aspects of its data and send out notifications of changes to that data. The data that is monitored is refered to as monitored objects, or just objects. An object can be a datastructure, a concept, part of the data of a system (the text in a word processor, an image in a web camera), a configuration of a system (the port number of a web server), a quantification of performance (load or efficiency on a server), etc... An ObjectID is a unique identifier for that object. For purposes of this work, the unique identifier is defined by the developer of the information source.

Understanding a CASS Awareness Environment

1. Provide users with the ability to browse through lists of information sources to which they can subscribe

2. Browsing for subsets of notifications

For example, in the case of a WebDAV server, monitored entities might consist of files, folders, system properties and system performance. Users then would browse through a hierarchical view of files and folders, selecting the files and folders that they want to monitor. Users may also browse through different system properties and select some so as to be notified when the server's configuration is changed. In the WebDAV scenario, the user may also browse through a list of different aspects of system performance and subscribe to be notified when load exceeds certain levels.

In this model, it is the responsibility of the information source to inform the awareness server of what objects it is monitoring, specifying where in the user browsable object hierarchy that entity exists, and maintaining that hierarchy as the information source's data changes. In a WebDAV server, as files and folders are created and deleted, the server must send object hierarchy manipulation commands to CASSIUS so that the awareness server's representation of the object hierarchy continues to match reality.

Note that these first points #1 and 2 are about providing users and tools with meta information. The impact of this meta information can be shown in this screen shot of the CASSandra subscription editor. On the top left is a hierarchy of information sources (which will be more impressive when we have more information sources). Users select the information source and are presented with a hierarchy of objects (in this case files and folders) which they can subscribe to. Selecting the file or folder does two things: it adds it to the formula being designed (right center panel of the user interface), and it finds all of the events that can affect the object and place them in the event hierarchy on the top right corner. Selecting the events adds them to the formula. Now imagine a user trying to create the subscription being designed up above without a user interface that provides this kind of meta information. However long it takes you to imagine it, it will take the user longer to do it correctly.

3. It is Important to Support Diverse Awareness Styles

The result of this goal is that a notification sent by any one information source should be easily interpreted and represented by a large number of awareness tools.

4. Any style of awareness tool should work with diverse information sources

1. It is important to provide a variety of styles of awareness tools that can fit within a variety of work environments. Once a style or set of styles is implemented, it can be reused to monitor any information source.
2. A single awareness tool/style can be used not only to choose one of many information sources to monitor, but in fact to take awareness information from diverse sources and merge them together into a more complete picture of a work environment.
3. A user can use multiple awareness tools in different styles monitoring diverse sets of information. A tool that uses peripheral sound can keep a person aware of activity in the work environment from one set of information sources, while more critical notifications are presented using a more intrusive style.

Some of the more important fields include a textual summary for use in brief textual or verbal descriptions of an event, numerical quantification of an event for use in awareness tools that use graphing or intensity of sound/sight to communicate to the user. A URL field is used to obtain more data on the nature of the event.

There are also the EventName and GenericEventName fields. The EventName is the application specific name of the event, while the GenericEventName is a generalized event name that can be interpreted by users and awareness tools that have limited or no understanding of the activity or nature of the information source. Generic Events currently consist of:

• Activate
• Deactivate
• Increase
• Decrease
• Change

Instrumenting Information Sources

The File Monitor Sample

> cd ../samples/filemonitor

> perl index.pl [directory to monitor] [URL to files] [URL to server] [Optional multiaccount mode]

• Directory to monitor: Enter the path to the directory structure you want to monitor.
• URL to files: With each notification, there should be a URL to the file being modified so that people interested in following up on the notification can quickly access the file. This can be left blank if the directory structure is not web accessible.
• multi-account mode: If this argument has a value, then each high level folder in [directory to monitor] will be treated as a separate account. Otherwise, each high level folder is treated as a high level object within a single account. Please note that all examples used in this README assume that you do not use this parameter -- it exists to help demonstrate the value of Account Classes.

>perl index.pl ~/cass "http://localhost:8080/~mkantor/cass"

1. Check to see if the account is already registered with the server

1. Choose a new name
2. Assume that the name was used in a previous run of this program and reuse it. (we take this course).
3. Register and request this already taken name, and be assigned a new name by the server that is based upon the requested name.

We request a list of all accounts that are in the "FileMonitor" account class (all accounts created by the filemonitor are assigned to the FileMonitor account class). This call returns a list which the program parses, searching to see if the desired name is already in use or not.

2. Register

Because we are monitoring the folder named cass, the account name cass is used (Account=cass). The account class FileMonitor is used (AccountClass=FileMonitor). Passwords are assigned, permission to register information sources on the server requires a global password, and other information about the account is specified.

When this command is finished, the information source will have registered, an account will have been created for it on the server, and all future access to the notification server will be through that account.

3. Provide EventNames for Files and Folders

Note that these types are defined only for the account FileMonitor.cass. If we were to create a new FileMonitor account, these types would need to be redefined for the new account. Also, Each event has a definition associated with it as explanation to users who may wish to subscribe to the event.

4. Initialize Object Hierarchy: Checking to see if objects exist

This call requests a list of children of an object (objects beneath the specified object in the hierarchy). If it returns 0 or more results then the object exists, if it returns a not found error then it does not exist.

5. Create Object in Hierarchy

This creates a new object named cassServlet.java with the unique identifier (ObjectID) of /home/mkantor/src/cassius/cassServlet.java. Note that if this were a webdav server, we would not use the path as the unique identifier as webdav is able to understand a file move/rename operation. In the case of a file move in webdav, the ObjectID remains the same and all subscriptions and notifications relevant to that file retain their integrity. FileMonitor perceives a file move operation as a file deletion and file creation, all notifications and subscriptions to the old ObjectID (file path) become broken (the server should probably do something with these notifications and subscriptions, but it does not at this time).

The new object is created as a subobject of /home/mkantor/cass/src/cassius, is of type File, and contains a description for the user to read when subscribing.

6. Monitor For Changes

Account=FileMonitor.cass&Password=testpass3&
Operation=Notify&ObjectID=/home/mkantor/cass/src/cassius&
Event=NewFile&GenericEvent=Increase&
Summary=/home/mkantor/src/cassius/cassServlet.java has been added to this directory tree&
Propagate=1&URL=http://localhost/~mkantor/cass/src/cassius&
NumericalValue=512

The numerical value is the size of the file/folder (it should be the number of files within the folder).

Just as a file creation causes a Create/Activate EventName/GenericEventName to be sent to the child and NewFile/Increase EventName/GenericEventName to all ancestors, there is also a Delete/Deactivate/ChildRemoved/Decrease set of EventNames/GenericEventNames, and Modify/Change/ChildUpdated/Change events/genericevents.

CassDAV

Now consider what happens if every WebDAV event generates a CASSIUS notification. Every member of the work group can use awareness tools which will enable them to maintain awareness of which files and folders have changed or are being changed. No explicit effort is needed for users to send these notifications, they perform their work just as they always would have, saving their work to a mounted directory rather than a local directory, and all of the people who can be affected by the changes made (or not made) can now maintain awareness of the work going on in their work environment.

Given a range of awareness tools, different users can monitor these webdav folders in different ways. Depending upon different users needs, some of them may use peripheral awareness tools which make sounds or use peripheral vision to make the user aware of activity in different files and folders of the webdav directory. Others may want more active notifications that disrupt their work and explicitly tell them that a specific file has been changed. Still others may not want the information presented to them directly, but rather through the file system itself -- a few enhancements to a WebDAV client can enable it to represent the last set of notifications sent out concerning each file, including whether the file is currently locked and by whom. And people who are not directly working on the WebDAV directory but are affected by the progress of the work can use another awareness tool for subscribing to receive emailed digests summarizing activity each week.

Installation

> cd $catalina_home/webapps/cassius
> mv cassdav ..

> cd ../cassdav/WEB-INF
> cp servlets-cassdav.jar $catalina_home/server/lib/
> cp lib/mysql_comp.jar $catalina_home/common/lib
> mysqladmin create CASSDAV
> mysql -D CASSDAV < InitializeDatabase.txt

> cd $catalina_home/conf
> edit tomcat-users.conf

  <user name="username" password="userpassword" roles="tomcat" />

Finally, restart your tomcat server.

CassDAV can be accessed with the URL: http://localhost:8080/cassdav

Notes on Using CassDAV

Monitoring files vs. folders

An example of where this can be particularly irritating is if you use a program like emacs which saves backup copies as <filename>~. It turns out that emacs does not create <filename>~, but in fact moves <filename> to <filename>~ and then creates a new <filename>. If you were subscribed to <filename> and someone edits it with emacs, you will soon find yourself monitoring <filename>~ instead because it is the file that you requested to monitor, even though its relevance has been made obsolete by emacs' backup technique.

An alternate approach to monitoring a file where you do not need to receive every lock, unlock and other events is to monitor a folder that contains the file. The folder will receive most notifcations sent concerning changes to the file, but if the file is moved to a trash or archive folder and a new file replaces it, notifications will be sent saying that the file was moved to another location, and then all further notifications will concern the replacement file. Naturally, the folder itself can be moved...

Notifications

WebDAV method	CASSIUS Event	CASSIUS GenericEvent	Description
GET	Get	Activate	The file has been downloaded either to a local file system or into the memory of an application such as emacs
PUT	Create	Activate	The file has been uploaded or saved to the server, and there was not previously a file with this name. This should happen when either copying files to the CassDAV directory or when executing a save operation from an application.
PUT	Update	Activate	The file has been uploaded or saved to the server, and there was a version of the file that was overwritten by the new version. This should happen when either copying files to the CassDAV directory or when executing a save operation unless the save is performed by emacs which moves the file to be overwritten.
DELETE	Delete	Deactivate	The file has been removed from the server.
COPY	Copy	Increase	The file has been copied to a second location on the server. A COPY WebDAV event also results in a Create event being sent to the newly created file.
MOVE	Rename	Change	The filename has been changed, but remains within the same folder.
MOVE	Move	Change	The file has been moved to a new folder.
LOCK	Lock	Activate	The file has been locked for exclusive write permissions of a single user.
UNLOCK	Unlock	Deactivate	The file has been unlocked and any user can modify it.

Users who monitor a folder can receive any of the above file events and can also receive:

WebDAV method	CASSIUS Event	CASSIUS GenericEvent	Description
GET	GetChild	Activate	An item in this folder has been downloaded.
PUT	FileUpdate	Activate	An item in this folder has been uploaded.
PUT	FileAdded	Activate	An file has been uploaded into this folder.
PUT	FolderAdded	Activate	An folder has been uploaded into this folder.
DELETE	FileRemoved	Deactivate	An file has been removed from this folder.
DELETE	FolderRemoved	Deactivate	An folder has been removed from this folder.
MOVE	ChildRename	Change	A file or folder within this folder has been renamed.
COPY	ChildCopy	Change	A file or folder within this folder has been copied.

Note that notifications sent about files will be observed not only by people monitoring that file or folder; all of these folder events will be propagated up to the parent folder, grandparent folder, and on up to the root folder.

This list of events actually is longer than it should be -- while very descriptive, it gives users more choices than they really want for designing a quick subscription. Suggestions are of course welcome.

Notifications contain a URL that links the user to the document that has been affected. However, these URLs work much better in applets where they utilize the web browser's ability to log onto a server. Java applications provided with this distribution do not provide a way of entering a username and password to access the CassDAV server and view the document.

Awareness Tools

< NAME='Samples'>EventList Tool

cd cassius/cassandra
setenv CLASSPATH CASSandra.jar:$CLASSPATH (or whatever equivalent syntax your system uses to add a jar file to your classpath)
java EventList <usename> <URL to server>

simpleScroller Tool

cd cassius/cassandra
setenv CLASSPATH CASSandra.jar:$CLASSPATH (or whatever equivalent syntax your system uses to add a jar file to your classpath)
java simpleScroller <usename> <URL to server>

BiffArray Tool

Each biff can monitor a different source if information. For example, if one has six biffs, two could monitor files that you work with, two could monitor people, one could monitor activity on a chat group, and the last could monitor the state of your group's printer.

A related feature is that the user can configure each biff to make a different sound when it detects an event. This has two effects on usage:

1. If the same type of event comes repeatedly, the graphic won't change, it is only through sound that the user becomes aware that the event repeated
2. The user interface does not need to be visible to be useful

Clicking on a biff when it has no subscription will open the subscription editor. Clicking on a biff when it does have a subscription will clear its latest icon (like clearing the original XBiff), so that the next time that same type of event occurs, you can see it change icons from empty to the icon for the type of event received. Right clicking on a biff allows you to edit the subscriptions, sounds, and make other changes.

Note that to access sounds and icons, it is currently required to run this from the cassandra directory.

cd cassius/cassandra
setenv CLASSPATH CASSandra.jar:$CLASSPATH (or whatever equivalent syntax your system uses to add a jar file to your classpath)
java BiffArray <usename> <URL to server>

Building Awareness Tools

Some quick definitions:

Username	Identifies the user who is subscribing to receive notifications from the server
Interface/InterfaceName (in the context of a message to the server)	Identifies the awareness style that the user wants the notifications sent to. Each subscription is associated with a username and an InterfaceName, and when a client polls or subscribes, it must send both to the server.
Interface (in a Java context)	A set of Java methods that must be implemented -- unrelated to Interface/InterfaceName as a message to the server

CASSandra Toolkit Tutorial

Toolkit.NotificationListener Interface

// Interface for tools that want to be notified of new notifications
public interface NotificationListener {

      // Sends a vector of all of the new cassandra.Notification objects
      public void notificationsReceived(Vector inNotifications);

      // Notifies the awareness tool that the latest attempt to poll
      // for new notifications returned nothing.  Generally, this
      // will not be used, but is handy for tools that act once
      // every X seconds, and need to know if there was new data
      // to determine what action to take.  One could also implement
      // a thread within the awareness tool, but this approach lets the tool
      // act immediately when it knows what if any new data has arrived.
      public void notificationsNotReceived();

      // Returns a unique string that identifies the user interface style.
      public String getInterfaceName();
}

Toolkit Public Methods

public class Toolkit {
    public Vector getNotifications();

    public Notification[] getNotifications(int inLastXNotifications);

    public Toolkit(String  inUsername,  // documented later in this section
                   String  inServletURL,
                   int     inPollInterval,
                   Long    inSince,
                   int     inPolicy, 
                   int     inPolicyComparison, 
                   boolean inDebug);

    public void startPolling(); // Starts polling thread, call if using toolkit to help poll for notifications.

    public void sendMessage(String inMessage);  // Send message to the server.  Message must be of form: "Operation=xx&Param1=val1&Param2=...".  Message is sent in a separate thread so that the main thread of execution does not have to be concerned with delays in http requests.

    public Vector sendMessage(String inMessage, boolean waitForResponse); // Same as above, except that if waitForResponse is true, then the message and response are completed within this thread, forcing this thread to wait for completion.  The advantage is that this thread gets to examine the server's response which is returned in a Vector.  Each element of the Vector is a line of the response.
}

Awareness Tool Implementation

import javax.swing.*;
import java.util.Vector;
import cassandra.*;

class YourClass extends JFrame implements Toolkit.NotificationListener {

    // Keep an instance of the toolkit handy
    Toolkit mTK;

    // This label will display the most recent notification we have received
    JLabel  mNotificationDisplay;

    // This button will allow us to change what we are subscribed to
    JButton mSubscribeButton;

    // the main routine
    public static void main(String[] args) 
    {
      // Initialize a toolkit. Parameters explained in next subsection.
      Toolkit lTK = new Toolkit("mkantor",
                                "http://localhost:8080/cassius/cass",
                                 15,
                                 new Long(new java.util.Date().getTime()-1000*3600*2),
                                 Toolkit.DELETE_POLICY_MORE_THAN, 
                                 0,
                                 (args.length >= 3));

      // Initialize the awareness tool, passing it the toolkit
      YourClass lYourClass = new YourClass(lTK);

      // Start the toolkit's threads. (see section on Toolkit implementation for explanation of threads)
      lTK.startPolling();
    }

    // Constructor takes in the toolkit instance.
    public YourClass(Toolkit inTK) {

      // Give the window an appropriate name
      super(getInterfaceName());

      // Save the toolkit instance
      mTK = inTK;

      // Start listening for notifications
      mTK.addNotificationListener(this);

      // Initialize graphical objects
      mNotificationDisplay = new JLabel("Waiting for notification");
      mSubscribeButton = new JButton("Subscribe");
      
      // If the user clicks on the Subscribe button, open the subscription window.
      // It is for this call that we need to save the toolkit instance.
      // To provide your own subscription editing window, replace 
      // SwingSubscriptionHandler (distributed with CASSandra) with
      // your own implementation.
      mSubscribeButton.addActionListener (new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                new SwingSubscriptionHandler(mTK,getInterfaceName()); 
            }
          });

      // Finish creating the user interface
      getContentPane().add(mNotificationDisplay,BorderLayout.CENTER); 
      getContentPane().add(mSubscribeButton,BorderLayout.SOUTH); 
      setSize(200,200);
      setVisible(true);
   }

   // When notifications are detected, display only the most recent notification
   public void NotificationsReceived(Vector inNotifications) {
       Notification n = (Notification)inNotifications.elementAt(inNotifications.size()-1);
       mNotificationDisplay.setText(n.getObjectName() + ":" + n.getSummary() + ":" + n.getEvent());
   }

   public void NotificationsNotReceived() {}

   // Return the interface name to be used when communicating with the server.
   public String getInterfaceName(){return "YourClass";}
}

Toolkit Constructor

    public Toolkit(String  inUsername,
                   String  inServletURL,
                   int     inPollInterval,
                   Long    inSince,
                   int     inPolicy, 
                   int     inPolicyComparison, 
                   boolean inDebug)

Notification Class

public class Notification {
    public String getObjectID();
    public String getObjectName();
    public String getObjectType();
    public String getObjectDescription();
    public long   getTimeReceived();
    public String getURL();
    public String getSummary();
    public float  getNumericalValue();
    public String getEvent();
    public String getGenericEvent();
}

Implementation Checklist

1. Implement the Toolkit.NotificationListener interface
2. Construct an instance of the Toolkit
3. Add the NotificationListener to the toolkit's list of notificationListeners.
4. Give users access to the subscription edit window by calling new SwingSubscriptionHandler(toolkit,interface_name)

Complex Example

import javax.swing.*;
import java.util.Vector;
import cassandra.*;

class YourClass extends JFrame {

    // Keep an instance of the toolkit handy
    Toolkit mTK;

    // the main routine
    public static void main(String[] args) 
    {
      // Initialize a toolkit.
      Toolkit lTK = new Toolkit("mkantor",
                                "http://localhost:8080/cassius/cass",
                                15,
                                new Long(new java.util.Date().getTime()-1000*3600*2),
                                Toolkit.DELETE_POLICY_MORE_THAN, 
                                0,
                                (args.length >= 3));

      // Initialize the awareness tool, passing it the toolkit
      YourClass lYourClass = new YourClass(lTK);

      // Start the toolkit Poll thread.
      lTK.startPolling();
    }

    // Constructor takes in the toolkit instance.
    public YourClass(Toolkit inTK) {

      // Give the window an appropriate name
      super(getInterfaceName());

      // Save the toolkit instance
      mTK = inTK;

      // Create the three buttons, each of which can have its own subscriptions
      // and directly receive notifications from the toolkit.  Each listener
      // MUST have a unique InterfaceName, or they will share the same subscriptions.
      getContentPane().add(new CASSButton("InterfaceName 1"),BorderLayout.WEST);
      getContentPane().add(new CASSButton("InterfaceName 2"),BorderLayout.CENTER);
      getContentPane().add(new CASSButton("InterfaceName 3"),BorderLayout.EAST);

      setSize(300,150);
      setVisible(true);
   }

   // Inner class defines an awareness component
   class CASSButton extends JButton implements Toolkit.NotificationListener 
   {
      String mInterfaceName;

      // One way to insure that every CASSButton has a unique interface name
      // is to have some other class pass it a unique interface name.
      public CASSButton(String inInterfaceName) 
      {
         // Set the button label to reflect that no notifications have yet been received.
         super("No Notifications Received");

         // Save the name of this awareness component's Interface style.
         mInterfaceName = inInterfaceName;   

         // Add this awareness component to the notification listeners.
         mTK.addNotificationListener(this);

        // Clicking on the button allows users to change the button's subscriptions.
        addActionListener (new ActionListener() {
            public void actionPerformed(ActionEvent e) {
                new SwingSubscriptionHandler(mTK,getInterfaceName()); 
            }
          });
      }

      // When notifications are detected, display only the most recent notification
      public void NotificationsReceived(Vector inNotifications) {
         Notification n = (Notification)inNotifications.elementAt(inNotifications.size()-1);
         setText(n.getObjectName() + ":" n.getSummary() + ":" + n.getEvent());
      }

      public void NotificationsNotReceived() {}

      // Return the interface name to be used when communicating with the server.
      public String getInterfaceName(){return mInterfaceName;}
   }
}

CASSandra Toolkit Implementation & Modification

Message Handler: PollLoop Thread

Operation=Poll&Username=user&Interface=Style1&Operation=Poll&Username=user&Interface=Style2&....

MessageHandler Thread

Toolkit Interfaces

    public interface NotificationListener {
      public void notificationsReceived(Vector inNotifications);
      public void notificationsNotReceived();
      public String getInterfaceName();
    }
  
    public interface ObjectListener {
      public void objectsReceived(Vector inObjects);
    }

    public interface CASSEventListener {
      public void CASSEventsReceived(Vector inEvents, String inType);
    }

    public interface SubscriptionListener {
      public void subscriptionsReceived(Vector inSubscriptions);
    }

    public interface AccountListener {
      public void accountsReceived(Vector inAccounts);
    }

    public void addNotificationListener(NotificationListener inList);
    public void addAccountListener(AccountListener inList);
    public void addCASSEventListener(CASSEventListener inList);
    public void addObjectListener(ObjectListener inList);
    public void addSubscriptionListener(SubscriptionListener inList);

Communication with CASSIUS

public Vector sendMessage(String inMessage, boolean waitForResponse);

If waitForResponse is true, the http request and response are performed by this thread, preventing it from further execution until it is complete. In this case, the server's response is returned directly to the caller as a Vector of Strings representing the lines of the response.

If waitForResponse is false, then the http request is sent to another thread for execution. In this case, the current thread can continue executing other tasks, but can not directly obtain a response. Responses can be obtained for data requests (ListAccounts, ListSubscriptions, etc...), by implementing the appropriate Listener interface and adding your object as a listener.

Implementing Awareness Tools Without CASSandra

> cd samples/simpleaware
> text.pl "http://localhost:8080/cassius/cass" "[AND FileMonitor.cass.ObjectID = /Users/mkantor/cass/src/cassius/cassServlet.java, FileMonitor.cass.Event = Modify]"

1. Subscribe

Note first of all that if sending this as Get request (i.e. url-to-server?Operation=Susbscribe&...) that having an "=" in the middle of a parameter creates problems. To actually submit the above request as a Get request, it is necessary to replace the "=" with "%3D":
Operation=Subscribe&Username=testuser&Interface=text&Method=Replace&
Formula=[AND FileMonitor.cass.ObjectID %3D /Users/mkantor/cass/src/cassius/cassServlet.java, FileMonitor.cass.Event %3D Modify]

The Method parameter is set to Replace which instructs the server to replace any existing subscriptions for this user and interface with the new subscription. For more information about the Method parameter, see the API at the end of this document. The formula here specifies that

1. It is looking for notifications from within the cass account of the FileMonitor account class,
2. It is looking for notifications of changes to the object with the ID = /Users/mkantor/cass/src/cassius/cassServlet.java,
3. AND that EventName must be "Modify".

Poll

This tells the server to look for all notifications that A) Match any of the subscriptions for this username and interface, and B) Have arrived since the last Poll operation. You will note that there is no authentication currently used to prove that this really is the specified user. Security is an issue that is only marginally handled in this implementation of the CASSIUS server.

Responses come in the form of

0:Returning 2 Results
AccountClass.AccountName
ObjectName
ObjectID
Event
GenericEvent
Textual Summary
Numerical Value
URL to Information source
URL to more information about this event
Next AccountClass.AccountName, etc...

Sample Perl code

require "URLLib.pm";
local($Connect) = new URLLib();
$servlet_URL = "http://localhost:8080/cassius/cass";
$query = "Operation=......";
local($Response) = $Connect->Post($servlet_URL,$query);
if ($Response =~ /^0/) {
   print("Operation Accepted, response code began with a 0");
} else {
   print("ERROR: $Response");
}

Note that you can also use:
local($Response) = $Connect->Get($servlet_URL,$query);

Using CASSandra for information sources

1. You do not need to implement code for sending http requests, nor worry about creating threads that allow the message passing to happen outside of your normal execution thread.
2. Future enhancements to the toolkit will replace strings of "Operation=x&Account=y..." with method calls that will generate these strings for you.

API

Operation=NewObject&Account=FileMonitor.cass&Password=testpass3&ObjectID=1&
Operation=NewObject&ObjectID=2

Account Management APIs

An account consists of an account name and zero or more account classes that categorize the account. All access to the account is in the form [AccountClass].[AccountName] where the account class is any of the account's classes. For example: FileMonitor.cass. If the account has no class, then it is simply [AccountName].

Register Account

Table 1. Register new information source with Notification Server

Responses

• 0:Account {[comma-separated-list-of-classes]}.[name] Registered
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: No Account Name
• 2:Operation Failed, Incomplete Input: Account Must Have Value
• 7:Account Exists in classes: [comma-separated-list-of-classes], Assigned name is {[comma-separated-list-of-classes]}.[name]

Example

local($AccountName) = "cass";
local($response) = $Connection->Get($servlet_URL,
                                    "Operation=Register&".
                                    "Account=$AccountName&".
                                    "AccountClass=FileMonitor&".
                                    "GlobalPassword=Spanikopizza&".
                                    "ApplicationPassword=testpass3&".
                                    "URL=http://localhost/~mkantor/cass&".
                                    "Description=Monitored Folder");

if ($response =~ /^7:Account Exists in classes: (.*), Assigned name is (.*)\.(.*)/) {
   $AccountName = $3;
   print("Name unavailable, assigned name is $AccountName\n");
} elsif ($response =~ /^0/) {
   print("Registered!\n");
} else {
   print ("FAILED!\n");
}

UnRegister

Table 2. Unregister an information source from a notification server

Responses

• 0:Account {[comma-separated-list-of-classes]}.[name] Unregistered
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Account not specified
• 2:Operation Failed, Incomplete Input: Password not specified
• 4:Account [AccountPath] Not Found

Example

local($response) = $Connection->Get($servlet_URL,
                                    "Operation=UnRegister&".
                                    "Account=FileMonitor.cass&".
                                    "Password=testpass3&");
unless ($response =~ /^0/) {
   print ("FAILED!\n");
}

Change Account Information

Table 3. Change the account information

This operation is important because the nature, role and location of a source of information can move. For example, if the source of information is a document being monitored, the document can change from being a rough draft to a draft ready for review, it may be passed around, and edited on different machines, etc...

Responses

• 0:Account {[comma-separated-list-of-classes]}.[name] Modified
• 1:Permsission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 2:Operation Failed, Incomplete Input: Name can not have empty value
• 4:Account [AccountPath] Not Found
• 7:Account Exists in classes: [comma-separated-list-of-classes], Assigned name is {[comma-separated-list-of-classes]}.[name]

Example

local($AccountName) = "new name";
local($response) = $Connection->Get($servlet_URL,
                                    "Operation=ChangeRegistration&".
                                    "Account=FileMonitor.cass&".
                                    "Password=testpass3&".
                                    "Name=$AccountName"
                                    "Class=Not a FileMonitor,New Class&".
                                    "URL=http://new.url.com"
                                    "Description=New description");

if ($response =~ /^7:Account Exists in classes: (.*), Assigned name is (.*)\.(.*)/) {
   $AccountName = $3;
   print("Name unavailable, assigned name is $AccountName\n");
} elsif ($response =~ /^0/) {
   print("Registration Changed\n");
} else {
   print ("FAILED!\n");
}

Listing Accounts

Table 4. List Accounts

Responses

• 0:Returning [count] Results
  [AccountClassName]
  Account Class
  
  [AccountName]
  [Comma-separated-account-class-list]
  [Description-of-account]
• 2:Operation Failed, Incomplete Input: Can use only one of IgnoreAcccounts, Hierarchical and AccountClass parameters

Example

local($DesiredAccountName) = "cass";

local($result) = $Connect->Get($servlet_URL,
                               "Operation=ListAccounts&AccountClass=FileMonitor");
if ($result =~ /0:Returning (\d+) Results/) {

   # In Perl, $1 contains the value of (\d+) above -- some number of digits
   local($resultcount) = $1;

   # Read the result string into an array, one line of the response per array element.
   local(@results) = split(/\n/, $result); 

   # Delete the first element of the array which is the 0:Returning x Results
   shift(@results);

   for ($i = 0; $i < $resultcount; $i += 3) {
     local($AccountName,$AccountClasses,$Description) = ($results[$i], $results[$i + 1], $results[$i + 2]);

     if ($DesiredAccountName eq $AccountName) {
        print("$DesiredAccountName is in use");
        return;
     }
   }
   print("$DesiredAccountName is available");
} else {
  print("ListAccount operation has failed: $result");
}

Object Management APIs

In order to create this hierarchy, information sources must send objects to the server using the NewObject command, and place the object in the hierarchy. Each object has a ParentID property which gives the ObjectID of the object that they are contained within. If there is no parent, then the object is at the top of the object hierarchy. The parent object can be either a monitored object, or simply a place holder used to construct a hierarchy that will have meaning to the users.

For example, a section of a document is a monitorable object -- an object will be created on the server to represent it and act as the target for notifications sent from the information source to the server. It may also have subsections represented by subobjects. Both object and parent have meaning here and structuring them in this way should be intuitive to users familiar with document structures (i.e. all users). If what the information source is monitoring is the amount of load on the machine, an object representing this concept will sldo be sent to the server. In this case, it may not be as clear what the parent of such an object should be, but it and other aspects of performance monitored by the information source may all be grouped under an object called "Performance". The performance object has no real meaning in that it does not receive notifications, but is used solely to structure the information for the user. This distinction is not specified to the server when creating or using the objects.

Any object manipulation operation that affects a parent object can affect the children. Deleting or moving an object will delete or move all of its children.

Creating New Objects

Table A-8. Create a new object in the object hierarchy

Responses

• 0:Object [ObjectID] Created
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: ObjectID not specified
• 2:Operation Failed, Incomplete Input: ObjectName not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 4:Account [AccountPath] Not Found
• 9:Operation Failed, Flawed Input: ParentID can not be self
• 9:Operation Failed, Flawed Input: ObjectID already in use not currently implemented

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=NewObject&".
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&".
                               "ObjectName=src&".
                               "ObjectID=/home/users/mkantor/cass/src&".
                               "ParentID=/home/users/mkantor/cass&".
                               "Type=Folder&".
                               "Description=Folder in monitored directory&".
                               "Operation=NewObject&".
                               "ObjectName=cassServelet.java&".
                               "ObjectID=/home/users/mkantor/cass/src/cassServlet.java&".
                               "ParentID=/home/users/mkantor/cass/src&".
                               "Type=File&".
                               "Description=File in monitored directory");

if ($result ne "0:Object /home/users/mkantor/cass/src Created\n0:Object /home/users/mkantor/cass/src/cassServlet.java Created\n") {
   print("Operation Failed, output was: $result");
} else {
   print("Two objects created");
}

Remove Object

Table 5. Remove object from object hierarchy

Returns

• 0:Object [ObjectID] Removed
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: ObjectID not specified
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 4:Account [AccountPath] Not Found

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=RemoveObject&".
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&".
                               "ObjectID=/home/users/mkantor/cass/src/cassServlet.java");
if ($result =~ /^0/) {
   print("Object removed");
} else {
   print("ERROR: $result");
}

Modify Object

Table 6. ModifyObject command for moving and redefining objects

Responses

• 0:Object [ObjectID] Modified
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: ObjectID not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 4:Account [AccountPath] Not Found
• 4:Object [ObjectID] Not Found
• 9:Operation Failed, Flawed Input: ParentID can not be self

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=ModifyObject&". # the next four lines identify the object
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&". 
                               "ObjectID=/home/users/mkantor/cass/src/cassServlet.java&".
                               "ObjectName=cassServlet.java.backup&". # the next three lines indicate what to change
                               "ParentID=/home/users/mkantor/cass/backups&".
                               "Description=Backup File");
if ($result =~ /^0:/) {
  print("Object Modified\n");
} else {
  print("ERROR: $result\n");
}

List Objects in Account

Table 7. Lists objects that users can subscribe to

Responses

• 0:Returning [count] Results
  [[Optional-Object-Type]][GreatGreatGreatGrandParentID]:...:[ParentID]:[ObjectID]:[ObjectName]
  [Description]
  [Number of Children]
• 2:Operation Failed, Incomplete Input: Account not specified
• 4:Account [AccountPath] Not Found
• 4:Object [ParentID] Not Found

[File]/home/users/mkantor/cass/src:/home/users/mkantor/cass/src/cassServlet.java:cassServlet.java

/home/users/mkantor/cass/src:/home/users/mkantor/cass/src/cassServlet.java:cassServlet.java

Example

local($result) = $Connect->Get($server_URL,
                              "Operation=ListObjects&".
                              "Account=FileMonitor.cass&".
                              "ParentID=/home/users/mkantor/cass/src");
if ($result =~ /^0:Returning (\d+) Results/) {

   # In Perl, $1 contains the value of (\d+) above -- some number of digits
   local($resultcount) = $1;

   # Read the result string into an array, one line of the response per array element.
   local(@results) = split(/\n/, $result); 

   # Delete the first element of the array which is the 0:Returning x Results
   shift(@results);

   for ($i = 0; $i < $resultcount; $i += 2) {
       local($AccountIDInfo,$Description) = ($results[$i], $results[$i + 1]);
       $AccountIDInfo =~ /^(\[.*\])?(.*):(.*):(.*)$/;
       
       local($ObjectType, $ParentID, $ObjectID, $ObjectName) = ($1,$2,$3,$4);
       if ($ObjectName eq "cassServlet.java") {
          print("Found it!");
          return;
       }
   }
   print("Not found!");
} else {
   print("ERROR: $result");
}

Working with Types

Defining Types

Table 8. Define a new Object Type

Responses

• 0:Type [typename] Created
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 2:Operation Failed, Incomplete Input: Type not specified
• 4:Account [AccountPath] Not Found

Example

local($result) = $Connect->Get($server_URL,
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&".
                               "Operation=DefineType&".
                               "Type=File&".
                               "Event=Create&Definition=File added to file system&".
                               "Event=Delete&Definition=File removed from file system&".
                               "Event=Modify&Definition=Modification date on file has been updated&".
                               "Operation=DefineType&".
                               "Type=Folder&".
                               "Event=Create&Definition=File added to file system&".
                               "Event=Delete&Definition=File removed from file system&".
                               "Event=NewFile&Definition=Folder has new file&".
                               "Event=ChildRemoved&Definition=Folder lost a file&".
                               "Event=ChildUpdated&Definition=File was updated in this folder");
if ($result eq "0:Type File Created\n0:Type Folder Created\n") {
   print("Types file and folder created");
} else {
   print("Error");
}

Remove Types

Table 9. Delete an Object Type

Responses

• 0:Type [typename] Removed
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 2:Operation Failed, Incomplete Input: Type not specified
• 4:Account [AccountPath] Not Found

Example

local($result) = $Connect->Get($server_URL,
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&".
                               "Operation=RemoveType&".
                               "Type=File&");
if ($result =~ /^0:/)
   print("Type removed");
} else {
   print("Error:$result");
}

ListEvents

Table 10. List events in the specified type

Responses

• 0:Returning [count] Results
  [EventName]:[Definition]
• 2:Operation Failed, Incomplete Input: Account not specified
• 2:Operation Failed, Incomplete Input: Type not specified
• 4:Account [AccountPath] Not Found

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=ListEvents&".
                                "Account=FileMonitor.cass&".
                              "Type=$ObjectType");
if ($result =~ /^0:/) {
       # If the result is OK, then put each line of the result in a separate element of an array
       local(@results) = split(/\n/, $result);          

       for ($i = 1; $i <= $#results; $i++) {
          local($event,$definition) = split(":", $results[$i]);
          print("Event: $event, Definition: $definition\n");
       }
       return;
} else {
       print("Error getting events: $result\n");
}

Working with Notifications

Sending a Notification

Table 11. Notification Description Table

Responses

• 0:Notification Accepted
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 2:Operation Failed, Incomplete Input: ObjectID not specified
• 2:Operation Failed, Incomplete Input: GenericEvent not specified
• 2:Operation Failed, Incomplete Input: GenericEvent Must Have Value
• 4:Account [AccountPath] Not Found

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=Notify&".
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&".
                               "ObjectID=/home/mkantor/src/cassius/cassServlet.java&".
                               "Event=Create&".
                               "GenericEvent=Activate&".
                               "Summary=/home/mkantor/src/cassius/cassServlet.java has been created&".
                               "URL=http://localhost/~mkantor/cass//home/mkantor/src/cassius/cassServlet.java&".
                               "NumericalValue=512&".
                               "Operation=Notify&".
                               "ObjectID=/home/mkantor/cass/src/cassius&".
                               "Event=NewFile&".
                               "GenericEvent=Increase&".
                               "Summary=/home/mkantor/src/cassius/cassServlet.java has been added to this directory tree&".
                               "Propagate=1&".
                               "URL=http://localhost/~mkantor/cass/src/cassius&".
                               "NumericalValue=512");
if ($result eq "0:Notification Accepted\n0:Notification Accepted\n") {
   print("done");
} else {
   print("ERROR: $result\n");
}

Polling for Notifications

Table 12. Polling for new notifications

Responses

• If Include parameter is not used:
  0:Returning [count] Results
  {[Optional-account-class-list]}.[AccountName]
  [ObjectName]
  [ObjectID]
  [Event]
  [GenericEvent]
  [Summary]
  [Numerical Value]
  [Event Time in seconds since 1970]
  [Information Source URL]
  [URL to event details]
• If Include parameter is used, and the notification does not contain a matching Data type
  -----PartBoundary1----
  Content-type: text/plain
  
  0:Returning [count] Results
  -----PartBoundary1----
  Content-type: text/plain
  
  {[Optional-account-class-list]}.[AccountName]
  [ObjectName]
  [ObjectID]
  [Event]
  [GenericEvent]
  [Summary]
  [Numerical Value]
  [Event Time in seconds since 1970]
  [Information Source URL]
  [URL to event details]
  -----PartBoundary1----
  Content-type: text/plain
  
  etc...
• If Include parameter is used, and the notification contains a matching Data type
  -----PartBoundary1----
  Content-type: text/plain
  
  0:Returning [count] Results
  -----PartBoundary1----
  Content-type: MIME/Multipart
  Boundary=PartBoundary1.1
  -----PartBoundary1.1----
  Content-type: text/plain
  
  {[Optional-account-class-list]}.[AccountName]
  [ObjectName]
  [ObjectID]
  [Event]
  [GenericEvent]
  [Summary]
  [Numerical Value]
  [Event Time in seconds since 1970]
  [Information Source URL]
  [URL to event details]
  -----PartBoundary1.1----
  Content-type: [type-of-data]
  [Data]
  -----PartBoundary1----
  Content-type: MIME/Multipart
  Boundary=PartBoundary1.1
  
  etc...

Creating Subscriptions

Table 13. Parameters for an awareness tool to subscribe to an information source

Formulas

<AccountClass> := string without '.' characters
<AccountName> := string without '.' characters
<AccountPath> := [<AccountClass>.]<AccountName>
<relationship> := "=" | "!=" | ">" | "<" | ">=" | "<=" | "contains"

<Field> := "ObjectID" | "Event" | "GenericEvent" | "NumericalValue" | "timestamp" | "Summary" | "Person" | "Place" | "ObjectName" | "Description"

<value> := string | integer
<FormulaSubExpr> := <AccountPath>.<field> <relationship> <value>
<Boolean> := "AND" | "OR" | ""
<FormulaExpr> := "["<Boolean><FormulaSubExpr> {"," <FormulaSubExpr>}"]"}
<SubscriptionFormula := "["<Boolean>(<FormulaSubExpr | <FormulaExpr>) {"," <FormulaExpr> | <FormulaSubExpr>)} "]"

Formula Example 1

Or this formula which monitors for all events affecting cassServlet.java
[AND FileMonitor.cass.ObjectID = /home/users/mkantor/cass/src/cassServlet.java]

Which can be simplified to
[FileMonitor.cass.ObjectID = /home/users/mkantor/cass/src/cassServlet.java]

and then

FileMonitor.cass.ObjectID = /home/users/mkantor/cass/src/cassServlet.java

All of these are acceptable formulas, the last three being equivalent and receiving all events that affect cassServlet.java.

Formula Example 2

Responses

• 0:Subscription [formula] Created
• 0:Subscriptions [username]:[interfacename] Copied
• 0:Subscriptions [username]:[interfacename] Removed
• 2:Operation Failed, Incomplete Input: Method [method parameter] not recognized
• 2:Operation Failed, Incomplete Input: Formula not specified
• 2:Operation Failed, Incomplete Input: CopyInterface not specified
• 4:Account [AccountPath] Not Found
• 9:Operation Failed, Flawed Input:ERROR IN Formula: [formula]

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=Subscribe&".
                               "Username=testuser&".
                               "Interface=testmonitor&".
                               "Formula=[AND FileMonitor.cass.ObjectID = /home/users/mkantor/cass/src/cassServlet.java,".
                               "FileMonitor.cass.Event = Modify]");
if ($result =~ /^0/) {
   print("Subscription Created");
} else {
   print("ERROR: $result");
}

Listing Subscriptions

Table 14. List subscription matching a constraint.

Responses

• 0:Returning [count] Results
  [username]:[interfacename]
  [formula]
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: Account must be specified when using ObjectID, Event or DefaultEvent
• 2:Operation Failed, Incomplete Input: Must specify one of the following parameters: Username, Interface, or Account
• 4:Account [accountpath] Not Found

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=ListSubscriptions&".
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&".
                               "ObjectID=/home/users/mkantor/cass/src/cassServlet.java&".
                               "Event=Modify");
if ($result =~ /^0:Returning (\d+) Results/) {
   # In Perl, $1 contains the value of (\d+) above -- some number of digits
   local($resultcount) = $1;

   # Read the result string into an array, one line of the response per array element.
   local(@results) = split(/\n/, $result); 

   # Delete the first element of the array which is the 0:Returning x Results
   shift(@results);

   for ($i = 0; $i < $resultcount; $i += 2) {
       local($UserInfo,$Formula) = ($results[$i], $results[$i + 1]);
        $UserInfo =~ /^(.*):(.*)$/;
       
       local($username,$interface) = ($1,$2);
       print("$username is subscribed to cassServlet.java\n");
   }
} else {
   print("ERRROR: $result\n");
}

Purging Notifications

It is important to purge notifications occasionally due to the performance hit in searching for matching notifications among tens of thousands of out of date notifications.

Parameter	Description
Operation	ClearNotifications
Account	Account path; either AccountClass.AccountName (where AccountClass can be any of the account's classes), or if there is no class then just AccountName
Password	Password for accessing this account
OlderThan	Optional Delete all notifications that are older than this number of hours. If unspecified, deletes all notifications.

Table 15. Remove notifications from an account.

Responses

• 0:Notifications Older Than [OlderThan] Hours: Deleted
• 1:Permission Denied, please check your password and confirm that your IP address has permission to access
• 2:Operation Failed, Incomplete Input: Password not specified
• 2:Operation Failed, Incomplete Input: Account not specified
• 4:Account [accountpath] Not Found

Example

local($result) = $Connect->Get($server_URL,
                               "Operation=ClearNotifications&".
                               "Account=FileMonitor.cass&".
                               "Password=testpass3&".
                               "OlderThan=".30*24);
if ($result =~ /^0:/) {
   print("Deleted!\n");
} else {
   print("ERROR: $result\n");
}

Utilities

• perl test.pl "Operation=...&Account=..."
• sendMessage.java "http://localhost:8080/cassius/cass" Operation=...&Account=..."

Bugs/TODO

1. Deleting and recreating an account invalidates all SQL formulas for that account. Currently this results in a failure of the SQL expression, in the future it should detect the failure and recompute the SQL.
2. Icon in Object browser needs to distinguish between zero children and children not yet loaded.
3. If no objects in hierarchy, does not unload prior account
4. Reselecting account should reload objects (or does this already happen?
5. Creating objects whose parents are not null yet do not exist should raise an error. Confirm that this is the case.
6. Consider adding the generic event "NoEffect" for events that have no effect upon an object yet are worth sending notifications on.
7. Enable BiffArray to find sounds/icons regardless of where it is running from