Package totalcross.io

Class DataStream

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    Direct Known Subclasses:
    DataStreamLE
    public class DataStream
extends Stream
    DataStream can be attached to any Stream such as a PortConnector, PDBFile, or ByteArrayStream, which lets you read and write standard Java data types like int, double, and String in a simple manner. Here's an example: 
     PortConnector port = new PortConnector(9600, 0);
 DataStream ds = new DataStream(port);
 ds.writeString("Hello");
 int status = ds.readUnsignedByte();
 if (status == 1)
 {
    ds.writeString("Pi");
    ds.writeDouble(3.14);
 }
 port.close();

    Important!: All methods read and write numeric data in the big endian format (Java format). For more information, see this.
    See Also:
    DataStreamLE

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected byte[] buffer
      a four byte array for reading and writing numbers
      static java.lang.String EOSMessage
      Message thrown when an end of stream is reached when reading.
      protected Stream stream
      The underlying stream, from where bytes are read and written.
      protected static byte[] zeros  

    • Constructor Summary

      Constructors 
      Constructor Description
      DataStream​(Stream stream)
      Constructs a new DataStream which sits upon the given stream using big endian notation for multibyte values.
      DataStream​(Stream stream, boolean ensureWrite)
      Constructs a new DataStream which sits upon the given stream using big endian notation for multibyte values.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void close()
      Closes the stream.
      Stream getStream()
      Returns the base stream attached to this stream.
      int pad​(int n)
      Pads the stream writing 0 the given number of times.
      char[] readBigChars()
      Reads an array of chars, where its length is stored in the first four bytes as an int.
      java.lang.String readBigString()
      Reads a big string, converting from Pascal (the length is placed before the string) to Java format.
      boolean readBoolean()
      Reads a byte from the stream as a boolean.
      byte readByte()
      Reads a single byte from the stream.
      int readBytes​(byte[] buf)
      Reads bytes from the stream.
      int readBytes​(byte[] buf, int start, int count)
      Reads bytes from the stream.
      protected int readBytesInternal​(byte[] buf, int start, int count, boolean throwEOF)
      Blocks until the requested number of bytes is read from the underlying stream, only returning less than count if the end of the stream is reached.
      char readChar()
      Reads a two-byte character.
      char[] readChars()
      Reads an array of chars.
      void readChars​(char[] chars, int len)
      Reads a char array with the given length.
      int readChars​(char[] chars, int start, int count)
      Reads 'count' chars from the stream to the given char array, starting from index 'start'.
      protected char[] readChars​(int len)
      Reads a char array with the given length.
      java.lang.String readCString()
      Reads a C-style string from the stream.
      double readDouble()
      Reads a double.
      java.lang.String readFixedString​(int length)
      Reads a fixed length string from the stream.
      double readFloat()
      Reads a float value from the stream as four bytes in IEEE 754 format.
      int readInt()
      Reads an integer from the stream as four bytes.
      long readLong()
      Reads a long.
      java.lang.Object readObject()
      Read a Storable object.
      short readShort()
      Reads a short from the stream as two bytes.
      java.lang.String readSmallString()
      Read a small String.
      java.lang.String readString()
      Reads a string, converting from Pascal (the length is placed before the string) to Java format.
      java.lang.String[] readStringArray()
      Reads an array of Strings.
      java.lang.String[] readStringArray​(int size)
      Reads an array of Strings.
      int readUnsignedByte()
      Reads a single unsigned byte from the stream.
      long readUnsignedInt()
      Reads an unsigned integer from the stream as four bytes.
      The returned value will range from 0 to 4294967295.
      int readUnsignedShort()
      Reads an unsigned short from the stream as two bytes.
      int skip​(int n)
      Deprecated.
      Use skipBytes instead.
      int writeBigChars​(char[] chars, int start, int len)
      Writes an array of chars, placing its length in the first four bytes, as an int.
      int writeBigString​(java.lang.String s)
      Writes the string into the stream, converting it from Java format to Pascal format (the length is placed before the string).
      int writeBoolean​(boolean bool)
      Writes a boolean to the stream as a byte.
      int writeByte​(byte by)
      Writes a single byte to the stream.
      int writeByte​(int by)
      Writes a single byte to the stream.
      int writeBytes​(byte[] buf)
      Writes bytes to the stream.
      int writeBytes​(byte[] buf, int start, int count)
      Writes bytes to the stream.
      protected int writeBytesInternal​(byte[] buf, int start, int count)  
      int writeChar​(char c)
      Writes a two-byte character.
      int writeChars​(char[] chars, int start, int len)
      Writes an array of chars, placing its length in the first two bytes, as an unsigned short.
      int writeChars​(char[] chars, int start, int len, int lenSize)
      Writes the given char array, writting the length as an int or as a short or as a byte or don't writting the length, depending on the number of bytes given (4,2,1,0).
      int writeChars​(java.lang.String s, int len)
      Writes the String as a char array.
      int writeCString​(java.lang.String s)
      Writes a C-style string to the stream.
      int writeDouble​(double d)
      Writes a double.
      void writeFixedString​(java.lang.String s, int length)
      Writes a fixed length string to the stream.
      void writeFixedString​(java.lang.String s, int length, char pad)
      Writes a fixed length string to the stream.
      int writeFloat​(double f)
      Writes a float value to the stream as four bytes in IEEE 754 format
      int writeInt​(int i)
      Writes an integer to the stream as four bytes.
      int writeLong​(long l)
      Writes a long.
      void writeObject​(Storable s)
      Write the given Object using the Storable class.
      int writeShort​(int i)
      Writes a short to the stream as two bytes.
      int writeSmallString​(java.lang.String s)
      Write a small String comprised of only ASCII chars (each char is casted to byte).
      int writeSmallString8​(java.lang.String s)
      Write a small String taking each char as a byte.
      int writeString​(java.lang.String s)
      Writes the string into the stream, converting it from Java format to Pascal format (the length is placed before the string).
      int writeStringArray​(java.lang.String[] v)
      writes the string array into the stream

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • stream

        protected Stream stream
        The underlying stream, from where bytes are read and written.

      • buffer

        protected byte[] buffer
        a four byte array for reading and writing numbers

      • zeros

        protected static byte[] zeros

      • EOSMessage

        public static final java.lang.String EOSMessage
        Message thrown when an end of stream is reached when reading.
        See Also:
        Constant Field Values

    • Constructor Detail

      • DataStream

        public DataStream​(Stream stream)
        Constructs a new DataStream which sits upon the given stream using big endian notation for multibyte values.
        Parameters:
        stream - the base stream, from where bytes are read and written.

      • DataStream

        public DataStream​(Stream stream,
                  boolean ensureWrite)
        Constructs a new DataStream which sits upon the given stream using big endian notation for multibyte values.
        Parameters:
        stream - the base stream, from where bytes are read and written.
        ensureWrite - if true, write operations are blocked until all the requested data is written to the underlying stream.

    • Method Detail

      • close

        public void close()
           throws IOException
        Closes the stream. This just calls the close method of the attached stream, thus closing it. Usually, this method may never be called. Remember that closing a stream twice might throw an IOException, so if you call this close method, don't call the base Stream's.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        IOException
        IOException

      • pad

        public final int pad​(int n)
              throws IOException
        Pads the stream writing 0 the given number of times.
        Parameters:
        n - The number of zeros to be written
        Throws:
        IOException

      • readBoolean

        public final boolean readBoolean()
                          throws EOFException,
                                 IOException
        Reads a byte from the stream as a boolean. True is returned if the byte is not zero, false if it is.
        Returns:
        the boolean value read.
        Throws:
        EOFException
        IOException

      • readBytes

        public final int readBytes​(byte[] buf,
                           int start,
                           int count)
                    throws IOException
        Description copied from class: Stream
        Reads bytes from the stream. Returns the number of bytes actually read or -1 if the end of the stream was reached. (if applicable to the stream)
        Specified by:
        readBytes in class Stream
        Parameters:
        buf - the byte array to read data into
        start - the start position in the array
        count - the number of bytes to read
        Throws:
        IOException

      • readBytes

        public final int readBytes​(byte[] buf)
                    throws IOException
        Reads bytes from the stream. Returns the number of bytes actually read.
        Parameters:
        buf - the byte array to read data into
        Throws:
        IOException - If an error prevented the read operation from occurring.

      • readInt

        public int readInt()
            throws EOFException,
                   IOException
        Reads an integer from the stream as four bytes. The returned value will range from -2147483648 to 2147483647.
        Returns:
        the integer value
        Throws:
        EOFException
        IOException

      • readUnsignedByte

        public final int readUnsignedByte()
                           throws EOFException,
                                  IOException
        Reads a single unsigned byte from the stream. The returned value will range from 0 to 255. Use writeByte to write the unsigned byte.
        Returns:
        the read byte.
        Throws:
        EOFException
        IOException
        See Also:
        writeByte(int)

      • readUnsignedShort

        public int readUnsignedShort()
                      throws EOFException,
                             IOException
        Reads an unsigned short from the stream as two bytes. The returned value will range from 0 to 65535. Use writeShort to write the unsigned short.
        Returns:
        the short
        Throws:
        EOFException
        IOException
        See Also:
        writeShort(int)

      • readUnsignedInt

        public long readUnsignedInt()
                     throws EOFException,
                            IOException
        Reads an unsigned integer from the stream as four bytes.
        The returned value will range from 0 to 4294967295.
        Returns:
        the integer value stored in a long
        Throws:
        EOFException
        IOException
        Since:
        TotalCross 1.27

      • writeBoolean

        public final int writeBoolean​(boolean bool)
                       throws IOException
        Writes a boolean to the stream as a byte. True values are written as 1 and false values as 0.
        Parameters:
        bool - the boolean to write
        Returns:
        the number of bytes written: 1
        Throws:
        IOException

      • writeByte

        public final int writeByte​(byte by)
                    throws IOException
        Writes a single byte to the stream.
        Parameters:
        by - the byte to write
        Returns:
        the number of bytes written: 1
        Throws:
        IOException

      • writeByte

        public final int writeByte​(int by)
                    throws IOException
        Writes a single byte to the stream.
        Parameters:
        by - the byte to write (only least significant byte is written)
        Returns:
        the number of bytes written: 1
        Throws:
        IOException

      • writeBytes

        public final int writeBytes​(byte[] buf,
                            int start,
                            int count)
                     throws IOException
        Description copied from class: Stream
        Writes bytes to the stream. Returns the number of bytes actually written or throws an IOException if an error prevented the write operation from occurring.
        Specified by:
        writeBytes in class Stream
        Parameters:
        buf - the byte array to write data from
        start - the start position in the byte array
        count - the number of bytes to write
        Returns:
        the number of bytes actually written
        Throws:
        IOException

      • writeBytes

        public final int writeBytes​(byte[] buf)
                     throws IOException
        Writes bytes to the stream.
        Overrides:
        writeBytes in class Stream
        Parameters:
        buf - the byte array to write data from
        Returns:
        the number of bytes written: buf.length
        Throws:
        IOException

      • writeFloat

        public int writeFloat​(double f)
               throws IOException
        Writes a float value to the stream as four bytes in IEEE 754 format
        Parameters:
        f - the float to write
        Returns:
        the number of bytes written: 4
        Throws:
        IOException

      • writeInt

        public int writeInt​(int i)
             throws IOException
        Writes an integer to the stream as four bytes.
        Parameters:
        i - the integer to write
        Returns:
        the number of bytes written: 4
        Throws:
        IOException

      • writeShort

        public int writeShort​(int i)
               throws IOException
        Writes a short to the stream as two bytes.
        Parameters:
        i - the short to write
        Returns:
        the number of bytes written: 2
        Throws:
        IOException

      • readString

        public java.lang.String readString()
                            throws EOFException,
                                   IOException
        Reads a string, converting from Pascal (the length is placed before the string) to Java format.

        The String size is limited to 65535 characters.

        Returns:
        a zero or more length string. null is never returned.
        Throws:
        EOFException
        IOException

      • readBigString

        public java.lang.String readBigString()
                               throws EOFException,
                                      IOException
        Reads a big string, converting from Pascal (the length is placed before the string) to Java format.

        The String size is limited to 2,147,483,647 characters.

        Returns:
        a zero or more length string. null is never returned.
        Throws:
        EOFException
        IOException
        Since:
        TotalCross 1.0

      • readStringArray

        public java.lang.String[] readStringArray()
                                   throws EOFException,
                                          IOException
        Reads an array of Strings.

        The array length is limited to 65535 elements.

        Returns:
        a zero or more length array. null is never returned.
        Throws:
        EOFException
        IOException

      • readStringArray

        public java.lang.String[] readStringArray​(int size)
                                   throws EOFException,
                                          IOException
        Reads an array of Strings.
        Parameters:
        size - The of the string array.
        Returns:
        a zero or more length array. null is never returned.
        Throws:
        EOFException
        IOException

      • writeString

        public int writeString​(java.lang.String s)
                throws IOException
        Writes the string into the stream, converting it from Java format to Pascal format (the length is placed before the string).

        The String size is limited to 65535 characters.

        Returns:
        the number of bytes written.
        Throws:
        IOException

      • writeBigString

        public int writeBigString​(java.lang.String s)
                   throws IOException
        Writes the string into the stream, converting it from Java format to Pascal format (the length is placed before the string).

        The String size is limited to 2,147,483,647 characters.

        Returns:
        the number of bytes written.
        Throws:
        IOException
        Since:
        TotalCross 1.0

      • writeStringArray

        public int writeStringArray​(java.lang.String[] v)
                     throws IOException
        writes the string array into the stream
        Returns:
        the number of bytes written.
        Throws:
        IOException

      • writeDouble

        public int writeDouble​(double d)
                throws IOException
        Writes a double.
        Returns:
        the number of bytes written: 8
        Throws:
        IOException
        Since:
        SuperWaba 2.0

      • writeLong

        public int writeLong​(long l)
              throws IOException
        Writes a long.
        Throws:
        IOException
        Since:
        SuperWaba 2.0

      • readCString

        public java.lang.String readCString()
                             throws EOFException,
                                    IOException
        Reads a C-style string from the stream. This is a NUL (0) terminated series of characters. This format is commonly used by other applications. Note that if you're creating your own stream, choose readString instead of readCString, because readCString is *much* slower. Also, this method does not handle correctly unicode characters.
        Returns:
        the loaded String
        Throws:
        EOFException
        IOException

      • writeCString

        public final int writeCString​(java.lang.String s)
                       throws IOException
        Writes a C-style string to the stream. This means that all the characters of the string are written out, followed by a NUL (0) character. This format is commonly used by other applications.
        Parameters:
        s - the string to write
        Returns:
        the number of bytes written.
        Throws:
        IOException

      • writeChar

        public int writeChar​(char c)
              throws IOException
        Writes a two-byte character.
        Parameters:
        c - the character to be written.
        Returns:
        the number of bytes written: 2
        Throws:
        IOException
        Since:
        SuperWaba 4.21

      • readChars

        public char[] readChars()
                 throws EOFException,
                        IOException
        Reads an array of chars. The length is stored in the first two bytes as an unsigned short.

        The char array size is limited to 65535 characters.

        Throws:
        EOFException
        IOException
        Since:
        SuperWaba 3.5

      • readChars

        public void readChars​(char[] chars,
                      int len)
               throws EOFException,
                      IOException
        Reads a char array with the given length.
        Parameters:
        chars - An already created chars array.
        len - The array length.
        Throws:
        EOFException
        IOException
        Since:
        TotalCross 1.01

      • readChars

        public int readChars​(char[] chars,
                     int start,
                     int count)
              throws EOFException,
                     IOException
        Reads 'count' chars from the stream to the given char array, starting from index 'start'.
        Parameters:
        chars - a char array
        start - starting position on the char array
        count - number of chars to be read from the stream
        Throws:
        EOFException
        IOException
        Since:
        TotalCross 1.15

      • readBigChars

        public char[] readBigChars()
                    throws EOFException,
                           IOException
        Reads an array of chars, where its length is stored in the first four bytes as an int.

        The char array size is limited to 2,147,483,647 characters.

        Throws:
        EOFException
        IOException
        Since:
        TotalCross 1.0 beta3

      • writeChars

        public int writeChars​(char[] chars,
                      int start,
                      int len)
               throws IOException
        Writes an array of chars, placing its length in the first two bytes, as an unsigned short.

        The char array size is limited to 65535 characters.

        Parameters:
        len - the length to be written or -1 if it is to write the whole char array
        chars - the char array to be written.
        start - the starting index (in most cases: 0).
        Returns:
        the number of bytes written.
        Throws:
        IOException
        Since:
        SuperWaba 3.5

      • writeBigChars

        public int writeBigChars​(char[] chars,
                         int start,
                         int len)
                  throws IOException
        Writes an array of chars, placing its length in the first four bytes, as an int.

        The char array size is limited to 2,147,483,647 characters.

        Parameters:
        len - the length to be written or -1 if it is to write the whole char array
        chars - the char array to be written.
        start - the starting index (in most cases: 0).
        Returns:
        the number of bytes written.
        Throws:
        IOException
        Since:
        TotalCross 1.0 beta3

      • writeChars

        public int writeChars​(char[] chars,
                      int start,
                      int len,
                      int lenSize)
               throws IOException
        Writes the given char array, writting the length as an int or as a short or as a byte or don't writting the length, depending on the number of bytes given (4,2,1,0).
        Throws:
        IOException

      • writeChars

        public int writeChars​(java.lang.String s,
                      int len)
               throws IOException
        Writes the String as a char array. The chars are read using the charAt method from the String class. This method is faster than the other writeChars method on blackberry, but slower on other devices.

        The char array size is limited to 65535 characters.

        Parameters:
        s - The String to be written. Must not be null!
        len - The maximum number of chars to be written. Must be less than the String's length.
        Throws:
        IOException
        Since:
        TotalCross 1.0 beta 4

      • getStream

        public Stream getStream()
        Returns the base stream attached to this stream.

      • readFixedString

        public java.lang.String readFixedString​(int length)
                                 throws EOFException,
                                        IOException
        Reads a fixed length string from the stream. The given number of characters are read and converted to a String.
        Parameters:
        length - the number of characters to read
        Returns:
        the loaded string
        Throws:
        EOFException
        IOException

      • writeFixedString

        public void writeFixedString​(java.lang.String s,
                             int length)
                      throws IOException
        Writes a fixed length string to the stream. If the given string is longer than the given length, it will be truncated and if it is shorter, it will be padded with spaces.
        Parameters:
        s - the string to write
        length - the length of the fixed string
        Throws:
        IOException

      • writeFixedString

        public void writeFixedString​(java.lang.String s,
                             int length,
                             char pad)
                      throws IOException
        Writes a fixed length string to the stream. If the given string is longer than the given length, it will be truncated and if it is shorter, it will be padded the given pad character.
        Parameters:
        s - the string to write
        length - the length of the fixed string
        pad - the character to pad if the string is shorter than the length
        Throws:
        IOException

      • readObject

        public java.lang.Object readObject()
                            throws java.lang.ClassNotFoundException,
                                   java.lang.InstantiationException,
                                   java.lang.IllegalAccessException,
                                   EOFException,
                                   IOException
        Read a Storable object.
        Throws:
        java.lang.ClassNotFoundException
        java.lang.InstantiationException
        java.lang.IllegalAccessException
        EOFException
        IOException
        See Also:
        Storable

      • readSmallString

        public java.lang.String readSmallString()
                                 throws EOFException,
                                        IOException
        Read a small String. If the length is 0, an empty String is returned.

        The String size is limited to 255 characters.

        Throws:
        EOFException
        IOException
        Since:
        TotalCross 1.0

      • writeSmallString

        public int writeSmallString​(java.lang.String s)
                     throws IOException
        Write a small String comprised of only ASCII chars (each char is casted to byte). The length is written as a single byte before the byte array.

        The String size is limited to 255 characters.

        Throws:
        IOException
        Since:
        TotalCross 1.0

      • writeSmallString8

        public int writeSmallString8​(java.lang.String s)
                      throws IOException
        Write a small String taking each char as a byte. To read it, use readString. The maximum allowed length is 65536.
        Throws:
        IOException
        Since:
        TotalCross 1.52

      • writeBytesInternal

        protected int writeBytesInternal​(byte[] buf,
                                 int start,
                                 int count)
                          throws IOException
        Throws:
        IOException

      • readBytesInternal

        protected int readBytesInternal​(byte[] buf,
                                int start,
                                int count,
                                boolean throwEOF)
                         throws EOFException,
                                IOException
        Blocks until the requested number of bytes is read from the underlying stream, only returning less than count if the end of the stream is reached.
        Parameters:
        buf -
        start -
        count -
        Returns:
        The number of bytes read, which will usually be equal to count. It may return a positive value smaller than count if the end of the stream is reached during the read operation, or -1 if the end of stream and nothing was read.
        Throws:
        EOFException
        IOException

      • skip

        @Deprecated
public int skip​(int n)
         throws IOException
        Deprecated.
        Use skipBytes instead.
        Throws:
        IOException