ewe.util
Class ByteEncoder

java.lang.Object
  ewe.util.ByteEncoder

public class ByteEncoder

extends Object

A ByteEncoder is used to encode data as a sequence of bytes in an efficient manner. It consists of a number of static methods that encode data to a ByteArray or decode data from a sequence of bytes.

Constructor Summary

ByteEncoder()

Method Summary

static String	classOfData(byte[] source, int offset, int lengthLeft) Return the class of the data as a string as it would be returned if you had called getClass().getName() on the original data.
static int	countEncoded(byte[] source, int offset, int lengthLeft) Count how many data units (primitive values or object values) are stored in sequence in the specified sequence of bytes.
static Wrapper[]	decode(byte[] source, int offset, int lengthLeft)
static int	decode(byte[] source, int offset, int lengthLeft, Wrapper dest) Decode a data unit at the specified location, placing it in the destination Wrapper.
static void	decodeEncodableObjectData(byte[] source, int offset, int dataLength, Object obj) Decode the fields of an Encodable object, as encoded by encodeEncodableObjectData().
static Wrapper	decodeField(byte[] source, int offset, int length, String fieldName, Wrapper dest) This searchs for a field name and returns the encoded value associated with the field.
static Object	decodeObject(byte[] source, int offset, int lengthLeft, Object dest) Decode an object into the specified destination object.
static void	decodeObjectData(byte[] source, int offset, int dataLength, Object obj) Decode the data bytes of the object, as encoded by encodeObjectData.
static Object	decodeObjectField(byte[] source, int offset, int length, String fieldName, Object dest)
static Object	decodeObjectField(ByteArray source, String fieldName)
static Object[]	decodeObjects(byte[] source, int offset, int lengthLeft, Object[] dest) Decode an array of Objects.
static int	decodeString(byte[] source, int offset, int lengthLeft, Wrapper dest)
static String	decodeStringField(byte[] source, int offset, int length, String fieldName)
static String	decodeStringField(ByteArray source, String fieldName)
static int	encode(ByteArray dest, byte[] source, int offset, int length) This encodes the bytes as a byte array data unit.
static int	encode(ByteArray dest, Wrapper w) Fully encode any data type, including a null object reference.
static int	encodeEncodableObjectData(ByteArray dest, Encodable obj) Encode the fields of an Encodable object.
static int	encodeField(ByteArray dest, String fieldName, byte[] data, int offset, int length)
static int	encodeField(ByteArray dest, String fieldName, Object data)
static int	encodeField(ByteArray dest, String fieldName, Wrapper data)
static int	encodeObject(ByteArray dest, Object obj) Encode an object, specifying the full class of the object.
static int	encodeObjectData(ByteArray dest, Object obj) Encode only the data for the Object, not any information about the class of the Object.
static Range	findField(byte[] source, int offset, int length, String fieldName, Range dest)
static Range	getByteArrayBytes(byte[] source, int offset, int length, Range dest)
static Range	getByteArrayBytes(byte[] source, Range foundData, Range dest)
static Range	getFieldByteArray(byte[] source, int offset, int length, String fieldName, Range dest)
static boolean	isObjectOrArray(byte[] source, int offset, int lengthLeft)
static boolean	isString(byte[] source, int offset, int lengthLeft)
static int	sizeOfData(byte[] source, int offset, int lengthLeft) Return the number of bytes stored starting at the particular offset.
static int	typeOfData(byte[] source, int offset, int lengthLeft) Return the Wrapper type of the data stored at the specified location.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Constructor Detail

ByteEncoder

public ByteEncoder()

Method Detail

encodeEncodableObjectData

public static int encodeEncodableObjectData(ByteArray dest,
                                            Encodable obj)

Encode the fields of an Encodable object. The data is encoded by encoding a sequence of field name and field value pairs. After it is encoded you can add on extra fields if you like, as long as their names do not conflict with already saved field names.

Note that this method does not store information about the class of the object. This means you must know the object class and have a pre-created object to call the corresponding decodeEncodableObjectData() when you are ready to decode it.

Parameters:

dest - The destination ByteArray or null to just get the number of bytes needed.

obj - The object to encode.

Returns:

the number of bytes encoded or would need to be encoded.

encodeObjectData

public static int encodeObjectData(ByteArray dest,
                                   Object obj)

Encode only the data for the Object, not any information about the class of the Object. Do not call this method for arrays.

The method used to encode the object depends on the class of the object or the interfaces it implements. The type of Objects you can encode are:

• A ewe.util.Vector - in which case it is encoded as an array of objects, each one encoded using encodeObject().
• A ByteEncodable object - in which case the encodeBytes() method is used.
• A Textable object - in which case the getText() method is called on the object and the returned String is encoded.
• A LiveData object - in which case the textEncode() method is called on the object and the returned String is encoded.
• An Encodable object - in which case all public fields are encoded individually using encodeEncodableObjectData().
• Any other object has its toString() method called on it and the returned String is then encoded.

Parameters:

dest - The destination ByteArray or null to just get the number of bytes needed.

obj - The object to encode.

Returns:

the number of bytes encoded or would need to be encoded.

decodeEncodableObjectData

public static void decodeEncodableObjectData(byte[] source,
                                             int offset,
                                             int dataLength,
                                             Object obj)
                                      throws StreamCorruptedException

Decode the fields of an Encodable object, as encoded by encodeEncodableObjectData().

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

dataLength - the number of bytes.

obj - the destination object.

Throws:

StreamCorruptedException

decodeObjectData

public static void decodeObjectData(byte[] source,
                                    int offset,
                                    int dataLength,
                                    Object obj)
                             throws StreamCorruptedException,
                                    ClassNotFoundException

Decode the data bytes of the object, as encoded by encodeObjectData. This is not to be used on arrays.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

dataLength - the number of bytes.

obj - the destination object.

Throws:

StreamCorruptedException

ClassNotFoundException

sizeOfData

public static int sizeOfData(byte[] source,
                             int offset,
                             int lengthLeft)
                      throws StreamCorruptedException

Return the number of bytes stored starting at the particular offset.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

Returns:

the number of bytes stored starting at the particular offset.

Throws:

StreamCorruptedException

typeOfData

public static int typeOfData(byte[] source,
                             int offset,
                             int lengthLeft)
                      throws StreamCorruptedException

Return the Wrapper type of the data stored at the specified location.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

lengthLeft - the number of bytes.

Returns:

The type of the data as a Wrapper type. If lengthLeft is less than or equal to zero then a StreamCorruptedException() will be thrown.

Throws:

StreamCorruptedException

isString

public static boolean isString(byte[] source,
                               int offset,
                               int lengthLeft)
                        throws StreamCorruptedException

Throws:

StreamCorruptedException

isObjectOrArray

public static boolean isObjectOrArray(byte[] source,
                                      int offset,
                                      int lengthLeft)
                               throws StreamCorruptedException

Throws:

StreamCorruptedException

classOfData

public static String classOfData(byte[] source,
                                 int offset,
                                 int lengthLeft)
                          throws StreamCorruptedException

Return the class of the data as a string as it would be returned if you had called getClass().getName() on the original data.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

lengthLeft - the number of bytes.

Returns:

the class of the data stored at a location. If this is null then a null object pointer is stored at that location.

Throws:

IllegalArgumentException - if the data at the specified location is not an Object or Array class.

StreamCorruptedException

countEncoded

public static int countEncoded(byte[] source,
                               int offset,
                               int lengthLeft)
                        throws StreamCorruptedException

Count how many data units (primitive values or object values) are stored in sequence in the specified sequence of bytes.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

lengthLeft - the number of bytes.

Returns:

the number of data units stored at the specified offset.

Throws:

StreamCorruptedException

encode

public static int encode(ByteArray dest,
                         Wrapper w)

Fully encode any data type, including a null object reference.

Parameters:

dest - the destination ByteArray or null to determine the number of bytes needed.

w - a wrapper that holds the data to be encoded.

Returns:

the number of bytes encoded or decoded.

decode

public static int decode(byte[] source,
                         int offset,
                         int lengthLeft,
                         Wrapper dest)
                  throws StreamCorruptedException,
                         ClassNotFoundException

Decode a data unit at the specified location, placing it in the destination Wrapper. If the stored value is an object you can set a destination object by calling setObject() on the Wrapper before calling this method. Then the data will attempt to be decoded into that object. However if that object is inappropriate, then a new object will be created and returned instead.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

lengthLeft - the number of bytes.

Returns:

the number of bytes used by the data unit.

Throws:

StreamCorruptedException

ClassNotFoundException

decodeString

public static int decodeString(byte[] source,
                               int offset,
                               int lengthLeft,
                               Wrapper dest)
                        throws StreamCorruptedException

Throws:

StreamCorruptedException

encodeObject

public static int encodeObject(ByteArray dest,
                               Object obj)

Encode an object, specifying the full class of the object. If you want to just encode the data of the object, use encodeObjectData() instead, however you should not use that method for immutable objects such as Strings. For immutable object you should use this.

Parameters:

dest - The destination ByteArray or null to just find out how many bytes are needed.

obj - The object to encode.

Returns:

The number of bytes encoded.

decodeObject

public static Object decodeObject(byte[] source,
                                  int offset,
                                  int lengthLeft,
                                  Object dest)
                           throws StreamCorruptedException,
                                  ClassNotFoundException

Decode an object into the specified destination object. This method is capable of creating a new object as long as it has an appropriate constructor. If you encoded the object using encodeObjectData() then you should decode it using decodeObjectData() instead. The encodeObjectData() method does not store class information about the object and so cannot create a new instance of an encoded class.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

dest - the destination object which may be null, in which case a new instance of the object will be created (if possible).

Returns:

the destination object or a new object if no destination or an incorrect destination is provided.

Throws:

StreamCorruptedException

ClassNotFoundException

decodeObjects

public static Object[] decodeObjects(byte[] source,
                                     int offset,
                                     int lengthLeft,
                                     Object[] dest)
                              throws StreamCorruptedException,
                                     ClassNotFoundException

Decode an array of Objects.

Parameters:

source - the source of the data bytes.

offset - the offset of the first byte.

lengthLeft - the number of bytes.

dest - the destination objects which may be null, in which case a new instance of the objects will be returned.

Returns:

Throws:

StreamCorruptedException

ClassNotFoundException

decode

public static Wrapper[] decode(byte[] source,
                               int offset,
                               int lengthLeft)
                        throws StreamCorruptedException,
                               ClassNotFoundException

Throws:

StreamCorruptedException

ClassNotFoundException

encodeField

public static int encodeField(ByteArray dest,
                              String fieldName,
                              Wrapper data)

encodeField

public static int encodeField(ByteArray dest,
                              String fieldName,
                              Object data)

encodeField

public static int encodeField(ByteArray dest,
                              String fieldName,
                              byte[] data,
                              int offset,
                              int length)

encode

public static int encode(ByteArray dest,
                         byte[] source,
                         int offset,
                         int length)

This encodes the bytes as a byte array data unit. When decoded using decode() it will be decoded as a new byte array of the exact length as specified in this call.

Parameters:

dest -

source -

offset -

length -

Returns:

The number of bytes used.

findField

public static Range findField(byte[] source,
                              int offset,
                              int length,
                              String fieldName,
                              Range dest)
                       throws StreamCorruptedException

Throws:

StreamCorruptedException

getByteArrayBytes

public static Range getByteArrayBytes(byte[] source,
                                      int offset,
                                      int length,
                                      Range dest)
                               throws StreamCorruptedException

Throws:

StreamCorruptedException

getByteArrayBytes

public static Range getByteArrayBytes(byte[] source,
                                      Range foundData,
                                      Range dest)
                               throws StreamCorruptedException

Throws:

StreamCorruptedException

getFieldByteArray

public static Range getFieldByteArray(byte[] source,
                                      int offset,
                                      int length,
                                      String fieldName,
                                      Range dest)
                               throws StreamCorruptedException

Throws:

StreamCorruptedException

decodeField

public static Wrapper decodeField(byte[] source,
                                  int offset,
                                  int length,
                                  String fieldName,
                                  Wrapper dest)
                           throws StreamCorruptedException,
                                  ClassNotFoundException

This searchs for a field name and returns the encoded value associated with the field. It is assumed that the section of bytes contains a repeating sequence of a field name, followed by a value.

Throws:

StreamCorruptedException

ClassNotFoundException

decodeObjectField

public static Object decodeObjectField(byte[] source,
                                       int offset,
                                       int length,
                                       String fieldName,
                                       Object dest)
                                throws StreamCorruptedException,
                                       ClassNotFoundException

Throws:

StreamCorruptedException

ClassNotFoundException

decodeObjectField

public static Object decodeObjectField(ByteArray source,
                                       String fieldName)
                                throws StreamCorruptedException,
                                       ClassNotFoundException

Throws:

StreamCorruptedException

ClassNotFoundException

decodeStringField

public static String decodeStringField(byte[] source,
                                       int offset,
                                       int length,
                                       String fieldName)
                                throws StreamCorruptedException

Throws:

StreamCorruptedException

decodeStringField

public static String decodeStringField(ByteArray source,
                                       String fieldName)
                                throws StreamCorruptedException

Throws:

StreamCorruptedException