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.SQLException
public static SFSObject newInstance()
public java.util.Iterator<java.util.Map.Entry<java.lang.String,SFSDataWrapper>> iterator()
iterator
in interface ISFSObject
public boolean containsKey(java.lang.String key)
ISFSObject
containsKey
in interface ISFSObject
public boolean removeElement(java.lang.String key)
ISFSObject
removeElement
in interface ISFSObject
key
- the element namepublic int size()
ISFSObject
size
in interface ISFSObject
public byte[] toBinary()
ISFSObject
toBinary
in interface ISFSObject
public java.lang.String toJson()
ISFSObject
toJson
in interface ISFSObject
public java.lang.String getDump()
ISFSObject
getDump
in interface ISFSObject
public java.lang.String getDump(boolean noFormat)
ISFSObject
getDump
in interface ISFSObject
noFormat
- if true the dump will not be pretty-printedpublic java.lang.String getHexDump()
ISFSObject
getHexDump
in interface ISFSObject
public boolean isNull(java.lang.String key)
ISFSObject
isNull
in interface ISFSObject
key
- the property namepublic SFSDataWrapper get(java.lang.String key)
get
in interface ISFSObject
public java.lang.Boolean getBool(java.lang.String key)
ISFSObject
getBool
in interface ISFSObject
public java.util.Collection<java.lang.Boolean> getBoolArray(java.lang.String key)
ISFSObject
getBoolArray
in interface ISFSObject
public java.lang.Byte getByte(java.lang.String key)
ISFSObject
getByte
in interface ISFSObject
public byte[] getByteArray(java.lang.String key)
ISFSObject
NOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
getByteArray
in interface ISFSObject
public java.lang.Double getDouble(java.lang.String key)
ISFSObject
getDouble
in interface ISFSObject
public java.util.Collection<java.lang.Double> getDoubleArray(java.lang.String key)
ISFSObject
getDoubleArray
in interface ISFSObject
public java.lang.Float getFloat(java.lang.String key)
ISFSObject
getFloat
in interface ISFSObject
public java.util.Collection<java.lang.Float> getFloatArray(java.lang.String key)
ISFSObject
getFloatArray
in interface ISFSObject
public java.lang.Integer getInt(java.lang.String key)
ISFSObject
getInt
in interface ISFSObject
public java.util.Collection<java.lang.Integer> getIntArray(java.lang.String key)
ISFSObject
getIntArray
in interface ISFSObject
public java.util.Set<java.lang.String> getKeys()
ISFSObject
getKeys
in interface ISFSObject
public java.lang.Long getLong(java.lang.String key)
ISFSObject
getLong
in interface ISFSObject
public java.util.Collection<java.lang.Long> getLongArray(java.lang.String key)
ISFSObject
getLongArray
in interface ISFSObject
public ISFSArray getSFSArray(java.lang.String key)
ISFSObject
getSFSArray
in interface ISFSObject
ISFSArray
public ISFSObject getSFSObject(java.lang.String key)
ISFSObject
getSFSObject
in interface ISFSObject
public java.lang.Short getShort(java.lang.String key)
ISFSObject
getShort
in interface ISFSObject
public java.util.Collection<java.lang.Short> getShortArray(java.lang.String key)
ISFSObject
getShortArray
in interface ISFSObject
public java.lang.Integer getUnsignedByte(java.lang.String key)
ISFSObject
getUnsignedByte
in interface ISFSObject
public java.util.Collection<java.lang.Integer> getUnsignedByteArray(java.lang.String key)
ISFSObject
getUnsignedByteArray
in interface ISFSObject
public java.lang.String getUtfString(java.lang.String key)
ISFSObject
The string is limited to 32 KBytes
getUtfString
in interface ISFSObject
public java.lang.String getText(java.lang.String key)
ISFSObject
The string is limited to 2 GBytes
getText
in interface ISFSObject
public java.util.Collection<java.lang.String> getUtfStringArray(java.lang.String key)
ISFSObject
getUtfStringArray
in interface ISFSObject
public java.lang.Object getClass(java.lang.String key)
ISFSObject
NOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
getClass
in interface ISFSObject
newFromObject(Object)
public void putBool(java.lang.String key, boolean value)
ISFSObject
putBool
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putBoolArray(java.lang.String key, java.util.Collection<java.lang.Boolean> value)
ISFSObject
putBoolArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putByte(java.lang.String key, byte value)
ISFSObject
putByte
in interface ISFSObject
key
- the property namevalue
- the valueISFSObject.getUnsignedByte(String)
public void putByteArray(java.lang.String key, byte[] value)
ISFSObject
NOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.
putByteArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putDouble(java.lang.String key, double value)
ISFSObject
putDouble
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putDoubleArray(java.lang.String key, java.util.Collection<java.lang.Double> value)
ISFSObject
putDoubleArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putFloat(java.lang.String key, float value)
ISFSObject
putFloat
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putFloatArray(java.lang.String key, java.util.Collection<java.lang.Float> value)
ISFSObject
putFloatArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putInt(java.lang.String key, int value)
ISFSObject
putInt
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putIntArray(java.lang.String key, java.util.Collection<java.lang.Integer> value)
ISFSObject
putIntArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putLong(java.lang.String key, long value)
ISFSObject
putLong
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putLongArray(java.lang.String key, java.util.Collection<java.lang.Long> value)
ISFSObject
putLongArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putNull(java.lang.String key)
ISFSObject
This method will effectively add the key and a byte id to describe the Null value, thus "bloating" the message
putNull
in interface ISFSObject
key
- the property namepublic void putSFSArray(java.lang.String key, ISFSArray value)
ISFSObject
putSFSArray
in interface ISFSObject
key
- the property namevalue
- the valueISFSArray
public void putSFSObject(java.lang.String key, ISFSObject value)
ISFSObject
putSFSObject
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putShort(java.lang.String key, short value)
ISFSObject
putShort
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putShortArray(java.lang.String key, java.util.Collection<java.lang.Short> value)
ISFSObject
putShortArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putUtfString(java.lang.String key, java.lang.String value)
ISFSObject
putUtfString
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putText(java.lang.String key, java.lang.String value)
ISFSObject
putText
in interface ISFSObject
key
- the property namevalue
- the valuepublic void putUtfStringArray(java.lang.String key, java.util.Collection<java.lang.String> value)
ISFSObject
putUtfStringArray
in interface ISFSObject
key
- the property namevalue
- the valuepublic void put(java.lang.String key, SFSDataWrapper wrappedObject)
put
in interface ISFSObject
public void putClass(java.lang.String key, java.lang.Object o)
ISFSObject
SerializableSFSType
interface.putClass
in interface ISFSObject
key
- 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