com.googlecode.mobilityrpc.session
Interface MobilitySession

All Known Subinterfaces:

MobilitySessionInternal

All Known Implementing Classes:

MobilitySessionImpl

public interface MobilitySession

A gateway through which the application can send objects to remote machines.

Sessions can be created or accessed via MobilityController.getSession(java.util.UUID).

Sessions provide the following methods for sending objects to remote machines:

• void execute(String, Runnable) or
  void execute(ConnectionId, Runnable) or
  void execute(ConnectionId, ExecutionMode, Runnable)
  • Transfers the given Runnable object, and any objects it references, to the given remote machine, and executes it (calls the Runnable.run() method) on the remote machine
  • The run() method can call methods on on any referenced objects sent with it, or any methods in the remote application
  • This is useful for invoking methods on remote machines which have void return types or where the local application is not interested in returning any data from the remote machine
• T execute(String, Callable<T>) or
  T execute(ConnectionId, Callable<T>) or
  T execute(ConnectionId, ExecutionMode, Callable<T>)
  • Transfers the given Callable object, and any objects it references, to the given remote machine, and executes it (calls the Callable.call() method) on the remote machine
  • The call() method can in turn call methods on on any referenced objects sent with it, or any methods in the remote application
  • The call() method returns an object, and the local application can implement call to fetch an object from the remote machine. Alternatively, it could implement this to return the same Callable (the Boomerang pattern), or a referenced object which was sent alongside the Callable back again to local application
  • The execute method will return the object fetched from the remote machine to the local application
  • This is useful for invoking methods on remote machines which return some objects or data, and transferring those objects or data to the local application, or sending an independent object which gathers data itself and returns it back to the local application

The methods above take the following arguments:

• ConnectionId
  • The address and port of the remote machine to which the object should be sent
• ExecutionMode
  • Specifies whether the operation should be performed synchronously or asynchronously, that is modes RETURN_RESPONSE and FIRE_AND_FORGET, respectively
    • When ExecutionMode.RETURN_RESPONSE is specified
      • The execute method on the local machine will block (wait) until the entire operation has been performed on the remote machine (run() or call() invoked), and the remote machine has returned a confirmation of the outcome of the operation to the local machine
    • When ExecutionMode.FIRE_AND_FORGET is specified
      • The execute method on the local machine will queue the object for sending to the remote machine and will then return immediately
      • A best-effort attempt will be made to execute the object on the remote machine
      • The remote machine will not send any response message

Author:

Niall Gallagher

Method Summary

<T> T	execute(ConnectionId connectionId, Callable<T> callable) Transfers the given Callable object, and any objects it references, to the given remote machine, and executes it (calls the Callable.call() method) on the remote machine.
<T> T	execute(ConnectionId connectionId, ExecutionMode executionMode, Callable<T> callable) Transfers the given Callable object, and any objects it references, to the given remote machine, and executes it (calls the Callable.call() method) on the remote machine.
void	execute(ConnectionId connectionId, ExecutionMode executionMode, Runnable runnable) Transfers the given Runnable object, and any objects it references, to the given remote machine, and executes it (calls the Runnable.run() method) on the remote machine.
void	execute(ConnectionId connectionId, Runnable runnable) Transfers the given Runnable object, and any objects it references, to the given remote machine, and executes it (calls the Runnable.run() method) on the remote machine.
<T> T	execute(String address, Callable<T> callable) Transfers the given Callable object, and any objects it references, to the given remote machine, and executes it (calls the Callable.call() method) on the remote machine.
void	execute(String address, Runnable runnable) Transfers the given Runnable object, and any objects it references, to the given remote machine, and executes it (calls the Runnable.run() method) on the remote machine.
MobilityController	getMobilityController() Returns the mobility controller which manages this session.
SessionClassLoader	getSessionClassLoader() Returns the class loader associated with this session.
UUID	getSessionId() Returns the UUID of this session.
void	release() Removes this session from the mobility controller.

Method Detail

getSessionId

UUID getSessionId()

Returns the UUID of this session.

Returns:

the UUID of this session

execute

void execute(String address,
             Runnable runnable)

Transfers the given Runnable object, and any objects it references, to the given remote machine, and executes it (calls the Runnable.run() method) on the remote machine.

This is a convenience method for calling execute(ConnectionId, ExecutionMode, Runnable) with ExecutionMode.RETURN_RESPONSE and default port 5739 in the connection id.

Parameters:

address - The address (ip or name) of the remote machine

runnable - The object to send and execute on the remote machine

execute

void execute(ConnectionId connectionId,
             Runnable runnable)

Transfers the given Runnable object, and any objects it references, to the given remote machine, and executes it (calls the Runnable.run() method) on the remote machine.

This is a convenience method for calling execute(ConnectionId, ExecutionMode, Runnable) with ExecutionMode.RETURN_RESPONSE.

Parameters:

connectionId - The address/port of the remote machine

runnable - The object to send and execute on the remote machine

execute

void execute(ConnectionId connectionId,
             ExecutionMode executionMode,
             Runnable runnable)

Transfers the given Runnable object, and any objects it references, to the given remote machine, and executes it (calls the Runnable.run() method) on the remote machine.

Parameters:

connectionId - The address/port of the remote machine

executionMode - Either of the following, see: ExecutionMode.RETURN_RESPONSE or ExecutionMode.FIRE_AND_FORGET

runnable - The object to send to the remote machine

execute

<T> T execute(String address,
              Callable<T> callable)

Transfers the given Callable object, and any objects it references, to the given remote machine, and executes it (calls the Callable.call() method) on the remote machine. Transfers the object returned by the call method on the remote machine, and any objects it references, back to the local application.

This is a convenience method for calling execute(ConnectionId, ExecutionMode, Runnable) with ExecutionMode.RETURN_RESPONSE and default port 5739 in the connection id.

Parameters:

address - The address (ip or name) of the remote machine

callable - The object to send to the remote machine

Returns:

The object returned by the Callable.call() method on the remote machine (transferred back to this machine)

execute

<T> T execute(ConnectionId connectionId,
              Callable<T> callable)

Transfers the given Callable object, and any objects it references, to the given remote machine, and executes it (calls the Callable.call() method) on the remote machine. Transfers the object returned by the call method on the remote machine, and any objects it references, back to the local application.

This is a convenience method for calling execute(ConnectionId, ExecutionMode, Runnable) with ExecutionMode.RETURN_RESPONSE.

Parameters:

connectionId - The address/port of the remote machine

callable - The object to send to the remote machine

Returns:

The object returned by the Callable.call() method on the remote machine (transferred back to this machine)

execute

<T> T execute(ConnectionId connectionId,
              ExecutionMode executionMode,
              Callable<T> callable)

Transfers the given Callable object, and any objects it references, to the given remote machine, and executes it (calls the Callable.call() method) on the remote machine. Transfers the object returned by the call method on the remote machine, and any objects it references, back to the local application.

Parameters:

connectionId - The address/port of the remote machine

executionMode - Either of the following, see: ExecutionMode.RETURN_RESPONSE or ExecutionMode.FIRE_AND_FORGET

callable - The object to send to the remote machine

Returns:

The object returned by the Callable.call() method on the remote machine (transferred back to this machine)

getSessionClassLoader

SessionClassLoader getSessionClassLoader()

Returns the class loader associated with this session.

Returns:

The class loader associated with this session

getMobilityController

MobilityController getMobilityController()

Returns the mobility controller which manages this session.

Returns:

The mobility controller which manages this session

release

void release()

Removes this session from the mobility controller.

All references to the session and its class loader will be released by the library. This means that, unless some application code has stored a reference to the session somewhere, the session and all of the classes it has loaded will be garbage collected. Also note that this means that any data stored in static fields in those classes will also be garbage collected.

Deferred Session Release
Note that if this is called on a remote machine by an object sent to that machine, the remote machine will defer releasing the session until all threads concurrently processing requests in that session have finished.

This mechanism allows mobile code to effectively schedule the session in which it is executing, on what it views as the local machine, to be released after it has finished executing on that machine.

If this method is called by a thread not managed by the library (e.g. from the host application), the method will check if remote threads are executing in the session, and either schedule the session to be released when those threads finish, or release it immediately if the session is actually not in use.

See also MobilityController.releaseSession(java.util.UUID), which bypasses this safeguard, and allows sessions to be released immediately.