| java.lang.Object
 com.hp.hpl.jena.ontology.OntDocumentManager
| OntDocumentManager | | public class OntDocumentManager (Code) | |
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
com.hp.hpl.jena.util.FileManager 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
OntDocumentManager.setFileManager(FileManager) method. For
example:
OntDocumentManager dm = OntDocumentManager.getInstance();
dm.setFileManager( FileManager.get() );
Note that in Jena 2.3, we have deprecated the capability of the document manager
to store a table of known prefixes, and a table mapping document URI's to ontology language
types. The intention is to remove both of these capabilities from
Jena 2.4 onwards. If this change would be problematic, please send email to the
Jena support
list.
author:
Ian Dickinson, HP Labs
author:
(email)
version:
CVS $Id: OntDocumentManager.java,v 1.63 2008/01/10 19:03:31 ian_dickinson Exp $ |
| Inner Class :public static interface ReadFailureHandler | |
| Inner Class :public static interface ReadHook | |
| Inner Class :public static class DefaultReadHook implements ReadHook | |
| Constructor Summary | |
| public | OntDocumentManager()
Initialise a document manager by searching the default path for ontology
metadata about known ontologies cached locally. | | public | OntDocumentManager(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 willalso replace the current search path for this document manager. | | public | OntDocumentManager(FileManager fileMgr, 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. | | public | OntDocumentManager(Model config)
Initialise a document manager with the given configuration model. | | public | OntDocumentManager(FileManager fileMgr, Model config)
Initialise a document manager with the given configuration model. |
| Method Summary | |
| public void | addAltEntry(String docURI, String locationURL)
Add an entry for an alternative copy of the document with the given document
URI. | | public void | addIgnoreImport(String uri)
| | public void | addLanguageEntry(String docURI, String language)
| | public void | addModel(String docURI, Model model)
Add an entry that model is the appropriate model to use
for the given ontology document. | | public void | addModel(String docURI, Model model, boolean replace)
| | public void | addPrefixMapping(String uri, String prefix)
Add a prefix mapping between the given public base URI and the
given prefix. | | public void | clearCache()
| | public void | configure(Model config)
| | public void | configure(Model config, boolean reset)
Configure this document manager according to the configuration options
supplied by the given configuration model. | | public String | doAltURLMapping(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. | | protected Model | findMetadata(String configPath)
Search the given path for a resolvable URI, from which we load a model
(assuming RDF/XML). | | public void | forget(String docURI)
Remove all managed entries for the given document. | | 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. | | public PrefixMapping | getDeclaredPrefixMapping()
| | public FileManager | getFileManager()
| | 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. | | public String | getLanguage(String uri)
Answer the representation of the ontology document with the given URI, if known. | | public String | getLoadedPolicyURL()
| | public String | getMetadataSearchPath()
Answer the path used to search for the ontology metadata to load. | | public Model | getModel(String uri)
Answer the cached model corresponding to the given document, if known. | | public OntModel | getOntology(String uri, OntModelSpec spec)
Answer the ontology model that results from loading the document with the
given URI. | | public String | getPrefixForURI(String uri)
Answer the prefix for the qnames in the given document, if known. | | public boolean | getProcessImports()
Answer the policy flag indicating whether the imports statements of
loaded ontologies will be processed to build a union of s. | | public ReadFailureHandler | getReadFailureHandler()
Answer the handler object that handles failed document read attempts,
or null if not defined. | | public ReadHook | getReadHook()
| | public String | getURIForPrefix(String prefix)
Answer the base URI for qnames with the given prefix, if known. | | public boolean | ignoringImport(String uri)
| | protected void | initialiseMetadata(String path)
Initialise the mappings for uri's and prefixes by loading metadata
from an RDF model. | | public Iterator | listDocuments()
Answer an iterator over the ontology document URI's that this document manager
knows to re-direct to other URL's. | | public Iterator | listIgnoredImports()
| | public void | loadImport(OntModel model, String uri)
Add the given model from the given URI as an import to the given model. | | protected void | loadImport(OntModel model, String importURI, List readQueue)
Load the document referenced by the given URI into the model. | | public void | loadImports(OntModel model)
Inspect the statements in the graph expressed by the given model, and load
into the model any imported documents. | | protected void | loadImports(OntModel model, List readQueue)
| | protected void | processMetadata(Model metadata)
Load the ontology specification metadata from the model into the local
mapping tables. | | protected void | queueImports(Model model, List readQueue, Profile profile)
| | protected boolean | read(Model model, String uri, boolean warn)
Load into the given model from the given URI, or from a local cache URI if defined. | | public void | removeIgnoreImport(String uri)
| | 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. | | public void | reset()
Reset all state in this document manager back to the default
values it would have had when the object was created. | | public void | setCacheModels(boolean cacheModels)
| | protected void | setDefaultPrefixMappings()
Set the default prefix mappings. | | protected void | setDefaults()
| | public void | setFileManager()
| | public void | setFileManager(FileManager fileMgr)
| | public void | setMetadataSearchPath(String path, boolean replace)
Change the search path for loading ontology metadata to the given path. | | public void | setProcessImports(boolean processImports)
Set the policy flag for processing imports of loaded ontologies. | | public void | setReadFailureHandler(ReadFailureHandler rfHandler)
Set the handler for read failures, overwriting any existing value. | | public ReadHook | setReadHook(ReadHook hook)
Replace the existing ReadHook with the given value. | | public void | setUseDeclaredPrefixes(boolean useDeclaredPrefixes)
| | public void | unloadImport(OntModel model, String uri)
| | protected void | unloadImports(OntModel model, List unloadQueue)
| | public boolean | useDeclaredPrefixes()
Answer true if, according to the policy expressed by this document manager, newly
generated ontology models should include the pre-declared namespace prefixes. |
| ALT_URL | | final public static Property ALT_URL(Code) | | Represents the alternative local copy of the public ontology; assumed to be resolvable, hence URL not URI
|
| ANCHOR | | final public static String ANCHOR(Code) | | The anchor char is added to the end of namespace prefix expansions
|
| CACHE_MODELS | | final public static Property CACHE_MODELS(Code) | | Defines boolean policy choice of caching loaded models
|
| DEFAULT_METADATA_PATH | | final public static String DEFAULT_METADATA_PATH(Code) | | The default path for searching for the metadata on locally cached ontologies
|
| DOC_MGR_POLICY | | final public static Resource DOC_MGR_POLICY(Code) | | rdf:type for document manager policy nodes
|
| IGNORE_IMPORT | | final public static Property IGNORE_IMPORT(Code) | | Specifies the URI of an ontology that we do not want to import, even if processImports is true.
|
| LANGUAGE | | final public static Property LANGUAGE(Code) | | Represents the ontology language used to encode the ontology
|
| NS | | final public static String NS(Code) | | Namespace for ontology metadata resources and properties
|
| ONTOLOGY_SPEC | | final public static Resource ONTOLOGY_SPEC(Code) | | rdf:type for ontology specification nodes in meta-data file
|
| PREFIX | | final public static Property PREFIX(Code) | | Represents the standard prefix for this namespace
|
| PROCESS_IMPORTS | | final public static Property PROCESS_IMPORTS(Code) | | Defines boolean policy choice of loading the imports closure
|
| PUBLIC_URI | | final public static Property PUBLIC_URI(Code) | | Represents the public URI of an ontology; also used to derive the namespace
|
| USE_DECLARED_NS_PREFIXES | | final public static Property USE_DECLARED_NS_PREFIXES(Code) | | The policy property for including the pre-declared namespace prefixes in a model.
|
| m_fileMgr | | protected FileManager m_fileMgr(Code) | | FileManager instance that provides location resolution service - defaults to global instance
|
| m_ignoreImports | | protected Set m_ignoreImports(Code) | | List of URI's that will be ignored when doing imports processing
|
| m_languageMap | | protected Map m_languageMap(Code) | | Mapping of public public URI's to language resources
|
| m_policyURL | | protected String m_policyURL(Code) | | The URL of the policy file that was loaded, or null if no external policy file has yet been loaded
|
| m_prefixMap | | protected PrefixMapping m_prefixMap(Code) | | Default prefix mapping to use to seed all models
|
| m_processImports | | protected boolean m_processImports(Code) | | Flag: process the imports closure
|
| m_readHook | | protected ReadHook m_readHook(Code) | | Read hook that can intercept the process of reading a file or URL
|
| m_rfHandler | | protected ReadFailureHandler m_rfHandler(Code) | | Optional handler for failed read
|
| m_searchPath | | protected String m_searchPath(Code) | | The search path for metadata
|
| m_useDeclaredPrefixes | | protected boolean m_useDeclaredPrefixes(Code) | | Flag to control whether we include the standard prefixes in generated models - default true.
|
| m_usingGlobalFileMgr | | protected boolean m_usingGlobalFileMgr(Code) | | Flag to indicate we're using a copy of the global file manager
|
| OntDocumentManager | | public OntDocumentManager()(Code) | |
Initialise a document manager by searching the default path for ontology
metadata about known ontologies cached locally.
|
| OntDocumentManager | | public OntDocumentManager(String path)(Code) | |
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 willalso replace the current search path for this document manager. Usenull to prevent loading of any initial ontology metadata. The path is a seriesof URL's, separated by a semi-colon (;). |
| OntDocumentManager | | public OntDocumentManager(FileManager fileMgr, String path)(Code) | |
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.OntDocumentManager(String) |
| OntDocumentManager | | public OntDocumentManager(Model config)(Code) | | 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)(Code) | | 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
Parameters:
config - An RDF model containing configuration information for this document manager. |
| addAltEntry | | public void addAltEntry(String docURI, String locationURL)(Code) | |
Add an entry for an alternative copy of the document with the given document
URI.
Parameters:
docURI - The public URI of the ontology document
Parameters:
locationURL - A locally resolvable URL where an alternative copy of theontology document can be found |
| addIgnoreImport | | public void addIgnoreImport(String uri)(Code) | | Add the given URI to the set of URI's we ignore in imports statements
Parameters:
uri - A URI to ignore when importing |
| addLanguageEntry | | public void addLanguageEntry(String docURI, String language)(Code) | |
Add an entry that language is the URI defining the
representation language for the given document
Parameters:
docURI - The public URI of the ontology document
Parameters:
language - A string defining the URI of the language |
| addModel | | public void addModel(String docURI, Model model)(Code) | |
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
OntDocumentManager.addModel(String,Model,boolean) for an alternative
that can replace existing models).
Parameters:
docURI - The public URI of the ontology document
Parameters:
model - A model containing the triples from the document |
| addModel | | public void addModel(String docURI, Model model, boolean replace)(Code) | |
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
Parameters:
model - A model containing the triples from the document
Parameters:
replace - If true, replace any existing entry with this one. |
| addPrefixMapping | | public void addPrefixMapping(String uri, String prefix)(Code) | |
Add a prefix mapping between the given public base URI and the
given prefix.
Parameters:
uri - The base URI that prefix expands to
Parameters:
prefix - A qname prefix |
| clearCache | | public void clearCache()(Code) | |
Remove all entries from the model cache
|
| configure | | public void configure(Model config)(Code) | | 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: OntDocumentManager.configure(Model,boolean) |
| configure | | public void configure(Model config, boolean reset)(Code) | | 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
Parameters:
reset - If true, reset the document manager to default values, beforeattempting to configure the document manager using the given model.
See Also: OntDocumentManager.reset |
| doAltURLMapping | | public String doAltURLMapping(String uri)(Code) | |
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 The resolvable location of the alternative copy, if known, or uri otherwise |
| findMetadata | | protected Model findMetadata(String configPath)(Code) | |
Search the given path for a resolvable URI, from which we load a model
(assuming RDF/XML).
Parameters:
configPath - The path to search A model loaded by resolving an entry on the path, or null ifno path entries succeed. |
| forget | | public void forget(String docURI)(Code) | |
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 |
| getCacheModels | | public boolean getCacheModels()(Code) | |
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.
If true, a cache is maintained of loaded models from their URI's. |
| getDeclaredPrefixMapping | | public PrefixMapping getDeclaredPrefixMapping()(Code) | | Answer the namespace prefix map that contains the shared prefixes managed by this
document manager.
The namespace prefix mapping |
| getFileManager | | public FileManager getFileManager()(Code) | | Answer the file manager instance being used by this document manager.
This object's file manager |
| getInstance | | public static OntDocumentManager getInstance()(Code) | |
OntDocumentManager is not a singleton, but a global default instance is available
for applications where a single shared document manager is sufficient.
The default, global instance of a document manager |
| getLanguage | | public String getLanguage(String uri)(Code) | |
Answer the representation of the ontology document with the given URI, if known.
Parameters:
uri - The ontology document to lookup The URI of the representation language, or null. |
| getLoadedPolicyURL | | public String getLoadedPolicyURL()(Code) | | 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.
The most recently loaded policy URL or null. |
| getMetadataSearchPath | | public String getMetadataSearchPath()(Code) | |
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.
The ontology metadata search path, as a string. |
| getModel | | public Model getModel(String uri)(Code) | |
Answer the cached model corresponding to the given document, if known.
Parameters:
uri - The ontology document to lookup The model for the document, or null if the model is not known.
See Also: OntDocumentManager.getOntology |
| getOntology | | public OntModel getOntology(String uri, OntModelSpec spec)(Code) | |
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.
Parameters:
spec - Specifies the structure of the ontology model to create An ontology model containing the statements from the ontology document.
See Also: OntDocumentManager.getModel |
| getPrefixForURI | | public String getPrefixForURI(String uri)(Code) | |
Answer the prefix for the qnames in the given document, if known.
Parameters:
uri - The ontology document to lookup The string to use as a prefix when serialising qnames in thegiven document's namespace, or null if not known |
| getProcessImports | | public boolean getProcessImports()(Code) | |
Answer the policy flag indicating whether the imports statements of
loaded ontologies will be processed to build a union of s.
True if imported models will be included in a loaded model |
| getReadFailureHandler | | public ReadFailureHandler getReadFailureHandler()(Code) | | Answer the handler object that handles failed document read attempts,
or null if not defined.
The current read failure handler, or null |
| getReadHook | | public ReadHook getReadHook()(Code) | | Answer the current ReadHook for this document manager instance
The read hook |
| getURIForPrefix | | public String getURIForPrefix(String prefix)(Code) | |
Answer the base URI for qnames with the given prefix, if known.
Parameters:
prefix - A prefix string The basename that the prefix expands to, or null |
| ignoringImport | | public boolean ignoringImport(String uri)(Code) | | Answer true if the given URI is one that will be ignored during imports
Parameters:
uri - A URI to test True if uri will be ignored as an import |
| initialiseMetadata | | protected void initialiseMetadata(String path)(Code) | |
Initialise the mappings for uri's and prefixes by loading metadata
from an RDF model.
Parameters:
path - The URI path to search for a loadable model |
| listDocuments | | public Iterator listDocuments()(Code) | |
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.
An Iterator ranging over the public URI strings for the knowndocument URI's. |
| listIgnoredImports | | public Iterator listIgnoredImports()(Code) | | Answer an iterator over the set of URI's we're ignoring
An iterator over ignored imports |
| loadImport | | public void loadImport(OntModel model, String uri)(Code) | | 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
Parameters:
uri - The URI of a document to import |
| loadImport | | protected void loadImport(OntModel model, String importURI, List readQueue)(Code) | |
Load the document referenced by the given URI into the model. The cache will be
used if permitted by the policy, and the imports of loaded model will be added to
the end of the queue.
Parameters:
model - The composite model to load into
Parameters:
importURI - The URI of the document to load
Parameters:
readQueue - Cumulative read queue for this operation |
| loadImports | | public void loadImports(OntModel model)(Code) | |
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
for this manager is not to process imports. If the
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. |
| loadImports | | protected void loadImports(OntModel model, List readQueue)(Code) | | Load all of the imports in the queue
Parameters:
model - The model to load the imports into
Parameters:
readQueue - The queue of imports to load |
| processMetadata | | protected void processMetadata(Model metadata)(Code) | |
Load the ontology specification metadata from the model into the local
mapping tables.
Parameters:
metadata - A model containing metadata about ontologies. |
| queueImports | | protected void queueImports(Model model, List readQueue, Profile profile)(Code) | | Add the ontologies imported by the given model to the end of the queue.
|
| read | | protected boolean read(Model model, String uri, boolean warn)(Code) | |
Load into the given model from the given URI, or from a local cache URI if defined.
Parameters:
model - A model to read statements into
Parameters:
uri - A URI string
Parameters:
warn - If true, warn on RDF exception True if the uri was read successfully |
| removeIgnoreImport | | public void removeIgnoreImport(String uri)(Code) | | 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 |
| reset | | public void reset(boolean reload)(Code) | | 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 thesearch path. |
| reset | | public void reset()(Code) | | 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: OntDocumentManager.reset(boolean) |
| setCacheModels | | public void setCacheModels(boolean cacheModels)(Code) | |
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: OntDocumentManager.getCacheModels() |
| setDefaultPrefixMappings | | protected void setDefaultPrefixMappings()(Code) | | Set the default prefix mappings.
|
| setDefaults | | protected void setDefaults()(Code) | | Set the default option settings.
|
| setFileManager | | public void setFileManager()(Code) | | 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)(Code) | | 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 |
| setMetadataSearchPath | | public void setMetadataSearchPath(String path, boolean replace)(Code) | |
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 OntDocumentManager.getMetadataSearchPath for format)
Parameters:
replace - If true, clear existing mappings first |
| setProcessImports | | public void setProcessImports(boolean processImports)(Code) | |
Set the policy flag for processing imports of loaded ontologies.
Parameters:
processImports - If true, load imported ontologies during load
See Also: OntDocumentManager.getProcessImports |
| setReadFailureHandler | | public void setReadFailureHandler(ReadFailureHandler rfHandler)(Code) | | Set the handler for read failures, overwriting any existing value.
Parameters:
rfHandler - The new handler for failed document read attempts. |
| setReadHook | | public ReadHook setReadHook(ReadHook hook)(Code) | | Replace the existing ReadHook with the given value. The previous read
hook is returned.
Parameters:
hook - The new read hook The old read hook
exception:
IllegalArgumentException - if the new read hook is null |
| setUseDeclaredPrefixes | | public void setUseDeclaredPrefixes(boolean useDeclaredPrefixes)(Code) | | Set the flag that determines whether pre-declared namespace prefixes will be added to newly
generated ontology models.
Parameters:
useDeclaredPrefixes - If true, new models will include the pre-declared prefixes set heldby this document manager. |
| unloadImport | | public void unloadImport(OntModel model, String uri)(Code) | | Remove from the given model the import denoted by the given URI.
Parameters:
model - A model
Parameters:
uri - The URI of a document to no longer import |
| unloadImports | | protected void unloadImports(OntModel model, List unloadQueue)(Code) | | Unload all of the imports in the queue
Parameters:
model - The model to unload the imports from
Parameters:
unloadQueue - The queue of imports to unload |
| useDeclaredPrefixes | | public boolean useDeclaredPrefixes()(Code) | | Answer true if, according to the policy expressed by this document manager, newly
generated ontology models should include the pre-declared namespace prefixes.
True if pre-declared prefixes should be added to the models |
|
|