one.world.core
Interface MovingProtocol

public interface MovingProtocol

Definition of the environment moving protocol. The protocol to move environments from one node to another uses REP as its transport and dynamic tuples as protocol messages. This interface defines the different protocol messages as well as the payload (fields) for each message type.

The ordering of protocol messages is as follows:

    Sender                     Receiver

      -------- request-move -------->
      <-------- allow-move ----------
      ------ send-descriptors ------>
      <---- confirm-descriptors -----
    ( ---------- send-tuple -------->
      <-------- confirm-tuple ------- ) *
      ------- send-check-point ----->
      <------- complete-move --------
 

The * for the pair of send-tuple, confirm-tuple messages indicates that zero or more such message rounds are performed.

The sender sends the original request-move message to the event handler exported under the name MOVE_ACCEPTOR on the receiving node. Subsequent message are sent to the source of the allow-move message. The receiver sends all messages to the source of the request-move message. Both the sender and the receiver use the closure of the previously received message for the next outgoing message, thus chaining the closure originally used for the request-move message throughout the protocol.

Both sender and receiver may send an exceptional event indicating some exceptional condition at any time, which effectively cancels the move. Furthermore, both sender and receiver time out after TIMEOUT milliseconds when waiting for a message, which also cancels the move.

Corresponding to the different rounds of the protocol, the sender and receiver go through several states. The sender starts out in the initial state. After receiving the allow-move message, it enters the descriptor state. After receiving the confirm-descriptors message, it enters the content state. Finally, after receiving the complete-move message, it enters the final state.

The receiver starts out in the initial state when receiving a request-move message. After receiving the send-descriptors message, it enters the descriptor state. After receiving either a send-tuple or send-check-point message, it enters the content state. Finally, after completing the move, it enters the final state.

On an exceptional condition, both sender and receiver enter the error state, which cancels the move.

Note that the complete-move message may be lost, since REP provides at-most-once message delivery guarantees. As a result, the receiver may successfully complete the moving protocol, while the sender thinks it has ended exceptionally and thus abort the move operation. Applications that require stronger semantics need to implement their own recovery protocol.

Version:

$Revision: 1.4 $

Field Summary

static String	CHECK_POINT The field specifying a check-point.
static String	CLONE The field specifying whether the environment tree is being cloned.
static String	DESCRIPTORS The field specifying environment descriptors.
static String	ENV_ID The field specifying an environment ID.
static String	ENV_NAME The field specifying an environment name.
static String	MOVE_ACCEPTOR The REP name of the event handler accepting requests to move environment(s) to this node.
static String	MSG The field specifying the message type.
static String	MSG_ALLOW The allow-move message.
static String	MSG_CHECK_POINT The send-check-point message.
static String	MSG_COMPLETE The complete-move message.
static String	MSG_CONFIRM The confirm-descriptors message.
static String	MSG_CONFIRM_TUPLE The confirm-tuple message.
static String	MSG_DESCRIPTORS The send-descriptors message.
static String	MSG_REQUEST The request-move message.
static String	MSG_SEND_TUPLE The send-tuple message.
static String	PATH The field specifying an environment path.
static int	STATE_CONTENT The state code for the content state.
static int	STATE_DESCRIPTOR The state code for the descriptor state.
static int	STATE_ERROR The state code for the error state.
static int	STATE_FINAL The state code for the final state.
static int	STATE_INITIAL The state code for the initial state.
static long	TIMEOUT The timeout for waiting for a message.
static String	TUPLE The field specifying a tuple in binary form.
static String	TUPLE_ID The field specifying a tuple ID.

Field Detail

MOVE_ACCEPTOR

public static final String MOVE_ACCEPTOR

The REP name of the event handler accepting requests to move environment(s) to this node. The name of this event handler is "one.world.move.acceptor.

MSG

public static final String MSG

The field specifying the message type. The value must be one of the messages specified in this interface.

MSG_REQUEST

public static final String MSG_REQUEST

The request-move message. This protocol message specifies the ID and name of the root of the environment tree being moved, the path of the new parent on the remote node, and whether the environments are being cloned.

See Also:

ENV_ID, ENV_NAME, PATH, CLONE

MSG_ALLOW

public static final String MSG_ALLOW

The allow-move message. This protocol message specifies the ID of the new parent environment.

See Also:

ENV_ID

MSG_DESCRIPTORS

public static final String MSG_DESCRIPTORS

The send-descriptors message. This protocol message specifies the descriptors for the environment tree being moved.

See Also:

DESCRIPTORS

MSG_CONFIRM

public static final String MSG_CONFIRM

The confirm-descriptors message. This protocol message is empty.

MSG_SEND_TUPLE

public static final String MSG_SEND_TUPLE

The send-tuple message. This protocol message specifies the tuple in binary form and the ID of the tuple's environment.

See Also:

TUPLE, ENV_ID

MSG_CONFIRM_TUPLE

public static final String MSG_CONFIRM_TUPLE

The confirm-tuple message. This protocol message confirms that a previously sent send-tuple message.

See Also:

TUPLE_ID

MSG_CHECK_POINT

public static final String MSG_CHECK_POINT

The send-check-point message. This protocol message specifies the check-point of the environment tree.

See Also:

CHECK_POINT

MSG_COMPLETE

public static final String MSG_COMPLETE

The complete-move message. This protocol message is empty.

ENV_ID

public static final String ENV_ID

The field specifying an environment ID. The value of the field must be a Guid representing the ID of the root environment of the tree being moved.

ENV_NAME

public static final String ENV_NAME

The field specifying an environment name. The value of the field must be a string representing the name of the root environment of the tree being moved.

PATH

public static final String PATH

The field specifying an environment path. The value of the field must be a string representing the path of the new parent environment on the receiving node.

CLONE

public static final String CLONE

The field specifying whether the environment tree is being cloned. The value of the field must be a boolean representing the flag for whether the environment tree is being clone.

DESCRIPTORS

public static final String DESCRIPTORS

The field specifying environment descriptors. The value of the field must be an array of environment descriptors whose entries are valid environment descriptors representing all environments in the tree being moved.

TUPLE

public static final String TUPLE

The field specifying a tuple in binary form. The value of the field must be of type BinaryData. The binary data must be the serialized form of a tuple and the ID of the binary data tuple must be the same as the ID of the serialized tuple.

TUPLE_ID

public static final String TUPLE_ID

The field specifying a tuple ID. The value of the field must be a Guid representing the ID of a tuple.

CHECK_POINT

public static final String CHECK_POINT

The field specifying a check-point. The value of the field must be a CheckPoint representing a valid check-point of the tree being moved.

TIMEOUT

public static final long TIMEOUT

The timeout for waiting for a message. This constant can be specified using the "one.world.moving.protocol.timeout" system property. If this system property is not defined, the default is 60 seconds.

STATE_INITIAL

public static final int STATE_INITIAL

The state code for the initial state.

STATE_DESCRIPTOR

public static final int STATE_DESCRIPTOR

The state code for the descriptor state.

STATE_CONTENT

public static final int STATE_CONTENT

The state code for the content state.

STATE_FINAL

public static final int STATE_FINAL

The state code for the final state.

STATE_ERROR

public static final int STATE_ERROR

The state code for the error state.