com.ibm.aglet
Interface AgletContext

All Known Implementing Classes:

AgletContextImpl

public interface AgletContext

The AgletContext interface is used by an aglet to get information about its environment and to send messages to the environment and other aglets currently active in that environment. It provides means for maintaining and managing running aglets in an environment where the host system is secured against malicious aglets.

Version:

1.50 $Date: 2001/07/28 06:34:04 $

Author:

Danny B. Lange, Mitsuru Oshima

Method Summary

void	addContextListener(ContextListener listener) Adds the specified context listener to receive context events from this context.
void	clearCache(java.net.URL codebase) Clears class cache in memory.
AgletProxy	createAglet(java.net.URL codeBase, java.lang.String code, java.lang.Object init) Creates an instance of the specified aglet class.
java.util.Enumeration	getAgletProxies() Gets an enumeration of all aglets in the current context including deactivated aglets.
java.util.Enumeration	getAgletProxies(int type) Gets an array of aglet proxies in the current context.
AgletProxy	getAgletProxy(AgletID id) Gets a proxy for an aglet in the current context.
AgletProxy	getAgletProxy(java.net.URL contextAddress, AgletID id) Deprecated.
java.applet.AudioClip	getAudioClip(java.net.URL audio) Gets an audio clip.
java.net.URL	getHostingURL() Returns the URL of the daemon serving this context.
java.awt.Image	getImage(ImageData image) Gets an image.
java.awt.Image	getImage(java.net.URL image) Gets an image.
ImageData	getImageData(java.net.URL image) Gets an image data.
java.lang.String	getName() Gets the name of the context.
java.lang.Object	getProperty(java.lang.String key) Gets the context property indicated by the key.
java.lang.Object	getProperty(java.lang.String key, java.lang.Object def) Gets the context property indicated by the key and default value.
ReplySet	multicastMessage(Message msg) Sends a multicast message to the subscribers in the context.
void	removeContextListener(ContextListener listener) Removes the specified context listener.
AgletProxy	retractAglet(java.net.URL url) Deprecated.
AgletProxy	retractAglet(java.net.URL url, AgletID aid) Retracts the aglet specified by its url and id
void	setProperty(java.lang.String key, java.lang.Object value) Sets the context property indicated by the key and value.
void	showDocument(java.net.URL url) Shows a new document.
void	shutdown() Shutdown the context.
void	shutdown(Message msg) Shutdown the context with the specific message object.
void	start() Starts the context.
void	start(boolean reactivate) Starts the context.

Method Detail

addContextListener

public void addContextListener(ContextListener listener)

Adds the specified context listener to receive context events from this context.

Parameters:

listener - the context listener

Throws:

java.lang.SecurityException -

clearCache

public void clearCache(java.net.URL codebase)

Clears class cache in memory.

Parameters:

codebase - the codebase of the cache to clean up. if null, entire cache in this context is cleared.

createAglet

public AgletProxy createAglet(java.net.URL codeBase,
                              java.lang.String code,
                              java.lang.Object init)
                       throws java.io.IOException,
                              AgletException,
                              java.lang.ClassNotFoundException,
                              java.lang.InstantiationException

Creates an instance of the specified aglet class. The aglet's class code file can be located on the local file system as well as on a remote server. If the codeBase is null, the context will search for the code in the local system's aglet search path (AGLET_PATH). The createAglet method takes three arguments: codeBase, code, and init:

Parameters:

codeBase - codeBase specifies the base URL of the aglet class file, in other words, the (possibly remote) directory that contains the aglet's code. If this argument is null, then the directories specified in the local host's aglet search path are searched. The aglet search path works in a similar way to Java's class path. It is typically an environment variable that specifies a list of directories to be searched for aglet code files.

code - code gives the name of the file that contains the aglet's compiled class code. This file is relative to the base URL of the aglet, and cannot be absolute.

init - init is an object passed on to the aglet's onCreation method.

Returns:

the proxy of the new aglet.

Throws:

AgletException - if the aglets can not be created.

UnknownHostException - if the given host could not be found.

ServerNotFoundException - if the server could not be found.

java.lang.InstantiationException - if the instantiation failed.

java.lang.ClassNotFoundException - if the class not found.

See Also:

Aglet.onCreation(java.lang.Object)

getAgletProxies

public java.util.Enumeration getAgletProxies()

Gets an enumeration of all aglets in the current context including deactivated aglets.

Returns:

a list of proxies.

getAgletProxies

public java.util.Enumeration getAgletProxies(int type)

Gets an array of aglet proxies in the current context.

Parameters:

type - the type of aglets. ACTIVE, INACTIVE or ACTIVE | INACTIVE,

Returns:

a list of proxies that matches the given state.

See Also:

Aglet.ACTIVE, Aglet.INACTIVE

getAgletProxy

public AgletProxy getAgletProxy(AgletID id)

Gets a proxy for an aglet in the current context. The selected aglet is specified by its identity.

Parameters:

id - the identity of the aglet.

Returns:

the proxy.

getAgletProxy

public AgletProxy getAgletProxy(java.net.URL contextAddress,
                                AgletID id)

Deprecated.

Gets a proxy for an aglet in a remote context. The remote context is identified by its URL, and the aglet is indicated by its identifier.

Parameters:

contextAddress - the address specifing a remote context.

id - the identity of the aglet.

Returns:

the proxy.

See Also:

getName

getAudioClip

public java.applet.AudioClip getAudioClip(java.net.URL audio)

Gets an audio clip.

Parameters:

audio - an absolute URL giving the location of the audio file.

Returns:

the Audio clip object give by the URL.

getHostingURL

public java.net.URL getHostingURL()

Returns the URL of the daemon serving this context.

Returns:

the URL of the daemon. null if the hosting information is not available.

getImage

public java.awt.Image getImage(ImageData image)

Gets an image. This is a tempolary solution.

Parameters:

image - a serializable image data.

Returns:

the image object converted from the image data.

getImage

public java.awt.Image getImage(java.net.URL image)

Gets an image.

Parameters:

image - an absolute URL giving the location of the image file.

Returns:

the image object give by the URL.

getImageData

public ImageData getImageData(java.net.URL image)

Gets an image data. This is a tempolary solution.

Parameters:

image - an absolute URL giving the location of the image file.

Returns:

the serializable image data.

getName

public java.lang.String getName()

Gets the name of the context. Each context running in the same server can be distinguished by the name. The example of an address for contexts is, "atp://host.com:4434/name".

Returns:

a name of aglet context

getProperty

public java.lang.Object getProperty(java.lang.String key)

Gets the context property indicated by the key.

Parameters:

key - the name of the context property.

Returns:

the value of the specified key.

getProperty

public java.lang.Object getProperty(java.lang.String key,
                                    java.lang.Object def)

Gets the context property indicated by the key and default value.

Parameters:

key - the name of the context property.

def - the value to use if this property is not set.

Returns:

the value of the specified key.

multicastMessage

public ReplySet multicastMessage(Message msg)

Sends a multicast message to the subscribers in the context.

Parameters:

message - to send

Returns:

ReplySet containing FutureReplies

removeContextListener

public void removeContextListener(ContextListener listener)

Removes the specified context listener.

Parameters:

listener - the context listener

Throws:

java.lang.SecurityException -

retractAglet

public AgletProxy retractAglet(java.net.URL url)
                        throws java.io.IOException,
                               AgletException

Deprecated.

Retracts the aglet specified by its url: atp://host-domain-name/#aglet-identity.

Parameters:

url - the location and aglet identity of the aglet to be retracted.

Returns:

the aglet proxy for the retracted aglet.

Throws:

AgletException - when the method failed to retract the aglet.

UnknownHostException - if the specified HOST is not found.

ServerNotFoundException - if the aglet server specified in the URL is not available.

MalformedURLException - if the given url is not URI for an aglet.

RequestRefusedException - if the retraction refused.

AgletNotFoundException - if the aglet could not be found.

retractAglet

public AgletProxy retractAglet(java.net.URL url,
                               AgletID aid)
                        throws java.io.IOException,
                               AgletException

Retracts the aglet specified by its url and id

Parameters:

url - the location of the aglet to be retracted.

id - the aglet identity of the aglet to be retracted.

Returns:

the aglet proxy for the retracted aglet.

Throws:

AgletException - when the method failed to retract the aglet.

UnknownHostException - if the specified HOST is not found.

ServerNotFoundException - if the aglet server specified in the URL is not available.

MalformedURLException - if the given url is not URI for an aglet.

RequestRefusedException - if the retraction refused.

AgletNotFoundException - if the aglet could not be found.

setProperty

public void setProperty(java.lang.String key,
                        java.lang.Object value)

Sets the context property indicated by the key and value.

Parameters:

key - the name of the context property.

value - the value to be stored.

Returns:

the value of the specified key.

showDocument

public void showDocument(java.net.URL url)

Shows a new document. This may be ignored by the aglet context.

Parameters:

url - an url to be shown

shutdown

public void shutdown()

Shutdown the context. This is ignored if the context is already stopped.

Throws:

java.lang.SecurityException - if the current execution context is not allowd to shutdown

See Also:

start

shutdown

public void shutdown(Message msg)

Shutdown the context with the specific message object. This message object is delivered to all aglets in the context before all aglets are killed. This is ignored if the context is already stopped.

Throws:

java.lang.SecurityException - if the current execution context is not allowd to shutdown

See Also:

start

start

public void start()

Starts the context. This is ignored if the context is already runnig.

Throws:

java.lang.SecurityException -

start

public void start(boolean reactivate)

Starts the context. This is ignored if the context is already runnig.

Parameters:

reactivate - if false, it does not activate aglets in the deactivation spool

Throws:

java.lang.SecurityException -