org.apache.commons.codec.binary

Class Hex

java.lang.Object

org.apache.commons.codec.binary.Hex

All Implemented Interfaces:

BinaryDecoder, BinaryEncoder, Decoder, Encoder

public class Hex
extends Object
implements BinaryEncoder, BinaryDecoder

Converts hexadecimal Strings. The charset used for certain operation can be set, the default is set in DEFAULT_CHARSET_NAME This class is thread-safe.

Since:

1.1

Field Summary

Fields

Modifier and Type	Field and Description
static java.nio.charset.Charset	DEFAULT_CHARSET Default charset is Charsets.UTF_8
static String	DEFAULT_CHARSET_NAME Default charset name is CharEncoding.UTF_8

Constructor Summary

Constructors

Constructor and Description
Hex() Creates a new codec with the default charset name DEFAULT_CHARSET
Hex(java.nio.charset.Charset charset) Creates a new codec with the given Charset.
Hex(String charsetName) Creates a new codec with the given charset name.

Method Summary

Modifier and Type	Method and Description
byte[]	decode(byte[] array) Converts an array of character bytes representing hexadecimal values into an array of bytes of those same values.
byte[]	decode(ByteBuffer buffer) Converts a buffer of character bytes representing hexadecimal values into an array of bytes of those same values.
Object	decode(Object object) Converts a String or an array of character bytes representing hexadecimal values into an array of bytes of those same values.
static byte[]	decodeHex(char[] data) Converts an array of characters representing hexadecimal values into an array of bytes of those same values.
static byte[]	decodeHex(String data) Converts a String representing hexadecimal values into an array of bytes of those same values.
byte[]	encode(byte[] array) Converts an array of bytes into an array of bytes for the characters representing the hexadecimal values of each byte in order.
byte[]	encode(ByteBuffer array) Converts byte buffer into an array of bytes for the characters representing the hexadecimal values of each byte in order.
Object	encode(Object object) Converts a String or an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
static char[]	encodeHex(byte[] data) Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
static char[]	encodeHex(byte[] data, boolean toLowerCase) Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
protected static char[]	encodeHex(byte[] data, char[] toDigits) Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
static char[]	encodeHex(ByteBuffer data) Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order.
static char[]	encodeHex(ByteBuffer data, boolean toLowerCase) Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order.
protected static char[]	encodeHex(ByteBuffer byteBuffer, char[] toDigits) Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order.
static String	encodeHexString(byte[] data) Converts an array of bytes into a String representing the hexadecimal values of each byte in order.
static String	encodeHexString(byte[] data, boolean toLowerCase) Converts an array of bytes into a String representing the hexadecimal values of each byte in order.
static String	encodeHexString(ByteBuffer data) Converts a byte buffer into a String representing the hexadecimal values of each byte in order.
static String	encodeHexString(ByteBuffer data, boolean toLowerCase) Converts a byte buffer into a String representing the hexadecimal values of each byte in order.
java.nio.charset.Charset	getCharset() Gets the charset.
String	getCharsetName() Gets the charset name.
protected static int	toDigit(char ch, int index) Converts a hexadecimal character to an integer.
String	toString() Returns a string representation of the object, which includes the charset name.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CHARSET

public static final java.nio.charset.Charset DEFAULT_CHARSET

Default charset is Charsets.UTF_8

Since:

1.7

DEFAULT_CHARSET_NAME

public static final String DEFAULT_CHARSET_NAME

Default charset name is CharEncoding.UTF_8

Since:

1.4

See Also:

Constant Field Values

Constructor Detail

Hex

public Hex()

Creates a new codec with the default charset name DEFAULT_CHARSET

Hex

public Hex(java.nio.charset.Charset charset)

Creates a new codec with the given Charset.

Parameters:

charset - the charset.

Since:

1.7

Hex

public Hex(String charsetName)

Creates a new codec with the given charset name.

Parameters:

charsetName - the charset name.

Throws:

java.nio.charset.UnsupportedCharsetException - If the named charset is unavailable

Since:

1.4, 1.7 throws UnsupportedCharsetException if the named charset is unavailable

Method Detail

decode

public byte[] decode(byte[] array)
              throws DecoderException

Converts an array of character bytes representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.

Specified by:

decode in interface BinaryDecoder

Parameters:

array - An array of character bytes containing hexadecimal digits

Returns:

A byte array containing binary data decoded from the supplied byte array (representing characters).

Throws:

DecoderException - Thrown if an odd number of characters is supplied to this function

See Also:

decodeHex(char[])

decode

public byte[] decode(ByteBuffer buffer)
              throws DecoderException

Converts a buffer of character bytes representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.

Parameters:

buffer - An array of character bytes containing hexadecimal digits

Returns:

A byte array containing binary data decoded from the supplied byte array (representing characters).

Throws:

DecoderException - Thrown if an odd number of characters is supplied to this function

Since:

1.11

See Also:

decodeHex(char[])

decode

public Object decode(Object object)
              throws DecoderException

Converts a String or an array of character bytes representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed String or array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.

Specified by:

decode in interface Decoder

Parameters:

object - A String, ByteBuffer, byte[], or an array of character bytes containing hexadecimal digits

Returns:

A byte array containing binary data decoded from the supplied byte array (representing characters).

Throws:

DecoderException - Thrown if an odd number of characters is supplied to this function or the object is not a String or char[]

See Also:

decodeHex(char[])

decodeHex

public static byte[] decodeHex(char[] data)
                        throws DecoderException

Converts an array of characters representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed array, as it takes two characters to represent any given byte. An exception is thrown if the passed char array has an odd number of elements.

Parameters:

data - An array of characters containing hexadecimal digits

Returns:

A byte array containing binary data decoded from the supplied char array.

Throws:

DecoderException - Thrown if an odd number or illegal of characters is supplied

decodeHex

public static byte[] decodeHex(String data)
                        throws DecoderException

Converts a String representing hexadecimal values into an array of bytes of those same values. The returned array will be half the length of the passed String, as it takes two characters to represent any given byte. An exception is thrown if the passed String has an odd number of elements.

Parameters:

data - A String containing hexadecimal digits

Returns:

A byte array containing binary data decoded from the supplied char array.

Throws:

DecoderException - Thrown if an odd number or illegal of characters is supplied

Since:

1.11

encode

public byte[] encode(byte[] array)

Converts an array of bytes into an array of bytes for the characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

The conversion from hexadecimal characters to the returned bytes is performed with the charset named by getCharset().

Specified by:

encode in interface BinaryEncoder

Parameters:

array - a byte[] to convert to Hex characters

Returns:

A byte[] containing the bytes of the lower-case hexadecimal characters

Since:

1.7 No longer throws IllegalStateException if the charsetName is invalid.

See Also:

encodeHex(byte[])

encode

public byte[] encode(ByteBuffer array)

Converts byte buffer into an array of bytes for the characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

The conversion from hexadecimal characters to the returned bytes is performed with the charset named by getCharset().

Parameters:

array - a byte buffer to convert to Hex characters

Returns:

A byte[] containing the bytes of the lower-case hexadecimal characters

Since:

1.11

See Also:

encodeHex(byte[])

encode

public Object encode(Object object)
              throws EncoderException

Converts a String or an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed String or array, as it takes two characters to represent any given byte.

The conversion from hexadecimal characters to bytes to be encoded to performed with the charset named by getCharset().

Specified by:

encode in interface Encoder

Parameters:

object - a String, ByteBuffer, or byte[] to convert to Hex characters

Returns:

A char[] containing lower-case hexadecimal characters

Throws:

EncoderException - Thrown if the given object is not a String or byte[]

See Also:

encodeHex(byte[])

encodeHex

public static char[] encodeHex(byte[] data)

Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte[] to convert to Hex characters

Returns:

A char[] containing lower-case hexadecimal characters

encodeHex

public static char[] encodeHex(byte[] data,
                               boolean toLowerCase)

Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte[] to convert to Hex characters

toLowerCase - true converts to lowercase, false to uppercase

Returns:

A char[] containing hexadecimal characters in the selected case

Since:

1.4

encodeHex

protected static char[] encodeHex(byte[] data,
                                  char[] toDigits)

Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte[] to convert to Hex characters

toDigits - the output alphabet (must contain at least 16 chars)

Returns:

A char[] containing the appropriate characters from the alphabet For best results, this should be either upper- or lower-case hex.

Since:

1.4

encodeHex

public static char[] encodeHex(ByteBuffer data)

Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte buffer to convert to Hex characters

Returns:

A char[] containing lower-case hexadecimal characters

Since:

1.11

encodeHex

public static char[] encodeHex(ByteBuffer data,
                               boolean toLowerCase)

Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte buffer to convert to Hex characters

toLowerCase - true converts to lowercase, false to uppercase

Returns:

A char[] containing hexadecimal characters in the selected case

Since:

1.11

encodeHex

protected static char[] encodeHex(ByteBuffer byteBuffer,
                                  char[] toDigits)

Converts a byte buffer into an array of characters representing the hexadecimal values of each byte in order. The returned array will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

byteBuffer - a byte buffer to convert to Hex characters

toDigits - the output alphabet (must be at least 16 characters)

Returns:

A char[] containing the appropriate characters from the alphabet For best results, this should be either upper- or lower-case hex.

Since:

1.11

encodeHexString

public static String encodeHexString(byte[] data)

Converts an array of bytes into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte[] to convert to Hex characters

Returns:

A String containing lower-case hexadecimal characters

Since:

1.4

encodeHexString

public static String encodeHexString(byte[] data,
                                     boolean toLowerCase)

Converts an array of bytes into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte[] to convert to Hex characters

toLowerCase - true converts to lowercase, false to uppercase

Returns:

A String containing lower-case hexadecimal characters

Since:

1.11

encodeHexString

public static String encodeHexString(ByteBuffer data)

Converts a byte buffer into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte buffer to convert to Hex characters

Returns:

A String containing lower-case hexadecimal characters

Since:

1.11

encodeHexString

public static String encodeHexString(ByteBuffer data,
                                     boolean toLowerCase)

Converts a byte buffer into a String representing the hexadecimal values of each byte in order. The returned String will be double the length of the passed array, as it takes two characters to represent any given byte.

Parameters:

data - a byte buffer to convert to Hex characters

toLowerCase - true converts to lowercase, false to uppercase

Returns:

A String containing lower-case hexadecimal characters

Since:

1.11

getCharset

public java.nio.charset.Charset getCharset()

Gets the charset.

Returns:

the charset.

Since:

1.7

getCharsetName

public String getCharsetName()

Gets the charset name.

Returns:

the charset name.

Since:

1.4

toDigit

protected static int toDigit(char ch,
                             int index)
                      throws DecoderException

Converts a hexadecimal character to an integer.

Parameters:

ch - A character to convert to an integer digit

index - The index of the character in the source

Returns:

An integer

Throws:

DecoderException - Thrown if ch is an illegal hex character

toString

public String toString()

Returns a string representation of the object, which includes the charset name.

Overrides:

toString in class Object

Returns:

a string representation of the object.