Module gov.nist.secauto.metaschema.databind

Package gov.nist.secauto.metaschema.databind

Interface IBindingContext

All Known Implementing Classes:

DefaultBindingContext

public interface IBindingContext

Provides information supporting a binding between a set of Module models and corresponding Java classes.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	IBindingContext.IBindingMatcher	Implementations of this interface provide a means by which a bound class can be found that corresponds to an XML element, JSON property, or YAML item name.
static interface	IBindingContext.IModuleLoaderStrategy
static interface	IBindingContext.ISchemaValidationProvider

Method Summary

Modifier and Type	Method	Description
<CLASS extends IBoundObject> CLASS	deepCopy(CLASS other, IBoundObject parentInstance)	Create a deep copy of the provided bound object.
Class<? extends IBoundObject>	getBoundClassForRootJsonName(String rootName)	Determine the bound class for the provided JSON/YAML property/item name using any registered matchers.
Class<? extends IBoundObject>	getBoundClassForRootXmlQName(QName rootQName)	Determine the bound class for the provided XML QName.
IBoundDefinitionModelComplex	getBoundDefinitionForClass(Class<? extends IBoundObject> clazz)	Get the IBoundDefinitionModel instance associated with the provided Java class.
<TYPE extends IDataTypeAdapter<?>> TYPE	getJavaTypeAdapterInstance(Class<TYPE> clazz)	Get's the IDataTypeAdapter associated with the specified Java class, which is used to read and write XML, JSON, and YAML data to and from instances of that class.
static IBindingContext	instance()	Get the singleton IBindingContext instance, which can be used to load information that binds a model to a set of Java classes.
IBoundLoader	newBoundLoader()	Get a new IBoundLoader instance.
<CLASS extends IBoundObject> IDeserializer<CLASS>	newDeserializer(Format format, Class<CLASS> clazz)	Gets a data IDeserializer which can be used to read Java instance data for the provided class from the requested format.
<CLASS extends IBoundObject> ISerializer<CLASS>	newSerializer(Format format, Class<CLASS> clazz)	Gets a data ISerializer which can be used to write Java instance data for the provided class in the requested format.
default IConstraintValidator	newValidator(IConstraintValidationHandler handler, IConfiguration<ValidationFeature<?>> config)	Get a new single use constraint validator.
IBindingContext.IBindingMatcher	registerBindingMatcher(IBoundDefinitionModelAssembly definition)	Register a matcher used to identify a bound class by the definition's root name.
IBindingContext.IBindingMatcher	registerBindingMatcher(Class<? extends IBoundObject> clazz)	Register a matcher used to identify a bound class by the definition's root name.
IBoundDefinitionModelComplex	registerClassBinding(IBoundDefinitionModelComplex definition)	Register a class binding for a given bound class.
IBindingContext	registerModule(IModule module, Path compilePath)	Generate, compile, and load a set of generated Module annotated Java classes based on the provided Module module.
IBoundModule	registerModule(Class<? extends IBoundModule> clazz)	Load a bound Metaschema module implemented by the provided class.
default IValidationResult	validate(IDefinitionNodeItem<?,?> nodeItem, IBoundLoader loader, IConfiguration<ValidationFeature<?>> config)	Perform constraint validation on the provided bound object represented as an IDefinitionNodeItem.
default IValidationResult	validate(IDocumentNodeItem nodeItem, IBoundLoader loader, IConfiguration<ValidationFeature<?>> config)	Perform constraint validation on the provided bound object represented as an IDocumentNodeItem.
default IValidationResult	validate(URI target, Format asFormat, IBindingContext.ISchemaValidationProvider schemaProvider, IConfiguration<ValidationFeature<?>> config)	Load and perform schema and constraint validation on the target.
default IValidationResult	validateWithConstraints(URI target, IConfiguration<ValidationFeature<?>> config)	Load and validate the provided target using the associated Module module constraints.

Method Details

instance

@NonNull
static IBindingContext instance()

Get the singleton IBindingContext instance, which can be used to load information that binds a model to a set of Java classes.

Returns:

a new binding context

registerBindingMatcher

@NonNull
IBindingContext.IBindingMatcher registerBindingMatcher(@NonNull
 IBoundDefinitionModelAssembly definition)

Register a matcher used to identify a bound class by the definition's root name.

Parameters:

definition - the definition to match for

Returns:

the matcher

registerBindingMatcher

@NonNull
IBindingContext.IBindingMatcher registerBindingMatcher(@NonNull
 Class<? extends IBoundObject> clazz)

Register a matcher used to identify a bound class by the definition's root name.

Parameters:

clazz - the definition class to match for, which must represent a root assembly definition

Returns:

the matcher

registerClassBinding

@Nullable
IBoundDefinitionModelComplex registerClassBinding(@NonNull
 IBoundDefinitionModelComplex definition)

Register a class binding for a given bound class.

Parameters:

definition - the bound class information to register

Returns:

the old bound class information or null if no binding existed for the associated class

getBoundDefinitionForClass

@Nullable
IBoundDefinitionModelComplex getBoundDefinitionForClass(@NonNull
 Class<? extends IBoundObject> clazz)

Get the IBoundDefinitionModel instance associated with the provided Java class.

Typically the class will have a MetaschemaAssembly or MetaschemaField annotation.

Parameters:

clazz - the class binding to load

Returns:

the associated class binding instance or null if the class is not bound

getBoundClassForRootXmlQName

@Nullable
Class<? extends IBoundObject> getBoundClassForRootXmlQName(@NonNull
 QName rootQName)

Determine the bound class for the provided XML QName.

Parameters:

rootQName - the root XML element's QName

Returns:

the bound class or null if not recognized

See Also:

• registerBindingMatcher(Class)

getBoundClassForRootJsonName

@Nullable
Class<? extends IBoundObject> getBoundClassForRootJsonName(@NonNull
 String rootName)

Determine the bound class for the provided JSON/YAML property/item name using any registered matchers.

Parameters:

rootName - the JSON/YAML property/item name

Returns:

the bound class or null if not recognized

See Also:

• registerBindingMatcher(Class)

getJavaTypeAdapterInstance

@Nullable
<TYPE extends IDataTypeAdapter<?>> TYPE getJavaTypeAdapterInstance(@NonNull
 Class<TYPE> clazz)

Get's the IDataTypeAdapter associated with the specified Java class, which is used to read and write XML, JSON, and YAML data to and from instances of that class. Thus, this adapter supports a direct binding between the Java class and structured data in one of the supported formats. Adapters are used to support bindings for simple data objects (e.g., String, BigInteger, ZonedDateTime, etc).

Type Parameters:

TYPE - the class type of the adapter

Parameters:

clazz - the Java Class for the bound type

Returns:

the adapter instance or null if the provided class is not bound

registerModule

@NonNull
IBoundModule registerModule(@NonNull
 Class<? extends IBoundModule> clazz)

Load a bound Metaschema module implemented by the provided class.

Also registers any associated bound classes.

Implementations are expected to return the same IModule instance for multiple calls to this method with the same class argument.

Parameters:

clazz - the class implementing a bound Metaschema module

Returns:

the loaded module

registerModule

@NonNull
IBindingContext registerModule(@NonNull
 IModule module,
 @NonNull
 Path compilePath)
                        throws IOException

Generate, compile, and load a set of generated Module annotated Java classes based on the provided Module module.

Parameters:

module - the Module module to generate classes for

compilePath - the path to the directory to generate classes in

Returns:

this instance

Throws:

IOException - if an error occurred while generating or loading the classes

newSerializer

@NonNull
<CLASS extends IBoundObject> ISerializer<CLASS> newSerializer(@NonNull
 Format format,
 @NonNull
 Class<CLASS> clazz)

Gets a data ISerializer which can be used to write Java instance data for the provided class in the requested format.

The provided class must be a bound Java class with a MetaschemaAssembly or MetaschemaField annotation for which a IBoundDefinitionModel exists.

Type Parameters:

CLASS - the Java type this serializer can write data from

Parameters:

format - the format to serialize into

clazz - the Java data object to serialize

Returns:

the serializer instance

Throws:

NullPointerException - if any of the provided arguments, except the configuration, are null

IllegalArgumentException - if the provided class is not bound to a Module assembly or field

UnsupportedOperationException - if the requested format is not supported by the implementation

See Also:

• getBoundDefinitionForClass(Class)

newDeserializer

@NonNull
<CLASS extends IBoundObject> IDeserializer<CLASS> newDeserializer(@NonNull
 Format format,
 @NonNull
 Class<CLASS> clazz)

Gets a data IDeserializer which can be used to read Java instance data for the provided class from the requested format.

The provided class must be a bound Java class with a MetaschemaAssembly or MetaschemaField annotation for which a IBoundDefinitionModel exists.

Type Parameters:

CLASS - the Java type this deserializer can read data into

Parameters:

format - the format to serialize into

clazz - the Java data type to serialize

Returns:

the deserializer instance

Throws:

NullPointerException - if any of the provided arguments, except the configuration, are null

IllegalArgumentException - if the provided class is not bound to a Module assembly or field

UnsupportedOperationException - if the requested format is not supported by the implementation

See Also:

• getBoundDefinitionForClass(Class)

newBoundLoader

@NonNull
IBoundLoader newBoundLoader()

Get a new IBoundLoader instance.

Returns:

the instance

deepCopy

@NonNull
<CLASS extends IBoundObject> CLASS deepCopy(@NonNull
 CLASS other,
 IBoundObject parentInstance)
                                     throws BindingException

Create a deep copy of the provided bound object.

Type Parameters:

CLASS - the bound object type

Parameters:

other - the object to copy

parentInstance - the object's parent or null

Returns:

a deep copy of the provided object

Throws:

BindingException - if an error occurred copying content between java instances

NullPointerException - if the provided object is null

IllegalArgumentException - if the provided class is not bound to a Module assembly or field

newValidator

default IConstraintValidator newValidator(@NonNull
 IConstraintValidationHandler handler,
 @Nullable
 IConfiguration<ValidationFeature<?>> config)

Get a new single use constraint validator.

Parameters:

handler - the validation handler to use to process the validation results

config - the validation configuration

Returns:

the validator

validate

default IValidationResult validate(@NonNull
 IDocumentNodeItem nodeItem,
 @NonNull
 IBoundLoader loader,
 @Nullable
 IConfiguration<ValidationFeature<?>> config)

Perform constraint validation on the provided bound object represented as an IDocumentNodeItem.

Parameters:

nodeItem - the node item to validate

loader - a module loader used to load and resolve referenced resources

config - the validation configuration

Returns:

the validation result

Throws:

IllegalArgumentException - if the provided class is not bound to a Module assembly or field

validate

default IValidationResult validate(@NonNull
 IDefinitionNodeItem<?,?> nodeItem,
 @NonNull
 IBoundLoader loader,
 @Nullable
 IConfiguration<ValidationFeature<?>> config)

Perform constraint validation on the provided bound object represented as an IDefinitionNodeItem.

Parameters:

nodeItem - the node item to validate

loader - a module loader used to load and resolve referenced resources

config - the validation configuration

Returns:

the validation result

Throws:

IllegalArgumentException - if the provided class is not bound to a Module assembly or field

validate

default IValidationResult validate(@NonNull
 URI target,
 @NonNull
 Format asFormat,
 @NonNull
 IBindingContext.ISchemaValidationProvider schemaProvider,
 @Nullable
 IConfiguration<ValidationFeature<?>> config)
                            throws IOException

Load and perform schema and constraint validation on the target. The constraint validation will only be performed if the schema validation passes.

Parameters:

target - the target to validate

asFormat - the schema format to use to validate the target

schemaProvider - provides callbacks to get the appropriate schemas

config - the validation configuration

Returns:

the validation result

Throws:

IOException - if an error occurred while reading the target

validateWithConstraints

default IValidationResult validateWithConstraints(@NonNull
 URI target,
 @Nullable
 IConfiguration<ValidationFeature<?>> config)
                                           throws IOException

Load and validate the provided target using the associated Module module constraints.

Parameters:

target - the file to load and validate

config - the validation configuration

Returns:

the validation results

Throws:

IOException - if an error occurred while parsing the target