|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD | DETAIL: ENUM CONSTANTS | FIELD | METHOD |
java.lang.Objectjava.lang.Enum<Protocol>
com.buildforge.services.common.api.Protocol
public enum Protocol
An enumeration of the line protocols that are implemented in the
Java version of the Services Layer, both in the client and in the
server. There are some general conventions that are imposed on all
of these protocols by the object serialization system that the
services layer uses. The most obvious is that only certain types
of data may be serialized to a services layer connection, and
several of these data types are merged into another data type in
the process, with the result that the data may deserialize to a
different format. For types such as boolean
that may
exist either as a base type or as an object which wraps that base
type, both forms are accepted and should exhibit the same behavior,
and the result object will always contain the wrapped form.
The data types are summarized by the following chart:
Source type | Mapped type | Comments |
---|---|---|
null | null | |
boolean | boolean | |
int | int | |
number | number | This type may contain an int, a long, or a double. The protocol implementation should yield the smallest of these formats that is sufficient to hold the value. The values 9e999999 and -9e999999 are substituted for Infinity and -Infinity, respectively. The handling of NaN is either to preserve it if the data format has a way to represent it uniquely, or to map it to the string "NaN", if there is no such mechanism available. If the data format has a generic mechanism for escaping strings, it is recommended that the initial 'N' be escaped using that format so that sufficiently clever implementations of the protocol may use that escaping to indicate whether "NaN" represents a numeric NaN or the string "NaN" without having to guess. |
Enum | String |
Enumerated types are converted to strings using their
name() method. It is up to the recipient of
the data to understand that the string represents an enumerated
type and to reconstrict it as appropriate. |
String | String | Every protocol is required to accurately preserve all valid Unicode character sequences. If an invalid sequence is found during the encoding, it must be replaced with substitution characters to indicate the omission. Recommended values are, in order of preference, U+FFFD - REPLACEMENT CHARACTER, U+001A - SUBSTITUTE, U+007F - DELETE, and U+003F - QUESTION MARK. |
array | array | |
DBObject | array |
Every DBObject must implement DBObject.toArray() ,
which every protocol will use to render the object as an array
when sending it across the wire. It is up to the recipient of
the data to understand that the array represents an object and
to reconstruct it using DBObject.fromArray(Object[]) .
|
hash | hash | The keys of a hash table are required to be simple strings of at most 255 characters. They may not contain any characters that must be quoted in any of the protocols, so they must consist only of printable ASCII characters, and the characters U+0022 (QUOTATION MARK - "), U+0025 (PERCENT SIGN - %), U+0026 (AMPERSAND - &), U+003C (LESS-THAN SIGN - <), and U+003E (GREATER-THAN SIGN - >) are explicitly forbidden. |
Requests are sent as hash tables. If the data format provides a
suitable mechanism for doing so, then the hash table should be
marked as a request object that is distinct from ordinary hashes,
and the command number should not be stored as an ordinary key.
If that is not possible, then the command is stored to the key
"*cmd"
with the command represented as an unsigned
hexadecimal string. Requests may also specify a user ID, which
should use "*as"
for the key when out-of-band data
is not available.
It must be possible for the protocol implementation to recover
from any error except an IOException or a
ProtocolException
. If an exception occurs from which
recovery is not possible, then one of these exception types should
be thrown with the original problem as the exception's cause. In
most cases, this will mean that every data structure that is
started must be ended gracefully. For example, in the
JSON
protocol, arrays are begun with [ and
closed with ]. Once the array is started, the protocol
must ensure that it is ended, regardless of whether or not an
exception occurs.
Requests must be represented in such a way that a request can be cancelled. In data-only protocols, this is generally done by writing requests within an array structure, from which only the final entry will be used. To keep memory use at a minimum, the protocol implementation should discard earlier request objects as soon as it determines that they have been cancelled (if possible) rather than build the entire array up front.
Responses take the same form as requests, except that
COMMAND_RESPONSE
and
COMMAND_ERROR
.
Enum Constant Summary | |
---|---|
BINARY
Uses a proprietary binary data format to represent request and response data. |
|
JSON
Uses the JavaScript Object Notation to represent request and response data. |
|
XML
Uses eXtensible Markup Language to represent request and response data. |
Method Summary | |
---|---|
static Protocol |
getDefault()
Queries the protocol that should be used by default for new connections. |
static void |
setDefaultProtocol(Protocol defaultProtocol)
Sets the protocol that should be used by default for new connections. |
static Protocol |
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. |
static Protocol[] |
values()
Returns an array containing the constants of this enum type, in the order they're declared. |
Methods inherited from class java.lang.Enum |
---|
compareTo, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf |
Methods inherited from class java.lang.Object |
---|
getClass, notify, notifyAll, wait, wait, wait |
Enum Constant Detail |
---|
public static final Protocol BINARY
request ::= header { hashentry } footer (arbitrary repeat count) header ::= CTRL_CMD cmdid | CTRL_AS userid cmdid cmdid ::= INT4 userid ::= INT4 hashentry ::= CTRL_ENTRY key value footer ::= CTRL_GO | CTRL_ABORT key ::= latin1 value ::= TYPE_NULL | TYPE_TRUE | TYPE_FALSE | TYPE_INTEGER INT4 | TYPE_NUMBER latin1 | TYPE_LATIN1 latin1 | TYPE_STRING string | TYPE_ARRAY array | TYPE_HASH hash string ::= utf8 array ::= LEN2 { value } hash ::= { hashentry } CTRL_ENDHASH (arbitrary repeat count) latin1 ::= LEN1 { LATIN1 } utf8 ::= LEN4 { UTF8 } LEN1 ::= 0x00 - 0xFE LEN2 ::= 0x0000 - 0xFFFE LEN4 ::= 0x00000000 - 0x7FFFFFFF INT4 ::= 0x00000000 - 0xFFFFFFFF DBOTYPE ::= (DBO_* constant from APIConstants) EXTYPE ::= (EX_* constant from APIConstants) LATIN1 ::= 0x00 to 0xFF UTF8 ::= ASCII | 0xC2-0xDF 0x80-0xBF | 0xE0 0xA0-0xBF 0x80-0xBF | 0xE1-0xEC 0x80-0xBF 0x80-0xBF | 0xED 0x80-0x9F 0x80-0xBF | 0xEE-0xEF 0x80-0xBF 0x80-0xBF | 0xF0 0x90-0xBF 0x80-0xBF 0x80-0xBF | 0xF1-0xF3 0x80-0xBF 0x80-0xBF 0x80-0xBF | 0xF4 0x80-0x8F 0x80-0xBF 0x80-0xBF TheTYPE_*
constants are as defined inAPIConstants
.
public static final Protocol JSON
NaN
value is represented as
"\\u004EaN"
, which is "NaN"
with
the initial 'N'
unnecessarily escaped. The
purpose of this is described in the general documentation
for Protocol
."*cmd"
and "*as"
for the request header
data, as described under Protocol
.U+201A4 must be represented as as the UTF-16 surrogate
pair 𠆤
.
- Outside of string values, whitespace is unimportant and may
vary with the design and fine-tuning of the JSON encoder.
An example request might look like this:
[{"*cmd":"80000003", "*ping":[-42.7e+8, 0, 0e-0, true, "Hello", false, null, -1e12341234]}]The response to it would look something like this:
[ { "*cmd": "80000001", "*ping": [ -4.27E9, 0, 0.0, true, "Hello", false, null, -9E999999 ] } ]
public static final Protocol XML
<null key="MyNull">Text</null>
is found,
then Text
is silently ignored.
The method used by this protocol is to escape all characters
outside the printable ASCII range (that is,
U+0020-U+007E), as well as the characters
U+0022 (QUOTATION MARK - "),
U+0025 (PERCENT SIGN - %),
U+0026 (AMPERSAND - &),
U+003C (LESS-THAN SIGN - <), and
U+003E (GREATER-THAN SIGN - >).
They escape sequence takes the form %XX
, where
XX is the hexadecimal coding of a byte value, with
UTF-8 used as the encoding and either case accepted for the
letters A-F.
For example, U+00A9 (COPYRIGHT SIGN - ©) is encoded as %C2%A9 or %c2%a9, and U+4E2A (Unified CJK - 个) is encoded as %E4%B8%AA or %e4%b8%aa.
An example request might look like this:
<packet> <request cmd="80000003" /> <string key="*cmd" value="80000003" /> <array key="*ping"> <string value="0" /> <string value="-42.7" /> <string value="0" /> <string value="Hello" /> </array> </request> </packet>
Method Detail |
---|
public static final Protocol[] values()
for(Protocol c : Protocol.values()) System.out.println(c);
public static Protocol valueOf(java.lang.String name)
name
- the name of the enum constant to be returned.
java.lang.IllegalArgumentException
- if this enum type has no constant
with the specified namepublic static Protocol getDefault()
Protocol
that will be used by defaultpublic static void setDefaultProtocol(Protocol defaultProtocol)
defaultProtocol
- the Protocol
to use
java.lang.NullPointerException
- if defaultProtocol is null
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD | DETAIL: ENUM CONSTANTS | FIELD | METHOD |