Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.ibm.aglet
Class Aglet

    java.lang.Object
      |
      +--com.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
`static int` | `ACTIVE` State of Aglet.
`static int` | `INACTIVE`
`static short` | `MAJOR_VERSION`
`static short` | `MINOR_VERSION`

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

### MINOR_VERSION

    public static final short MINOR_VERSION

### ACTIVE

    public static final int ACTIVE

  State of Aglet.
  See Also:
    `AgletContext.getAgletProxies()`

### INACTIVE

    public static final int INACTIVE

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.
  Overrides:
    `clone` in class `java.lang.Object`
  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.
  Parameters:
    `millisecounds` - duration of the aglet deactivating. If this is 0, it will be activeted at the next startup time.
  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
  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
  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:
    `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

### 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

### getImage

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

  Gets an image

### 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.
  Parameters:
    `msg` - the message sent to the aglet
  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:
    `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:
    `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.
  Parameters:
    `proxy` - the proxy to set

### 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.
  Parameters:
    `message` - the message.

### 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:
    `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:
    `IllegalMonitorStateException` - If the current thread is not the owner of the monitor.
  See Also:
    `MessageManager.waitMessage()`, `notifyMessage`, `notifyAllMessages`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD