|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.devexperts.io.IOUtil
public class IOUtil
Utility class that provides algorithms for data serialization and deserialization. It defines several compact data formats and provides clean and convenient API to use them.
The following table defines used serial format (the first byte is given in bits with 'x' representing payload bit; the remaining bytes are given in bit count):
0xxxxxxx - for -64 <= N < 64 10xxxxxx 8x - for -8192 <= N < 8192 110xxxxx 16x - for -1048576 <= N < 1048576 1110xxxx 24x - for -134217728 <= N < 134217728 11110xxx 32x - for -17179869184 <= N < 17179869184 (includes whole range of signed int) 111110xx 40x - for -2199023255552 <= N < 2199023255552 1111110x 48x - for -281474976710656 <= N < 281474976710656 11111110 56x - for -36028797018963968 <= N < 36028797018963968 11111111 64x - for -9223372036854775808 <= N < 9223372036854775808 (the range of signed long)
This method first writes length of encapsulated data in a compact format and then writes data itself.
By convention values of length lesser than -1
are illegal (reserved for future use);
length value of -1
indicates special case of null
data (if applicable);
length value of 0
indicates empty data (as applicable; e.g. no data elements); and
positive values of length indicate either number of data elements or number of bytes they occupy.
Note: the length of encapsulated data is formally declared as long
value;
readers shall read full 64-bit length value and report overflow if they cannot handle large values.
int
value),
UTF-16 encoding (String
class) and
UTF-8 encoding (serial format).
The UTF API uses compact encapsulation with length defined as number of UTF-8 encoded bytes.
Note: the UTF API uses official UTF-8 encoding format while Java serialization uses modified UTF-8 format. This results with several APIs that simingly work with same UTF-8 encoding, yet they differ in encoding and encapsulation.
The serial form of individual object is defined as a byte array those content is a result of independent
serialization of that object by new instance of ObjectOutputStream
. When this byte array is written
to the output it uses compact encapsulation.
The serial form of declared group of objects uses more efficient serialization of primitive data
(individual and arrays) and single ObjectOutputStream
for remaining non-primitive data.
It uses compact encapsulation of resulting byte array when writing it to the output.
This API requires knowledge of declared data types on both sides (serialization and deserialization)
in order to work. It is intended for cases when method arguments shall be serialized for RMI because
in this cases both sides know declared types of those arguments.
The compression API uses Deflate algorithm (see RFC 1951) and wraps compressed data blocks using ZLIB format (see RFC 1950). It can be used arbitrarily and it is also intended to be used transparently by serialization API.
Method Summary | |
---|---|
static Object |
bytesToObject(byte[] bytes)
Deserializes an array of bytes into object with Java Serialization. |
static Object |
bytesToObject(byte[] bytes,
ClassLoader cl)
Deserializes an array of bytes into object with Java Serialization. |
static Object[] |
bytesToObjects(Class[] types,
byte[] bytes)
Deserializes an array of bytes into declared group of objects according to their declared types. |
static Object[] |
bytesToObjects(Class[] types,
byte[] bytes,
ClassLoader cl)
Deserializes an array of bytes into declared group of objects according to their declared types. |
static void |
checkRange(byte[] b,
int off,
int len)
Throws IndexOutOfBoundsException if parameters are out of range. |
static byte[] |
compress(byte[] bytes)
Compresses an array of bytes using Deflate algorithm as appropriate. |
static byte[] |
decompress(byte[] bytes)
Decompresses an array of bytes using Inflate algorithm repeatedly as appropriate. |
static byte[] |
deflate(byte[] bytes,
int level)
Compresses an array of bytes using Deflate algorithm with specified compression level. |
static int |
getCompactLength(long n)
Returns number of bytes that are needed to write specified number in a compact format. |
static byte[] |
inflate(byte[] bytes)
Decompresses an array of bytes using Inflate algorithm (reverse of Deflate algorithm). |
static boolean |
isCompressionEnabled()
Returns value of compression strategy. |
static byte[] |
objectsToBytes(Class[] types,
Object... objects)
Serializes a declared group of objects to an array of bytes according to their declared types. |
static byte[] |
objectToBytes(Object object)
Serializes an object to an array of bytes with Java Serialization. |
static byte[] |
readByteArray(DataInput in)
Reads an array of bytes from the data input in a compact encapsulation format. |
static char[] |
readCharArray(DataInput in)
Reads an array of characters from the data input in a CESU-8 format with compact encapsulation. |
static String |
readCharArrayString(DataInput in)
Deprecated. |
static int |
readCompactInt(DataInput in)
Reads an int value from the data input in a compact format. |
static long |
readCompactLong(DataInput in)
Reads a long value from the data input in a compact format. |
static Object |
readObject(DataInput in)
Reads an object from the data input as a Java-serialized byte array with compact encapsulation. |
static Object |
readObject(DataInput in,
ClassLoader cl)
Reads an object from the data input as a Java-serialized byte array with compact encapsulation. |
static int |
readUTFChar(DataInput in)
Reads Unicode code point from the data input in a UTF-8 format. |
static String |
readUTFString(DataInput in)
Reads Unicode string from the data input in a UTF-8 format with compact encapsulation. |
static void |
setCompressionEnabled(boolean compressionEnabled)
Sets new value for compression strategy. |
static void |
writeByteArray(DataOutput out,
byte[] bytes)
Writes an array of bytes to the data output in a compact encapsulation format. |
static void |
writeCharArray(DataOutput out,
char[] chars)
Writes an array of characters to the data output in a CESU-8 format with compact encapsulation. |
static void |
writeCharArray(DataOutput out,
String str)
Writes an array of characters to the data output in a CESU-8 format with compact encapsulation. |
static void |
writeCompactInt(DataOutput out,
int v)
Writes an int value to the data output in a compact format. |
static void |
writeCompactLong(DataOutput out,
long v)
Writes a long value to the data output in a compact format. |
static void |
writeObject(DataOutput out,
Object object)
Writes an object to the data output as a Java-serialized byte array with compact encapsulation. |
static void |
writeUTFChar(DataOutput out,
int codePoint)
Writes a Unicode code point to the data output in a UTF-8 format. |
static void |
writeUTFString(DataOutput out,
String str)
Writes a string to the data output in a UTF-8 format with compact encapsulation. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static void checkRange(byte[] b, int off, int len)
IndexOutOfBoundsException
if parameters are out of range.
public static int getCompactLength(long n)
n
- the number those compact length is returned
public static void writeCompactInt(DataOutput out, int v) throws IOException
int
value to the data output in a compact format.
out
- the destination to write tov
- the int
value to be written
IOException
- if an I/O error occurspublic static void writeCompactLong(DataOutput out, long v) throws IOException
long
value to the data output in a compact format.
out
- the destination to write tov
- the long
value to be written
IOException
- if an I/O error occurspublic static int readCompactInt(DataInput in) throws IOException
int
value from the data input in a compact format.
If actual encoded value does not fit into an int
data type,
then it is truncated to int
value (only lower 32 bits are returned);
the number is read entirely in this case.
in
- the source to read from
int
value read
IOException
- if an I/O error occurspublic static long readCompactLong(DataInput in) throws IOException
long
value from the data input in a compact format.
in
- the source to read from
long
value read
IOException
- if an I/O error occurspublic static void writeByteArray(DataOutput out, byte[] bytes) throws IOException
out
- the destination to write tobytes
- the byte array to be written
IOException
- if an I/O error occurspublic static byte[] readByteArray(DataInput in) throws IOException
in
- the source to read from
IOException
- if an I/O error occurspublic static void writeCharArray(DataOutput out, char[] chars) throws IOException
out
- the destination to write tochars
- the char array to be written
IOException
- if an I/O error occurspublic static void writeCharArray(DataOutput out, String str) throws IOException
String
and treats it as char array.
out
- the destination to write tostr
- the string to be written
IOException
- if an I/O error occurspublic static char[] readCharArray(DataInput in) throws IOException
in
- the source to read from
UTFDataFormatException
- if the bytes do not represent a valid CESU-8 encoding of a character
or if resulting code point is beyond Basic Multilingual Plane (BMP)
IOException
- if an I/O error occurspublic static String readCharArrayString(DataInput in) throws IOException
in
- the source to read from
UTFDataFormatException
- if the bytes do not represent a valid CESU-8 encoding of a character
or if resulting code point is beyond Basic Multilingual Plane (BMP)
IOException
- if an I/O error occurspublic static void writeUTFChar(DataOutput out, int codePoint) throws IOException
out
- the destination to write tocodePoint
- the code point to be written
UTFDataFormatException
- if codePoint is not a valid Unicode character
IOException
- if an I/O error occurspublic static int readUTFChar(DataInput in) throws IOException
in
- the source to read from
UTFDataFormatException
- if the bytes do not represent a valid UTF-8 encoding of a character
IOException
- if an I/O error occurspublic static void writeUTFString(DataOutput out, String str) throws IOException
out
- the destination to write tostr
- the string to be written
UTFDataFormatException
- if str is too long
IOException
- if an I/O error occurspublic static String readUTFString(DataInput in) throws IOException
in
- the source to read from
UTFDataFormatException
- if the bytes do not represent a valid UTF-8 encoding of a string
IOException
- if an I/O error occurspublic static byte[] objectToBytes(Object object) throws IOException
Marshalled
objects as a special case and
returns the result of Marshalled.getBytes()
call.
object
- the object to be serialized
IOException
- if object cannot be serializedpublic static Object bytesToObject(byte[] bytes) throws IOException
bytes
- the byte array to be deserialized
IOException
- if object cannot be deserializedpublic static Object bytesToObject(byte[] bytes, ClassLoader cl) throws IOException
bytes
- the byte array to be deserializedcl
- the ClassLoader that will be used to load classes; null
for default
IOException
- if object cannot be deserializedpublic static byte[] objectsToBytes(Class[] types, Object... objects) throws IOException
Marshalled
objects as a special case and
implicitly converts them into original objects via Marshalled.getObject()
call.
types
- the declared types of serialized objectsobjects
- the actual objects to be serialized
IllegalArgumentException
- if types
and objects
have different lengths
ClassCastException
- if actual object types do not match declared types
IOException
- if objects cannot be serializedpublic static Object[] bytesToObjects(Class[] types, byte[] bytes) throws IOException
types
- the declared types of serialized objectsbytes
- the byte array to be deserialized
ClassCastException
- if actual object types do not match declared types
IOException
- if objects cannot be deserializedpublic static Object[] bytesToObjects(Class[] types, byte[] bytes, ClassLoader cl) throws IOException
types
- the declared types of serialized objectsbytes
- the byte array to be deserializedcl
- the ClassLoader that will be used to load classes; null
for default
ClassCastException
- if actual object types do not match declared types
IOException
- if objects cannot be deserializedpublic static void writeObject(DataOutput out, Object object) throws IOException
Marshalled
objects as a special case and
writes the result of Marshalled.getBytes()
call.
out
- the destination to write toobject
- the object to be written
IOException
- if an I/O error occurs or if object cannot be serializedpublic static Object readObject(DataInput in) throws IOException
in
- the source to read from
IOException
- if an I/O error occurs or if object cannot be deserializedpublic static Object readObject(DataInput in, ClassLoader cl) throws IOException
in
- the source to read fromcl
- the ClassLoader that will be used to load classes; null
for default
IOException
- if an I/O error occurs or if object cannot be deserializedpublic static byte[] deflate(byte[] bytes, int level)
bytes
- the byte array to be compressedlevel
- the compression level from 0
to 9
inclusive; -1
for default
public static byte[] inflate(byte[] bytes) throws DataFormatException
bytes
- the byte array to be decompressed
DataFormatException
- if data format error has occuredpublic static boolean isCompressionEnabled()
true
if compression is enabled, false
otherwisepublic static void setCompressionEnabled(boolean compressionEnabled)
compressionEnabled
- the value of compression flagpublic static byte[] compress(byte[] bytes)
deflate(byte[], int)
method this method determines if compression is necessary or not based on
compression strategy (see isCompressionEnabled()
) and heuristics related to specified byte array.
If decided negative it returns original byte array, otherwise it uses fastest compression level.
This method is intended for transparent compression of serialized data and similar cases.
bytes
- the byte array to be compressed as appropriate
public static byte[] decompress(byte[] bytes)
This method is intended for transparent decompression of serialized data and similar cases.
bytes
- the byte array to be decompressed as appropriate
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |