totalcross.io
Class DataStream

totalcross.lang.Object
  totalcross.io.Stream
      totalcross.io.DataStream

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 totalcross.lang.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

protected byte[]	buffer a four byte array for reading and writing numbers
static 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

Fields inherited from class totalcross.io.Stream

skipBuffer

Constructor Summary

DataStream(Stream stream)
Constructs a new DataStream which sits upon the given stream using big endian notation for multibyte values.

Method Summary

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.
String	readBigString() Reads a big string, converting from Pascal (the length is placed before the string) to Java format.
boolean	readBoolean() Reads a boolean from the stream as a byte.
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 void	readBytesInternal(byte[] buf, int start, int count)
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.
String	readCString() Reads a C-style string from the stream.
double	readDouble() Reads a double.
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.
Object	readObject() Read a Storable object.
short	readShort() Reads a short from the stream as two bytes.
String	readSmallString() Read a small String.
String	readString() Reads a string, converting from Pascal (the length is placed before the string) to Java format.
String[]	readStringArray() Reads an array of Strings.
int	readUnsignedByte() Reads a single unsigned byte from the stream.
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(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.
int	writeBytes(String str) Writes the given totalcross.lang.String as a byte array, retrieved using String.getBytes.
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(String s, int len) Writes the totalcross.lang.String as a char array.
int	writeCString(String s) Writes a C-style string to the stream.
int	writeDouble(double d) Writes a double.
void	writeFixedString(String s, int length) Writes a fixed length string to the stream.
void	writeFixedString(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 totalcross.lang.Object using the Storable class.
int	writeShort(int i) Writes a short to the stream as two bytes.
int	writeSmallString(String s) Write a small totalcross.lang.String comprised of only ASCII chars (each char is casted to byte).
int	writeString(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(String[] v) writes the string array into the stream

Methods inherited from class totalcross.io.Stream

skipBytes

Methods inherited from class totalcross.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 String EOSMessage

Message thrown when an end of stream is reached when reading.

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.

Method Detail

close

public void close()
           throws IOException

Closes the stream. This just call the close method of the attached stream, thus closing it. Usually, this method may never be called. Remember that closing a stream twice will throw an IOException, so if you call this close method, don't call the base Stream's.

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 IOException

Reads a boolean from the stream as a byte. True is returned if the byte is not zero, false if it is.

Returns:

the boolean value read.

Throws:

IOException

readByte

public final byte readByte()
                    throws IOException

Reads a single byte from the stream. The returned value will range from -128 to 127.

Returns:

the read byte

Throws:

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.

readFloat

public double readFloat()
                 throws IOException

Reads a float value from the stream as four bytes in IEEE 754 format.

Returns:

the float value as a double.

Throws:

IOException

readInt

public int readInt()
            throws IOException

Reads an integer from the stream as four bytes. The returned value will range from -2147483648 to 2147483647.

Returns:

the integer value

Throws:

IOException

readShort

public short readShort()
                throws IOException

Reads a short from the stream as two bytes. The returned value will range from -32768 to 32767.

Returns:

the short value

Throws:

IOException

readDouble

public double readDouble()
                  throws IOException

Reads a double.

Returns:

the double value

Throws:

IOException

Since:

SuperWaba 2.0

readLong

public long readLong()
              throws IOException

Reads a long.

Returns:

the long value

Throws:

IOException

Since:

SuperWaba 2.0

readUnsignedByte

public final int readUnsignedByte()
                           throws 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:

IOException

See Also:

writeByte(int)

readUnsignedShort

public int readUnsignedShort()
                      throws 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:

IOException

See Also:

writeShort(int)

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 -1 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

writeBytes

public final int writeBytes(String str)
                     throws IOException

Writes the given totalcross.lang.String as a byte array, retrieved using String.getBytes. The totalcross.lang.String is written as-is, nothing is placed before or after it.

Overrides:

writeBytes in class Stream

Parameters:

str - the totalcross.lang.String to get the bytes from

Returns:

the number of bytes written: buf.length

Throws:

IOException

Since:

TotalCross 1.0 beta 5

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 String readString()
                  throws IOException

Reads a string, converting from Pascal (the length is placed before the string) to Java format.

The totalcross.lang.String size is limited to 65535 characters.

Returns:

a zero or more length string. null is never returned.

Throws:

IOException

readBigString

public String readBigString()
                     throws IOException

Reads a big string, converting from Pascal (the length is placed before the string) to Java format.

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

Returns:

a zero or more length string. null is never returned.

Throws:

IOException

Since:

TotalCross 1.0

readStringArray

public String[] readStringArray()
                         throws 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:

IOException

writeString

public int writeString(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 totalcross.lang.String size is limited to 65535 characters.

Returns:

the number of bytes written.

Throws:

IOException

writeBigString

public int writeBigString(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 totalcross.lang.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(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 String readCString()
                   throws 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:

IOException

writeCString

public final int writeCString(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

readChar

public char readChar()
              throws IOException

Reads a two-byte character.

Throws:

IOException

Since:

SuperWaba 4.21

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 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:

IOException

Since:

SuperWaba 3.5

readChars

public void readChars(char[] chars,
                      int len)
               throws IOException

Reads a char array with the given length.

Parameters:

chars - An already created chars array.

len - The array length.

Throws:

IOException

Since:

TotalCross 1.01

readChars

public int readChars(char[] chars,
                     int start,
                     int count)
              throws 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:

IOException

Since:

TotalCross 1.15

readBigChars

public char[] readBigChars()
                    throws 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:

IOException

Since:

TotalCross 1.0 beta3

readChars

protected char[] readChars(int len)
                    throws IOException

Reads a char array with the given length.

Throws:

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(String s,
                      int len)
               throws IOException

Writes the totalcross.lang.String as a char array. The chars are read using the charAt method from the totalcross.lang.String class. This is 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 totalcross.lang.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 String readFixedString(int length)
                       throws 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:

IOException

writeFixedString

public void writeFixedString(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(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

writeObject

public void writeObject(Storable s)
                 throws IOException

Write the given totalcross.lang.Object using the Storable class.

Throws:

IOException

See Also:

Storable

readObject

public Object readObject()
                  throws totalcross.lang.ClassNotFoundException,
                         totalcross.lang.InstantiationException,
                         totalcross.lang.IllegalAccessException,
                         IOException

Read a Storable object.

Throws:

totalcross.lang.ClassNotFoundException

totalcross.lang.InstantiationException

totalcross.lang.IllegalAccessException

IOException

See Also:

Storable

readSmallString

public String readSmallString()
                       throws IOException

Read a small String. The length must have been written as a single byte before the byte array. If it was 0, an empty totalcross.lang.String is returned.

The totalcross.lang.String size is limited to 255 characters.

Throws:

IOException

Since:

TotalCross 1.0

writeSmallString

public int writeSmallString(String s)
                     throws IOException

Write a small totalcross.lang.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 totalcross.lang.String size is limited to 255 characters.

Throws:

IOException

Since:

TotalCross 1.0

readBytesInternal

protected void readBytesInternal(byte[] buf,
                                 int start,
                                 int count)
                          throws IOException

Throws:

IOException

skip

public int skip(int n)
         throws IOException

Deprecated. Use skipBytes instead.

Throws:

IOException