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