Package com.smartfoxserver.entities.data

Class SFSArray

java.lang.Object
com.smartfoxserver.entities.data.SFSArray
All Implemented Interfaces:
ISFSArray, Serializable
Direct Known Subclasses:
SFSArrayLite
public class SFSArray extends Object implements ISFSArray, Serializable
SFSArray and SFSObject represent a platform-neutral, high-level objects that abstract the data transport between client and server. They are used to respectively represent data in form of a List or Map. They can be nested and they can transport many different data types (from bytes to integers, doubles, strings and a lot more)

Let's consider this simple example: we need to send the data relative to a combat vehicle in a multiplayer game. In order reduce the amount of bytes sent to a minimum we will send the data as an array avoiding the overhead of key names for each item. 

                ISFSArray sfsa = new SFSArray();
                sfsa.addByte(10);       // the vehicle id
                sfsa.addShort(5000); // the vehicle current health
                sfsa.addIntArray(Arrays.asList(120,150)); // the x,y position on the terrain as int[]
                sfsa.addShortString("Hurricane"); // the vehicle name
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. In this example we imagined to have a wide RTS environment and we used an int[] to transmit the x,y position of the vehicle.

The following is a list of type supported by the SFSArray class:

TypeItem sizeArray Len
null--- 
bool1 byte 
byte1 byte 
short2 bytes 
int4 bytes 
long8 bytes 
float4 bytes 
double8 bytes 
Vector28 bytes 
Vector312 bytes 
short string<= 255 bytes 
string<= 2ˆ15 bytes 
text<= 2ˆ31 bytes 
bool array1 byte<= 2ˆ15
byte array1 byte<= 2ˆ31
short array2 bytes<= 2ˆ15
int array4 bytes<= 2ˆ15
long array8 bytes<= 2ˆ15
float array4 bytes<= 2ˆ15
double array8 bytes<= 2ˆ15
Vector2 array8 bytes<= 2ˆ15
Vector3 array12 bytes<= 2ˆ15
short string array<= 255 bytes<= 2ˆ15
string array<= 2ˆ15 bytes<= 2ˆ15

NOTE #1: all strings are treated as UTF-8 and therefore characters may be represented by multiple bytes. A String with 255 characters might use more than 255 bytes to be represented.

NOTE #2: SFSObject and SFSArray can be nested inside each other to create more complex data structures.

NOTE #3: SFSObject and SFSArray methods are not thread safe.

NOTE #4: An SFSArray can contain a maximum of 32768 elements.

See Also:

  • Constructor Details

    • SFSArray

      public SFSArray()

  • Method Details

    • newFromBinaryData

      public static SFSArray newFromBinaryData(byte[] bytes)
      Rebuild an SFSArray form its binary form
      Parameters:
      bytes - the binary data
      Returns:
      the original SFSArray
      Throws:
      IllegalStateException - if there's any problem with decoding the binary data

    • newFromResultSet

      public static SFSArray newFromResultSet(ResultSet rset) throws SQLException
      Throws:
      SQLException

    • newFromJsonData

      public static SFSArray newFromJsonData(String jsonStr)
      Internal

    • newInstance

      public static SFSArray newInstance()
      Static constructor, similar to new SFSArray();
      Returns:
      a new SFSArray

    • getDump

      public String getDump()
      Description copied from interface: ISFSArray
      Get a detailed dump of the SFSArray structure
      Specified by:
      getDump in interface ISFSArray
      Returns:
      a detailed dump of the SFSArray structure

    • getDump

      public String getDump(boolean noFormat)
      Description copied from interface: ISFSArray
      Get a detailed dump of the SFSArray structure
      Specified by:
      getDump in interface ISFSArray
      Parameters:
      noFormat - if true the dump will not be pretty-printed
      Returns:
      a detailed dump of the SFSArray structure

    • getHexDump

      public String getHexDump()
      Description copied from interface: ISFSArray
      Get a pretty-printed hex-dump of the array
      Specified by:
      getHexDump in interface ISFSArray
      Returns:
      a pretty-printed hex-dump of the array

    • toBinary

      public byte[] toBinary()
      Description copied from interface: ISFSArray
      Return the binary representation of the SFSArray
      Specified by:
      toBinary in interface ISFSArray
      Returns:
      the binary representation of the SFSArray

    • toJson

      public String toJson()
      Description copied from interface: ISFSArray
      Return the JSON representation of the SFSArray
      Specified by:
      toJson in interface ISFSArray
      Returns:
      the JSON representation of the SFSArray
      Internal

    • isNull

      public boolean isNull(int index)
      Description copied from interface: ISFSArray
      Checks if a specific element is null.
      Specified by:
      isNull in interface ISFSArray
      Parameters:
      index - the index of the element in the array
      Returns:
      true if the item is null

    • get

      public SFSDataWrapper get(int index)
      Specified by:
      get in interface ISFSArray

    • getBool

      public Boolean getBool(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Boolean. It can be null if no element exists for the specified index
      Specified by:
      getBool in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getByte

      public Byte getByte(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Byte. It can be null if no element exists for the specified index
      Specified by:
      getByte in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getUnsignedByte

      public Integer getUnsignedByte(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as an unsigned Integer (bytes are always signed, -127 < b < 127)
      It can be null if no element exists for the specified index
      Specified by:
      getUnsignedByte in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getShort

      public Short getShort(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Short. It can be null if no element exists for the specified index
      Specified by:
      getShort in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getInt

      public Integer getInt(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Integer. It can be null if no element exists for the specified index
      Specified by:
      getInt in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getLong

      public Long getLong(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Long. It can be null if no element exists for the specified index
      Specified by:
      getLong in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getFloat

      public Float getFloat(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Float. It can be null if no element exists for the specified index
      Specified by:
      getFloat in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getDouble

      public Double getDouble(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Double. It can be null if no element exists for the specified index
      Specified by:
      getDouble in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getString

      public String getString(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as string, with a max length of 32768 bytes It can be null if no element exists for the specified index
      Specified by:
      getString in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getShortString

      public String getShortString(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as short string, with a max length of 255 bytes It can be null if no element exists for the specified index
      Specified by:
      getShortString in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getText

      public String getText(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as long String, with a max length of 2 GBytes. It can be null if no element exists for the specified index
      Specified by:
      getText in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getVector2

      public SFSVector2 getVector2(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as SFSVector2.
      Specified by:
      getVector2 in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getVector3

      public SFSVector3 getVector3(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as SFSVector3.
      Specified by:
      getVector3 in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getBoolArray

      public Collection<Boolean> getBoolArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of Boolean. It can be null if no element exists for the specified index
      Specified by:
      getBoolArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getByteArray

      public byte[] getByteArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as byte array. It can be null if no element exists for the specified index

      NOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.

      Specified by:
      getByteArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getUnsignedByteArray

      public Collection<Integer> getUnsignedByteArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as a Collection of unsigned integers. It can be null if no element exists for the specified index
      Specified by:
      getUnsignedByteArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getShortArray

      public Collection<Short> getShortArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of Short. It can be null if no element exists for the specified index
      Specified by:
      getShortArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getIntArray

      public Collection<Integer> getIntArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of Int. It can be null if no element exists for the specified index
      Specified by:
      getIntArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getLongArray

      public Collection<Long> getLongArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of Long. It can be null if no element exists for the specified index
      Specified by:
      getLongArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getFloatArray

      public Collection<Float> getFloatArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of Float. It can be null if no element exists for the specified index
      Specified by:
      getFloatArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getDoubleArray

      public Collection<Double> getDoubleArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of Double. It can be null if no element exists for the specified index
      Specified by:
      getDoubleArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getStringArray

      public Collection<String> getStringArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of String. It can be null if no element exists for the specified index Each string is limited to 32768 bytes
      Specified by:
      getStringArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getShortStringArray

      public Collection<String> getShortStringArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of String. It can be null if no element exists for the specified index Each string is limited to 255 bytes
      Specified by:
      getShortStringArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getVector2Array

      public Collection<SFSVector2> getVector2Array(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of SFSVector2. It can be null if no element exists for the specified index
      Specified by:
      getVector2Array in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getVector3Array

      public Collection<SFSVector3> getVector3Array(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as Collection of SFSVector3. It can be null if no element exists for the specified index Each string is limited to 255 bytes
      Specified by:
      getVector3Array in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getSFSArray

      public ISFSArray getSFSArray(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as ISFSArray. It can be null if no element exists for the specified index
      Specified by:
      getSFSArray in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null

    • getSFSObject

      public ISFSObject getSFSObject(int index)
      Description copied from interface: ISFSArray
      Get the element at the specified index as ISFSObject. It can be null if no element exists for the specified index
      Specified by:
      getSFSObject in interface ISFSArray
      Parameters:
      index -
      Returns:
      the element, or null
      See Also:

    • addBool

      public void addBool(boolean value)
      Description copied from interface: ISFSArray
      Add a boolean
      Specified by:
      addBool in interface ISFSArray
      Parameters:
      value -

    • addBoolArray

      public void addBoolArray(Collection<Boolean> value)
      Description copied from interface: ISFSArray
      Add an collection of boolean
      Specified by:
      addBoolArray in interface ISFSArray
      Parameters:
      value -

    • addByte

      public void addByte(byte value)
      Description copied from interface: ISFSArray
      Add a byte (signed 8-bit)
      Specified by:
      addByte in interface ISFSArray
      Parameters:
      value -

    • addByteArray

      public void addByteArray(byte[] value)
      Description copied from interface: ISFSArray
      Add an array of bytes

      NOTE: This is not supported for HTML5 / Websocket clients, which includes Unity WebGL exports.

      Specified by:
      addByteArray in interface ISFSArray
      Parameters:
      value -

    • addDouble

      public void addDouble(double value)
      Description copied from interface: ISFSArray
      Add a byte (signed decimal 64-bit)
      Specified by:
      addDouble in interface ISFSArray
      Parameters:
      value -

    • addDoubleArray

      public void addDoubleArray(Collection<Double> value)
      Description copied from interface: ISFSArray
      Add a collection of double
      Specified by:
      addDoubleArray in interface ISFSArray
      Parameters:
      value -

    • addFloat

      public void addFloat(float value)
      Description copied from interface: ISFSArray
      Add a byte (signed decimal 32-bit)
      Specified by:
      addFloat in interface ISFSArray
      Parameters:
      value -

    • addFloatArray

      public void addFloatArray(Collection<Float> value)
      Description copied from interface: ISFSArray
      Add a collection of float
      Specified by:
      addFloatArray in interface ISFSArray
      Parameters:
      value -

    • addInt

      public void addInt(int value)
      Description copied from interface: ISFSArray
      Add a byte (signed 32-bit)
      Specified by:
      addInt in interface ISFSArray
      Parameters:
      value -

    • addIntArray

      public void addIntArray(Collection<Integer> value)
      Description copied from interface: ISFSArray
      Add a collection of int
      Specified by:
      addIntArray in interface ISFSArray
      Parameters:
      value -

    • addLong

      public void addLong(long value)
      Description copied from interface: ISFSArray
      Add a byte (signed 64-bit)
      Specified by:
      addLong in interface ISFSArray
      Parameters:
      value -

    • addLongArray

      public void addLongArray(Collection<Long> value)
      Description copied from interface: ISFSArray
      Add a collection of long
      Specified by:
      addLongArray in interface ISFSArray
      Parameters:
      value -

    • addNull

      public void addNull()
      Description copied from interface: ISFSArray
      Add a null field to the Object. Normally we recommend that null values are simply not sent. On the other end of the application you can simply check if a specific key exists or not, to detect a null.

      This method will effectively add the key and a byte id to describe the Null value, thus "bloating" the message

      Specified by:
      addNull in interface ISFSArray

    • addSFSArray

      public void addSFSArray(ISFSArray value)
      Description copied from interface: ISFSArray
      Add a nested ISFSArray
      Specified by:
      addSFSArray in interface ISFSArray
      Parameters:
      value -

    • addSFSObject

      public void addSFSObject(ISFSObject value)
      Description copied from interface: ISFSArray
      Add a nested ISFSObject
      Specified by:
      addSFSObject in interface ISFSArray
      Parameters:
      value -

    • addShort

      public void addShort(short value)
      Description copied from interface: ISFSArray
      Add a byte (signed 16-bit)
      Specified by:
      addShort in interface ISFSArray
      Parameters:
      value -

    • addShortArray

      public void addShortArray(Collection<Short> value)
      Description copied from interface: ISFSArray
      Add a collection of short
      Specified by:
      addShortArray in interface ISFSArray
      Parameters:
      value -

    • addString

      public void addString(String value)
      Description copied from interface: ISFSArray
      Add a UTF encoded string with max length of 32768 bytes
      Specified by:
      addString in interface ISFSArray
      Parameters:
      value -

    • addShortString

      public void addShortString(String value)
      Description copied from interface: ISFSArray
      Add a UTF encoded string with max length of 255 bytes
      Specified by:
      addShortString in interface ISFSArray
      Parameters:
      value -

    • addText

      public void addText(String value)
      Description copied from interface: ISFSArray
      Add a UTF encoded long String with max length of 2 GBytes
      Specified by:
      addText in interface ISFSArray
      Parameters:
      value -

    • addVector2

      public void addVector2(SFSVector2 value)
      Description copied from interface: ISFSArray
      Add a SFSVector2 (2x float 32bit)
      Specified by:
      addVector2 in interface ISFSArray
      Parameters:
      value -

    • addVector3

      public void addVector3(SFSVector3 value)
      Description copied from interface: ISFSArray
      Add a SFSVector3 (3x float 32bit)
      Specified by:
      addVector3 in interface ISFSArray
      Parameters:
      value -

    • addStringArray

      public void addStringArray(Collection<String> value)
      Description copied from interface: ISFSArray
      Add a collection of UTF encoded strings, each string limited to a max of 32768 bytes The collection is also limited to a max of 32768 elements
      Specified by:
      addStringArray in interface ISFSArray
      Parameters:
      value -

    • addShortStringArray

      public void addShortStringArray(Collection<String> value)
      Description copied from interface: ISFSArray
      Add a collection of UTF encoded strings, each string limited to a max of 255 bytes The collection is also limited to a max of 32768 elements
      Specified by:
      addShortStringArray in interface ISFSArray
      Parameters:
      value -

    • addVector2Array

      public void addVector2Array(Collection<SFSVector2> value)
      Description copied from interface: ISFSArray
      Add a collection of SFSVector2
      Specified by:
      addVector2Array in interface ISFSArray
      Parameters:
      value -

    • addVector3Array

      public void addVector3Array(Collection<SFSVector3> value)
      Description copied from interface: ISFSArray
      Add a collection of SFSVector3
      Specified by:
      addVector3Array in interface ISFSArray
      Parameters:
      value -

    • add

      public void add(SFSDataWrapper wrappedObject)
      Specified by:
      add in interface ISFSArray

    • contains

      public boolean contains(Object obj)
      Description copied from interface: ISFSArray
      Checks if a specific element is contained in the array
      Specified by:
      contains in interface ISFSArray
      Parameters:
      obj - the object
      Returns:
      true if the object exists

    • getElementAt

      public Object getElementAt(int index)
      Specified by:
      getElementAt in interface ISFSArray

    • iterator

      public Iterator<SFSDataWrapper> iterator()
      Specified by:
      iterator in interface ISFSArray

    • removeElementAt

      public void removeElementAt(int index)
      Description copied from interface: ISFSArray
      Remove an element at a specific index
      Specified by:
      removeElementAt in interface ISFSArray
      Parameters:
      index - the index of the element to remove

    • size

      public int size()
      Description copied from interface: ISFSArray
      Return the number of elements contained in the array
      Specified by:
      size in interface ISFSArray
      Returns:
      the number of elements contained in the array

    • toString

      public String toString()
      Overrides:
      toString in class Object