[ Download ] [ User Docs ] [ FAQs ] [ Home ] [ Dev API ] [ Tools ] [ License ]
This glossary provides the key methods that you will need to use to write a Hablet. Click on the any method below to get a better description of it.
Habanero Class Methods
The ncsa.habanero.Habanero class offers several static methods that allow hablet developers to access the Habanero framework in several ways (ie. determining the characteristics of event, setting an event type to be shared, sending an arbitrary AWTEvent to be shared, and setting and loading a clipboard image).
static public boolean isLocalEvent()
This static method is used to determine whether or not an event has been passed to an event method from the hablet or from the Habanero framework. Returns true if the event has originated from the hablet, false if it originates from the framework.
static public Object getCurrentArg()
This method returns on object that was included as an arg in the Habanero method sendEvent. It is not recommended to use this method - subclassing an AWTEvent to include an Object argument and sharing it via the sendEvent method is the preferred way of sharing an Object.
static public Object getSource()
This method returns the source of the current shared event. NOTE: the source Object returned is not the original component from the initiator's client, but the equivalent component for each individual user. This method is used to replace the AWTEvent.getSource() method which returns null after passing through the Habanero framework.
static public void addSharedEventType(Class eventType, Mirrorable m)
static public void addSharedEventType(Class eventType, int id, Mirrorable m)
This method is used to register a particular event as a shared event. It is usually called in the startInFrame method of any class that implements the Wrapped interface, like the Hablet class. eventType refers to the class of the event to be shared and is usually created with the Class.forName(String className) method. id is used when you want to share a specific id for the eventType you want to share. m refers to the a Mirrorable object which in most cases will be the Hablet in which startInFrame is implemented
static public void addShippingDecision(ShippingDecisionFunction fn, Mirrorable m)
This method allows for an alternate way of sharing events in Habanero. As with the addSharedEventType method, this is usually called in the startInFrame method of a class implementing the Wrapped interface. fn is a class that implements ShippingDecisionFunction that controls which events should be shared and which shouldn't. You need to write your own extension of this class and add instance of it to this first argument. The second argument, m, refers to a Mirrorable object which in most cases will be the Hablet in which startInFrame is implemented.
static public void setClipboard(ncsa.awt.draw.ImagePrimitiveP clipboard)
The whiteboard hablet included with Habanero allows a clipboard image to be
loaded onto its canvas. Using this method you can load an ImagePrimitiveP object like a FileImagePrimitive or a URLImagePrimitive onto that clipboard for use with other hablets.
static public ncsa.awt.draw.ImagePrimitiveP getClipboard(){
Call this method to return the image currently in the Habanero clipboard, which can then be used in any hablet.
Returns the id of this object, which is the hostname + listening port. This id allows you to get a SessionParticipant object for the corresponding user.
static public void sendBeep(SessionParticipant p)
This will send a system beep to the session participant referred to in p.
static public boolean sendEvent(AWTEvent event)
static public boolean sendEvent(AWTEvent event, Object arg)
This method sends an AWTEvent, event, to the framework so that is shared with the other participants. This is useful when an event needs to be shared in very specific instances and not all of the time. arg can be a state object that needs to be shared with the event. Use getCurrentArg() to retrieve this object.
Wrapped Interface Method
The main container of your hablet must implement the ncsa.habanero.Wrapped interface. ncsa.habanero.Hablet already implements this so it is good idea to extend this class when preparing your main container. This interface contains only one method that is necessary to register your hablet with the habanero framework, but it does extend the Marshallable interface which we will go over later on.
void startInFrame(MirrorFrame f)
This method is called when a hablet is first instantiated. Generally what you want to do in this method is make sure the hablet is constructed properly, determine which events are to be shared and finally show the MirrorFrame, f, by using f.setVisible(true). If your hablet is an extended applet than it is a good idea to call the init() method of the applet here as well. When this method is called when a participant is joining a session already in progress the init() method shouldn't be called because it will most likely create an instance of the main container that can't share its state with other participants. Before showing the MirrorFrame be sure that your main container has been added to it.
Marshallable Interface Methods
This is the interface any object which needs to be marshalled (ie sent across the network) has to implement. The marshallable interface extends the Serializable interface which contains 2 methods used in the Serialization process. It is a good idea to have any classes other than your Hablet class implement this interface. Basically, writeObject should snapshot the state in such a way that readObject can recreate that state in a new object.
private void writeObject(java.io.ObjectOutputStream out)
This method performs any necessary cleanup or preperation for serialization, which occurs when an object is shared in Habanero. Generally it will call defaultWriteObject, but if you want to customize how your class is shared you will need to override this method. Remember that all of the transient fields should not be included in this method.
private void readObject(java.io.ObjectInputStream in)
This method intializes an object from serialization. It is called when users receive and object. You can call defaultReadObject here, but you'll need to override it if you want to specify exactly how you want to read in the data. NOTE:The order of reading in must equal the order of writing in the writeObject method.
Hablet Class Methods
The ncsa.habanero.Hablet class was created as a way to make the conversion of applets to Hablets much easier. It provides some overrides of the applet class methods as well as several helper methods to allow the reading and writing of its state when new participants join. The writeHablet and readHablet methods are essential to preserving the collaborative state of the object. By extending Hablet instead of Applet, it will be much easier to convert an existing applet.
protected void writeHablet(MarshallOutputStream out)
When someone joins a session already in progress, this method is called from
the hablet instantiator's session. You must determine which instance variables need to be shared in order to share the state of the hablet, and using java.io.ObjectOutputStream methods, write those variables to out.
protected void readHablet(MarshallInputStream in)
Whoever joins a session in progress has this method called. Essentially this takes the place of the constructor. You are not creating a brand new instance of the hablet, you are copying an existing instance. Thus using methods from the java.io.ObjectInputStream class you need to recreate the state of the hablet. NOTE: The objects must be read in in the same order as they were written in the writeHabletMethod.
public Image getImage(URL url, String name)
public Image getImage(URL url)
public Image getImage(String name)
These methods override the getImage methods from the java.applet.Applet class that would throw exceptions if called in the Habanero environment. These use the default toolkit in order to load the Image objects.
ShippingDecisionFunction Interface Method
You must create a class that implements this interface if you are planning on using the ncsa.habanero.Habanero. addShippingDecision method to control the sharing of events. The ship method determines which events will be shared and which will not.
public boolean ship(java.awt.AWTEvent event)
This method determines which events a hablet will be sharing with the other session participants. It will return true if the event argument meets the conditions you require to share it, otherwise it will return false.
FileImagePrimitive Class Methods
This is one of the classes that we created in order to allow the ability to share images that are transient by nature and cannot be serialized. FileImagePrimitive deals with images that are created from file names.
public FileImagePrimitive(String fn)
These are constructors for the FileImagePrimitive class. The first constructor will require a call to the newImage method in order to create an actual image while the second one creates an image from the full filename in the argument fn.
This returns the Image object that is referenced by the FileImagePrimitive.
public int getImageHeight()
Return the width and the height of the image, respectively.
URLImagePrimitive Class Methods
This is the second of the classes that we created in order to allow the ability to share images that are transient by nature and cannot be serialized. URLImagePrimitive deals with images that are created from URL objects.
public URLImagePrimitive(URL url)
These are constructors for the FileImagePrimitive class. The first constructor will require a call to the newImage method in order to create an actual image while the second one creates an image from the full filename in the argument fn.
This returns the Image object that is referenced by the FileImagePrimitive.
public int getImageHeight()
Return the width and the height of the image, respectively.
MirrorFrame Class Methods
This is a window which knows how to send events over the Internet. The idea is that events travel up the component hierarchy until they arrive here, and are then checked to see if they should be sent. You can specify the type of Event to be sent - the default is that only ACTION_EVENTS are sent. Habanero creates these internally - as a rule, someone writing a * collaborative application does not have to make any. The ncsa.habanero.MirrorFrame class offers two methods that return either a specific unique id of the frame or the Collobject that the frame is using.
This method returns a String id that allows users to differentiates between MirrorFrames.
public Collobject getCollobject()
Returns the Collobject that pertains to the MirrorFrame.
Collobject Class Methods
A Collobject generally wraps a previously invented application, which exists in a frame. The Collobject has its own Arbitrator. Generally, the Collobject creates a frame to display the wrapped object, although if the object is already a frame, the Collobject doesn't bother. We consider the wrapped object to be a view on the Collobject, and it is possible for there to be more than one (with different display attributes, for example).
public Arbitrator arbitrator()
This returns the Arbitrator which corresponds to the collobject. You need to call this in order to send Lock requests and releases to the Arbitrator.
This returns a Session object the pertains to the current collaborative session.
This method will close the Hablet that corresponds to the Collobject.
public void registerIdentifiable(Identifiable i)
This registers a class that implements the Identifiable interface, thus allowing for the sharing of events.
public void unregisterIdentifiable(Identifiable i)
This unregisters a class that implements the Identifiable interface, thus preventing the sharing of events.
public SessionParticipant originator()
This returns a SessionParticipant which is the user that created the hablet that pertains to the current Collobject.
Session Class Methods
The Session class represents a set of Collobjects which are being used by (and thus available to) a set of participants. In particular, all participants see all of the Collobjects, and the Session is the ancestor (probably the parent in most cases) of all of the Collobjects.
This returns the name of the server.
This returns the time that the session was started.
public void postMessage(ServerMessage message, Arbitrator from)
public void postMessage(ServerMessage message, Arbitrator from, String strWho)
This method will post a server message to participants. If strWho is one of the arguments, then the message is only sent to the user specified in strWho. This method can only be called from an arbitrator.
public synchronized SessionParticipant getParticipant(String id)
This will return a SessionParticipant object pertaining to the id argument.
public synchronized boolean containsParticipant(SessionParticipant p)
This determines whether a SessionParticipant is a member of the current Session.
public synchronized Enumeration getParticipants()
public Enumeration getParticipantList()
This returns an enumeration that is a list of all of the SessionParticipants of the current Session.
This returns a String that identifies the current session.
public SessionParticipant owner()
This returns the person that started the current Session or the oldest member of the Session if the creator has left.
Arbitrator Class Methods
The Arbitrator is the abstract superclass for all floor control objects. The basic idea is that an Arbitrator is sent an ActionRequest. After some sort of checking or negotiation, the Arbitrator grants the request, creates an ActionGranted, and sends that to a router.
public Key getLock (Lock lkdNew)
public Key getLock (Lock lkdNew, Key oldKey)
This method is called when a client requests a specific type of Lock. A key is returned by the arbitrator that says whether the lock was granted. For example if I wanted to get a Lock on mouse movements, I'd extend Lock to create an object called MouseLock. If the arbitrator granted the lock it would return a Key with a value larger than -1. Otherwise it would return Key.NoKey. oldKey would be needed to compare the current key with another one.
public void releaseLock (Key lkFinished)
This method is called when a client wants to release a lock they currently have. The key received in getLock would be the argument for lkFinished. The arbitrator would compare the current key with lkFinished and would then release the lock if they were equal.
This returns a Session object the pertains to the current collaborative session.
public boolean arbitrate(ActionRequest request)
This method determines whether or not an action is to be executed. This all depends on the locks that pertain to the arbitrator's hablet.
When a hablet is closed, its arbitrator's stop method is called. Use this to stop any threads or to deinitialize any objects pertaining to the arbitrator.
Shutdownable Interface Methods
When closing a Hablet it should have a Shutdownable interface that sets instance variables to null and destroy any sockets, windows or bitmaps. Each Hablet inplements its own version of shutDown() specific to the application.
public void shutDown()
This method is called when a hablet is being closed.
Identifiable Interface Methods
The Identifiable interface is intended for applications which have components which are not descendants of the Wrapped object and require the handling of shared events. If so, there must be an ancestor which implements the Identifiable interface. Any class implementing Identifiable must be registered with a Collobject to enabled sharing of events.
This method should return an ID that differentiates between all of the other objects that implement this interface.
SessionParticipant Class Methods
The SessionParticipant object identifies a particular client within the collaboration.
Returns a unique identifier for this participant.
Returns the name of the host this participant is on.
Returns this participant's port in String form.
Returns this participant's port in int form.
Returns the name that the participant entered in their id card.
public boolean isValidAddress()
Determines whether or not the particpant's address actually exists or is working.
Habanero® is a registered trademark owned by The Board of Trustees of the University of Illinois. Copyright 1996-1998. All rights reserved. Java(TM) is a proprietary trademark owned by Sun Microsystems, Inc.