Class ConvertedEncoding<T,S>
- Type Parameters:
T
- This encoder's value typeS
- The delegate encoder's value type
- All Implemented Interfaces:
Encoding<T>
,NaturalSortAware
,Serializable
,Comparator<T>
- Direct Known Subclasses:
StringConvertedEncoding
Encoding
that relies on some other Encoding
, converting values to/from
the other Encoding
's Java type.
This class provides a convenient way to implement custom Encoding
s when the target values can be converted
into some other form for which another Encoding
(the "delegate") already exists. A Guava Converter
converts values between the type supported by this encoding and the type supported by the delegate encoding.
It's convert()
method must throw IllegalArgumentException
if an unsupported
value is encountered. The Converter
should be non-lossy when supported values are round-tripped.
This encoding will sort values in the same order as the delegate sorts the corresponding converted values. Null values are supported by this encoding when the delegate supports them; if so, null always converts to/from null.
The Converter
must be Serializable
in order for an instance of this class to also be
Serializable
.
- See Also:
-
Field Summary
Fields inherited from class io.permazen.encoding.AbstractEncoding
encodingId, typeToken
Fields inherited from interface io.permazen.encoding.Encoding
MAX_ARRAY_DIMENSIONS
-
Constructor Summary
ConstructorDescriptionConvertedEncoding
(EncodingId encodingId, TypeToken<T> typeToken, T defaultValue, Encoding<S> delegate, Converter<T, S> converter, boolean sortsNaturally) Primary constructor.ConvertedEncoding
(EncodingId encodingId, Class<T> type, T defaultValue, Encoding<S> delegate, Converter<T, S> converter, boolean sortsNaturally) -
Method Summary
Modifier and TypeMethodDescriptionint
Order two field values.fromString
(String string) Parse a non-null value previously encoded bytoString(T)
.boolean
Determine whether any of this encoding's encoded values start with a0x00
byte.boolean
Determine whether any of this encoding's encoded values start with a0xff
byte.read
(ByteReader reader) Read a value from the given input.void
skip
(ByteReader reader) Read and discard abyte[]
encoded value from the given input.boolean
Determine if this instance sorts Java instances naturally.final boolean
Determine whether this encoding supports null values.Encode a non-null value as aString
for later decoding byfromString()
.Verify the given object is a valid instance of thisEncoding
's Java type and cast it to that type.withEncodingId
(EncodingId encodingId) Build an encoding that has the givenEncodingId
but is otherwise equivalent to this encoding.void
write
(ByteWriter writer, T obj) Write a value to the given output.Methods inherited from class io.permazen.encoding.AbstractEncoding
equals, getDefaultValue, getDefaultValueBytes, getEncodingId, getTypeToken, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.Comparator
reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong
Methods inherited from interface io.permazen.encoding.Encoding
convert, decode, encode, getKeyRange, validateAndWrite
-
Constructor Details
-
ConvertedEncoding
public ConvertedEncoding(EncodingId encodingId, TypeToken<T> typeToken, T defaultValue, Encoding<S> delegate, Converter<T, S> converter, boolean sortsNaturally) Primary constructor.- Parameters:
encodingId
- encoding ID for this encoding, or null to be anonymoustypeToken
- represented Java typedefaultValue
- default value for this encoding; must be null if this encoding supports nullsdelegate
- delegate encoderconverter
- value convertersortsNaturally
- true if this encoding sorts naturally, otherwise false- Throws:
IllegalArgumentException
- if any parameter other thandefaultValue
is null
-
ConvertedEncoding
public ConvertedEncoding(EncodingId encodingId, Class<T> type, T defaultValue, Encoding<S> delegate, Converter<T, S> converter, boolean sortsNaturally) - Parameters:
encodingId
- encoding ID for this encoding, or null to be anonymoustype
- represented Java typedefaultValue
- default value for this encoding; must be null if this encoding supports nullsdelegate
- delegate encoderconverter
- converts between native form andString
form; should beSerializable
sortsNaturally
- true if this encoding sorts naturally, otherwise false- Throws:
IllegalArgumentException
- if any parameter other thandefaultValue
is null
-
-
Method Details
-
withEncodingId
Description copied from interface:Encoding
Build an encoding that has the givenEncodingId
but is otherwise equivalent to this encoding.If this encoding already has
encodingId
, then this method may (but is not required to) return this same instance.- Parameters:
encodingId
- new encoding'sEncodingId
, or null for an anonymized encoding- Returns:
- a version of this encoding with the given
EncodingId
-
read
Description copied from interface:Encoding
Read a value from the given input.- Parameters:
reader
- byte input- Returns:
- field value (possibly null)
-
write
Description copied from interface:Encoding
Write a value to the given output.- Parameters:
writer
- byte outputobj
- value to write (possibly null)
-
skip
Description copied from interface:Encoding
Read and discard abyte[]
encoded value from the given input.- Parameters:
reader
- byte input
-
toString
Description copied from interface:Encoding
Encode a non-null value as aString
for later decoding byfromString()
.Each of the characters in the returned
String
must be one of the valid XML characters (tab, newline, carriage return,\u0020 - \ud7ff
, and\ue000 - \ufffd
).- Parameters:
obj
- actual value, never null- Returns:
- string encoding of
value
acceptable tofromString()
- See Also:
-
fromString
Description copied from interface:Encoding
Parse a non-null value previously encoded bytoString(T)
.- Parameters:
string
- non-null value previously encoded as aString
bytoString(T)
- Returns:
- actual value
-
sortsNaturally
public boolean sortsNaturally()Description copied from interface:NaturalSortAware
Determine if this instance sorts Java instances naturally.This method should return true only if all of the following are true:
- This class also implements
Comparator
for some Java typeT
. - Type
T
has a natural ordering (i.e.,T
itself implementsComparable
). - The ordering implied by this class's
compare()
method is identical toT
's natural ordering.
- Returns:
- true if this instance orders Java values in their natural order
- This class also implements
-
supportsNull
public final boolean supportsNull()Description copied from interface:Encoding
Determine whether this encoding supports null values.The implementation in
Encoding
returnsfalse
.- Returns:
- true if null is a valid value, otherwise false
-
validate
Description copied from interface:Encoding
Verify the given object is a valid instance of thisEncoding
's Java type and cast it to that type.Note that this method must throw
IllegalArgumentException
, notClassCastException
orNullPointerException
, ifobj
does not have the correct type, or is an unsupported value - including null if null is not supported.This method is allowed to perform widening conversions of the object that lose no information, e.g., from
Integer
toLong
.The implementation in
Encoding
first verifies the value is not null if this instance does not allow null values, and then attempts to cast the value using this instance's raw Java type. Subclasses should override this method to implement any other restrictions.- Parameters:
obj
- object to validate- Returns:
obj
cast to this encoding's type
-
compare
Description copied from interface:Encoding
Order two field values.This method must provide a total ordering of all supported Java values that is consistent with the database ordering, i.e., the unsigned lexicographical ordering of the corresponding
byte[]
encoded field values.If null is a supported Java value, then the this method must accept null parameters without throwing an exception (note, this is a stronger requirement than the
Comparator
interface normally requires).Note: by convention, null values usually sort last.
-
hasPrefix0x00
public boolean hasPrefix0x00()Description copied from interface:Encoding
Determine whether any of this encoding's encoded values start with a0x00
byte. Certain optimizations are possible when this is not the case. It is safe for this method to always return true.Note: changing the result of this method may result in an incompatible encoding if this encoding is wrapped in another class.
The implementation in
Encoding
returnstrue
.- Returns:
- true if an encoded value starting with
0x00
exists
-
hasPrefix0xff
public boolean hasPrefix0xff()Description copied from interface:Encoding
Determine whether any of this encoding's encoded values start with a0xff
byte. Certain optimizations are possible when this is not the case. It is safe for this method to always return true.Note: changing the result of this method may result in an incompatible encoding if this encoding is wrapped in another class.
The implementation in
Encoding
returnstrue
.- Returns:
- true if an encoded value starting with
0xff
exists
-