com.ibm.aglet
Interface AgletProxy

public interface AgletProxy

AgletProxy interface is a placeholder for aglets. The purpose of this interface is to provide a mechanism to control and limit direct access to aglets.

Version:

1.50 $Date: 2001/07/28 06:33:57 $

Author:

Danny B. Lange, Mitsuru Oshima, ONO Kouichi

Method Summary

void	activate() Activates the aglet.
java.lang.Object	clone() Clones the aglet and its proxy.
void	deactivate(long duration) Deactivates the aglet.
void	delegateMessage(Message msg) Delegates a message to the aglet.
AgletProxy	dispatch(Ticket ticket) Dispatches the aglet to the location specified by the ticket as the argument.
AgletProxy	dispatch(java.net.URL address) Dispatches the aglet to the location specified by the argument address.
void	dispose() Disposes the aglet.
java.lang.String	getAddress() Gets the current address of the target aglet.
Aglet	getAglet() Gets the aglet that the proxy manages.
java.lang.String	getAgletClassName() Gets the aglet's class name.
AgletID	getAgletID() Gets the aglet's id.
AgletInfo	getAgletInfo() Gets the AgletInfo object of the aglet.
boolean	isActive() Checks if the aglet is active or deactivated.
boolean	isRemote() Checks if the aglet proxy is referencing a remote aglet.
boolean	isState(int type) Checks if the aglet is in the state give by type.
boolean	isValid() Checks if the aglet proxy is invalid or not.
FutureReply	sendAsyncMessage(Message msg) Sends a message in asynchronous way.
FutureReply	sendFutureMessage(Message msg) Sends a future message to the aglet.
java.lang.Object	sendMessage(Message msg) Sends a message in synchronous way.
void	sendOnewayMessage(Message msg) Sends a oneway message to the aglet.
void	suspend(long duration) This is an experimental feature.

Method Detail

activate

public void activate()
              throws java.io.IOException,
                     AgletException

Activates the aglet. This is a forced activation of a deactivated/resumed aglet.

Throws:

java.io.IOException - if the activation failed.

AgletException - if the aglet is not valid.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clones the aglet and its proxy. Note that the cloned aglet will get activated. If you like to get cloned aglet which is not activated, throw ThreadDeath exception in the onClone method.

Overrides:

clone in class java.lang.Object

Returns:

the new aglet proxy what holds cloned aglet.

Throws:

java.lang.CloneNotSupportedException - if the cloning fails.

InvalidAgletException - if the aglet is invalid.

deactivate

public void deactivate(long duration)
                throws java.io.IOException,
                       InvalidAgletException

Deactivates the aglet. The system may store the aglet in the spool (disk or memory depending on the server). The aglet will be re-activated later (at the given time or manually).

Parameters:

duration - duration of the aglet deactivating in milliseconds. If this is 0, it will be activeted at the next startup time.

Throws:

InvalidAgletException - if the aglet is not valid.

java.lang.IllegalArgumentException - if the minutes parameter is negative.

delegateMessage

public void delegateMessage(Message msg)
                     throws InvalidAgletException

Delegates a message to the aglet. The message needs to be a message passed as an argument to Aglet#handleMessage. The delegated message is sent to the receiver and will be handled in the Aglet#handleMessage(Message) method.

Parameters:

msg - a message to delegate

Throws:

InvalidAgletException - if the aglet proxy is not valid.

See Also:

Aglet.handleMessage(com.ibm.aglet.Message)

dispatch

public AgletProxy dispatch(Ticket ticket)
                    throws java.io.IOException,
                           AgletException

Dispatches the aglet to the location specified by the ticket as the argument.

Parameters:

address - the address of the destination context.

Returns:

the AgletProxy of the dispatched (remote) aglet.

Throws:

ServerNotFoundException - if the server

UnknownHostException - if the host given in the URL doesn't exist.

MalformedURLException - if the given url dosn't specify the host.

RequestRefusedException - if the remote server refused the dispatch request.

InvalidAgletException - if the aglet is not valid.

dispatch

public AgletProxy dispatch(java.net.URL address)
                    throws java.io.IOException,
                           AgletException

Dispatches the aglet to the location specified by the argument address.

Parameters:

address - the address of the destination context.

Returns:

the AgletProxy of the dispatched (remote) aglet.

Throws:

ServerNotFoundException - if the server

UnknownHostException - if the host given in the URL doesn't exist.

MalformedURLException - if the given url dosn't specify the host.

RequestRefusedException - if the remote server refused the dispatch request.

InvalidAgletException - if the aglet is not valid.

dispose

public void dispose()
             throws InvalidAgletException

Disposes the aglet.

Throws:

InvalidAgletException - if the aglet is invalid.

getAddress

public java.lang.String getAddress()
                            throws InvalidAgletException

Gets the current address of the target aglet.

Returns:

InvalidAgletException if the aglt is not valid.

getAglet

public Aglet getAglet()
               throws InvalidAgletException

Gets the aglet that the proxy manages.

Returns:

the aglet

Throws:

InvalidAgletException - if the aglet is not valid.

java.lang.SecurityException - if you are not allowed to access the aglet.

getAgletClassName

public java.lang.String getAgletClassName()
                                   throws InvalidAgletException

Gets the aglet's class name.

Returns:

the class name.

Throws:

InvalidAgletException - if the aglet is not valid.

getAgletID

public AgletID getAgletID()
                   throws InvalidAgletException

Gets the aglet's id.

Returns:

the aglet's id

Throws:

InvalidAgletException - if the aglet is not valid.

getAgletInfo

public AgletInfo getAgletInfo()
                       throws InvalidAgletException

Gets the AgletInfo object of the aglet.

Returns:

the AgletInfo object

Throws:

InvalidAgletException - if the aglet is not valid.

See Also:

AgletInfo

isActive

public boolean isActive()
                 throws InvalidAgletException

Checks if the aglet is active or deactivated.

Returns:

true if the aglet is active.

Throws:

InvalidAgletException - if the aglet is not valid.

isRemote

public boolean isRemote()

Checks if the aglet proxy is referencing a remote aglet.

Returns:

true if the aglet resides at the remote site.

isState

public boolean isState(int type)

Checks if the aglet is in the state give by type.

Parameters:

type - an integer value specifying the aglet's state

Returns:

true if the aglet is in the same state as the type give as an argument.

See Also:

Aglet.ACTIVE, Aglet.INACTIVE

isValid

public boolean isValid()

Checks if the aglet proxy is invalid or not. The aglet proxy become invalid in the following way.

1. The aglet is disposed.
2. The aglet is dispatched.

If the aglet is deactivated, it become INACTIVE.

Returns:

true if the aglet proxy is valid. false if not.

sendAsyncMessage

public FutureReply sendAsyncMessage(Message msg)
                             throws InvalidAgletException

Sends a message in asynchronous way.

Parameters:

msg - a message to send.

Returns:

a future object that will give you the reply of the message.

Throws:

InvalidAgletException - if the aglet is not valid any longer.

sendFutureMessage

public FutureReply sendFutureMessage(Message msg)
                              throws InvalidAgletException

Sends a future message to the aglet. The invocation will

Parameters:

msg - a message to send.

Returns:

a future object that will give you the reply of the message.

Throws:

InvalidAgletException - if the aglet is not valid any longer.

sendMessage

public java.lang.Object sendMessage(Message msg)
                             throws InvalidAgletException,
                                    NotHandledException,
                                    MessageException

Sends a message in synchronous way. This waits for finishing the message handing.

Parameters:

msg - a message to send.

Returns:

the result object if any. null if not.

Throws:

InvalidAgletException - if the aglet is not valid any longer.

NotHandledException - if the aglet didn't handle the the message.

MessageException - a exception which the handleMessage method raised.

sendOnewayMessage

public void sendOnewayMessage(Message msg)
                       throws InvalidAgletException

Sends a oneway message to the aglet. No acknowledgement will be sent back to the sender.

Parameters:

msg - a message to send.

Throws:

InvalidAgletException - if the aglet is not valid any longer.

suspend

public void suspend(long duration)
             throws InvalidAgletException

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 is re-activated by activate(). The caller is required to have "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.