Package com.smartfoxserver.v2.entities.data

Class SFSArray

  • All Implemented Interfaces:
    ISFSArray, java.io.Serializable
    Direct Known Subclasses:
    SFSArrayLite
    public class SFSArray
extends java.lang.Object
implements ISFSArray, java.io.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 Map/Dictionary and List/Array. They can be nested and they can transport many different data types (from bytes to integers, doubles, strings and a lot more)

    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. 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.addUtfString("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:

    • null
    • boolean
    • byte
    • short
    • int
    • long
    • float
    • double
    • utf-string
    • boolean array
    • byte array
    • short array
    • int array
    • long array
    • float array
    • double array
    • utf-string array
    • SFSObject
    • SFSArray
    Strings are handled via UTF-8 encoding, to support all languages and character sets.
    SFSArrays and SFSObjects can be nested to create complex data structures.

    NOTE: SFSArray is not thread safe.

    Limitations: An SFSArray can contain a maximum of 32768 elements, also the UTF Strings length is expressed using a signed short integer which means that a string can be long up to 32768 characters.

    See Also:
    SFSObject, Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      SFSArray()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(SFSDataWrapper wrappedObject)  
      void addBool​(boolean value)
      Add a boolean
      void addBoolArray​(java.util.Collection<java.lang.Boolean> value)
      Add an collection of boolean
      void addByte​(byte value)
      Add a byte (signed 8-bit)
      void addByteArray​(byte[] value)
      Add an array of bytes
      void addClass​(java.lang.Object o)
      Add a Class instance.
      void addDouble​(double value)
      Add a byte (signed decimal 64-bit)
      void addDoubleArray​(java.util.Collection<java.lang.Double> value)
      Add a collection of double
      void addFloat​(float value)
      Add a byte (signed decimal 32-bit)
      void addFloatArray​(java.util.Collection<java.lang.Float> value)
      Add a collection of float
      void addInt​(int value)
      Add a byte (signed 32-bit)
      void addIntArray​(java.util.Collection<java.lang.Integer> value)
      Add a collection of int
      void addLong​(long value)
      Add a byte (signed 64-bit)
      void addLongArray​(java.util.Collection<java.lang.Long> value)
      Add a collection of long
      void addNull()
      Add a null field to the Object.
      void addSFSArray​(ISFSArray value)
      Add a nested ISFSArray
      void addSFSObject​(ISFSObject value)
      Add a nested ISFSObject
      void addShort​(short value)
      Add a byte (signed 16-bit)
      void addShortArray​(java.util.Collection<java.lang.Short> value)
      Add a collection of short
      void addText​(java.lang.String value)
      Add a long String encoded in UTF-8 with max length of 2 GBytes
      void addUtfString​(java.lang.String value)
      Add a String encoded in UTF-8 with max length of 32 KBytes
      void addUtfStringArray​(java.util.Collection<java.lang.String> value)
      Add a collection of string
      boolean contains​(java.lang.Object obj)
      Checks if a specific element is contained in the array
      SFSDataWrapper get​(int index)  
      java.lang.Boolean getBool​(int index)
      Get the element at the specified index as Boolean.
      java.util.Collection<java.lang.Boolean> getBoolArray​(int index)
      Get the element at the specified index as Collection of Boolean.
      java.lang.Byte getByte​(int index)
      Get the element at the specified index as Byte.
      byte[] getByteArray​(int index)
      Get the element at the specified index as byte array.
      java.lang.Object getClass​(int index)
      Get the element at the specified index as Class instance.
      java.lang.Double getDouble​(int index)
      Get the element at the specified index as Double.
      java.util.Collection<java.lang.Double> getDoubleArray​(int index)
      Get the element at the specified index as Collection of Double.
      java.lang.String getDump()
      Get a detailed dump of the SFSArray structure
      java.lang.String getDump​(boolean noFormat)
      Get a detailed dump of the SFSArray structure
      java.lang.Object getElementAt​(int index)  
      java.lang.Float getFloat​(int index)
      Get the element at the specified index as Float.
      java.util.Collection<java.lang.Float> getFloatArray​(int index)
      Get the element at the specified index as Collection of Float.
      java.lang.String getHexDump()
      Get a pretty-printed hex-dump of the array
      java.lang.Integer getInt​(int index)
      Get the element at the specified index as Integer.
      java.util.Collection<java.lang.Integer> getIntArray​(int index)
      Get the element at the specified index as Collection of Int.
      java.lang.Long getLong​(int index)
      Get the element at the specified index as Long.
      java.util.Collection<java.lang.Long> getLongArray​(int index)
      Get the element at the specified index as Collection of Long.
      ISFSArray getSFSArray​(int index)
      Get the element at the specified index as ISFSArray.
      ISFSObject getSFSObject​(int index)
      Get the element at the specified index as ISFSObject.
      java.lang.Short getShort​(int index)
      Get the element at the specified index as Short.
      java.util.Collection<java.lang.Short> getShortArray​(int index)
      Get the element at the specified index as Collection of Short.
      java.lang.String getText​(int index)
      Get the element at the specified index as long String, with a max length of 2 GBytes.
      java.lang.Integer getUnsignedByte​(int index)
      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
      java.util.Collection<java.lang.Integer> getUnsignedByteArray​(int index)
      Get the element at the specified index as a Collection of unsigned integers.
      java.lang.String getUtfString​(int index)
      Get the element at the specified index as String, with a max length of 32 KBytes.
      java.util.Collection<java.lang.String> getUtfStringArray​(int index)
      Get the element at the specified index as Collection of String.
      boolean isNull​(int index)
      Checks if a specific element is null.
      java.util.Iterator<SFSDataWrapper> iterator()  
      static SFSArray newFromBinaryData​(byte[] bytes)
      Rebuild an SFSArray form its binary form
      static SFSArray newFromJsonData​(java.lang.String jsonStr)
      Creates an SFSObject from a JSON literal.
      static SFSArray newFromResultSet​(java.sql.ResultSet rset)  
      static SFSArray newInstance()
      Static constructor, similar to new SFSArray();
      void removeElementAt​(int index)
      Remove an element at a specific index
      int size()
      Return the number of elements contained in the array
      byte[] toBinary()
      Return the binary representation of the SFSArray
      java.lang.String toJson()
      Return the JSON representation of the SFSArray
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • SFSArray

        public SFSArray()

    • Method Detail

      • newFromBinaryData

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

      • newFromResultSet

        public static SFSArray newFromResultSet​(java.sql.ResultSet rset)
                                 throws java.sql.SQLException
        Throws:
        java.sql.SQLException

      • newFromJsonData

        public static SFSArray newFromJsonData​(java.lang.String jsonStr)
        Creates an SFSObject from a JSON literal. Type conversion is done as follows:

        JSON SFSObject
        Bool Bool
        Number Integer, Long, Double (autodetect)
        String UTF String
        Array SFSArray
        Object SFSObject
        Parameters:
        jsonStr - the JSON literal
        Returns:
        the SFSObject

      • newInstance

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

      • getDump

        public java.lang.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 java.lang.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 java.lang.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 java.lang.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

      • 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

      • getBool

        public java.lang.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
        Returns:
        the element, or null

      • getByte

        public java.lang.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
        Returns:
        the element, or null

      • getUnsignedByte

        public java.lang.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
        Returns:
        the element, or null

      • getShort

        public java.lang.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
        Returns:
        the element, or null

      • getInt

        public java.lang.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
        Returns:
        the element, or null

      • getLong

        public java.lang.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
        Returns:
        the element, or null

      • getFloat

        public java.lang.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
        Returns:
        the element, or null

      • getDouble

        public java.lang.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
        Returns:
        the element, or null

      • getUtfString

        public java.lang.String getUtfString​(int index)
        Description copied from interface: ISFSArray
        Get the element at the specified index as String, with a max length of 32 KBytes. It can be null if no element exists for the specified index
        Specified by:
        getUtfString in interface ISFSArray
        Returns:
        the element, or null

      • getText

        public java.lang.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
        Returns:
        the element, or null

      • getBoolArray

        public java.util.Collection<java.lang.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
        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
        Returns:
        the element, or null

      • getUnsignedByteArray

        public java.util.Collection<java.lang.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
        Returns:
        the element, or null

      • getShortArray

        public java.util.Collection<java.lang.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
        Returns:
        the element, or null

      • getIntArray

        public java.util.Collection<java.lang.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
        Returns:
        the element, or null

      • getLongArray

        public java.util.Collection<java.lang.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
        Returns:
        the element, or null

      • getFloatArray

        public java.util.Collection<java.lang.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
        Returns:
        the element, or null

      • getDoubleArray

        public java.util.Collection<java.lang.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
        Returns:
        the element, or null

      • getUtfStringArray

        public java.util.Collection<java.lang.String> getUtfStringArray​(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
        Specified by:
        getUtfStringArray in interface ISFSArray
        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
        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
        Returns:
        the element, or null
        See Also:
        ISFSObject

      • getClass

        public java.lang.Object getClass​(int index)
        Description copied from interface: ISFSArray
        Get the element at the specified index as Class instance. The class definition is contained in the instance itself and it will be rebuilt using reflection. 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:
        getClass in interface ISFSArray
        Returns:
        the element, or null
        See Also:
        SFSObject.newFromObject(Object)

      • addBool

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

      • addBoolArray

        public void addBoolArray​(java.util.Collection<java.lang.Boolean> value)
        Description copied from interface: ISFSArray
        Add an collection of boolean
        Specified by:
        addBoolArray in interface ISFSArray

      • addByte

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

      • 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

      • addDouble

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

      • addDoubleArray

        public void addDoubleArray​(java.util.Collection<java.lang.Double> value)
        Description copied from interface: ISFSArray
        Add a collection of double
        Specified by:
        addDoubleArray in interface ISFSArray

      • addFloat

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

      • addFloatArray

        public void addFloatArray​(java.util.Collection<java.lang.Float> value)
        Description copied from interface: ISFSArray
        Add a collection of float
        Specified by:
        addFloatArray in interface ISFSArray

      • addInt

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

      • addIntArray

        public void addIntArray​(java.util.Collection<java.lang.Integer> value)
        Description copied from interface: ISFSArray
        Add a collection of int
        Specified by:
        addIntArray in interface ISFSArray

      • addLong

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

      • addLongArray

        public void addLongArray​(java.util.Collection<java.lang.Long> value)
        Description copied from interface: ISFSArray
        Add a collection of long
        Specified by:
        addLongArray in interface ISFSArray

      • 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

      • addShort

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

      • addShortArray

        public void addShortArray​(java.util.Collection<java.lang.Short> value)
        Description copied from interface: ISFSArray
        Add a collection of short
        Specified by:
        addShortArray in interface ISFSArray

      • addUtfString

        public void addUtfString​(java.lang.String value)
        Description copied from interface: ISFSArray
        Add a String encoded in UTF-8 with max length of 32 KBytes
        Specified by:
        addUtfString in interface ISFSArray

      • addText

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

      • addUtfStringArray

        public void addUtfStringArray​(java.util.Collection<java.lang.String> value)
        Description copied from interface: ISFSArray
        Add a collection of string
        Specified by:
        addUtfStringArray in interface ISFSArray

      • addClass

        public void addClass​(java.lang.Object o)
        Description copied from interface: ISFSArray
        Add a Class instance. The instance must implement the SerializableSFSType interface.

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

        Specified by:
        addClass in interface ISFSArray
        Parameters:
        o - the instance
        See Also:
        SFSObject.newFromObject(Object)

      • contains

        public boolean contains​(java.lang.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 java.lang.Object getElementAt​(int index)
        Specified by:
        getElementAt 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object