Module gov.nist.secauto.metaschema.core

Package gov.nist.secauto.metaschema.core.datatype

Interface IDataTypeAdapter<TYPE>

All Known Implementing Classes:

AbstractCustomJavaDataTypeAdapter, AbstractDataTypeAdapter, AbstractIntegerAdapter, AbstractMarkupAdapter, AbstractStringAdapter, Base64Adapter, BooleanAdapter, DateAdapter, DateTimeAdapter, DateTimeWithTZAdapter, DateWithTZAdapter, DayTimeAdapter, DecimalAdapter, EmailAddressAdapter, HostnameAdapter, IntegerAdapter, IPv4AddressAdapter, IPv6AddressAdapter, MarkupLineAdapter, MarkupMultilineAdapter, NcNameAdapter, NonNegativeIntegerAdapter, PositiveIntegerAdapter, StringAdapter, TokenAdapter, UriAdapter, UriReferenceAdapter, UuidAdapter, YearMonthAdapter

public interface IDataTypeAdapter<TYPE>

Method Summary

Modifier and Type	Method	Description
String	asString(Object value)	Gets the value as a string suitable for writing as text.
boolean	canHandleQName(QName nextElementQName)	Determines if adapter can parse the next element.
IAnyAtomicItem	cast(IAnyAtomicItem item)	Cast the provided item to an item of this type, if possible.
TYPE	copy(Object obj)	Create a copy of the provided value.
String	getDefaultJsonValueKey()	Gets the default value to use as the JSON/YAML field name for a Metaschema field value if no JSON value key flag or name is configured.
Class<? extends IAnyAtomicItem>	getItemClass()	Get the java type of the associated item.
Class<TYPE>	getJavaClass()	Get the Java class supported by this adapter.
com.fasterxml.jackson.databind.jsonFormatVisitors.JsonFormatTypes	getJsonRawType()	The JSON primative type of the data type.
List<String>	getNames()	Get the metaschema type names associated with this adapter.
default String	getPreferredName()	Get the most preferred name for this data type.
default boolean	isAtomic()	Determines if the data type is an atomic, scalar value.
boolean	isParsingStartElement()	Indicates if the adapter will parse the XMLStreamConstants.START_ELEMENT before parsing the value data.
boolean	isUnrappedValueAllowedInXml()	Determines if the data type's value is allowed to be unwrapped in XML when the value is a field value.
boolean	isXmlMixed()	Determines if the datatype uses mixed text and element content in XML.
IAnyAtomicItem	newItem(Object value)	Construct a new item of this type using the provided value.
TYPE	parse(com.fasterxml.jackson.core.JsonParser parser)	Parses a JSON property value.
TYPE	parse(String value)	Parses a provided string.
TYPE	parse(org.codehaus.stax2.XMLEventReader2 eventReader)	This method is expected to parse content starting at the next event.
default Supplier<TYPE>	parseAndSupply(com.fasterxml.jackson.core.JsonParser parser)	Parses a provided string using parse(JsonParser).
default Supplier<TYPE>	parseAndSupply(String value)	Parses a provided string using parse(String).
default Supplier<TYPE>	parseAndSupply(org.codehaus.stax2.XMLEventReader2 eventReader)	Parses a provided string using parse(XMLEventReader2).
TYPE	toValue(Object value)	Casts the provided value to the type associated with this adapter.
void	writeJsonValue(Object instance, com.fasterxml.jackson.core.JsonGenerator writer)	Writes the provided Java class instance as a JSON/YAML field value.
void	writeXmlValue(Object instance, QName parentName, org.codehaus.stax2.XMLStreamWriter2 writer)	Writes the provided Java class instance data as XML.
void	writeXmlValue(Object instance, StartElement parent, org.codehaus.stax2.evt.XMLEventFactory2 eventFactory, XMLEventWriter eventWriter)	Writes the provided Java class instance data as XML.

Method Detail

getNames

@NonNull
List<String> getNames()

Get the metaschema type names associated with this adapter. This name must be unique with respect to all other metaschema types.

At least one name must be provided, with the first name being the most preferred name.

Returns:

the name

getJsonRawType

com.fasterxml.jackson.databind.jsonFormatVisitors.JsonFormatTypes getJsonRawType()

The JSON primative type of the data type.

Returns:

the JSON data type

getPreferredName

@NonNull
default String getPreferredName()

Get the most preferred name for this data type.

Returns:

the name

getJavaClass

@NonNull
Class<TYPE> getJavaClass()

Get the Java class supported by this adapter.

Returns:

the Java class

toValue

@NonNull
TYPE toValue(@NonNull
             Object value)

Casts the provided value to the type associated with this adapter.

Parameters:

value - a value of the provided type

Returns:

the typed value

asString

@NonNull
String asString(@NonNull
                Object value)

Gets the value as a string suitable for writing as text. This is intended for data types that have a simple string-based structure in XML and JSON, such as for XML attributes or JSON keys. An adapter for a complex data structures that consist of XML elements will throw an UnsupportedOperationException when this is called.

Parameters:

value - the data to formatted as a string

Returns:

a string

Throws:

UnsupportedOperationException - if the data type cannot be represented as a string

copy

@NonNull
TYPE copy(@NonNull
          Object obj)

Create a copy of the provided value.

Parameters:

obj - the value to copy

Returns:

the copy

isAtomic

default boolean isAtomic()

Determines if the data type is an atomic, scalar value. Complex structures such as Markup are not considered atomic.

Returns:

true if the data type is an atomic scalar value, or false otherwise

getItemClass

@NonNull
Class<? extends IAnyAtomicItem> getItemClass()

Get the java type of the associated item.

Returns:

the java associated item type

newItem

@NonNull
IAnyAtomicItem newItem(@NonNull
                       Object value)

Construct a new item of this type using the provided value.

Parameters:

value - the item's value

Returns:

a new item

cast

@NonNull
IAnyAtomicItem cast(IAnyAtomicItem item)

Cast the provided item to an item of this type, if possible.

Parameters:

item - the atomic item to cast

Returns:

an atomic item of this type

Throws:

InvalidValueForCastFunctionException - if the provided item type cannot be cast to this item type

isParsingStartElement

boolean isParsingStartElement()

Indicates if the adapter will parse the XMLStreamConstants.START_ELEMENT before parsing the value data.

Returns:

true if the adapter requires the start element for parsing, or false otherwise

canHandleQName

boolean canHandleQName(@NonNull
                       QName nextElementQName)

Determines if adapter can parse the next element. The next element's QName is provided for this purpose.

This will be called when the parser encounter's an element it does not recognize. This gives the adapter a chance to request parsing of the data.

Parameters:

nextElementQName - the next element's namespace-qualified name

Returns:

true if the adapter will parse the element, or false otherwise

parse

@NonNull
TYPE parse(@NonNull
           String value)

Parses a provided string. Used to parse XML attributes, simple XML character data, and JSON/YAML property values.

Parameters:

value - the string value to parse

Returns:

the parsed data as the adapter's type

Throws:

IllegalArgumentException - if the data is not valid to the data type

parse

@NonNull
TYPE parse(@NonNull
           org.codehaus.stax2.XMLEventReader2 eventReader)
    throws IOException

This method is expected to parse content starting at the next event. Parsing will continue until the next event represents content that is not handled by this adapter. This means the event stream should be positioned after any XMLStreamConstants.END_ELEMENT that corresponds to an XMLStreamConstants.START_ELEMENT parsed by this adapter.

If isParsingStartElement() returns true, then the first event to parse will be the XMLStreamConstants.START_ELEMENT for the element that contains the value data, then the value data. If this is the case, this method must also parse the corresponding XMLStreamConstants.END_ELEMENT. Otherwise, the first event to parse will be the value data.

The value data is expected to be parsed completely, leaving the event stream on a peeked event corresponding to content that is not handled by this method.

Parameters:

eventReader - the XML parser used to read the parsed value

Returns:

the parsed value

Throws:

IOException - if a parsing error occurs

parse

@NonNull
TYPE parse(@NonNull
           com.fasterxml.jackson.core.JsonParser parser)
    throws IOException

Parses a JSON property value.

Parameters:

parser - the JSON parser used to read the parsed value

Returns:

the parsed value

Throws:

IOException - if a parsing error occurs

parseAndSupply

@NonNull
default Supplier<TYPE> parseAndSupply(@NonNull
                                      String value)
                               throws IOException

Parses a provided string using parse(String).

This method may pre-parse the data and then return copies, since the data can only be parsed once, but the supplier might be called multiple times.

Parameters:

value - the string value to parse

Returns:

a supplier that will provide new instances of the parsed data

Throws:

IOException - if an error occurs while parsing

See Also:

parse(String)

parseAndSupply

@NonNull
default Supplier<TYPE> parseAndSupply(@NonNull
                                      org.codehaus.stax2.XMLEventReader2 eventReader)
                               throws IOException

Parses a provided string using parse(XMLEventReader2).

This method may pre-parse the data and then return copies, since the data can only be parsed once, but the supplier might be called multiple times.

Parameters:

eventReader - the XML parser used to read the parsed value

Returns:

a supplier that will provide new instances of the parsed data

Throws:

IOException - if an error occurs while parsing

See Also:

parse(String), parse(XMLEventReader2)

parseAndSupply

@NonNull
default Supplier<TYPE> parseAndSupply(@NonNull
                                      com.fasterxml.jackson.core.JsonParser parser)
                               throws IOException

Parses a provided string using parse(JsonParser).

This method may pre-parse the data and then return copies, since the data can only be parsed once, but the supplier might be called multiple times.

Parameters:

parser - the JSON parser used to read the parsed value

Returns:

a supplier that will provide new instances of the parsed data

Throws:

IOException - if an error occurs while parsing

See Also:

parse(String), parse(JsonParser)

writeXmlValue

void writeXmlValue(@NonNull
                   Object instance,
                   @NonNull
                   StartElement parent,
                   @NonNull
                   org.codehaus.stax2.evt.XMLEventFactory2 eventFactory,
                   @NonNull
                   XMLEventWriter eventWriter)
            throws IOException,
                   XMLStreamException

Writes the provided Java class instance data as XML. The parent element information is provided as a StartElement event, which allows namespace information to be obtained from the parent element using the StartElement.getName() and StartElement.getNamespaceContext() methods, which can be used when writing the provided instance value.

Parameters:

instance - the Field instance value to write

parent - the StartElement XML event that is the parent of the data to write

eventFactory - the XML event factory used to generate XML writing events

eventWriter - the XML writer used to output XML as events

Throws:

XMLStreamException - if an unexpected error occurred while processing the XML output

IOException - if an unexpected error occurred while writing to the output stream

writeXmlValue

void writeXmlValue(@NonNull
                   Object instance,
                   @NonNull
                   QName parentName,
                   @NonNull
                   org.codehaus.stax2.XMLStreamWriter2 writer)
            throws XMLStreamException

Writes the provided Java class instance data as XML. The parent element information is provided as an XML QName, which allows namespace information to be obtained from the parent element. Additional namespace information can be gathered using the XMLStreamWriter.getNamespaceContext() method, which can be used when writing the provided instance value.

Parameters:

instance - the Field instance value to write

parentName - the qualified name of the XML data's parent element

writer - the XML writer used to output the XML data

Throws:

XMLStreamException - if an unexpected error occurred while processing the XML output

writeJsonValue

void writeJsonValue(@NonNull
                    Object instance,
                    @NonNull
                    com.fasterxml.jackson.core.JsonGenerator writer)
             throws IOException

Writes the provided Java class instance as a JSON/YAML field value.

Parameters:

instance - the Field instance value to write

writer - the JSON/YAML writer used to output the JSON/YAML data

Throws:

IOException - if an unexpected error occurred while writing the JSON/YAML output

getDefaultJsonValueKey

@NonNull
String getDefaultJsonValueKey()

Gets the default value to use as the JSON/YAML field name for a Metaschema field value if no JSON value key flag or name is configured.

Returns:

the default field name to use

isUnrappedValueAllowedInXml

boolean isUnrappedValueAllowedInXml()

Determines if the data type's value is allowed to be unwrapped in XML when the value is a field value.

Returns:

true if allowed, or false otherwise.

isXmlMixed

boolean isXmlMixed()

Determines if the datatype uses mixed text and element content in XML.

Returns:

true if the datatype uses mixed text and element content in XML, or false otherwise