public class SFSObject extends java.lang.Object implements ISFSObject
These two classes provide a fine-grained control over each data item sent over the network and provide high speed serialization using the default SFS2X binary protocol.
Let's consider this simple example: we need to send the data relative to a combat vehicle in a multiplayer game.
ISFSObject sfso = new SFSObject();
sfso.putByte("id", 10);
sfso.putShort("health", 5000);
sfso.putIntArray("pos", Arrays.asList(120,150));
sfso.putUtfString("name", "Hurricane");
In the above code we can use a single Byte (signed 8-bit) to send any small integer value, a Short (signed 16-bit)
for larger values and integers for any number that should be represented as regular 32-bit value.
The following is a list of type supported by the SFSObject class:
NOTE: UTF-8/multi-byte strings are not supported in key names. In other words you should restrict key names to standard ASCII characters.
It is also recommended to keep key names very short to save bandwidth. Strings values, instead, are handled via UTF-8 encoding, to support all languages and character sets. SFSObjects and SFSArrays can be nested to create complex data structures.Limitations: UTF Strings length is expressed using a signed short integer which means that a string can be up to 32768 characters. (Sending a larger text can be done via set/getText methods) The same applies to all the array types whose length is encoded in the same way, thus limiting the max length of an array to 32768 elements.
NOTE: SFSObject is not thread safe.
SFSArray| Constructor and Description |
|---|
SFSObject() |
| Modifier and Type | Method and Description |
|---|---|
boolean |
containsKey(java.lang.String key)
Looks for a specific key in the object
|
SFSDataWrapper |
get(java.lang.String key) |
java.lang.Boolean |
getBool(java.lang.String key)
Get the element for the specified key as Boolean.
|
java.util.Collection<java.lang.Boolean> |
getBoolArray(java.lang.String key)
Get the element for the specified key as a Collection of Booleans.
|
java.lang.Byte |
getByte(java.lang.String key)
Get the element for the specified key as Byte (signed 8 bit).
|
byte[] |
getByteArray(java.lang.String key)
Get the element for the specified key as a Collection of Byte.
|
java.lang.Object |
getClass(java.lang.String key)
Get the element for the specified key as a Class instance.
|
java.lang.Double |
getDouble(java.lang.String key)
Get the element for the specified key as Double (signed decimal 64 bit).
|
java.util.Collection<java.lang.Double> |
getDoubleArray(java.lang.String key)
Get the element for the specified key as a Collection of Double.
|
java.lang.String |
getDump()
Get a detailed dump of the SFSObject structure
|
java.lang.String |
getDump(boolean noFormat)
Get a detailed dump of the SFSObject structure
|
java.lang.Float |
getFloat(java.lang.String key)
Get the element for the specified key as Float (signed decimal 32 bit).
|
java.util.Collection<java.lang.Float> |
getFloatArray(java.lang.String key)
Get the element for the specified key as a Collection of Float.
|
java.lang.String |
getHexDump()
Get a pretty-printed hex-dump of the object
|
java.lang.Integer |
getInt(java.lang.String key)
Get the element for the specified key as Integer (signed 32 bit).
|
java.util.Collection<java.lang.Integer> |
getIntArray(java.lang.String key)
Get the element for the specified key as a Collection of Integer.
|
java.util.Set<java.lang.String> |
getKeys()
Get a Set of all keys
|
java.lang.Long |
getLong(java.lang.String key)
Get the element for the specified key as Long (signed 64 bit).
|
java.util.Collection<java.lang.Long> |
getLongArray(java.lang.String key)
Get the element for the specified key as a Collection of Long.
|
ISFSArray |
getSFSArray(java.lang.String key)
Get the element for the specified key as ISFSArray.
|
ISFSObject |
getSFSObject(java.lang.String key)
Get the element for the specified key as ISFSObject.
|
java.lang.Short |
getShort(java.lang.String key)
Get the element for the specified key as Short (signed 16 bit).
|
java.util.Collection<java.lang.Short> |
getShortArray(java.lang.String key)
Get the element for the specified key as a Collection of Short.
|
java.lang.String |
getText(java.lang.String key)
Get the element for the specified key as String using UTF-8 encoding.
|
java.lang.Integer |
getUnsignedByte(java.lang.String key)
Get the element for the specified key as unsigned byte.
|
java.util.Collection<java.lang.Integer> |
getUnsignedByteArray(java.lang.String key)
Get the element for the specified key as a Collection of unsigned Byte.
|
java.lang.String |
getUtfString(java.lang.String key)
Get the element for the specified key as String using UTF-8 encoding.
|
java.util.Collection<java.lang.String> |
getUtfStringArray(java.lang.String key)
Get the element for the specified key as a Collection of String.
|
boolean |
isNull(java.lang.String key)
Checks if a specific element is of SFSDataType.NULL.
|
java.util.Iterator<java.util.Map.Entry<java.lang.String,SFSDataWrapper>> |
iterator() |
static SFSObject |
newFromBinaryData(byte[] bytes)
Rebuild an SFSObject form its binary form
|
static ISFSObject |
newFromJsonData(java.lang.String jsonStr)
Creates an SFSObject from a JSON literal.
|
static SFSObject |
newFromObject(java.lang.Object o)
Converts any POJO (Plain Old Java Object) into an SFSObject providing a number of conventions and supported data types.
|
static SFSObject |
newFromResultSet(java.sql.ResultSet rset) |
static SFSObject |
newInstance()
Static constructor, similar to new SFSObject();
|
void |
put(java.lang.String key,
SFSDataWrapper wrappedObject) |
void |
putBool(java.lang.String key,
boolean value)
Add a boolean
|
void |
putBoolArray(java.lang.String key,
java.util.Collection<java.lang.Boolean> value)
Add a Collection of boolean
|
void |
putByte(java.lang.String key,
byte value)
Add a byte (signed 8-bit)
|
void |
putByteArray(java.lang.String key,
byte[] value)
Add an array of bytes
NOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
|
void |
putClass(java.lang.String key,
java.lang.Object o)
Add a Class instance.
|
void |
putDouble(java.lang.String key,
double value)
Add a double value (signed 32-bit)
|
void |
putDoubleArray(java.lang.String key,
java.util.Collection<java.lang.Double> value)
Add a Collection of double
|
void |
putFloat(java.lang.String key,
float value)
Add a float value (signed 32-bit)
|
void |
putFloatArray(java.lang.String key,
java.util.Collection<java.lang.Float> value)
Add a Collection of float
|
void |
putInt(java.lang.String key,
int value)
Add a short value (signed 32-bit)
|
void |
putIntArray(java.lang.String key,
java.util.Collection<java.lang.Integer> value)
Add a Collection of int
|
void |
putLong(java.lang.String key,
long value)
Add a long value (signed 32-bit)
|
void |
putLongArray(java.lang.String key,
java.util.Collection<java.lang.Long> value)
Add a Collection of long
|
void |
putNull(java.lang.String key)
Add a null field to the Object.
|
void |
putSFSArray(java.lang.String key,
ISFSArray value)
Add a nested ISFSArray
|
void |
putSFSObject(java.lang.String key,
ISFSObject value)
Add a nested SFSObject
|
void |
putShort(java.lang.String key,
short value)
Add a short value (signed 16-bit)
|
void |
putShortArray(java.lang.String key,
java.util.Collection<java.lang.Short> value)
Add a Collection of short
|
void |
putText(java.lang.String key,
java.lang.String value)
Add a string value (encoded in UTF-8), with a limit of 2 GBytes.
|
void |
putUtfString(java.lang.String key,
java.lang.String value)
Add a string value (encoded in UTF-8), with a limit of 32 KBytes.
|
void |
putUtfStringArray(java.lang.String key,
java.util.Collection<java.lang.String> value)
Add a Collection of string
|
boolean |
removeElement(java.lang.String key)
Remove an element in the object
|
int |
size()
Get the size of the SFSObject
|
byte[] |
toBinary()
Return a binary representation of the object
|
java.lang.String |
toJson()
Return a JSON representation of the object
|
java.lang.String |
toString() |
public static SFSObject newFromObject(java.lang.Object o)
Supported types:
Other rules:
Conventions: When de-serialized on the other end the system will look for a Class with the same fully qualified name and will attempt to instantiate it and populate with the received data via reflection.
NOTE: complex objects might take up a significantly large amount of bytes compared to regular SFSObjects.
If message size is a critical element and Class serialization seem to create too large packets we recommend to add a toSFSObject() and fromSFSObject()
methods on your classes to generate smaller representations of the data you need to transfer.
Also, if possible, try to export only the fields that are strictly necessary and using the most suitable data type (e.g a byte or short for small numbers, etc...)
public static SFSObject newFromBinaryData(byte[] bytes)
bytes - the binary datajava.lang.IllegalStateException - if there's any problem with decoding the binary datapublic static ISFSObject newFromJsonData(java.lang.String jsonStr)
| JSON | SFSObject
| Bool
| Bool
| Number
| Integer, Long, Double (autodetect)
| String
| UTF String
| Array
| SFSArray
| Object
| SFSObject
| |
jsonStr - the JSON literalpublic static SFSObject newFromResultSet(java.sql.ResultSet rset) throws java.sql.SQLException
java.sql.SQLExceptionpublic static SFSObject newInstance()
public java.util.Iterator<java.util.Map.Entry<java.lang.String,SFSDataWrapper>> iterator()
iterator in interface ISFSObjectpublic boolean containsKey(java.lang.String key)
ISFSObjectcontainsKey in interface ISFSObjectpublic boolean removeElement(java.lang.String key)
ISFSObjectremoveElement in interface ISFSObjectkey - the element namepublic int size()
ISFSObjectsize in interface ISFSObjectpublic byte[] toBinary()
ISFSObjecttoBinary in interface ISFSObjectpublic java.lang.String toJson()
ISFSObjecttoJson in interface ISFSObjectpublic java.lang.String getDump()
ISFSObjectgetDump in interface ISFSObjectpublic java.lang.String getDump(boolean noFormat)
ISFSObjectgetDump in interface ISFSObjectnoFormat - if true the dump will not be pretty-printedpublic java.lang.String getHexDump()
ISFSObjectgetHexDump in interface ISFSObjectpublic boolean isNull(java.lang.String key)
ISFSObjectisNull in interface ISFSObjectkey - the property namepublic SFSDataWrapper get(java.lang.String key)
get in interface ISFSObjectpublic java.lang.Boolean getBool(java.lang.String key)
ISFSObjectgetBool in interface ISFSObjectpublic java.util.Collection<java.lang.Boolean> getBoolArray(java.lang.String key)
ISFSObjectgetBoolArray in interface ISFSObjectpublic java.lang.Byte getByte(java.lang.String key)
ISFSObjectgetByte in interface ISFSObjectpublic byte[] getByteArray(java.lang.String key)
ISFSObjectNOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
getByteArray in interface ISFSObjectpublic java.lang.Double getDouble(java.lang.String key)
ISFSObjectgetDouble in interface ISFSObjectpublic java.util.Collection<java.lang.Double> getDoubleArray(java.lang.String key)
ISFSObjectgetDoubleArray in interface ISFSObjectpublic java.lang.Float getFloat(java.lang.String key)
ISFSObjectgetFloat in interface ISFSObjectpublic java.util.Collection<java.lang.Float> getFloatArray(java.lang.String key)
ISFSObjectgetFloatArray in interface ISFSObjectpublic java.lang.Integer getInt(java.lang.String key)
ISFSObjectgetInt in interface ISFSObjectpublic java.util.Collection<java.lang.Integer> getIntArray(java.lang.String key)
ISFSObjectgetIntArray in interface ISFSObjectpublic java.util.Set<java.lang.String> getKeys()
ISFSObjectgetKeys in interface ISFSObjectpublic java.lang.Long getLong(java.lang.String key)
ISFSObjectgetLong in interface ISFSObjectpublic java.util.Collection<java.lang.Long> getLongArray(java.lang.String key)
ISFSObjectgetLongArray in interface ISFSObjectpublic ISFSArray getSFSArray(java.lang.String key)
ISFSObjectgetSFSArray in interface ISFSObjectISFSArraypublic ISFSObject getSFSObject(java.lang.String key)
ISFSObjectgetSFSObject in interface ISFSObjectpublic java.lang.Short getShort(java.lang.String key)
ISFSObjectgetShort in interface ISFSObjectpublic java.util.Collection<java.lang.Short> getShortArray(java.lang.String key)
ISFSObjectgetShortArray in interface ISFSObjectpublic java.lang.Integer getUnsignedByte(java.lang.String key)
ISFSObjectgetUnsignedByte in interface ISFSObjectpublic java.util.Collection<java.lang.Integer> getUnsignedByteArray(java.lang.String key)
ISFSObjectgetUnsignedByteArray in interface ISFSObjectpublic java.lang.String getUtfString(java.lang.String key)
ISFSObjectThe string is limited to 32 KBytes
getUtfString in interface ISFSObjectpublic java.lang.String getText(java.lang.String key)
ISFSObjectThe string is limited to 2 GBytes
getText in interface ISFSObjectpublic java.util.Collection<java.lang.String> getUtfStringArray(java.lang.String key)
ISFSObjectgetUtfStringArray in interface ISFSObjectpublic java.lang.Object getClass(java.lang.String key)
ISFSObjectNOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
getClass in interface ISFSObjectnewFromObject(Object)public void putBool(java.lang.String key,
boolean value)
ISFSObjectputBool in interface ISFSObjectkey - the property namevalue - the valuepublic void putBoolArray(java.lang.String key,
java.util.Collection<java.lang.Boolean> value)
ISFSObjectputBoolArray in interface ISFSObjectkey - the property namevalue - the valuepublic void putByte(java.lang.String key,
byte value)
ISFSObjectputByte in interface ISFSObjectkey - the property namevalue - the valueISFSObject.getUnsignedByte(String)public void putByteArray(java.lang.String key,
byte[] value)
ISFSObjectNOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
putByteArray in interface ISFSObjectkey - the property namevalue - the valuepublic void putDouble(java.lang.String key,
double value)
ISFSObjectputDouble in interface ISFSObjectkey - the property namevalue - the valuepublic void putDoubleArray(java.lang.String key,
java.util.Collection<java.lang.Double> value)
ISFSObjectputDoubleArray in interface ISFSObjectkey - the property namevalue - the valuepublic void putFloat(java.lang.String key,
float value)
ISFSObjectputFloat in interface ISFSObjectkey - the property namevalue - the valuepublic void putFloatArray(java.lang.String key,
java.util.Collection<java.lang.Float> value)
ISFSObjectputFloatArray in interface ISFSObjectkey - the property namevalue - the valuepublic void putInt(java.lang.String key,
int value)
ISFSObjectputInt in interface ISFSObjectkey - the property namevalue - the valuepublic void putIntArray(java.lang.String key,
java.util.Collection<java.lang.Integer> value)
ISFSObjectputIntArray in interface ISFSObjectkey - the property namevalue - the valuepublic void putLong(java.lang.String key,
long value)
ISFSObjectputLong in interface ISFSObjectkey - the property namevalue - the valuepublic void putLongArray(java.lang.String key,
java.util.Collection<java.lang.Long> value)
ISFSObjectputLongArray in interface ISFSObjectkey - the property namevalue - the valuepublic void putNull(java.lang.String key)
ISFSObjectThis method will effectively add the key and a byte id to describe the Null value, thus "bloating" the message
putNull in interface ISFSObjectkey - the property namepublic void putSFSArray(java.lang.String key,
ISFSArray value)
ISFSObjectputSFSArray in interface ISFSObjectkey - the property namevalue - the valueISFSArraypublic void putSFSObject(java.lang.String key,
ISFSObject value)
ISFSObjectputSFSObject in interface ISFSObjectkey - the property namevalue - the valuepublic void putShort(java.lang.String key,
short value)
ISFSObjectputShort in interface ISFSObjectkey - the property namevalue - the valuepublic void putShortArray(java.lang.String key,
java.util.Collection<java.lang.Short> value)
ISFSObjectputShortArray in interface ISFSObjectkey - the property namevalue - the valuepublic void putUtfString(java.lang.String key,
java.lang.String value)
ISFSObjectputUtfString in interface ISFSObjectkey - the property namevalue - the valuepublic void putText(java.lang.String key,
java.lang.String value)
ISFSObjectputText in interface ISFSObjectkey - the property namevalue - the valuepublic void putUtfStringArray(java.lang.String key,
java.util.Collection<java.lang.String> value)
ISFSObjectputUtfStringArray in interface ISFSObjectkey - the property namevalue - the valuepublic void put(java.lang.String key,
SFSDataWrapper wrappedObject)
put in interface ISFSObjectpublic void putClass(java.lang.String key,
java.lang.Object o)
ISFSObjectSerializableSFSType interface.putClass in interface ISFSObjectkey - the property nameo - the instance
NOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
newFromObject(Object)public java.lang.String toString()
toString in class java.lang.Object