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 final class	IBindingContext.BindingContextBuilder	Enables building a IBindingContext using common configuration options based on the builder pattern.
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	A behavioral class used by the binding context to load Metaschema modules.
static interface	IBindingContext.ISchemaValidationProvider	Provides schema validation capabilities.

Method Summary

Modifier and Type	Method	Description
static IBindingContext.BindingContextBuilder	builder()	Get a new builder that can produce a new, configured binding context.
<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.
static IConstraintLoader	getConstraintLoader()	Get a loader that supports loading Metaschema module constraints from a specified resource.
default <TYPE extends IDataTypeAdapter<?>> TYPE	getDataTypeAdapterInstance(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.
IBindingContext.IModuleLoaderStrategy	getModuleLoaderStrategy()	Get the Metaschema module loader strategy used by this binding context to load modules.
default IBindingMetaschemaModule	loadMetaschema(URL url)	Loads a Metaschema module from the specified URL.
default IBindingMetaschemaModule	loadMetaschema(Path path)	Loads a Metaschema module from the specified path.
default IBoundLoader	newBoundLoader()	Get a new IBoundLoader instance to load bound content instances.
default IConstraintLoader	newConstraintLoader()	Get a loader that supports loading Metaschema module constraints from a specified resource.
<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.
static IBindingContext	newInstance()	Get a new IBindingContext instance, which can be used to load information that binds a model to a set of Java classes.
static IBindingContext	newInstance(IBindingContext.IModuleLoaderStrategy strategy)	Get a new IBindingContext instance, which can be used to load information that binds a model to a set of Java classes.
IBindingModuleLoader	newModuleLoader()	Get a loader that supports loading a Metaschema module from a specified resource.
<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.
IBoundDefinitionModelComplex	registerClassBinding(IBoundDefinitionModelComplex definition)	Register a class binding for a given bound class.
default IBoundModule	registerModule(IModule module)	Registers the provided Metaschema module with this binding context.
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

builder

static IBindingContext.BindingContextBuilder builder()

Get a new builder that can produce a new, configured binding context.

Returns:

the builder

Since:

2.0.0

newInstance

@NonNull
static IBindingContext newInstance()

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

Returns:

a new binding context

Since:

2.0.0

newInstance

@NonNull
static IBindingContext newInstance(@NonNull
 IBindingContext.IModuleLoaderStrategy strategy)

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

Parameters:

strategy - the loader strategy to use when loading Metaschema modules

Returns:

a new binding context

Since:

2.0.0

getModuleLoaderStrategy

@NonNull
IBindingContext.IModuleLoaderStrategy getModuleLoaderStrategy()

Get the Metaschema module loader strategy used by this binding context to load modules.

Returns:

the strategy instance

Since:

2.0.0

newModuleLoader

@NonNull
IBindingModuleLoader newModuleLoader()

Get a loader that supports loading a Metaschema module from a specified resource.

Modules loaded with this loader are automatically registered with this binding context.

Use of this method requires that the binding context is initialized using a IBindingContext.IModuleLoaderStrategy that supports dynamic bound module loading. This can be accomplished using the SimpleModuleLoaderStrategy initialized using the DefaultModuleBindingGenerator. * @return the loader

Returns:

the loader

Since:

2.0.0

loadMetaschema

@NonNull
default IBindingMetaschemaModule loadMetaschema(@NonNull
 Path path)
                                         throws MetaschemaException,
IOException

Loads a Metaschema module from the specified path.

This method automatically registers the module with this binding context.

Use of this method requires that the binding context is initialized using a IBindingContext.IModuleLoaderStrategy that supports dynamic bound module loading. This can be accomplished using the SimpleModuleLoaderStrategy initialized using the DefaultModuleBindingGenerator.

Parameters:

path - the path to load the module from

Returns:

the loaded Metaschema module

Throws:

MetaschemaException - if an error occurred while processing the resource

IOException - if an error occurred parsing the resource

UnsupportedOperationException - if this binding context is not configured to support dynamic bound module loading

Since:

2.0.0

loadMetaschema

@NonNull
default IBindingMetaschemaModule loadMetaschema(@NonNull
 URL url)
                                         throws MetaschemaException,
IOException

Loads a Metaschema module from the specified URL.

This method automatically registers the module with this binding context.

Use of this method requires that the binding context is initialized using a IBindingContext.IModuleLoaderStrategy that supports dynamic bound module loading. This can be accomplished using the SimpleModuleLoaderStrategy initialized using the DefaultModuleBindingGenerator.

Parameters:

url - the URL to load the module from

Returns:

the loaded Metaschema module

Throws:

MetaschemaException - if an error occurred while processing the resource

IOException - if an error occurred parsing the resource

UnsupportedOperationException - if this binding context is not configured to support dynamic bound module loading

Since:

2.0.0

getConstraintLoader

@NonNull
static IConstraintLoader getConstraintLoader()

Get a loader that supports loading Metaschema module constraints from a specified resource.

Metaschema module constraints loaded this need to be used with a new IBindingContext instance to be applied to loaded modules. The new binding context must initialized using the PostProcessingModuleLoaderStrategy that is initialized with a ExternalConstraintsModulePostProcessor instance.

Returns:

the loader

Since:

2.0.0

newConstraintLoader

@NonNull
default IConstraintLoader newConstraintLoader()

Get a loader that supports loading Metaschema module constraints from a specified resource.

Metaschema module constraints loaded this need to be used with a new IBindingContext instance to be applied to loaded modules. The new binding context must initialized using the PostProcessingModuleLoaderStrategy that is initialized with a ExternalConstraintsModulePostProcessor instance.

Returns:

the loader

Since:

2.0.0

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
default IBoundModule registerModule(@NonNull
 IModule module)

Registers the provided Metaschema module with this binding context.

If the provided instance is not an instance of IBoundModule, then annotated Java classes for this module will be generated, compiled, and loaded based on the provided Module.

Parameters:

module - the Module module to generate classes for

Returns:

the registered module, which may be a different instance than what was provided if dynamic compilation was performed

Throws:

UnsupportedOperationException - if this binding context is not configured to support dynamic bound module loading and the module instance is not a subclass of IBoundModule

Since:

2.0.0

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

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

getDataTypeAdapterInstance

@Nullable
default <TYPE extends IDataTypeAdapter<?>> TYPE getDataTypeAdapterInstance(@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

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
default IBoundLoader newBoundLoader()

Get a new IBoundLoader instance to load bound content instances.

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