Package io.permazen.encoding

Interface EncodingRegistry

All Known Implementing Classes:

DefaultEncodingRegistry, SimpleEncodingRegistry

public interface EncodingRegistry

A registry of Encodings.

Encodings in an EncodingRegistry can be looked up by EncodingId or by Java type. Multiple Encodings may support the same Java type, so only the EncodingId lookup is guaranteed to be unique.

Note: Enum types are not directly handled in the core API layer; instead, the appropriate EnumValueEncoding must be used to encode values as EnumValues.

Instances must be thread safe.

Method Summary

Modifier and Type	Method	Description
default String	aliasForId(EncodingId encodingId)	Get the alias (or "nickname") for the given encoding ID in this registry, if any.
default <T> Encoding<T>	getEncoding(TypeToken<T> typeToken)	Get the unique Encoding in this registry that supports values of the given Java type.
Encoding<?>	getEncoding(EncodingId encodingId)	Get the Encoding with the given encoding ID in this registry.
default <T> Encoding<T>	getEncoding(Class<T> type)	Get the unique Encoding in this registry that supports values of the given Java type.
<T> List<Encoding<T>>	getEncodings(TypeToken<T> typeToken)	Get all of the Encodings in this registry that supports values of the given Java type.
default EncodingId	idForAlias(String alias)	Get the encoding ID corresponding to the given alias (or "nickname"), if any.

Method Details

getEncoding

Encoding<?> getEncoding(EncodingId encodingId)

Get the Encoding with the given encoding ID in this registry.

Parameters:

encodingId - encoding ID

Returns:

corresponding Encoding, if any, otherwise null

Throws:

IllegalArgumentException - if encodingId is null

idForAlias

default EncodingId idForAlias(String alias)

Get the encoding ID corresponding to the given alias (or "nickname"), if any.

See aliasForId() for details on aliases.

If alias is a valid alias, this method should return the corresponding EncodingId. If alias is not a valid alias, but is a valid encoding ID in string form, this method should return the corresponding EncodingId as if by new EncodingId(alias). Otherwise, this method should throw IllegalArgumentException.

Note: the EncodingId corresponding to an alias does not need to be actually registered with this instance in order for the alias to be valid.

The implementation in EncodingRegistry just invokes new EncodingId(alias).

Parameters:

alias - encoding ID alias

Returns:

corresponding encoding ID, never null

Throws:

IllegalArgumentException - if alias is null or not a valid alias

aliasForId

default String aliasForId(EncodingId encodingId)

Get the alias (or "nickname") for the given encoding ID in this registry, if any.

An EncodingRegistry may support aliases for some of its encoding ID's. Aliases are simply more friendly names for EncodingId strings, which are formatted as Uniform Resource Names (URNs).

Whereas EncodingId's are globally unique, aliases are only meaningful to the particular EncodingRegistry instance being queried. When a schema is recorded in a database, actual EncodingId's are always used.

In Permazen's DefaultEncodingRegistry, the built-in encodings all have aliases; for example, "int" is an alias for "urn:fdc:permazen.io:2020:int". Permazen's built-in encoding aliases are available via EncodingIds.aliasForId() and EncodingIds.idForAlias().

If no alias is known for encodingId, this method should return EncodingId.getId().

Note: an EncodingId does not need to be actually registered with this instance in order for it to have an alias.

The implementation in EncodingRegistry always returns EncodingId.getId().

Parameters:

encodingId - encoding ID

Returns:

corresponding alias, if any, otherwise EncodingId.getId()

Throws:

IllegalArgumentException - if encodingId is null

See Also:

• idForAlias(java.lang.String)

getEncodings

<T> List<Encoding<T>> getEncodings(TypeToken<T> typeToken)

Get all of the Encodings in this registry that supports values of the given Java type.

The Java type must exactly match the Encoding's supported Java type.

Type Parameters:

T - encoding value type

Parameters:

typeToken - encoding value type

Returns:

unmodifiable list of Encodings supporting Java values of type typeToken, possibly empty

Throws:

IllegalArgumentException - if typeToken is null

getEncoding

default <T> Encoding<T> getEncoding(TypeToken<T> typeToken)

Get the unique Encoding in this registry that supports values of the given Java type.

The Java type must exactly match the Encoding's supported Java type and there must be exactly one such Encoding, otherwise an IllegalArgumentException is thrown.

Type Parameters:

T - encoding value type

Parameters:

typeToken - encoding value type

Returns:

Encoding supporting Java values of type typeToken

Throws:

IllegalArgumentException - if typeToken is null

IllegalArgumentException - if no Encodings supports typeToken

IllegalArgumentException - if more than one Encoding supports typeToken

getEncoding

default <T> Encoding<T> getEncoding(Class<T> type)

Get the unique Encoding in this registry that supports values of the given Java type.

This is a convenience method, equivalent to: getEncoding(TypeToken.of(type)).

Type Parameters:

T - encoding value type

Parameters:

type - encoding value type

Returns:

Encoding supporting Java values of type type

Throws:

IllegalArgumentException - if type is null

IllegalArgumentException - if no Encodings supports type

IllegalArgumentException - if more than one Encoding supports type