com.buildforge.services.common.api
Enum Protocol

java.lang.Object
  extended by java.lang.Enum<Protocol>
      extended by com.buildforge.services.common.api.Protocol
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<Protocol>

public enum Protocol
extends java.lang.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:

 JSON does not have a dedicated integer type, so the more general, numeric type is used.
Source type Mapped typeComments
nullnull 
booleanboolean
intint
numbernumber 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.
EnumString 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.
StringString 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.
arrayarray 
DBObjectarray 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[]).
hashhash 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

  1. The form that specifies a user ID is invalid and should be treated as a protocol error.
  2. The only valid command codes are 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

BINARY

public static final Protocol BINARY
Uses a proprietary binary data format to represent request and response data. This is lighter and faster than the other protocols, but may be harder to implement and debug. The services layer binary protocol uses a combination of fixed- and variable-width fields to efficiently encode requests, as described in the pseudo-BNF below:

 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
 
 The TYPE_* constants are as defined in APIConstants.
 


JSON

public static final Protocol JSON
Uses the JavaScript Object Notation to represent request and response data. The following caveats apply:

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 ]
 } ]
 


XML

public static final Protocol XML
Uses eXtensible Markup Language to represent request and response data. The following caveats apply:
  • The protocol does not use text elements at all. If any are found during parsing, then they are silently discarded, regardless of whether or not they contain non-whitespace characters. In other words, if XML like <null key="MyNull">Text</null> is found, then Text is silently ignored.
  • The XML specification expressly forbids several character values that may legitimately exist in one of the strings being sent by this protocol, and the specification discourages the use of many others, as well. For example, the output from a command may include U+0008 (BACKSPACE) or U+001B (ESCAPE) because it intends for its output to be rendered on a terminal that interprets these contol codes. Since the XML specification does not permit these characters to exist in XML data, even as an entity escapes or within CData sections, the only option is to use a non-XML quoting mechanism to preserve them.

    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.

  • Outside of string values, whitespace is unimportant and may vary with the design and fine-tuning of the XML encoder.

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

values

public static final Protocol[] values()
Returns an array containing the constants of this enum type, in the order they're declared. This method may be used to iterate over the constants as follows:
for(Protocol c : Protocol.values())
        System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they're declared

valueOf

public static Protocol valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
java.lang.IllegalArgumentException - if this enum type has no constant with the specified name

getDefault

public static Protocol getDefault()
Queries the protocol that should be used by default for new connections.

Returns:
the Protocol that will be used by default

setDefaultProtocol

public static void setDefaultProtocol(Protocol defaultProtocol)
Sets the protocol that should be used by default for new connections.

Parameters:
defaultProtocol - the Protocol to use
Throws:
java.lang.NullPointerException - if defaultProtocol is null