com.foreach.common.spring.code

Class MappedStringEncoder

java.lang.Object

com.foreach.common.spring.code.MappedStringEncoder

public class MappedStringEncoder
extends Object

Encodes a number to a string according to an encoding map. The encoding matrix determines the maximum length of the resulting string as well as the largest number that can be encoded.

An encoding matrix can be assymetrical, but every position must have at least one possible value, and all values must be unique per position.

Encoding is reversable: the same encoder can also decode the code back into the numerical value.

A MappedStringEncoder can optionally support negative values. A separate position in the code will be sacrificed to encode the sign, which means the maximum encodable value will be impacted. The sign itself can be represented by any character.

Author:

Arne Vandamme

Field Summary

Fields

Modifier and Type	Field and Description
static int	UNSIGNED

Constructor Summary

Constructors

Constructor and Description
MappedStringEncoder() Creates a blank encoder that is unable to encode or decode any values.
MappedStringEncoder(int encodedStringLength, boolean supportNegativeValues) Creates a default encoder with a symmetrical encoding matrix.
MappedStringEncoder(int encodedStringLength, int signIndex) Creates a default encoder with a symmetrical encoding matrix.

Method Summary

Modifier and Type	Method and Description
void	buildEncodingMatrix(char[] columnValues, int numberOfColumns, boolean shiftColumnValues) Builds a symmetrical encoding matrix with the specified parameters.
void	buildEncodingMatrix(char[] columnValues, int numberOfColumns, boolean shiftColumnValues, int signColumnIndex) Builds a symmetrical encoding matrix with the specified parameters.
long	decode(String encoded) Decode a code string back to a number.
String	encode(long number, boolean pad) Encodes a number to a code string.
static MappedStringEncoder	forMaximumValue(long maxValue, boolean supportNegativeValues) Will create the shortest possible encoder that can encode the maximum value specified.
int	getCodeLength()
long	getMaxValue()
long	getMinValue()
boolean	isNegativeValuesSupported()
void	setEncodingMatrix(char[][] encodingMatrix) Sets the encoding matrix to use for encoding/decoding unsigned values.
void	setEncodingMatrix(char[][] encodingMatrix, int signIndex) Sets the encoding matrix to use.

Methods inherited from class java.lang.Object

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

Field Detail

UNSIGNED

public static final int UNSIGNED

See Also:

Constant Field Values

Constructor Detail

MappedStringEncoder

public MappedStringEncoder()

Creates a blank encoder that is unable to encode or decode any values. A valid encoding matrix needs to be set using setEncodingMatrix(char[][]).

MappedStringEncoder

public MappedStringEncoder(int encodedStringLength,
                           boolean supportNegativeValues)

Creates a default encoder with a symmetrical encoding matrix.

Parameters:

encodedStringLength - Length of a generated - fully padded - code.

supportNegativeValues - True if a position should be sacrificed to encode the sign.

MappedStringEncoder

public MappedStringEncoder(int encodedStringLength,
                           int signIndex)

Creates a default encoder with a symmetrical encoding matrix.

Parameters:

encodedStringLength - Length of a generated - fully padded - code.

signIndex - Index of the position where the sign value should be.

Method Detail

setEncodingMatrix

public void setEncodingMatrix(char[][] encodingMatrix)

Sets the encoding matrix to use for encoding/decoding unsigned values.

Parameters:

encodingMatrix - Character matrix to use for encoding/decoding.

setEncodingMatrix

public void setEncodingMatrix(char[][] encodingMatrix,
                              int signIndex)

Sets the encoding matrix to use. If a sign index is specified, that position should contain an encoding array with at least 2 values: the first being the positive sign and the second the negative. If more values are specified, these will simply ignored. The matrix must also be at least 2 positions as one position is required for the sign.

Specifying a negative sign index position will result in only positive values being supported.

Parameters:

encodingMatrix - Character matrix to use for encoding/decoding.

signIndex - Index of the position where the sign value should be.

buildEncodingMatrix

public void buildEncodingMatrix(char[] columnValues,
                                int numberOfColumns,
                                boolean shiftColumnValues)

Builds a symmetrical encoding matrix with the specified parameters. The matrix only supports unsigned values and depending on the shift parameter, the column values will be shifted for every position. Column values of ABC would result in zero being encoded as AAA (unshifted) or ABC (shifted).

The same parameters will always result in the same encoding matrix being generated.

Parameters:

columnValues - The possible values for a single position.

numberOfColumns - Number of positions in the code - also the code length.

shiftColumnValues - True if column values should be shifted for every position.

buildEncodingMatrix

public void buildEncodingMatrix(char[] columnValues,
                                int numberOfColumns,
                                boolean shiftColumnValues,
                                int signColumnIndex)

Builds a symmetrical encoding matrix with the specified parameters. Depending on the sign parameter the matrix will support signed values and depending on the shift parameter, the column values will be shifted for every position. Column values of ABC would result in zero being encoded as AAA (unshifted) or ABC (shifted).

The same parameters will always result in the same encoding matrix being generated.

Parameters:

columnValues - The possible values for a single position.

numberOfColumns - Number of positions in the code - also the code length.

shiftColumnValues - True if column values should be shifted for every position.

signColumnIndex - Index of the position where the sign value should be.

encode

public String encode(long number,
                     boolean pad)

Encodes a number to a code string.

Parameters:

number - Number to encode.

pad - True if resulting code should be padded to the full length.

Returns:

Code representing the number.

Throws:

IllegalArgumentException - in case the number cannot be encoded

decode

public long decode(String encoded)

Decode a code string back to a number.

Parameters:

encoded - Code string.

Returns:

Number represented by the code.

Throws:

IllegalArgumentException - if the code cannot be decoded with this encoder instance.

getCodeLength

public int getCodeLength()

Returns:

Full length of a code.

isNegativeValuesSupported

public boolean isNegativeValuesSupported()

Returns:

True if negative values are supported, if so a sign position is defined.

getMaxValue

public long getMaxValue()

Returns:

Largest possible value that can be encoded.

getMinValue

public long getMinValue()

Returns:

Smallest possible value that can be encoded.

forMaximumValue

public static MappedStringEncoder forMaximumValue(long maxValue,
                                                  boolean supportNegativeValues)

Will create the shortest possible encoder that can encode the maximum value specified. This will use a symmetrical encoding matrix.

In case of a negative value supporting encoding, the maximum value should be the absolute upper bound.

Parameters:

maxValue - Maximum value that needs to be encoded.

supportNegativeValues - True if negative values need to be encodable as well.

Returns:

Encoder instance.