Class MetadataSources

  • All Implemented Interfaces:
    Serializable

    public class MetadataSources
    extends Object
    implements Serializable
    Entry point for working with sources of O/R mapping metadata, either in the form of annotated classes, or as XML mapping documents.

    Note that XML mappings may be expressed using the JPA orm.xml format, or in Hibernate's legacy .hbm.xml format.

    An instance of MetadataSources may be obtained simply by instantiation, using new MetadataSources(). The client must register sources and then call buildMetadata(), or use getMetadataBuilder() to customize how the sources are processed (by registering naming strategies, etc).

    As an alternative to working directly with MetadataSources, and Metadata, a program may use Configuration.

    Since:
    5.0
    See Also:
    Serialized Form
    • Constructor Detail

      • MetadataSources

        public MetadataSources​(ServiceRegistry serviceRegistry)
        Create a new instance using the given ServiceRegistry.
        Parameters:
        serviceRegistry - The service registry to use.
      • MetadataSources

        public MetadataSources​(ServiceRegistry serviceRegistry,
                               boolean disableXmlMappingBinders)
        Consider this an SPI, used by Quarkus
    • Method Detail

      • isExpectedServiceRegistryType

        protected static boolean isExpectedServiceRegistryType​(ServiceRegistry serviceRegistry)
      • getXmlBindings

        public List<Binding<?>> getXmlBindings()
      • getExtraQueryImports

        public Map<String,​Class<?>> getExtraQueryImports()
      • getMetadataBuilder

        public MetadataBuilder getMetadataBuilder()
        Get a builder for metadata where non-default options can be specified.
        Returns:
        The built metadata.
      • getMetadataBuilder

        public MetadataBuilder getMetadataBuilder​(StandardServiceRegistry serviceRegistry)
        Get a builder for metadata where non-default options can be specified.
        Returns:
        The built metadata.
      • addAnnotatedClass

        public MetadataSources addAnnotatedClass​(Class<?> annotatedClass)
        Read metadata from the annotations attached to the given class.
        Parameters:
        annotatedClass - The class containing annotations
        Returns:
        this (for method chaining)
      • addAnnotatedClassName

        public MetadataSources addAnnotatedClassName​(String annotatedClassName)
        Read metadata from the annotations attached to the given class. The important distinction here is that the Class will not be accessed until later, which is important for on-the-fly bytecode enhancement
        Parameters:
        annotatedClassName - The name of a class containing annotations
        Returns:
        this (for method chaining)
      • addPackage

        public MetadataSources addPackage​(String packageName)
        Read package-level metadata.
        Parameters:
        packageName - java package name without trailing '.', cannot be null
        Returns:
        this (for method chaining)
      • addPackage

        public MetadataSources addPackage​(Package packageRef)
        Read package-level metadata.
        Parameters:
        packageRef - Java Package reference
        Returns:
        this (for method chaining)
      • addResource

        public MetadataSources addResource​(String name)
        Read mappings as an application resourceName (i.e. classpath lookup).
        Parameters:
        name - The resource name
        Returns:
        this (for method chaining purposes)
      • addFile

        public MetadataSources addFile​(String path)
        Read mappings from a particular XML file.

        The given path is resolved using File(String).

        Parameters:
        path - The path to a file
        Returns:
        this (for method chaining purposes)
        See Also:
        addFile(File)
      • addFile

        public MetadataSources addFile​(File file)
        Read mappings from a particular XML file.
        Parameters:
        file - The reference to the XML file
        Returns:
        this (for method chaining purposes)
      • addXmlBinding

        public MetadataSources addXmlBinding​(Binding<?> binding)
        Add XML mapping bindings created from an arbitrary source by the binder.
        Parameters:
        binding - The binding
        Returns:
        this (for method chaining purposes)
      • addCacheableFile

        public MetadataSources addCacheableFile​(File file)
        Add a cached mapping file. A cached file is a serialized representation of the DOM structure of a particular mapping. It is saved from a previous call as a file with the name {xmlFile}.bin where {xmlFile} is the name of the original mapping file.

        If a cached {xmlFile}.bin exists and is newer than {xmlFile}, the {xmlFile}.bin file will be read directly. Otherwise {xmlFile} is read and then serialized to {xmlFile}.bin for use the next time.
        Parameters:
        file - The cacheable mapping file to be added, {xmlFile} in above discussion.
        Returns:
        this (for method chaining purposes)
      • addCacheableFile

        public MetadataSources addCacheableFile​(File file,
                                                File cacheDirectory)
        Add a cached mapping file. A cached file is a serialized representation of the DOM structure of a particular mapping. It is saved from a previous call as a file with the name {xmlFile}.bin where {xmlFile} is the name of the original mapping file.

        If a cached {xmlFile}.bin exists and is newer than {xmlFile}, the {xmlFile}.bin file will be read directly. Otherwise {xmlFile} is read and then serialized to {xmlFile}.bin for use the next time.
        Parameters:
        file - The cacheable mapping file to be added, {xmlFile} in above discussion.
        Returns:
        this (for method chaining purposes)
      • addCacheableFileStrictly

        public MetadataSources addCacheableFileStrictly​(File file)
                                                 throws SerializationException
        INTENDED FOR TESTSUITE USE ONLY!

        Much like addCacheableFile(File) except that here we will fail immediately if the cache version cannot be found or used for whatever reason.

        Parameters:
        file - The xml file, not the bin!
        Returns:
        The dom "deserialized" from the cached file.
        Throws:
        SerializationException - Indicates a problem deserializing the cached dom tree
        MappingNotFoundException - Indicates that the cached file was not found or was not usable.
      • addCacheableFileStrictly

        public MetadataSources addCacheableFileStrictly​(File file,
                                                        File cacheDir)
                                                 throws SerializationException
        INTENDED FOR TESTSUITE USE ONLY!

        Much like addCacheableFile(File) except that here we will fail immediately if the cache version cannot be found or used for whatever reason.

        Parameters:
        file - The xml file, not the bin!
        Returns:
        The dom "deserialized" from the cached file.
        Throws:
        SerializationException - Indicates a problem deserializing the cached dom tree
        MappingNotFoundException - Indicates that the cached file was not found or was not usable.
      • addInputStream

        public MetadataSources addInputStream​(InputStreamAccess xmlInputStreamAccess)
        Read metadata from an InputStream access
        Parameters:
        xmlInputStreamAccess - Access to an input stream containing a DOM.
        Returns:
        this (for method chaining purposes)
      • addInputStream

        public MetadataSources addInputStream​(InputStream xmlInputStream)
        Read metadata from an InputStream.
        Parameters:
        xmlInputStream - The input stream containing a DOM.
        Returns:
        this (for method chaining purposes)
      • addURL

        public MetadataSources addURL​(URL url)
        Read mappings from a URL
        Parameters:
        url - The url for the mapping document to be read.
        Returns:
        this (for method chaining purposes)
      • addJar

        public MetadataSources addJar​(File jar)
        Read all .hbm.xml mappings from a jar file.

        Assumes that any file named *.hbm.xml is a mapping document. This method does not support orm.xml files!

        Parameters:
        jar - a jar file
        Returns:
        this (for method chaining purposes)
      • addDirectory

        public MetadataSources addDirectory​(File dir)
        Read all .hbm.xml mapping documents from a directory tree.

        Assumes that any file named *.hbm.xml is a mapping document. This method does not support orm.xml files!

        Parameters:
        dir - The directory
        Returns:
        this (for method chaining purposes)
        Throws:
        MappingException - Indicates problems reading the jar file or processing the contained mapping documents.