extra.io
Class DataStream

java.lang.Object
  |
  +--waba.io.Stream
        |
        +--extra.io.DataStream

public class DataStream

extends Stream

DataStream is a wrapper you can place around any Stream such as a SerialPort, Catalog, or BufferStream which lets you read and write standard Waba data types like ints, floats, and Strings in a simple manner. Here's an example

   SerialPort port=new SerialPort(9600,0);
   DataStream ds=new DataStream(port);
   ds.writeString("Hello");
   int status=ds.readUnsignedByte();
   if (status==1)
   {
     ds.writeString("Pi");
     ds.writeFloat(3.14);
   }
   port.close();
 

Constructor Summary

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

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

Method Summary

boolean	close() Closes the stream.
boolean	isBigEndian() Gets whether this DataStream is reading and writing numbers in big endian format, or little endian 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, int start, int count) Reads bytes from the stream.
String	readCString() Reads a C-style string from the stream.
String	readFixedString(int length) Reads a fixed length string from the stream.
float	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.
short	readShort() Reads a short from the stream as two bytes.
String	readString() Reads a string stored in a pascal type format.
int	readUnsignedByte() Reads a single unsigned byte from the stream.
int	readUnsignedShort() Reads an unsigned short from the stream as two bytes.
void	setBigEndian(boolean bigEndian) Sets whether numbers should be read and written in big endian format (most significant byte first) or little endian format (least significant byte first).
void	skip(int n) Skips reading the next n bytes in the stream
static String	toLowerCase(String s) Converts all characters in a string to lower case.
static String	toUpperCase(String s) Converts all characters in a string to upper case.
void	writeBoolean(boolean bool) Writes a boolean to the stream as a byte.
void	writeByte(byte by) Writes a single byte to the stream.
void	writeByte(int by) Writes a single byte to the stream.
int	writeBytes(byte[] buf, int start, int count) Writes bytes to the the stream.
void	writeCString(String s) Writes a C-style string to the stream.
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.
void	writeFloat(float f) Writes a float value to the stream as four bytes in IEEE 754 format
void	writeInt(int i) Writes an integer to the stream as four bytes.
void	writeShort(int i) Writes an short to the stream as two bytes.
void	writeString(String s) Writes a string in a pascal type format.

Methods inherited from class java.lang.Object

equals, hashCode, toString

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

DataStream

public DataStream(Stream stream,
                  boolean bigEndian)

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

Parameters:

stream - the base stream

bigEndian - true for big endian, false for little endian

Method Detail

setBigEndian

public void setBigEndian(boolean bigEndian)

Sets whether numbers should be read and written in big endian format (most significant byte first) or little endian format (least significant byte first). The default is true as this is the format used by Java but if you are reading data from another source that uses little endian you will need to set it to false. If you are only reading and writing your own data, this setting makes no difference, assuming you set both the reading and writing ends the same.

Parameters:

bigEndian - true for big endian, false for little endian

isBigEndian

public boolean isBigEndian()

Gets whether this DataStream is reading and writing numbers in big endian format, or little endian format.

Returns:

true for big endian, false for little endian

close

public boolean close()

Closes the stream. Returns true if the operation is successful and false otherwise.

Overrides:

close in class Stream

readInt

public int readInt()

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

Returns:

the integer

writeInt

public void writeInt(int i)

Writes an integer to the stream as four bytes.

Parameters:

i - the integer to write

readShort

public short readShort()

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

Returns:

the short

writeShort

public void writeShort(int i)

Writes an short to the stream as two bytes. As there is no short type in Waba but we often only want to only use two bytes in storage. an int is used but the upper two bytes are ignored.

Parameters:

i - the short to write

readUnsignedShort

public int readUnsignedShort()

Reads an unsigned short from the stream as two bytes. The returned value will range from 0 to 65535.

Returns:

the short

readFloat

public float readFloat()

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

Returns:

the float value

writeFloat

public void writeFloat(float f)

Writes a float value to the stream as four bytes in IEEE 754 format

Parameters:

f - the float to write

readString

public String readString()

Reads a string stored in a pascal type format. The first byte is read as an unsigned byte. If it is not 0xFF (255) the value is taken as the length of the string. If it is 0xFF, the next two bytes are read and interpreted as a short giving the length of the string to follow, which is then read.

Returns:

the loaded string

writeString

public void writeString(String s)

Writes a string in a pascal type format. If the length of the string is less than 255, this length is written out as a byte. If it is greater or equal to 255 in length, 0xFF is written followed by a short (two bytes) being the length. The characters of the string follow.

Parameters:

s - the string to write

readCString

public String readCString()

Reads a C-style string from the stream. This is a NUL (0) terminated series of characters. This format is commonly used by other Palm applications.

writeCString

public void writeCString(String s)

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 Palm applications.

Parameters:

s - the string to write

readFixedString

public String readFixedString(int length)

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

writeFixedString

public void writeFixedString(String s,
                             int length)

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

writeFixedString

public void writeFixedString(String s,
                             int length,
                             char pad)

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

the - character to pad if the string is shorter than the length

readBoolean

public boolean readBoolean()

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

writeBoolean

public void writeBoolean(boolean bool)

Writes a boolean to the stream as a byte. True values are written as 1 and false values as 0.

Parameters:

b - the boolean to write

readByte

public byte readByte()

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

writeByte

public void writeByte(byte by)

Writes a single byte to the stream.

Parameters:

b - the byte to write

writeByte

public void writeByte(int by)

Writes a single byte to the stream.

Parameters:

b - the byte to write (only least significant byte is written)

readUnsignedByte

public int readUnsignedByte()

Reads a single unsigned byte from the stream. The returned value will range from 0 to 255.

skip

public void skip(int n)

Skips reading the next n bytes in the stream

Parameters:

n - the number of bytes to skip

readBytes

public int readBytes(byte[] buf,
                     int start,
                     int count)

Reads bytes from the stream. Returns the number of bytes actually read or -1 if an error prevented the read operation from occurring.

Overrides:

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

writeBytes

public int writeBytes(byte[] buf,
                      int start,
                      int count)

Writes bytes to the the stream. Returns the number of bytes actually written or -1 if an error prevented the write operation from occurring.

Overrides:

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

toUpperCase

public static String toUpperCase(String s)

Converts all characters in a string to upper case.

Parameters:

s - the string to convert

Returns:

an upper case version of the string

toLowerCase

public static String toLowerCase(String s)

Converts all characters in a string to lower case.

Parameters:

s - the string to convert

Returns:

a lower case version of the string