National Center for Supercomputing Applications

University of Illinois

605 East Springfield Ave

Champaign, IL 61820

Copyright 1995-2001, Board of Trustees of the University of Illinois, All Rights Reserved

NCSA Habanero software, binary, Java-bytecode, and source (hereafter, Software) is copyrighted by The Board of Trustees of the University of Illinois (UI), and ownership remains with the UI.

The UI grants you (hereafter, Licensee) a license to use the Software for academic, research and internal business purposes only, without a fee. Licensee may distribute the binary and source code (if released) to third parties provided that the copyright notice and this statement appears on all copies and that no charge is associated with such copies.

Licensee may make derivative works. However, if Licensee distributes any derivative work based on or derived from the Software, then Licensee will (1) notify NCSA regarding its distributing of the derivative work, and (2) clearly notify users that such derivative work is a modified version and not the original NCSA Habanero distributed by the UI.

Any Licensee wishing to make commercial use of the Software should contact the UI, c/o NCSA, to negotiate an appropriate license for such commercial use. Commercial use included (1) integration of all or part of the Software into a product for sale or license by or on behalf of Licensee to third parties, or (2) distribution of the Software to third parties that need it to utilize a commercial product sold or licensed by or on behalf of Licensee.

UI MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THIS SOFTWARE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THE UI SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY THE USERS OF THIS SOFTWARE.

By using or copying this Software, Licensee agrees to abide by the copyright law and all other applicable laws of the U.S. including, but not limited to, export control laws, and the terms of this license. UI shall have the right to terminate this license immediately by written notice upon Licensee's breach of, or non-compliance with, any of its terms. Licensee may be held legally responsible for any copyright infringement that is caused or encouraged by Licensee's failure to abide by the terms of this license.

U.S. GOVERNMENT RESTRICTED RIGHTS

Trademarks

NCSA Habanero is a registered trademark of the Board of Trustees of the University of Illinois. All brand and product names are trademarks or registered trademarks of their respective holders.

Commercial Licensing, Questions, Comments, Suggestions

For information, contact the Principal Investigator, Larry S. Jackson

Installation and Configuration

ISAAC Services

The Habanero Server

The Habanero Client

File extensions

The Collaborative Tools

Appendix A

Appendix B

Appendix C

NCSA – SCS

NCSA Habanero v3.0

NCSA ISAAC Services v1.0

Habanero and ISAAC Working in Concert

A Summary of Habanero with ISAAC Services

A Summary of Habanero without ISAAC Services

System Requirements

Installing NCSA Habanero

• habanero.home - the directory where you put the Habanero classes and libraries

• dir.record - the directory where data will be recorded

• jini.lookup - defines the system hosting the Jini lookup services.

• rmi.codebase - Jini uses RMI which requires an httpd to run in the background. RMI uses it to share classes between your system and the Jini services. The port where the server runs is user definable.

• classfileserver.port - defines the port number you will use for the background httpd.

• dir.resources - defines the directory where temporary application resources can be stored. This directory is typically a sub directory of your habanero.rsc

• dir.scratch - defines the directory where temporary files are downloaded from the logical database (LDB).

1. Create a script that will launch the Habanero client and server. This script or batch file establishes the proper environment for the program, calls the Java interpreter with the proper class file.

Habanero Script Examples - Windows (NT, 98/95)

• When defining a path do not use carriage returns (CR) or line feeds (LF).
• Try to avoid white space when defining the path.

• Make sure the scripts have the execute permission.

• If white space exists in the path statement you may have to double quote the path string. For example: "c:\program files\ncsa\habanero3.0"

UNIX - A C-Shell style script for the Habanero Client

The NCSA owned files for the ISAAC services are available in the /isaac directory of the Habanero package. Each service is self-contained in its own sub-directory. There are four services and sub-directories that include Asynchronous (async), Logical database (ldb), Notification (notification), and Persistent Object Store (pos). Each directory contains the necessary classes, property files and sample scripts for the service. There is also an /isaac/scripts directory that contains sh scripts for Unix. These scripts start and stop the services, redirect the stdout and stderr messages into log files found in /isaac/scripts/logs and track the process IDs in the /isaac/scripts/PIDs directory.

The ISAAC services are dependent on classes from Habanero’s /ncsa/isaac directory and other 3^rd party software packages. We assume you will run ISAAC on a system where these classes and packages are available. The services run as stand-alone processes on any system that is correctly configured and connected to the Internet. The list of ISAAC dependencies include:

Java Servlet v 2.0 http://java.sun.com/products/servlet/index.html

Installation of each service involves:

• installing Habanero 3.0 and Jini v1.0
• obtaining and installing the 3^rd party software listed above
• following the installation and configuration outline for each service.

The following sections will describe the installation process for each ISAAC service.

Notification Services (NOTIF)

The files for the asynchronous services are located in the /isaac/notif directory. The async service is dependent on the following 3^rd party components:

UNIX - Edit the scripts found in /isaac/scripts directory.

Persistent Object Store (POS)

The files for the asynchronous services are located in the /isaac/pos directory. The async service is dependent on the following 3^rd party components:

UNIX - Edit the scripts found in /isaac/scripts directory.

Logical Database (LDB)

The files for the asynchronous services are located in the /isaac/ldb directory. The async service is dependent on the following 3^rd party components:

3. Configure the start-up scripts.

UNIX - Edit the scripts found in /isaac/scripts directory.

The asynchronous services files are located in the /isaac/async directory. The async service is dependent on the following 3^rd party components:

1. Define a directory for the ISAAC services. i.e. /usr/local/etc/habanero/isaac
2. Download and install Jigsaw v2.10, Java Servlet v2.0, Stored Objects into the /isaac/async directory.
3. Install Java Mail v1.1.2
1. Either move mail.jar file into the /isaac/async directory or include its current path in the CLASSPATH statement of the async script.
4. Install Java Beans Activation Framework v1.0.1
1. Either move the activation.jar file into the /isaac/async directory or include its current path in the CLASSPATH statement of the async script.
5. Edit the services.props file in the /isaac/async/service.rsc directory to reflect your system’s information.
6. Verify and edit the following files to make sure your systems name and its resource locations are correct. By default these files assume all resources are available from the /isaac/async directory.

• async.bat - is the windows startup batch file. Change the CLASSPATH statement so it reflects the correct paths for the jar files defined above.
• initializeDB and inititializeDB.bat – These scripts are used for building the stored Objects database (The script invokes a Habanero Isaac class file that reads MAIN.SETUP and uses NoteRec.java to generate MAIN.DB, MAIN.DBM and NoteRec_DB.java)
• MAIN.SETUP - is used by stored objects and is set with the class/fields for ISAAC.
• jiginstall* once the Jigsaw tar or zip files are unpacked, this script will configure Jigsaw for the host machine (i.e. set paths, system properties, etc...)
• killjig* - scripts for stopping Jigsaw
• NoteRec.class - is the java class whose instances are stored.

1. Configure the start-up script files.

The start sequence is important because of interdependencies. The Jini services must start first and then the ISAAC services. The ISAAC Async service is also dependent on a db and jigsaw processe. Scripts have been written to help simplify this process. Each service contains scripts in their respective directories. And a central script directory contains the necessary scripts for Jini and ISAAC. If tThe initital start-up should be performed While each service has its own start-up script, it is recommended you use the scripts that were provided and edited by you during the installation process. The scripts are platform specific and include:

Windows (NT, 98/95) - use the start_ISAAC_svcs.bat

UNIX - use the startAll script in the /isaac/scripts directory.

Manual Start Sequence for ISAAC:

¨ Start the httpd server that is used by RMI (/scripts/jini/start_rmid_run.bat)

¨ Start RMI daemon (/scripts/jini/start_httpd_srv.bat)

¨ Start Jini lookup service (/scripts/jini/start_jini_lookup.bat)

¨ Start xaction service (/scripts/jini/start_xaction.bat)

¨ Start ISAAC notification service (/scripts/isaac/start_notification.bat)

¨ Start ISAAC pos service (/scripts/isaac/start_pos.bat)

¨ Start ISAAC ldb service (/scripts/isaac/start_LDB.bat)

* you should see one or all of the following messages:

Type 'q' <enter> to shutdown LDB Service

Type 'r' <enter> to rebuild the database

Type 'l' <enter> to see how many lookups have been joined VerifyTimer.run()

Type 'v' <enter> to correct and verify session status

* first time users should select r to build the tables in the db.

¨ Start ISAAC async service

* NOTE: The following scripts need to run before you start the Async service

1) initialize the db (/isaac/async/initializeDB.bat)

2) start Jigsaw (/isaac/async/jigsaw/scripts/jigsaw.bat)

3) start async (/scripts/isaac/start_Async.bat)

When terminating services you should type 'q' <enter> in the console window if possible. Doing this allows the service to unregister itself with Jini. If you use control-c instead, it will take Jini a few moments realize that the service is down and unregister it.

The asynchronous services of ISAAC are described, and illustrated with AVI movies, on the ISAAC project website. The asynchronous service of the ISAAC environment make it possible for a participant to leave an active session and still keep in-touch with the session events through a web browser. When a user leaves a session using the "Make Asynchronous" option from the Connect, Leave and... menu, the session's server sends the events for that client to the LDB marked with the user's ID and the session name. The user can then view these events from a web page on a predefined site.

To gain access to the data a user has to log into the web site by entering their participant name from the Habanero ID card and leaving the password blank. The password capability was not implemented for the 3.0 alpha release and only a valid user id is required to gain access to the data.

After a session name is selected the servlet again queries the LDB for the specific events related to that session name and time stamp and returns the session details in an HTML format.

Not all hablets produce asynchronous events -- special handlers are needed in the tools code so the event information is translated into a useable web format. Furthermore, not all hablets lend themselves to textual or visual representation of their events, such as the Audio Chat tool. Currently, only the whiteboard, text chat, mpEdit, and voting tool hablets provide asynchronous output. There are also session management events that get displayed such as participants leaving or joining the session. The async pages are designed to provide a user a very quick and easy to understand synopsis of what has occurred (is occurring) in the session.

The information available from the web page includes the user's name, session name, a time stamp of the session, an email address link back to the session, two sort options and a refresh capability. By pressing the "Refresh" button the user can get live updates of events as they are received from the session.

A capability of sending email to a session exists if the server is running with the mail server option. The async web page provides a mailto link back to the active session and allows async users to send email and attachments to the session. However, as mentioned above, the Habanero server hosting the session must be running with its mailserver option. See the Habanero Server section for more details about running a server with its mail server option.

When the mailto link is clicked, the local email program is invoked and will allow the user to send a message. If a default email program is not available, you can still send email to a session using the following email address format:

<sessionName>PORT<number>@server.name.hosting.the.session

i.e. Sample_SessionPORT2000@morefun.ncsa.uiuc.edu

Note: Underscores, _, are inserted in the place of white space.

i.e. Sample Session = Sample_Session

Note: The ability of a Habanero server may be hindered by local security policies. Not all email servers are configured to allow mail to pass to other systems within their domain. You may need assistance from your local network administrators to all this condition to exist for the machine hosting the Habanero server.

The email sent to a session is available to both active (synchronous) and inactive (asynchronous) participants. The active clients can view the email and attachments through the Habanero client. The inactive clients see the email and attachments as another event that has occurred in the session. The email attachments follow the same mime type rules, as do the session items in the LDB explorer and can be redirected to the appropriate tool for display.

Lastly, if an asynchronous service is not available when a participant goes asynchronous, the system will revert back to its default mode of sending asynchronous events via email to the users email address that is listed in user ID.

Overview

The Habanero server runs as a background process and does not have a graphical user interface (GUI). The process is started from a command line console and will display messaging about the state of the server, stdout, and error messages, stderr. The server has a variety of command line switches that will you to customize the behavior of the server. Once the server process is started, Ctrl + C is only command that the console window will accept and is used to terminates the server process. Under UNIX the Habanero Server can be run as a background process or in the foreground with the console window minimized. Under Windows, the console window This window can be minimizedIt is typically started from a counsel window and any all messages are displayed in the counsel. The server is the link between the clients and acts as a reflector of events to the various Habanero clients during a Habanero session. The server also interacts with the active tools of a session by providing arbitration. All tools use the server’s default arbitrator to distinguish tool events. Some tools have additional arbitrator code, which provides rules checking, locks and gateway services to the various tools. All tool arbitration code runs at the server side.

The Habanero server supports multiple sessions and distinguishes each session by name. The session names are case sensitive. Thus, the session, "Sample Session", is considered a different session from "sample session". All sessions are initiated through the client.

The server is instantiated from a script or the command line. See the installation instructions for details.

Server command-line options

The server supports additional configuration options through command line parameters or switch statements. You can us any number of the switches in any order. The switches include:

• -listen <port_number>
  The -listen argument allows you to define which socket the server will use to listen for data. If the switch is not used the server will use the default port 2000.

-mailserver

• -mailserver

The Habanero framework provides the ability to email a running session. The email message can then be read and attachments can be viewed by using Habanero's file extension capabilities.

NOTE: You may have to register your computer as a system that is authorized to receive mail. Contact your system administrator before using this service.

Use the following email address syntax to send email including attachments to a Habanero session.

For example:

NOTE: The blank spaces in the session name get replaced with underscores.

Primary controls

Many of the controls that can be accessed through the Menus can be accessed through the Toolbar as well. So I will cover the Menus themselves, and where appropriate, point out which Toolbar button does the corresponding action. It should be noted here also that most controls will have tooltips accessible by simply letting the mouse pointer linger over the desired control.

Physical Layout

The environment is broken up into three main areas. The right-hand side is the desktop, where the various information panels and other session specific panels can be viewed and arranged. This is also where the LDB Explorer resides.

The left-hand side consists of two portions. The upper section are session controls and LDB panels, the lower portion is the Tools Palette.

Session control and LDB view panels

Tools Palette Panel

The Tools Palette Panel consists of folders that contain the various synchronous collaborative applications that are available on this client. To open or close a folder, one simply double-click on the folder. In order to launch a given application while in a session, simply double-click on the application's icon. If you are in Template Mode, double-clicking on an applications icon will add it to the list of tools that are to be launched when the current session template is launched. This list of tools to associate with a template can be viewed by opening the Tools in use panel while the desired template is selected.

LDB Explorer

The LDB Explorer provides a way to view and interact with the items that are stored within the Logical Database. The tree control on the left half allows one to view the folders that exist. By selecting a given folder you can view the items in that folder. There is also an "All Items" folder that will allow you to view everything. The right hand side is a table that lists all the items that are contained in the currently selected folder. The buttons on the toolbar at the top of the explorer allow you to interact with the content. Add Item has presents a dialog that allows you to add to a folder for the current session (if you are in a session), an existing selected folder, or to a custom folder of your own. Delete Item removes the selected item from the LDB. Neither of these two buttons use access control so anything that is added or deleted is seen by everyone. Save Locally allows you to save the selected item to your local machine. Load Item attempts to load the selected item by using information from the client's mime type browser.

The explorer is also Drag and Drop enabled. To add an item to a give folder, you can drag the item and drop it on the desired folder, or drag it onto the table portion and drop it into the currently selected folder.

Telnet

Habanero Conversion by NCSA

Chat

This is no ordinary chat tool. This Chat window does not utilize IRC for communication, but uses the Habanero object sharing mechanism. It also has the ability to log a chat session for future reference.

Author: NCSA

Copyright 1996-1999 University of Illinois

My Neighborhood

This tool allows you to share the contents of a folder during a session. Files can be transferred between session participants using this tool.

Clip-N-Ship

This tool allows for individual files sharing and dynamic installation of new hablets.

Hablet created by NCSA

Copyright 1996-1999 University of Illinois

MpEdit

Habanero Conversion by NCSA

Molecule Modeler

The Molecular Modeler (Java Lattice Crystallographic Tool) was designed to skeletally view model .pdb (protein data bank files) molecules in 3-dimensions. The original applet is by Tony Fu, while he was at the Department of Biochemistry & Molecular Biology of the University of British Columbia, Vancouver B.C.. The NCSA staff converted the applet to the Habanero framework and made a change to allow the buffering of events to permit faster manipulation of the image.

Original Author: Tai Y. Fu (Tony) Copyright © 1997 Tai Y. Fu

Habanero Conversion by NCSA

VNC

Hablet Conversion by NCSA

The Voting Tool

The Voting Tool brings democracy to a collaborative session. The initiator of the vote defines the question, the answer mode (Yes/No, %, multiple choice), the choices when necessary, and if the result information is anonymous. Once a vote is defined, the group receives a vote window. After the vote is complete each member receives a result window displaying the vote count.

Hablet created by NCSA

Copyright 1996-1999 University of Illinois

WhiteBoard

A tool capable of reading .gif, .jpg & .ppm files both locally and from a URL.  It includes a Microsoft Power Point Presentation mode and contains a variety of drawing tools to mark, manipulate, annotate and save the image as a jpeg.  The Whiteboard is a layered drawing tool, which means that objects in the Whiteboard can be moved independently from each other.

Hablet created by NCSA

Copyright 1996-1999 University of Illinois

The Demos Folder

The demos include a Calculator, BeZier Plane Simulator, Checkers, Scribble pad, VRML 1.0 Viewer, Tic Tac Toe and the Visible Human.

The Life of a Habanero Event

Habanero uses event replication as its mode of synchronization. Events that are generated in Hablets are caught (before they can act in the Hablet) and sent to the server where they are routed to each client.

From Hablet to Server

The GUI environment of java is event driven. Events that are generated by a mouse click etc… are processed asynchronously by passing the event to an event queue. The event dispatch thread is responsible for taking events from the queue and processing them. For example, when a user clicks on a menu bar an event is generated which goes to the event queue where it is processed by the event dispatch thread causing the submenu drop down list to be displayed.

Habanero 3.0 replaces the event queue in the JVM with its own event queue subclass. Each event that is placed on the event queue is analyzed to see if it is an event that originated at a hablet and therefore needs to be captured. The hablet programmer has the ability to define exactly which events are to be caught this way by defining shipping decision rules. Also, the hablet programmer can send internally generated events directly to the server thereby completely bypassing the event queue mechanism. Events that are caught are forwarded to the client side framework for shipment to the server, but before they can be sent they are wrapped in a StandardActionRequest object.

Every hablet, upon its instantiation on the client side, is assigned an arbitrator. The arbitrators on the client side are usually of the class DistributedArbitrator. The event, after removal from the event queue, is sent to this arbitrator where, in most cases, it is simply passed through. However, some events that are sent from hablets, like floor control events, might not be intended for routing to other clients or may expect an immediate answer form the server. The client side arbitrator is the locus of control for such interactions on the client side.

On the client side events leaving the DistributedArbitrator are next sent to the Session object which in turn forwards them to the communication manager (ClientListenerManager). The communication manager maintains the list of listeners (sockets to the server) for each session. Every session has one main session socket, but hablets can elect to have their own private sockets for efficiency purposes. The communication manager makes sure that the event is sent to the appropriate socket object based on the hablet from which it came.

The socket object (i.e. ClientListener) pushes the object through the socket to the server; however, the object must first pass through several layers of stream objects where additional processing occurs before the object is actually passed out of the client. The Habanero framework contains a rich set of stream classes that can record events, and replace event components for efficient transfer. For instance, Habanero stream classes are used to intercept the event target objects (usually a GUI component) and replace them with a specifier string that can be safely de-serialized on the server side (where no GUI display is active). The specifier string is a means of coding exactly which component in the hablet’s GUI hierarchy should receive this event. Since it is assumed that all of the instances of a hablet on each client are structurally identical, the specifier string is a reliable way of targeting the event to the exact same GUI component on every client. This makes the framework easier to use for the hablet programmer but imposes a certain homogeneity on each client environment. For example, a Chat hablet, running on a PC platform, would probably not be compatible with the same hablet on a handheld device, unless they each used the identical GUI structure and framework code.

As briefly mentioned above, the stream classes are where events are intercepted for recording or other purposes. When recording, events are captured in stream objects as they enter the client from the server. A special stream class called a SplitterStream is used to route events to any number of "observer" classes – memory and/or file recorders being just two examples.

The Journey through the Server

On the server side, events are received in a socket object called a RequestHandler. RequestHandlers are managed by a ServerListener, which in turn, is managed by the ServerListenerManager. In the server, like the client, a group of ServerListeners is defined for each session (one default listener for the session and additional listeners for each hablet that requires its own). Each ServerListener maintains a group of RequestHandlers – one handler for each client in the session.

When events leave the client, the events’ targets (usually a GUI component) are converted by the stream classes into a string structures called a specifiers. When the RequestHandler receives a new event, it decodes this specifier string for the target to determine where to send the event. Within the specifier string is coded the name of the hablet to which it is targeted. Whenever a hablet is started on a client, a hablet object (called a Collobject) and an arbitrator object are started on the server. The server uses the specifier string to identify the abitrator object for that hablet on the server side and sends it the event.

For simple hablets the arbitrator on the server side is nothing more than a router (called a CentralArbitrator). For more complex hablets, needing floor control or other special centralized operations, the hablet programmer can create a subclass of CentralArbitrator and implement a customized event handling mechanism. Hablets like whiteboard use such arbitrators for floor control as previously mentioned. Other hablets like VNC and telnet use special arbitrators that establish one connection to an external resource to be shared by all clients.

Once the arbitrator has finished processing an event it wraps the event in an ActionGranted object and assigns it a ticket number. The ticket is used to ensure that events that are sent to clients arrive and are processed in the proper order. Once a ticket has been assigned, the event is passed to the ServerListener then to the RequestHandler for socket transmission.

Back to the Client(s)

The ClientListener object on the client side receives events from the server. The stream classes on this socket de-serialize the event target and any other objects that are marked with the Specifiable interface. Just as on the server, an arbitrator associated with the target of this event is identified and the event is passed to this arbitrator (DistributedArbitrator) for delivery. The arbitrator passes the event to a Serializer object which checks that the event is serialized properly (based on its ticket number). If an event is received out of order then it is placed on a special wait queue where it is eventually processed when order is re-established. If the event is in order, the Serializer places it on the event queue for processing.

What is actually placed on the event queue at this point is not the event itself but the event wrapped in an ActionGranted object. When the event queue dispatches the ActionGranted, it passes control to the action’s ticket object which in turn calls the act method of the action. The act method of the action then takes the original event and dispatches it to the event queue. Now the event is processed normally as if it had never left the client.

Conclusion

The above describes the journey of a typical event through the Habanero framework. There are of course many exceptions that have to do with special events or session control events that have not been described here. There also exists a communication channel for servers and clients that is not a part of the event routing mechanism. Each SessionManager object (one per server and client) has its own socket for sending messages concerning the management of sessions (creation, joining, leaving). This socket is independent of sessions and therefore exists outside of the listener framework (which is managed by Session objects).

Adding Asynchronous Capability to a Hablet

Before you attempt to provide your tool an asynchronous capability you must realize not all tools have viewable components. The events that are saved must be viewable or accessible through a web browser interface. If the ISAAC services are available, the addition of an asynchronous handler will send clients session events to the LDB after the person leaves the session. Then this person can access the events from a predefined web site using a browser.

The asynchronous handler code is outlined in the following steps:

The sample uses the asynchronous handler for the Chat tool. First, create a new class, ChatAsynchronousHandler.java. The new class handler should implement AsynchronousHandler. For example:

public class ChatAsynchronousHandler implements AsynchronousHandler {

The new class should include the following import statements and functions:

import ncsa.habanero.*;

import ncsa.env.abstraction.Mail;

import ncsa.env.abstraction.InfoPart;

import java.awt.event.ActionEvent;

import ncsa.isaac.notification.*;

import java.rmi.MarshalledObject;

import java.rmi.RemoteException;

import net.jini.core.lookup.*;

import net.jini.core.entry.*;

import net.jini.core.discovery.*;

import net.jini.lookup.entry.*;

import net.jini.discovery.*;

The new class should also include the following methods and fields. Refer to the sample code found at the end of this section for implementation details.

package Chat;

import ncsa.habanero.*;

import ncsa.env.abstraction.Mail;

import ncsa.env.abstraction.InfoPart;

import java.awt.event.ActionEvent;

import ncsa.isaac.notification.*;

import java.rmi.MarshalledObject;

import java.rmi.RemoteException;

import net.jini.core.lookup.*;

import net.jini.core.entry.*;

import net.jini.core.discovery.*;

import net.jini.lookup.entry.*;

import net.jini.discovery.*;

/**

* This is the class that adds the asynchronous feature to a hablet.

*

* @author NCSA Habanero

* @version 1.0

* @since JDK1.0

*/

public class ChatAsynchronousHandler implements AsynchronousHandler {

private static final long serialVersionUID = 8112623508265000394L;

/**

* Publisher that dispatches the event

*/

Publisher PUB = null;

/**

* flag used to determine if event sent using mail

*/

boolean mailflag = false;

/**

* a reference to a Session

*/

Session toolSession = null;

/**

* Constructor

*/

public ChatAsynchronousHandler() { PUB = getPUB(); }

/**

* function to set the Session

* @param s reference to the particular Session

*/

public void setSession(Session s) { toolSession = s; }

/**

* function that handles which events get dispatched

* @param action the action that has taken place

* @param to the destination of the action

* @param from the source of the action

* @return boolean to say if the event has been handled successfully

*/

public boolean handle(Action action, SessionParticipant to, SessionParticipant from) {

if (mailflag) {

return sendByMail(action, to, from);

} else {

ActionEvent e = (ActionEvent)((AWTEventAction)action).getAWTEvent();

ISAACNotification inot = new ISAACNotification();

inot.setType("ASYNCH");

inot.stampDate();

//session name

if (toolSession == null){

inot.add("session_name","unknown");

} else {

inot.add("session_name", toolSession.getCollectionName());

}

//from name

inot.add("from_name", from.getName());

//action description

inot.add("action_description",e.getActionCommand());

//tool name

inot.add("tool_name", "Chat");

System.out.println("Sending ASYNCH notification");

try {

getPUB().sendNotification(inot);

} catch (Exception e1) {

PUB = null;

try {

getPUB().sendNotification(inot);

} catch (Exception e2) {

return sendByMail(action, to, from);

}}

return true;

}

}

/**

* function to send the asynchronous notification through email

* @param action the action that has taken place

* @param to the destination of the action

* @param from the source of the action

* @return boolean to signify if the action was sent as mail successfully

*/

protected boolean sendByMail(Action action, SessionParticipant to, SessionParticipant from) {

try {

Mail m = new Mail();

ActionEvent e = (ActionEvent)((AWTEventAction)action).getAWTEvent();

Habanero.println("sending chat to " + to);

m.send(((InfoPart)to).getEmail(),

"Chat from " + from.getName(),

e.getActionCommand());

return true;

} catch (Exception e) {

}

return false;

}

/**

* function to obtain the Publisher

* @return Publisher

*/

protected Publisher getPUB()

{

PUB = SessionManager.getManager().getPUB();

if (PUB == null) {

System.out.println("PUB is null: Chat asynchronous notifications will be sent using email");

mailflag = true;

}

return PUB;

}

}

Creating a Hablet that can open File Extensions:

In order to give your hablet the ability to open file extensions you will have to follow these steps:

In the constructor of your Properties class you will have to add the following line:

In the class that either extends ncsa.habanero.Hablet or implements ncsa.habanero.Wrapped you will also have to implement ncsa.mime.MimeLoadable. This requires that this class implements the following methods:

This method gets called right after a Hablet is instantiated and it contains a file that needs to be opened. The MimeFileObject will contain the file name and an associated InputStream with its contents.

public String getMimeType() This method should return the types of files that the hablet can open. Separate each type with a semicolon.

The MimeFileObject has one method and one field that will help out with loading it:

This method returns an InputStream that represents the file's bytes.

A String that represents the name of the file to be loaded.

Launching a File's Application:

There are two methods you can call to load a file's associated extension application but you need to get a MimeAssociations file first. You can do this by calling the following method:

This static method will return a MimeAssocations object that will allow you to call the following methods in order to load a file:

• public void launchFile(String fileName, InputStream fileBytes) Given a file's name and an InputStream that represents its bytes, its extension's associated application will be launched.
• public void launchFile(File f) Given a java.io.File object, its extension's associated application will be launched.

If an application hasn't been associated with an application a browser will be launched where you can set the appropriate application.