org.planx.xmlstore.stores
Class NetworkProtocol

java.lang.Object
  org.planx.xmlstore.stores.NetworkProtocol

public class NetworkProtocol
extends Object

An XML Store can be made available over the network by using a DistributedXMLStore or a NetworkListener. Such a store can be contacted either through other DistributedXMLStore's or through a RemoteXMLStore. In very general terms, such stores communicate using a request/reply protocol where the possible forms of requests are:

• LOAD vref
• SAVE node
• LOOKUP name
• BIND name vref
• REBIND name old-vref new-vref

This description documents in more detail the allowed requests and the possible responses.

All communication takes place over a TCP connection represented by a socket and its two associated streams (the port number is a configuration parameter). A request is sent over the input stream part of the socket, and the reply is received over the output stream part. A connection can be used for multiple requests.

Handshake

Before the real protocol can be begin, the two ends of the socket exchange a very simple form of handshake. The initiator of the connection sends what it believes to be the current protocol version number to which the recipient responds with what is believes to be current version. If those numbers match, communication may begin.

We describe that situation as follows:

• out: VERSION-NUMBER
• in: VERSION-NUMBER

In such descriptions ALL CAPS denote constants from the code (typically, in this class, NetworkProtocol, or in Node).

Load Request

A load request has the following communication pattern:

• out: load-request
• in: load-response

where

load-request	::=	REQUEST-LOAD value-reference
load-response	::=	RESPONSE-OK locator[=l] file-system
	|	response-error
response-error	::=	RESPONSE-UNKNOWN-VREF | RESPONSE-IO-EXCEPTION
	|	RESPONSE-NAME-SERVER-EXCEPTION | RESPONSE-UNBOUND-NAME

(see Serialization Formats below for the nonterminals value-reference, locator, long, and file-system).

The successful response includes a file system totalling s bytes; where s is the result of unmarshalling the long (as indicated by the syntax non-terminal[=identifier]). The file system contains definitions of nodes (as described below). In particular, the locator l includes an offset (counting from 0, the beginning of the file system, up to s-1) at which place one finds the result of loading the vref in the request in the remote XML Store. Therefore, the requester can construct the result of the load by unmarshalling the node indicated by l.

All requests follow the same communication pattern, so from now on we shall only document the format of the requests and responses.

Save Request

save-request	::=	REQUEST-SAVE locator[=l] long[=s] file-system
save-response	::=	RESPONSE-OK value-reference
	|	response-error

When saving a node, one constructs a file system (ie., a byte array) consisting of marshalled node representations (currently, the complete subtree reachable from the node to be saved). The request starts with a locator for the node to be saved, then follows the size of the file system, and finally the file system itself is transmitted. On success, the remote XML Store returns a value reference (through which the saved node may be later read).

Lookup Request

lookup-request	::=	REQUEST-LOOKUP string[=n]
lookup-response	::=	RESPONSE-OK value-reference
	|	response-error

Instructs the remote XML Store to lookup the name n. On success, the reponse includes the value reference currently bound to that name in the name server associated with the remote XML Store, otherwise an error code is returned.

Bind Request

bind-request	::=	REQUEST-BIND string[=n] value-reference[=v]
bind-response	::=	RESPONSE-OK
	|	response-error

Instructs the remote XML Store to bind the name n to the value reference v. If the name is not already bound, a RESPONSE-OK is returned, otherwise an error code.

Rebind Request

rebind-request	::=	REQUEST-REBIND string[=n] value-reference[=vold] value-reference[=vnew]
rebind-response	::=	RESPONSE-OK
	|	response-error

Instructs the remote XML Store to (re)bind the name n to the value reference v_new if the name is currently bound to v_old and only then. If the name is bound to the right value reference, a RESPONSE-OK is returned, otherwise an error code.

Exec Request

exec-request	::=	REQUEST-EXEC value-reference[=vcode] value-reference[=vargs]
exec-response	::=	RESPONSE-OK value-reference
	|	response-error

Instructs the remote XML Store to execute the code identified by v_code supplying it the argument identified by v_args. If the execution completes successfully, a RESPONSE-OK and a value reference identifying the result is returned, otherwise an error code.

Serialization Formats

Notation: non-terminal{count} means count occurrences of non-terminal in sequence; non-terminal[=id] means binding the result of unmarshalling non-terminal to the identifier id (which may be later used, also in the same production).

value-reference	::=	bytes{16}	(MD5 sum)
file-system	::=	node*	(s bytes in total)
node	::=	ELEMENT element
	|	CHARDATA string[=s]	(CharData(s))
	|	BINARY long[=s] bytes{s}[=ba]	(Binary(ba))
element	::=	string[=t] attributes[=as] int[=s] compact-locator{s}[=cs]	(Element(t,cs,as))
string	::=	int[=s] bytes{s}	(UTF8 encoded data)
attributes	::=	int[=s] attribute{s}[=as]	(AttributeList(as))
attribute	::=	string[=a] string[=v]	(Attribute(a,v))
compact-locator	::=	long[=p] 0	(Locator(p, file-system.id))
	|	long[=p] 1 source-id[=i]	(Locator(p, i))
locator	::=	long[=p] source-id[=i]	(Locator(p, i))
source-id	::=	bytes{5}[=i]	(SourceId(i))
long, int, ...			all follow the format in DataInput

Author:

Henning Niss, Thomas Ambus

Field Summary

static byte	PROTOCOL_VERSION
static byte	REQUEST_BIND
static byte	REQUEST_EXEC
static byte	REQUEST_LOAD
static byte	REQUEST_LOOKUP
static byte	REQUEST_REBIND
static byte	REQUEST_SAVE
static byte	REQUEST_VERSION
static byte	RESPONSE_IO_EXCEPTION
static byte	RESPONSE_NAME_SERVER_EXCEPTION
static byte	RESPONSE_NOT_A_CLASS
static byte	RESPONSE_OK
static byte	RESPONSE_UNBOUND_NAME
static byte	RESPONSE_UNKNOWN_VREF

Method Summary

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROTOCOL_VERSION

public static final byte PROTOCOL_VERSION

See Also:

Constant Field Values

REQUEST_VERSION

public static final byte REQUEST_VERSION

See Also:

Constant Field Values

REQUEST_LOAD

public static final byte REQUEST_LOAD

See Also:

Constant Field Values

REQUEST_SAVE

public static final byte REQUEST_SAVE

See Also:

Constant Field Values

REQUEST_LOOKUP

public static final byte REQUEST_LOOKUP

See Also:

Constant Field Values

REQUEST_BIND

public static final byte REQUEST_BIND

See Also:

Constant Field Values

REQUEST_REBIND

public static final byte REQUEST_REBIND

See Also:

Constant Field Values

REQUEST_EXEC

public static final byte REQUEST_EXEC

See Also:

Constant Field Values

RESPONSE_OK

public static final byte RESPONSE_OK

See Also:

Constant Field Values

RESPONSE_IO_EXCEPTION

public static final byte RESPONSE_IO_EXCEPTION

See Also:

Constant Field Values

RESPONSE_UNKNOWN_VREF

public static final byte RESPONSE_UNKNOWN_VREF

See Also:

Constant Field Values

RESPONSE_NAME_SERVER_EXCEPTION

public static final byte RESPONSE_NAME_SERVER_EXCEPTION

See Also:

Constant Field Values

RESPONSE_UNBOUND_NAME

public static final byte RESPONSE_UNBOUND_NAME

See Also:

Constant Field Values

RESPONSE_NOT_A_CLASS

public static final byte RESPONSE_NOT_A_CLASS

See Also:

Constant Field Values