Package org.apache.jena.ontology

Class OntDocumentManager

  • public class OntDocumentManager
extends java.lang.Object

    Provides services for managing ontology documents, including loading imported documents, and locally caching documents from resolvable URL's to improve load performance. This class now delegates some of the responsibility for resolving URI's and caching models to FileManager. By default, OntDocumentManager will use a copy of the singleton global FileManager. Alternatively, a specific FileManager can be given to a document manager instance to use when resolving URI's and file paths. Note that the default behaviour is to hold a copy of the global file manager. In order to ensure that the document manager directly uses the global file manager (e.g. so that document manager sees updates to the location mappings held by the file manager), use the setFileManager(FileManager) method. For example: 

    OntDocumentManager dm = OntDocumentManager.getInstance();
 dm.setFileManager( FileManager.get() );

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Property ALT_URL
      Represents the alternative local copy of the public ontology; assumed to be resolvable, hence URL not URI
      static java.lang.String ANCHOR
      The anchor char is added to the end of namespace prefix expansions
      static Property CACHE_MODELS
      Defines boolean policy choice of caching loaded models
      static java.lang.String DEFAULT_METADATA_PATH
      The default path for searching for the metadata on locally cached ontologies
      static Resource DOC_MGR_POLICY
      rdf:type for document manager policy nodes
      static Property IGNORE_IMPORT
      Specifies the URI of an ontology that we do not want to import, even if processImports is true.
      static Property LANGUAGE
      Represents the ontology language used to encode the ontology
      static java.lang.String NS
      Namespace for ontology metadata resources and properties
      static Resource ONTOLOGY_SPEC
      rdf:type for ontology specification nodes in meta-data file
      static Property PREFIX
      Represents the standard prefix for this namespace
      static Property PROCESS_IMPORTS
      Defines boolean policy choice of loading the imports closure
      static Property PUBLIC_URI
      Represents the public URI of an ontology; also used to derive the namespace
      static Property USE_DECLARED_NS_PREFIXES
      The policy property for including the pre-declared namespace prefixes in a model.

    • Constructor Summary

      Constructors 
      Constructor Description
      OntDocumentManager()
      Initialise a document manager by searching the default path for ontology metadata about known ontologies cached locally.
      OntDocumentManager​(java.lang.String path)
      Initialise a document manager by searching the given path for ontology metadata about known ontologies cached locally.
      OntDocumentManager​(Model config)
      Initialise a document manager with the given configuration model.
      OntDocumentManager​(FileManager fileMgr, java.lang.String path)
      Initialise a document manager by with the given FileManager, and then searching the given path for ontology metadata about known ontologies cached locally.
      OntDocumentManager​(FileManager fileMgr, Model config)
      Initialise a document manager with the given configuration model.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addAltEntry​(java.lang.String docURI, java.lang.String locationURL)
      Add an entry for an alternative copy of the document with the given document URI.
      void addIgnoreImport​(java.lang.String uri)
      Add the given URI to the set of URI's we ignore in imports statements
      void addModel​(java.lang.String docURI, Model model)
      Add an entry that model is the appropriate model to use for the given ontology document.
      void addModel​(java.lang.String docURI, Model model, boolean replace)
      Add an entry that model is the appropriate model to use for the given ontology document
      void clearCache()
      Remove all entries from the model cache
      void configure​(Model config)
      Configure this document manager using the given configuration information, after first resetting the model back to all default values.
      void configure​(Model config, boolean reset)
      Configure this document manager according to the configuration options supplied by the given configuration model.
      java.lang.String doAltURLMapping​(java.lang.String uri)
      Answer the URL of the alternative copy of the ontology document with the given URI, if known, or the URI unchanged if no alternative is known.
      void forget​(java.lang.String docURI)
      Remove all managed entries for the given document.
      boolean getCacheModels()
      Answer true if the models loaded by this document manager from a given URI will be cached, so that they can be re-used in other compound ontology models.
      FileManager getFileManager()
      Answer the file manager instance being used by this document manager.
      static OntDocumentManager getInstance()
      OntDocumentManager is not a singleton, but a global default instance is available for applications where a single shared document manager is sufficient.
      java.lang.String getLoadedPolicyURL()
      Answer the URL of the most recently loaded policy URL, or null if no document manager policy has yet been loaded since the metadata search path was last set.
      java.lang.String getMetadataSearchPath()
      Answer the path used to search for the ontology metadata to load.
      Model getModel​(java.lang.String uri)
      Answer the cached model corresponding to the given document, if known.
      OntModel getOntology​(java.lang.String uri, OntModelSpec spec)
      Answer the ontology model that results from loading the document with the given URI.
      boolean getProcessImports()
      Answer the policy flag indicating whether the imports statements of loaded ontologies will be processed to build a union of s.
      OntDocumentManager.ReadFailureHandler getReadFailureHandler()
      Answer the handler object that handles failed document read attempts, or null if not defined.
      OntDocumentManager.ReadHook getReadHook()
      Answer the current ReadHook for this document manager instance
      boolean ignoringImport​(java.lang.String uri)
      Answer true if the given URI is one that will be ignored during imports
      java.util.Iterator<java.lang.String> listDocuments()
      Answer an iterator over the ontology document URI's that this document manager knows to re-direct to other URL's.
      java.util.Iterator<java.lang.String> listIgnoredImports()
      Answer an iterator over the set of URI's we're ignoring
      void loadImport​(OntModel model, java.lang.String uri)
      Add the given model from the given URI as an import to the given model.
      void loadImports​(OntModel model)
      Inspect the statements in the graph expressed by the given model, and load into the model any imported documents.
      void removeIgnoreImport​(java.lang.String uri)
      Remove the given URI from the set of URI's we ignore in imports statements
      void reset()
      Reset all state in this document manager back to the default values it would have had when the object was created.
      void reset​(boolean reload)
      Reset all state in this document manager back to the default values it would have had when the object was created.
      void setCacheModels​(boolean cacheModels)
      Set the policy flag that indicates whether loaded models are cached by URI
      void setFileManager()
      Set the file manager used by this ODM instance to a copy of the global file manager (and, by extension, the global location mapper).
      void setFileManager​(FileManager fileMgr)
      Set the file manager used by this ODM instance to a copy of the global file manager (and, by extension, the global location mapper).
      void setMetadataSearchPath​(java.lang.String path, boolean replace)
      Change the search path for loading ontology metadata to the given path.
      void setProcessImports​(boolean processImports)
      Set the policy flag for processing imports of loaded ontologies.
      void setReadFailureHandler​(OntDocumentManager.ReadFailureHandler rfHandler)
      Set the handler for read failures, overwriting any existing value.
      OntDocumentManager.ReadHook setReadHook​(OntDocumentManager.ReadHook hook)
      Replace the existing ReadHook with the given value.
      void unloadImport​(OntModel model, java.lang.String uri)
      Remove from the given model the import denoted by the given URI.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • DEFAULT_METADATA_PATH

        public static final java.lang.String DEFAULT_METADATA_PATH
        The default path for searching for the metadata on locally cached ontologies
        See Also:
        Constant Field Values

      • NS

        public static final java.lang.String NS
        Namespace for ontology metadata resources and properties
        See Also:
        Constant Field Values

      • ANCHOR

        public static final java.lang.String ANCHOR
        The anchor char is added to the end of namespace prefix expansions
        See Also:
        Constant Field Values

      • ONTOLOGY_SPEC

        public static final Resource ONTOLOGY_SPEC
        rdf:type for ontology specification nodes in meta-data file

      • PUBLIC_URI

        public static final Property PUBLIC_URI
        Represents the public URI of an ontology; also used to derive the namespace

      • ALT_URL

        public static final Property ALT_URL
        Represents the alternative local copy of the public ontology; assumed to be resolvable, hence URL not URI

      • PREFIX

        public static final Property PREFIX
        Represents the standard prefix for this namespace

      • LANGUAGE

        public static final Property LANGUAGE
        Represents the ontology language used to encode the ontology

      • DOC_MGR_POLICY

        public static final Resource DOC_MGR_POLICY
        rdf:type for document manager policy nodes

      • CACHE_MODELS

        public static final Property CACHE_MODELS
        Defines boolean policy choice of caching loaded models

      • PROCESS_IMPORTS

        public static final Property PROCESS_IMPORTS
        Defines boolean policy choice of loading the imports closure

      • IGNORE_IMPORT

        public static final Property IGNORE_IMPORT
        Specifies the URI of an ontology that we do not want to import, even if processImports is true.

      • USE_DECLARED_NS_PREFIXES

        public static final Property USE_DECLARED_NS_PREFIXES
        The policy property for including the pre-declared namespace prefixes in a model.

    • Constructor Detail

      • OntDocumentManager

        public OntDocumentManager()

        Initialise a document manager by searching the default path for ontology metadata about known ontologies cached locally.

      • OntDocumentManager

        public OntDocumentManager​(java.lang.String path)

        Initialise a document manager by searching the given path for ontology metadata about known ontologies cached locally.

        Parameters:
        path - The search path to search for initial metadata, which will also replace the current search path for this document manager. Use null to prevent loading of any initial ontology metadata. The path is a series of URL's, separated by a semi-colon (;).

      • OntDocumentManager

        public OntDocumentManager​(FileManager fileMgr,
                          java.lang.String path)

        Initialise a document manager by with the given FileManager, and then searching the given path for ontology metadata about known ontologies cached locally.

        Parameters:
        path - The search path to search for initial metadata
        See Also:
        OntDocumentManager(String)

      • OntDocumentManager

        public OntDocumentManager​(Model config)

        Initialise a document manager with the given configuration model. This model is used in place of any model that might be found by searching the meta-data search path. Uses the default file manager, i.e. a copy of the global file manager.

        Parameters:
        config - An RDF model containing configuration information for this document manager.

      • OntDocumentManager

        public OntDocumentManager​(FileManager fileMgr,
                          Model config)

        Initialise a document manager with the given configuration model. This model is used in place of any model that might be found by searching the meta-data search path.

        Parameters:
        fileMgr - A file manager to use when locating source files for ontologies
        config - An RDF model containing configuration information for this document manager.

    • Method Detail

      • getInstance

        public static OntDocumentManager getInstance()

        OntDocumentManager is not a singleton, but a global default instance is available for applications where a single shared document manager is sufficient.

        Returns:
        The default, global instance of a document manager

      • getFileManager

        public FileManager getFileManager()

        Answer the file manager instance being used by this document manager.

        Returns:
        This object's file manager

      • setReadHook

        public OntDocumentManager.ReadHook setReadHook​(OntDocumentManager.ReadHook hook)
        Replace the existing ReadHook with the given value. The previous read hook is returned.
        Parameters:
        hook - The new read hook
        Returns:
        The old read hook
        Throws:
        java.lang.IllegalArgumentException - if the new read hook is null

      • getReadHook

        public OntDocumentManager.ReadHook getReadHook()
        Answer the current ReadHook for this document manager instance
        Returns:
        The read hook

      • setFileManager

        public void setFileManager()

        Set the file manager used by this ODM instance to a copy of the global file manager (and, by extension, the global location mapper).

      • setFileManager

        public void setFileManager​(FileManager fileMgr)

        Set the file manager used by this ODM instance to a copy of the global file manager (and, by extension, the global location mapper).

        Parameters:
        fileMgr - The new file manager

      • getMetadataSearchPath

        public java.lang.String getMetadataSearchPath()

        Answer the path used to search for the ontology metadata to load. The format is a ';' separated list of URI's. The first URI on the path that is readable is taken to be the location of the local ontology metadata.

        Returns:
        The ontology metadata search path, as a string.

      • setMetadataSearchPath

        public void setMetadataSearchPath​(java.lang.String path,
                                  boolean replace)

        Change the search path for loading ontology metadata to the given path. If replace is true, any existing mappings are removed before the new path is searched. Otherwise, existing data will only be replaced if it is clobbered by keys loaded from the metadata loaded from the new path.

        Parameters:
        path - The new metadata search path (see getMetadataSearchPath() for format)
        replace - If true, clear existing mappings first

      • setReadFailureHandler

        public void setReadFailureHandler​(OntDocumentManager.ReadFailureHandler rfHandler)
        Set the handler for read failures, overwriting any existing value.
        Parameters:
        rfHandler - The new handler for failed document read attempts.

      • getReadFailureHandler

        public OntDocumentManager.ReadFailureHandler getReadFailureHandler()
        Answer the handler object that handles failed document read attempts, or null if not defined.
        Returns:
        The current read failure handler, or null

      • configure

        public void configure​(Model config)

        Configure this document manager using the given configuration information, after first resetting the model back to all default values.

        Parameters:
        config - Document manager configuration as an RDF model
        See Also:
        configure( Model, boolean )

      • configure

        public void configure​(Model config,
                      boolean reset)

        Configure this document manager according to the configuration options supplied by the given configuration model. If reset is true, the document manager is first reset back to all default values.

        Parameters:
        config - Document manager configuration as an RDF model
        reset - If true, reset the document manager to default values, before attempting to configure the document manager using the given model.
        See Also:
        reset(boolean)

      • reset

        public void reset​(boolean reload)

        Reset all state in this document manager back to the default values it would have had when the object was created. Optionally reload the profile metadata from the search path. Note that the metadata search path is not changed by this reset.

        Parameters:
        reload - If true, reload the configuration file from the search path.

      • reset

        public void reset()

        Reset all state in this document manager back to the default values it would have had when the object was created. This does not reload the configuration information from the search path. Note also that the metadata search path is one of the values that is reset back to its default value.

        See Also:
        reset( boolean )

      • listDocuments

        public java.util.Iterator<java.lang.String> listDocuments()

        Answer an iterator over the ontology document URI's that this document manager knows to re-direct to other URL's. Note that being in this iteration does not mean that a document with the given name is in the set of cached models held by this document manager.

        Returns:
        An Iterator ranging over the public URI strings for the known document URI's.

      • doAltURLMapping

        public java.lang.String doAltURLMapping​(java.lang.String uri)

        Answer the URL of the alternative copy of the ontology document with the given URI, if known, or the URI unchanged if no alternative is known.

        Parameters:
        uri - The ontology document to lookup
        Returns:
        The resolvable location of the alternative copy, if known, or uri otherwise

      • addAltEntry

        public void addAltEntry​(java.lang.String docURI,
                        java.lang.String locationURL)

        Add an entry for an alternative copy of the document with the given document URI.

        Parameters:
        docURI - The public URI of the ontology document
        locationURL - A locally resolvable URL where an alternative copy of the ontology document can be found

      • addModel

        public void addModel​(java.lang.String docURI,
                     Model model)

        Add an entry that model is the appropriate model to use for the given ontology document. Will not replace any existing model that is cached for this URI (see addModel(String, Model, boolean) for an alternative that can replace existing models).

        Parameters:
        docURI - The public URI of the ontology document
        model - A model containing the triples from the document

      • addModel

        public void addModel​(java.lang.String docURI,
                     Model model,
                     boolean replace)

        Add an entry that model is the appropriate model to use for the given ontology document

        Parameters:
        docURI - The public URI of the ontology document
        model - A model containing the triples from the document
        replace - If true, replace any existing entry with this one.

      • forget

        public void forget​(java.lang.String docURI)

        Remove all managed entries for the given document. Note does not side-effect the prefixes table: this will have to be done separately.

        Parameters:
        docURI - The public URI for an ontology document

      • getOntology

        public OntModel getOntology​(java.lang.String uri,
                            OntModelSpec spec)

        Answer the ontology model that results from loading the document with the given URI. This may be a cached model, if this document manager's policy is to cache loaded models. If not, or if no model is cached, the document will be read into a suitable model. The model will contain the imports closure of the ontology, if that is the current policy of this document manager.

        Parameters:
        uri - Identifies the model to load.
        spec - Specifies the structure of the ontology model to create
        Returns:
        An ontology model containing the statements from the ontology document.
        See Also:
        getModel(java.lang.String)

      • getProcessImports

        public boolean getProcessImports()

        Answer the policy flag indicating whether the imports statements of loaded ontologies will be processed to build a union of s.

        Returns:
        True if imported models will be included in a loaded model

      • getCacheModels

        public boolean getCacheModels()

        Answer true if the models loaded by this document manager from a given URI will be cached, so that they can be re-used in other compound ontology models.

        Returns:
        If true, a cache is maintained of loaded models from their URI's.

      • setProcessImports

        public void setProcessImports​(boolean processImports)

        Set the policy flag for processing imports of loaded ontologies.

        Parameters:
        processImports - If true, load imported ontologies during load
        See Also:
        getProcessImports()

      • setCacheModels

        public void setCacheModels​(boolean cacheModels)

        Set the policy flag that indicates whether loaded models are cached by URI

        Parameters:
        cacheModels - If true, models will be cached by URI
        See Also:
        getCacheModels()

      • addIgnoreImport

        public void addIgnoreImport​(java.lang.String uri)

        Add the given URI to the set of URI's we ignore in imports statements

        Parameters:
        uri - A URI to ignore when importing

      • removeIgnoreImport

        public void removeIgnoreImport​(java.lang.String uri)

        Remove the given URI from the set of URI's we ignore in imports statements

        Parameters:
        uri - A URI to ignore no longer when importing

      • listIgnoredImports

        public java.util.Iterator<java.lang.String> listIgnoredImports()

        Answer an iterator over the set of URI's we're ignoring

        Returns:
        An iterator over ignored imports

      • ignoringImport

        public boolean ignoringImport​(java.lang.String uri)

        Answer true if the given URI is one that will be ignored during imports

        Parameters:
        uri - A URI to test
        Returns:
        True if uri will be ignored as an import

      • clearCache

        public void clearCache()

        Remove all entries from the model cache

      • loadImports

        public void loadImports​(OntModel model)

        Inspect the statements in the graph expressed by the given model, and load into the model any imported documents. Imports statements are recognised according to the model's language profile. An occurs check allows cycles of importing safely. This method will do nothing if the policy for this manager is not to process imports. If the cache policy for this doc manager allows, models will be cached by URI and re-used where possible.

        Parameters:
        model - An ontology model whose imports are to be loaded.

      • loadImport

        public void loadImport​(OntModel model,
                       java.lang.String uri)

        Add the given model from the given URI as an import to the given model. Any models imported by the given URI will also be imported.

        Parameters:
        model - A model to import into
        uri - The URI of a document to import

      • unloadImport

        public void unloadImport​(OntModel model,
                         java.lang.String uri)

        Remove from the given model the import denoted by the given URI.

        Parameters:
        model - A model
        uri - The URI of a document to no longer import

      • getLoadedPolicyURL

        public java.lang.String getLoadedPolicyURL()

        Answer the URL of the most recently loaded policy URL, or null if no document manager policy has yet been loaded since the metadata search path was last set.

        Returns:
        The most recently loaded policy URL or null.