io.urf.surf

Class SurfSerializer

java.lang.Object

io.urf.surf.SurfSerializer

public class SurfSerializer
extends Object

Simple serializer for the Simple URF (SURF) document format.

This serializer recognizes and can serialize the following type for SURF categories of resources:

Objects

• SurfObject

Literals

binary

• byte[]
• ByteBuffer

Boolean

• Boolean

character

• Character
• CodePointCharacter

email address

• EmailAddress

IRI

• URI
• URL

number

• BigInteger (serialized as decimal)
• BigDecimal (serialized as decimal)
• Number (including Integer, Long, and Double)

regular expression

• Pattern

string

• CharSequence (including String)

telephone number

• TelephoneNumber

temporal

• Date (serialized as instant)
• Instant
• MonthDay
• LocalDate
• LocalDateTime
• LocalTime
• OffsetDateTime
• OffsetTime
• Year
• YearMonth
• ZonedDateTime

UUID

• UUID

Collections

• List
• Map
• Set

This serializer is meant to be used once for generating a single SURF document. It should not be used to serialize multiple documents, as it maintains serialization state.

The serializer should be released after use so as not to leak memory of parsed resources when resources are present with tags/IDs and/or generate aliases.

This implementation is not thread safe.

Author:

Garret Wilson

Field Summary

Fields

Modifier and Type	Field and Description
static String	GENERATED_ALIAS_PREFIX The prefix used when generating aliases.

Constructor Summary

Constructors

Constructor and Description
SurfSerializer()

Method Summary

Modifier and Type	Method and Description
protected void	decreaseIndentLevel() Decreases the indention level.
protected String	determineAliasForResource(Object resource) Determines an alias to use with a resource, generating one if the graph requires it.
protected void	discoverResourceReferences(Object resource) Discovers whether there are references to the given resource and recursively all nested resources.
protected void	formatIndent(Appendable appendable) Appends indention characters at the appropriate level if formatting is enabled.
protected boolean	formatNewLine(Appendable appendable) Separates lines by adding a line separation character sequence if formatting is enabled.
Optional<String>	getAliasForResource(Object resource) Returns any alias associated with a resource.
CharSequence	getIndentSequence() Returns the sequence of characters used for each indention level.
CharSequence	getLineSeparator() Returns the sequence of characters used to separate lines.
protected Closeable	increaseIndentLevel() Increases the indention level.
boolean	isFormatted() Returns whether this serializer will format the document with additional whitespace and newlines.
boolean	isSequenceSeparatorRequired() Whether separators will always be added between sequence items even if newlines are present.
protected boolean	isSerialized(Object resource) Determines whether a given resource has already been serialized.
void	serialize(Appendable appendable, Object root) Serializes a SURF resource graph to a writer.
String	serialize(Object root) Serializes a SURF resource graph to a string.
void	serialize(OutputStream outputStream, Object root) Serializes a SURF resource graph to an output stream.
static void	serializeBinary(Appendable appendable, byte[] bytes) Serializes a binary literal along with its delimiter from an array of bytes.
static void	serializeBinary(Appendable appendable, ByteBuffer byteBuffer) Serializes a binary literal along with its delimiter from a byte buffer.
static void	serializeBoolean(Appendable appendable, boolean bool) Serializes a Boolean.
static void	serializeCharacter(Appendable appendable, int codePoint) Serializes a character surrounded by character delimiters.
static void	serializeCharacterCodePoint(Appendable appendable, char delimiter, int codePoint) Serializes a character as content, without any delimiters.
void	serializeDescription(Appendable appendable, SurfObject surfObject) Serializes a SURF resource description.
static void	serializeEmailAddress(Appendable appendable, com.globalmentor.net.EmailAddress emailAddress) Serializes an email address along with its delimiter.
static void	serializeIri(Appendable appendable, URI iri) Serializes an IRI along with its delimiters.
void	serializeList(Appendable appendable, List<?> list) Serializes a SURF list.
void	serializeMap(Appendable appendable, Map<?,?> map) Serializes a SURF map.
static void	serializeNumber(Appendable appendable, Number number) Serializes a number along with its delimiter if should be represented as a decimal.
void	serializeObject(Appendable appendable, SurfObject surfObject) Serializes a SURF object representation without the following description.
static void	serializeRegularExpression(Appendable appendable, Pattern regularExpression) Serializes a regular expression along with its delimiters.
void	serializeResource(Appendable appendable, Object resource) Serializes a SURF resource to a writer.
protected <I> void	serializeSequence(Appendable appendable, Iterable<I> sequence, com.globalmentor.io.function.IOBiConsumer<Appendable,I> itemSerializer) Serializes a general SURF sequence (such as a list).
void	serializeSet(Appendable appendable, Set<?> set) Serializes a SURF set.
static void	serializeString(Appendable appendable, CharSequence charSequence) Serializes a string surrounded by string delimiters.
static void	serializeTelephoneNumber(Appendable appendable, com.globalmentor.itu.TelephoneNumber telephoneNumber) Serializes a telephone number along with its delimiter.
static void	serializeTemporal(Appendable appendable, TemporalAccessor temporal) Serializes a temporal literal along with its delimiter.
static void	serializeUuid(Appendable appendable, UUID uuid) Serializes a UUID along with its delimiter.
void	setAliasForResource(Object resource, String alias) Associates an alias with a resource.
void	setFormatted(boolean formatted) Sets whether the serialization should be formatted.
void	setIndentSequence(CharSequence indentSequence) Set the sequence of characters used for each indention level.
void	setLineSeparator(CharSequence lineSeparator) Sets the sequence of characters used to separate lines.
void	setSequenceSeparatorRequired(boolean sequenceSeparatorRequired) Sets whether separators will always be added between sequence items even if newlines are present.
protected boolean	setSerialized(Object resource) Sets a resource has having been serialized.

Methods inherited from class java.lang.Object

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

Field Detail

GENERATED_ALIAS_PREFIX

public static final String GENERATED_ALIAS_PREFIX

The prefix used when generating aliases.

See Also:

Constant Field Values

Constructor Detail

SurfSerializer

public SurfSerializer()

Method Detail

isFormatted

public boolean isFormatted()

Returns whether this serializer will format the document with additional whitespace and newlines.

This implementation defaults to no formatting.

Returns:

Whether serialization output should be formatted.

setFormatted

public void setFormatted(boolean formatted)

Sets whether the serialization should be formatted.

Parameters:

formatted - Whether this serializer will format the document with additional whitespace and newlines.

getIndentSequence

public CharSequence getIndentSequence()

Returns the sequence of characters used for each indention level.

This implementation defaults to the horizontal tab character.

Returns:

The character(s) used for indention.

setIndentSequence

public void setIndentSequence(@Nonnull
                              CharSequence indentSequence)

Set the sequence of characters used for each indention level.

Parameters:

indentSequence - The character(s) to use for indention.

increaseIndentLevel

protected Closeable increaseIndentLevel()

Increases the indention level. No information is appended.

Returns:

An object that will automatically unindent when Closeable.close() is called.

formatIndent

protected void formatIndent(@Nonnull
                            Appendable appendable)
                     throws IOException

Appends indention characters at the appropriate level if formatting is enabled.

If formatting is turned off, no content will be added.

Parameters:

appendable - The appendable to which SURF data should be appended.

Throws:

IOException - If there was an error writing the indent.

See Also:

isFormatted(), getIndentSequence()

decreaseIndentLevel

protected void decreaseIndentLevel()

Decreases the indention level. No information is appended.

getLineSeparator

public CharSequence getLineSeparator()

Returns the sequence of characters used to separate lines.

This implementation defaults to the platform-dependent line separator for the current system.

Returns:

The character(s) used for line endings.

See Also:

System.lineSeparator()

setLineSeparator

public void setLineSeparator(@Nonnull
                             CharSequence lineSeparator)

Sets the sequence of characters used to separate lines.

Parameters:

lineSeparator - The character(s) to use for line endings.

See Also:

System.lineSeparator()

formatNewLine

protected boolean formatNewLine(@Nonnull
                                Appendable appendable)
                         throws IOException

Separates lines by adding a line separation character sequence if formatting is enabled.

If formatting is turned off, no content will be added.

Parameters:

appendable - The appendable to which SURF data should be appended.

Returns:

Whether or not a line separator sequence was actually appended.

Throws:

IOException - If there was an error writing the line separator.

See Also:

isFormatted(), getLineSeparator()

isSequenceSeparatorRequired

public boolean isSequenceSeparatorRequired()

Whether separators will always be added between sequence items even if newlines are present.

This implementation defaults to not adding sequence separators if not needed.

Returns:

Whether sequence separators will always be added even when options.

setSequenceSeparatorRequired

public void setSequenceSeparatorRequired(boolean sequenceSeparatorRequired)

Sets whether separators will always be added between sequence items even if newlines are present.

Parameters:

sequenceSeparatorRequired - Whether sequence separators will always be added even when options.

discoverResourceReferences

protected void discoverResourceReferences(@Nonnull
                                          Object resource)

Discovers whether there are references to the given resource and recursively all nested resources.

This method should not be called more than once for any resource graph, or all resources in the graph will be marked as having references.

Parameters:

resource - The resource graph for which references should be discovered.

getAliasForResource

public Optional<String> getAliasForResource(@Nonnull
                                            Object resource)

Returns any alias associated with a resource.

Parameters:

resource - The resource with which an alias may be associated.

Returns:

The alias, if any associated with the given resource.

setAliasForResource

public void setAliasForResource(@Nonnull
                                Object resource,
                                @Nonnull
                                String alias)

Associates an alias with a resource. This method allows associating aliases with non-object and non-collection resources as well, such as the number 5.

Aliases are not allowed to be set for objects with tags or IDs, which themselves serve as labels.

Parameters:

resource - The resource to associate with an alias.

alias - The alias to associate with the resource.

Throws:

NullPointerException - if the given resource and/or alias is null.

IllegalArgumentException - if the given alias is not a valid name token.

IllegalArgumentException - if an alias is given for a SurfObject with a tag or an ID.

determineAliasForResource

protected String determineAliasForResource(@Nonnull
                                           Object resource)

Determines an alias to use with a resource, generating one if the graph requires it.

• If an alias has already been associated with a resource, it is returned.
• Otherwise if the resource is a compound resource that has references, a new alias is generated, associated with the resource for future use and returned.
• An alias is never generated for a SurfObject with an a tag or an ID, as that serves as a label.

Parameters:

resource - The resource with which an alias may be associated, or null if there is no alias.

Returns:

The alias, if any associated with the given resource.

isSerialized

protected boolean isSerialized(@Nonnull
                               Object resource)

Determines whether a given resource has already been serialized.

Parameters:

resource - The resource to check.

Returns:

true if the resource has already been serialized.

setSerialized

protected boolean setSerialized(@Nonnull
                                Object resource)

Sets a resource has having been serialized.

Parameters:

resource - The resource to record as serialized.

Returns:

Whether the resource was previously marked as serialized before this call.

serialize

public String serialize(@Nonnull @Nullable
                        Object root)
                 throws IOException

Serializes a SURF resource graph to a string.

This method discovers resource references to that aliases may be generated as needed. This record of resource references is reset after serialization, but any generated aliases remain. This allows the same serializer to be used multiple times for the same graph, with the same aliases being used.

This is a convenience method that delegates to serialize(Appendable, Object).

Parameters:

root - The root SURF resource, or null if there is no resource to serialize.

Returns:

A serialized string representation of the given SURF resource graph.

Throws:

IOException - If there was an error writing the SURF data.

serialize

public void serialize(@Nonnull
                      OutputStream outputStream,
                      @Nullable
                      Object root)
               throws IOException

Serializes a SURF resource graph to an output stream.

This method discovers resource references to that aliases may be generated as needed. This record of resource references is reset after serialization, but any generated aliases remain. This allows the same serializer to be used multiple times for the same graph, with the same aliases being used.

Parameters:

outputStream - The output stream to receive SURF data.

root - The root SURF resource, or null if there is no resource to serialize.

Throws:

IOException - If there was an error writing the SURF data.

serialize

public void serialize(@Nonnull
                      Appendable appendable,
                      @Nullable
                      Object root)
               throws IOException

Serializes a SURF resource graph to a writer.

All references to the resources in the graph must have already been discovered if aliases need to be generated.

Parameters:

appendable - The appendable to which SURF data should be appended.

root - The root SURF resource, or null if there is no resource to serialize.

Throws:

NullPointerException - if the given appendable is null.

IOException - If there was an error writing the SURF data.

serializeResource

public void serializeResource(@Nonnull
                              Appendable appendable,
                              @Nullable
                              Object resource)
                       throws IOException

Serializes a SURF resource to a writer.

All references to the resources in the graph must have already been discovered if aliases need to be generated.

Parameters:

appendable - The appendable to which SURF data should be appended.

resource - The SURF resource to serialize to serialize.

Throws:

NullPointerException - if the given appendable and/or resource is null.

IOException - If there was an error appending the SURF data.

serializeObject

public void serializeObject(@Nonnull
                            Appendable appendable,
                            @Nonnull
                            SurfObject surfObject)
                     throws IOException

Serializes a SURF object representation without the following description.

All references to the resources in the graph must have already been discovered if aliases need to be generated.

Parameters:

appendable - The appendable to which SURF data should be appended.

surfObject - The information to be serialized as a SURF object.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.OBJECT_BEGIN

serializeDescription

public void serializeDescription(@Nonnull
                                 Appendable appendable,
                                 @Nonnull
                                 SurfObject surfObject)
                          throws IOException

Serializes a SURF resource description. The description section, including delimiters, will be serialized even if there are no properties.

All references to the resources in the graph must have already been discovered if aliases need to be generated.

Parameters:

appendable - The appendable to which SURF data should be appended.

surfObject - The SURF object with the description to be serialized.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.DESCRIPTION_BEGIN, SURF.DESCRIPTION_END

serializeBinary

public static void serializeBinary(@Nonnull
                                   Appendable appendable,
                                   @Nonnull
                                   byte[] bytes)
                            throws IOException

Serializes a binary literal along with its delimiter from an array of bytes.

Parameters:

appendable - The appendable to which SURF data should be appended.

bytes - The information to be serialized as a SURF binary literal.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.BINARY_BEGIN

serializeBinary

public static void serializeBinary(@Nonnull
                                   Appendable appendable,
                                   @Nonnull
                                   ByteBuffer byteBuffer)
                            throws IOException

Serializes a binary literal along with its delimiter from a byte buffer.

Parameters:

appendable - The appendable to which SURF data should be appended.

byteBuffer - The information to be serialized as a SURF binary literal.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.BINARY_BEGIN

serializeBoolean

public static void serializeBoolean(@Nonnull
                                    Appendable appendable,
                                    @Nonnull
                                    boolean bool)
                             throws IOException

Serializes a Boolean.

Parameters:

appendable - The appendable to which SURF data should be appended.

bool - The Boolean value to be serialized as a SURF Boolean.

Throws:

NullPointerException - if the given reader is null.

IllegalArgumentException - if the given code point is not a valid Unicode code point.

IOException - if there is an error appending to the appendable.

serializeCharacter

public static void serializeCharacter(@Nonnull
                                      Appendable appendable,
                                      @Nonnull
                                      int codePoint)
                               throws IOException

Serializes a character surrounded by character delimiters.

Parameters:

appendable - The appendable to which SURF data should be appended.

codePoint - The Unicode code point to be serialized as a SURF character.

Throws:

NullPointerException - if the given reader is null.

IllegalArgumentException - if the given code point is not a valid Unicode code point.

IOException - if there is an error appending to the appendable.

See Also:

SURF.CHARACTER_DELIMITER, serializeCharacterCodePoint(Appendable, char, int)

serializeCharacterCodePoint

public static void serializeCharacterCodePoint(@Nonnull
                                               Appendable appendable,
                                               char delimiter,
                                               int codePoint)
                                        throws IOException,
                                               com.globalmentor.io.ParseIOException

Serializes a character as content, without any delimiters.

This implementation does not escape the solidus (slash) character '/', which is not required to be escaped.

Parameters:

appendable - The appendable to which SURF data should be appended.

delimiter - The delimiter that surrounds the character and which should be escaped.

codePoint - The code point to serialize.

Throws:

NullPointerException - if the given appendable is null.

IOException - if there is an error appending to the appender.

com.globalmentor.io.ParseIOException - if a control character was represented, if the character is not escaped correctly, or the reader has no more characters before the current character is completely parsed.

See Also:

SURF.CHARACTER_REQUIRED_ESCAPED_CHARACTERS

serializeEmailAddress

public static void serializeEmailAddress(@Nonnull
                                         Appendable appendable,
                                         @Nonnull
                                         com.globalmentor.net.EmailAddress emailAddress)
                                  throws IOException

Serializes an email address along with its delimiter.

Parameters:

appendable - The appendable to which SURF data should be appended.

emailAddress - The information to be serialized as a SURF email address.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.EMAIL_ADDRESS_BEGIN

serializeIri

public static void serializeIri(@Nonnull
                                Appendable appendable,
                                @Nonnull
                                URI iri)
                         throws IOException

Serializes an IRI along with its delimiters.

This implementation serializes an IRI using a SURF IRI short form if possible.

Parameters:

appendable - The appendable to which SURF data should be appended.

iri - The information to be serialized as a SURF IRI.

Throws:

NullPointerException - if the given reader is null.

IllegalArgumentException - if the given IRI is not a true, absolute IRI with a scheme.

IOException - if there is an error appending to the appendable.

See Also:

SURF.IRI_BEGIN

serializeNumber

public static void serializeNumber(@Nonnull
                                   Appendable appendable,
                                   @Nonnull
                                   Number number)
                            throws IOException

Serializes a number along with its delimiter if should be represented as a decimal.

This implementation represents the following types as SURF decimal:

• BigDecimal
• BigInteger

Parameters:

appendable - The appendable to which SURF data should be appended.

number - The information to be serialized as a SURF number.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.NUMBER_DECIMAL_BEGIN

serializeRegularExpression

public static void serializeRegularExpression(@Nonnull
                                              Appendable appendable,
                                              @Nonnull
                                              Pattern regularExpression)
                                       throws IOException

Serializes a regular expression along with its delimiters.

Parameters:

appendable - The appendable to which SURF data should be appended.

regularExpression - The information to be serialized as a SURF regular expression.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.REGULAR_EXPRESSION_DELIMITER, SURF.REGULAR_EXPRESSION_ESCAPE

serializeString

public static void serializeString(@Nonnull
                                   Appendable appendable,
                                   @Nonnull
                                   CharSequence charSequence)
                            throws IOException

Serializes a string surrounded by string delimiters.

Parameters:

appendable - The appendable to which SURF data should be appended.

charSequence - The information to be serialized as a SURF string.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.STRING_DELIMITER, serializeCharacterCodePoint(Appendable, char, int)

serializeTelephoneNumber

public static void serializeTelephoneNumber(@Nonnull
                                            Appendable appendable,
                                            @Nonnull
                                            com.globalmentor.itu.TelephoneNumber telephoneNumber)
                                     throws IOException

Serializes a telephone number along with its delimiter.

Parameters:

appendable - The appendable to which SURF data should be appended.

telephoneNumber - The information to be serialized as a SURF telephone number.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

IllegalArgumentException - if the given telephone number is not in global form.

See Also:

SURF.TELEPHONE_NUMBER_BEGIN, TelephoneNumber.isGlobal()

serializeTemporal

public static void serializeTemporal(@Nonnull
                                     Appendable appendable,
                                     @Nonnull
                                     TemporalAccessor temporal)
                              throws IOException

Serializes a temporal literal along with its delimiter.

Parameters:

appendable - The appendable to which SURF data should be appended.

temporal - The information to be serialized as a SURF temporal.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.TEMPORAL_BEGIN

serializeUuid

public static void serializeUuid(@Nonnull
                                 Appendable appendable,
                                 @Nonnull
                                 UUID uuid)
                          throws IOException

Serializes a UUID along with its delimiter.

Parameters:

appendable - The appendable to which SURF data should be appended.

uuid - The information to be serialized as a SURF UUID.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.UUID_BEGIN

serializeList

public void serializeList(@Nonnull
                          Appendable appendable,
                          @Nonnull
                          List<?> list)
                   throws IOException

Serializes a SURF list.

All references to the resources in the graph must have already been discovered if aliases need to be generated.

Parameters:

appendable - The appendable to which SURF data should be appended.

list - The information to be serialized as a SURF list.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.LIST_BEGIN, SURF.LIST_END

serializeMap

public void serializeMap(@Nonnull
                         Appendable appendable,
                         @Nonnull
                         Map<?,?> map)
                  throws IOException

Serializes a SURF map.

All references to the resources in the graph must have already been discovered if aliases need to be generated.

Parameters:

appendable - The appendable to which SURF data should be appended.

map - The information to be serialized as a SURF map.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.MAP_BEGIN, SURF.MAP_END, SURF.MAP_KEY_DELIMITER, SURF.ENTRY_KEY_VALUE_DELIMITER

serializeSet

public void serializeSet(@Nonnull
                         Appendable appendable,
                         @Nonnull
                         Set<?> set)
                  throws IOException

Serializes a SURF set.

All references to the resources in the graph must have already been discovered if aliases need to be generated.

Parameters:

appendable - The appendable to which SURF data should be appended.

set - The information to be serialized as a SURF set.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error appending to the appendable.

See Also:

SURF.SET_BEGIN, SURF.SET_END

serializeSequence

protected <I> void serializeSequence(@Nonnull
                                     Appendable appendable,
                                     @Nonnull
                                     Iterable<I> sequence,
                                     @Nonnull
                                     com.globalmentor.io.function.IOBiConsumer<Appendable,I> itemSerializer)
                              throws IOException

Serializes a general SURF sequence (such as a list). For each sequence item, IOBiConsumer.accept(Object, Object) is called, passing the output Appendable along with the item to be serialized. The item serialization strategy will return false to indicate that there are no further items.

Type Parameters:

I - The type of item in the sequence.

Parameters:

appendable - The appendable to which SURF data should be appended.

sequence - An iterable representing the sequence to serialize.

itemSerializer - The serialization strategy, which is passed the Appendable to use for serialization, along with each item to serialize.

Throws:

NullPointerException - if the given appendable and/or item serializer is null.

IOException - if there is an error appending to the appender.