com.ibm.aglet
Class Aglet

java.lang.Object
  extended bycom.ibm.aglet.Aglet
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
Messenger, Notifier, Slave

public abstract class Aglet
extends java.lang.Object
implements java.io.Serializable

The Aglet class is the abstract base class for aglets. Use this class to create your own personalized aglets.

Version:
2.00 $Date: 2001/07/28 06:33:50 $
Author:
Danny B. Lange, Mitsuru Oshima
See Also:
Serialized Form

Field Summary
(package private)  AgletStub _stub
           
static int ACTIVE
          State of Aglet.
private  CloneListener cloneListener
           
static int INACTIVE
           
static short MAJOR_VERSION
           
static short MINOR_VERSION
           
private  MobilityListener mobilityListener
           
private  PersistencyListener persistencyListener
           
 
Constructor Summary
protected Aglet()
          Constructs an uninitialized aglet.
 
Method Summary
 void addCloneListener(CloneListener listener)
          Adds the specified clone listener to receive clone events from this aglet.
 void addMobilityListener(MobilityListener listener)
          Adds the specified mobility listener to receive mobility events from this aglet.
 void addPersistencyListener(PersistencyListener listener)
          Adds the specified persistency listener to receive persistency events from this aglet.
 java.lang.Object clone()
          Clones the aglet and the proxy that holds the aglet.
 void deactivate(long duration)
          Deactivates the aglet.
 void dispatch(Ticket ticket)
          Dispatches the aglet to the location (host) specified by the ticket as argument.
 void dispatch(java.net.URL destination)
          Dispatches the aglet to the location (host) specified by the argument.
 void dispatchEvent(AgletEvent ev)
          Dispatches an event to this aglet
 void dispose()
          Destroys and removes the aglet from its current aglet context.
 void exitMonitor()
          Exits the current monitor.
 AgletContext getAgletContext()
          Gets the context in which the aglet is currently executing.
 AgletID getAgletID()
          Gets the id of this aglet.
 AgletInfo getAgletInfo()
          Gets the info object of this aglet
 java.applet.AudioClip getAudioData(java.net.URL url)
          Gets an audio data
 java.net.URL getCodeBase()
          Gets the code base URL of this aglet
 java.awt.Image getImage(java.net.URL url)
          Gets an image
 java.awt.Image getImage(java.net.URL url, java.lang.String name)
          Gets an image
 MessageManager getMessageManager()
          Gets the message manager.
 java.security.PermissionCollection getProtections()
          Gets the protections: permission collection about who can send what kind of messages to the aglet
 AgletProxy getProxy()
          Gets the proxy of aglet.
 java.lang.String getText()
          Gets the message line of this Aglet.
 boolean handleMessage(Message message)
          Handles the message form outside.
 void notifyAllMessages()
          Notifies all of waiting threads.
 void notifyMessage()
          Notifies a single waiting thread.
 void onCreation(java.lang.Object init)
          Initializes the new aglet.
 void onDisposing()
          Is called when an attempt is made to dispose of the aglet.
protected  void processCloneEvent(CloneEvent ev)
          Processes clone events occurring on this aglet by dispatching them to any registered CloneListener objects.
protected  void processMobilityEvent(MobilityEvent ev)
          Processes mobility events occurring on this aglet by dispatching them to any registered MobilityListener objects.
protected  void processPersistencyEvent(PersistencyEvent ev)
          Processes persistency events occurring on this aglet by dispatching them to any registered PersistencyListener objects.
 void removeCloneListener(CloneListener l)
          Removes the specified clone listener so it no longer receives clone events.
 void removeMobilityListener(MobilityListener l)
          Removes the specified mobility listener so it no longer receives mobility events.
 void removePersistencyListener(PersistencyListener l)
          Removes the specified persistency listener so it no longer receives persistency events.
 void run()
          Is the entry point for the aglet's own thread of execution.
 void setProtections(java.security.PermissionCollection protections)
          Sets the protections: permission collection about who can send what kind of messages to the aglet
 void setStub(AgletStub stub)
          Sets the proxy for the aglet.
 void setText(java.lang.String text)
          Sets the text of this Aglet.
 void snapshot()
          [Preliminary] Save a snapshot of this aglet into a 2nd storage.
 void subscribeMessage(java.lang.String name)
          Subscribes to a named message.
 void suspend(long duration)
          This is an experimental feature.
 void unsubscribeAllMessages()
          Unsubscribes from all message kinds.
 boolean unsubscribeMessage(java.lang.String name)
          Unsubscribes from a named message.
 void waitMessage()
          Waits until it is notified.
 void waitMessage(long timeout)
          Waits until it is notified or the timeout expires
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAJOR_VERSION

public static final short MAJOR_VERSION
See Also:
Constant Field Values

MINOR_VERSION

public static final short MINOR_VERSION
See Also:
Constant Field Values

ACTIVE

public static final int ACTIVE
State of Aglet.

See Also:
AgletContext.getAgletProxies(), Constant Field Values

INACTIVE

public static final int INACTIVE
See Also:
Constant Field Values

_stub

transient AgletStub _stub

cloneListener

private CloneListener cloneListener

mobilityListener

private MobilityListener mobilityListener

persistencyListener

private PersistencyListener persistencyListener
Constructor Detail

Aglet

protected Aglet()
Constructs an uninitialized aglet. This method is called only once in the life cycle of an aglet. As a rule, you should never override this constructor. Instead, you should override onCreation() to initialize the aglet upon creation.

See Also:
onCreation(java.lang.Object)
Method Detail

addCloneListener

public final void addCloneListener(CloneListener listener)
Adds the specified clone listener to receive clone events from this aglet.

Parameters:
listener - the mobility listener

addMobilityListener

public final void addMobilityListener(MobilityListener listener)
Adds the specified mobility listener to receive mobility events from this aglet.

Parameters:
listener - the mobility listener

addPersistencyListener

public final void addPersistencyListener(PersistencyListener listener)
Adds the specified persistency listener to receive persistency events from this aglet.

Parameters:
listener - the persistency listener

clone

public final java.lang.Object clone()
                             throws java.lang.CloneNotSupportedException
Clones the aglet and the proxy that holds the aglet. Notice that it is the cloned aglet proxy which is returned by this method.

Returns:
the cloned proxy.
Throws:
java.lang.CloneNotSupportedException - when the cloning fails.
See Also:
CloneListener.onCloning(com.ibm.aglet.event.CloneEvent), CloneListener.onClone(com.ibm.aglet.event.CloneEvent)

deactivate

public final void deactivate(long duration)
                      throws java.io.IOException
Deactivates the aglet. The aglet will temporarily be stopped and removed from its current context. It will return to the context and resume execution after the specified period has elapsed.

Throws:
java.io.NotSerializableException - if the entire aglet is not serializable.
java.io.IOException - if I/O failed
java.lang.IllegalArgumentException - if the argument is negative.

dispatch

public final void dispatch(Ticket ticket)
                    throws java.io.IOException,
                           RequestRefusedException
Dispatches the aglet to the location (host) specified by the ticket as argument.

Parameters:
ticket - ticket to dispatch destination.
Throws:
ServerNotFoundException - if the server could not be found.
java.net.UnknownHostException - if the host given in the URL does not exist.
RequestRefusedException - if the remote server refused the dispatch request.
ServerNotFoundException - if the the destination is unavailable
java.io.NotSerializableException - if the entire aglet is not serializable
java.io.IOException
See Also:
MobilityListener.onDispatching(com.ibm.aglet.event.MobilityEvent), MobilityListener.onArrival(com.ibm.aglet.event.MobilityEvent)

dispatch

public final void dispatch(java.net.URL destination)
                    throws java.io.IOException,
                           RequestRefusedException
Dispatches the aglet to the location (host) specified by the argument.

Parameters:
destination - dispatch destination.
Throws:
ServerNotFoundException - if the server could not be found.
java.net.UnknownHostException - if the host given in the URL does not exist.
RequestRefusedException - if the remote server refused the dispatch request.
ServerNotFoundException - if the the destination is unavailable
java.io.NotSerializableException - if the entire aglet is not serializable
java.io.IOException
See Also:
MobilityListener.onDispatching(com.ibm.aglet.event.MobilityEvent), MobilityListener.onArrival(com.ibm.aglet.event.MobilityEvent)

dispatchEvent

public final void dispatchEvent(AgletEvent ev)
Dispatches an event to this aglet

Parameters:
ev - the aglet event

dispose

public final void dispose()
Destroys and removes the aglet from its current aglet context. A successful invocation of this method will kill all threads created by the given aglet.

See Also:
onDisposing()

exitMonitor

public void exitMonitor()
Exits the current monitor.

Throws:
java.lang.IllegalMonitorStateException - if the current thread is not the owner of the monitor.
See Also:
exitMonitor(), waitMessage, notifyMessage, notifyAllMessages

getAgletContext

public final AgletContext getAgletContext()
Gets the context in which the aglet is currently executing.

Returns:
the current execution context.

getAgletID

public final AgletID getAgletID()
Gets the id of this aglet.

Returns:
the AgletID object of this aglet
See Also:
aglet.AgletID

getAgletInfo

public final AgletInfo getAgletInfo()
Gets the info object of this aglet

Returns:
the aglet.AgletInfo object of this aglet
See Also:
aglet.AgletID

getAudioData

public final java.applet.AudioClip getAudioData(java.net.URL url)
                                         throws java.io.IOException
Gets an audio data

Throws:
java.io.IOException

getCodeBase

public final java.net.URL getCodeBase()
Gets the code base URL of this aglet

Returns:
the java.net.URL object of this aglet
See Also:
aglet.AgletID

getImage

public final java.awt.Image getImage(java.net.URL url)
                              throws java.io.IOException
Gets an image

Throws:
java.io.IOException

getImage

public final java.awt.Image getImage(java.net.URL url,
                                     java.lang.String name)
                              throws java.io.IOException
Gets an image

Throws:
java.io.IOException

getMessageManager

public final MessageManager getMessageManager()
Gets the message manager.

Returns:
the message manager.

getProtections

public java.security.PermissionCollection getProtections()
Gets the protections: permission collection about who can send what kind of messages to the aglet

Returns:
collection of protections about who can send what kind of messages to the aglet

getProxy

public final AgletProxy getProxy()
Gets the proxy of aglet.

Returns:
the proxy of aglet

getText

public final java.lang.String getText()
Gets the message line of this Aglet.

Returns:
the String representing a message the aglet shows.

handleMessage

public boolean handleMessage(Message message)
Handles the message form outside.

Returns:
true if the message was handled. Returns false if the message was not handled. If false is returned, the MessageNotHandled exception is thrown in the FutureReply.getReply and AgletProxy.sendMessage methods.
See Also:
FutureReply.getReply(), Message.sendReply(), AgletProxy.sendMessage(com.ibm.aglet.Message)

notifyAllMessages

public void notifyAllMessages()
Notifies all of waiting threads.

Throws:
java.lang.IllegalMonitorStateException - If the current thread is not the owner of the monitor.
See Also:
notifyAllMessages(), waitMessage, notifyMessage

notifyMessage

public void notifyMessage()
Notifies a single waiting thread.

Throws:
java.lang.IllegalMonitorStateException - If the current thread is not the owner of the monitor.
See Also:
notifyMessage(), waitMessage, notifyAllMessages

onCreation

public void onCreation(java.lang.Object init)
Initializes the new aglet. This method is called only once in the life cycle of an aglet. Override this method for custom initialization of the aglet.

Parameters:
init - the argument with which the aglet is initialized.
See Also:
AgletContext.createAglet(java.net.URL, java.lang.String, java.lang.Object)

onDisposing

public void onDisposing()
Is called when an attempt is made to dispose of the aglet. Subclasses may override this method to implement actions that should be taken in response to a request for disposal.

Throws:
java.lang.SecurityException - if the request for disposal is rejected.
See Also:
dispose(), AgletProxy.dispose()

processCloneEvent

protected void processCloneEvent(CloneEvent ev)
Processes clone events occurring on this aglet by dispatching them to any registered CloneListener objects.

Parameters:
ev - the clone event

processMobilityEvent

protected void processMobilityEvent(MobilityEvent ev)
Processes mobility events occurring on this aglet by dispatching them to any registered MobilityListener objects.

Parameters:
ev - the mobility event

processPersistencyEvent

protected void processPersistencyEvent(PersistencyEvent ev)
Processes persistency events occurring on this aglet by dispatching them to any registered PersistencyListener objects.

Parameters:
ev - the persistency event

removeCloneListener

public final void removeCloneListener(CloneListener l)
Removes the specified clone listener so it no longer receives clone events.

Parameters:
l - the clone listener

removeMobilityListener

public final void removeMobilityListener(MobilityListener l)
Removes the specified mobility listener so it no longer receives mobility events.

Parameters:
l - the mobility listener

removePersistencyListener

public final void removePersistencyListener(PersistencyListener l)
Removes the specified persistency listener so it no longer receives persistency events.

Parameters:
l - the persistency listener

run

public void run()
Is the entry point for the aglet's own thread of execution. This method is invoked upon a successful creation, dispatch, retraction, or activation of the aglet.

See Also:
onCreation(java.lang.Object), CloneListener.onClone(com.ibm.aglet.event.CloneEvent), MobilityListener.onArrival(com.ibm.aglet.event.MobilityEvent), PersistencyListener.onActivation(com.ibm.aglet.event.PersistencyEvent)

setProtections

public void setProtections(java.security.PermissionCollection protections)
Sets the protections: permission collection about who can send what kind of messages to the aglet

Parameters:
protections - collection of protections about who can send what kind of messages to the aglet

setStub

public final void setStub(AgletStub stub)
Sets the proxy for the aglet. This cannot be set twice. Called by the system.


setText

public final void setText(java.lang.String text)
Sets the text of this Aglet. A way for the aglet to display messages on the viewer window.


snapshot

public final void snapshot()
                    throws java.io.IOException
[Preliminary] Save a snapshot of this aglet into a 2nd storage. The snapshot will be activated only if the aglet is accidentally killed. (because of the system clash for instance) If one of dispose, dispatch and deactivate are invoked, this snapshot will be removed from 2nd storate. This call doesn't fire the persistency event, hence no lister is invoked.

Throws:
java.io.NotSerializableException - if the entire aglet is not serializable
java.io.IOException - if I/O failed

subscribeMessage

public final void subscribeMessage(java.lang.String name)
Subscribes to a named message.

Parameters:
name - the message kind.

suspend

public final void suspend(long duration)
                   throws AgletException,
                          java.lang.IllegalArgumentException
This is an experimental feature.

This is almost like deactivate(long duration), but there are some differences.

  1. The object of the aglet remains at the memory.
  2. No event is notified, thus ContextListener and PersistencyListener cannot know the suspend/activation.
The aglet will be re-activated by the resume(). The caller will need the "deactivate" permissoin.

Parameters:
duration - duration of the aglet deactivating in milliseconds. If this is 0, it will be activeted at the next startup time.
Throws:
AgletException - if the aglet cannot be suspended.
java.lang.IllegalArgumentException - if the minutes parameter is negative.

unsubscribeAllMessages

public final void unsubscribeAllMessages()
Unsubscribes from all message kinds.


unsubscribeMessage

public final boolean unsubscribeMessage(java.lang.String name)
Unsubscribes from a named message.

Parameters:
name - the message kind.
Returns:
true if the message kind was subscribed.

waitMessage

public void waitMessage()
Waits until it is notified.

Throws:
java.lang.IllegalMonitorStateException - If the current thread is not the owner of the monitor.
See Also:
MessageManager.waitMessage(), notifyMessage, notifyAllMessages

waitMessage

public void waitMessage(long timeout)
Waits until it is notified or the timeout expires

Parameters:
timeout - the maximum value to wait in milliseconds
Throws:
java.lang.IllegalMonitorStateException - If the current thread is not the owner of the monitor.
See Also:
MessageManager.waitMessage(), notifyMessage, notifyAllMessages