Module dev.metaschema.databind
Package dev.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.

  • 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) throws MetaschemaException
      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
      Throws:
      MetaschemaException - if an error occurred while registering the module

    • registerModule

      @NonNull default IBoundModule registerModule(@NonNull IModule module) throws MetaschemaException
      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:
      MetaschemaException - if an error occurred while registering the module
      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:

    • 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:

    • newBoundLoader

      @NonNull default IBoundLoader newBoundLoader()
      Get a new IBoundLoader instance to load bound content instances.
      Returns:
      the instance

    • newPermissiveBoundLoader

      @NonNull default IBoundLoader newPermissiveBoundLoader()
      Get a new IBoundLoader instance configured for permissive loading.

      This loader has DeserializationFeature.DESERIALIZE_VALIDATE_REQUIRED_FIELDS disabled, making it suitable for use with Metapath functions like fn:doc() where documents may be incomplete or under construction.

      Use this method when setting up a DynamicContext for Metapath evaluation to ensure that referenced documents can be loaded without strict required field validation.

      Returns:
      a permissive loader 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

      @NonNull @Owning default @Owning IConstraintValidator newValidator(@NonNull IConstraintValidationHandler handler, @Nullable IConfiguration<ValidationFeature<?>> config)
      Get a new single use constraint validator.

      The caller owns the returned validator and is responsible for closing it to release any resources (such as thread pools) when validation is complete.

      Example usage: 

      
 try (IConstraintValidator validator = context.newValidator(handler, config)) {
   validator.validate(item, documentUri);
   validator.finalizeValidation();
 }

      The @SuppressWarnings("resource") annotation on this method is intentional: ownership transfers to the caller who must close the 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) throws ConstraintValidationException
      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:
      ConstraintValidationException - if a constraint violation prevents validation from completing
      IllegalArgumentException - if the node item is not valid for validation

    • validate

      default IValidationResult validate(@NonNull IDefinitionNodeItem<?,?> nodeItem, @NonNull IBoundLoader loader, @Nullable IConfiguration<ValidationFeature<?>> config) throws ConstraintValidationException
      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:
      ConstraintValidationException - if a constraint violation prevents validation from completing
      IllegalArgumentException - if the node item is not valid for validation

    • validate

      default IValidationResult validate(@NonNull URI target, @NonNull Format asFormat, @NonNull IBindingContext.ISchemaValidationProvider schemaProvider, @Nullable IConfiguration<ValidationFeature<?>> config) throws IOException, ConstraintValidationException
      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
      ConstraintValidationException - if a constraint violation prevents validation from completing

    • validateWithConstraints

      default IValidationResult validateWithConstraints(@NonNull URI target, @Nullable IConfiguration<ValidationFeature<?>> config) throws IOException, ConstraintValidationException
      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
      ConstraintValidationException - if a constraint violation prevents validation from completing