com.ibm.aglet
Class Aglet

java.lang.Object
  |
  +--com.ibm.aglet.Aglet

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.

See Also:

Serialized Form

Field Summary

static int	ACTIVE State of Aglet.
static int	INACTIVE
static short	MAJOR_VERSION
static short	MINOR_VERSION

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.
com.ibm.awb.security.Permissions	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.
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(com.ibm.awb.security.Permissions 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, 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

Method Detail

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)

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)

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)

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()

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.

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.

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

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)

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)

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

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

dispatchEvent

public final void dispatchEvent(AgletEvent ev)

Dispatches an event to this aglet

Parameters:

ev - the aglet event

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()

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(java.lang.Object), AgletProxy.sendMessage(com.ibm.aglet.Message)

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

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

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

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

getProxy

public final AgletProxy getProxy()

Gets the proxy of aglet.

Returns:

the proxy of aglet

getAgletContext

public final AgletContext getAgletContext()

Gets the context in which the aglet is currently executing.

Returns:

the current execution context.

getMessageManager

public final MessageManager getMessageManager()

Gets the message manager.

Returns:

the message manager.

getAgletID

public final AgletID getAgletID()

Gets the id of this aglet.

Returns:

the AgletID object of this aglet

See Also:

aglet.AgletID

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

getAgletInfo

public final AgletInfo getAgletInfo()

Gets the info object of this aglet

Returns:

the aglet.AgletInfo object of this aglet

See Also:

aglet.AgletID

getText

public final java.lang.String getText()

Gets the message line of this Aglet.

Returns:

the String representing a message the aglet shows.

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.

setProtections

public void setProtections(com.ibm.awb.security.Permissions 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

getProtections

public com.ibm.awb.security.Permissions 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

subscribeMessage

public final void subscribeMessage(java.lang.String name)

Subscribes to a named message.

Parameters:

name - the message kind.

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.

unsubscribeAllMessages

public final void unsubscribeAllMessages()

Unsubscribes from all message kinds.

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

getAudioData

public final java.applet.AudioClip getAudioData(java.net.URL url)
                                         throws java.io.IOException

Gets an audio data

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