com.hp.hpl.jena.ontology
Class OntDocumentManager

java.lang.Object
  com.hp.hpl.jena.ontology.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.

Version:

CVS $Id: OntDocumentManager.java,v 1.20 2003/06/26 08:38:34 ian_dickinson Exp $

Author:

Ian Dickinson, HP Labs (email)

Field Summary

static Property	ALT_URL Represents the alternative local copy of the public ontology; assumed to be resolvable, hence URL not URI
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 java.lang.String	PATH_DELIMITER Delimiter between path entries
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

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.

Method Summary

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	addLanguageEntry(java.lang.String docURI, java.lang.String language) Add an entry that language is the URI defining the representation language for the given document
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	addPrefixMapping(java.lang.String uri, java.lang.String prefix) Add a prefix mapping between the given public base URI and the given prefix.
void	clearCache() Remove all entries from the model cache
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.
com.hp.hpl.jena.shared.PrefixMapping	getDeclaredPrefixMapping() Answer the namespace prefix map that contains the shared prefixes managed 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	getLanguage(java.lang.String uri) Answer the representation of the ontology document with the given URI, if known.
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.
Model	getOntology(java.lang.String uri, OntModelSpec spec) Answer the ontology model that results from loading the document with the given URI.
java.lang.String	getPrefixForURI(java.lang.String uri) Answer the prefix for the qnames in the given document, if known.
boolean	getProcessImports() Answer the policy flag indicating whether the imports statements of loaded ontologies will be processed to build a union of s.
java.lang.String	getURIForPrefix(java.lang.String prefix) Answer the base URI for qnames with the given prefix, if known.
boolean	ignoringImport(java.lang.String uri) Answer true if the given URI is one that will be ignored during imports
java.util.Iterator	listDocuments() Answer an iterator over the ontology documents this document mananger is managing.
java.util.Iterator	listIgnoredImports() Answer an iterator over the set of URI's we're ignoring
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	setCacheModels(boolean cacheModels) Set the policy flag that indicates whether loaded models are cached by URI
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	setUseDeclaredPrefixes(boolean useDeclaredPrefixes) Set the flag that determines whether pre-declared namespace prefixes will be added to newly generated ontology models.
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.

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

PATH_DELIMITER

public static final java.lang.String PATH_DELIMITER

Delimiter between path entries

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

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.

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

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

listDocuments

public java.util.Iterator listDocuments()

Answer an iterator over the ontology documents this document mananger is managing.

Returns:

An Iterator ranging over the public URI strings for the known (i.e. cached) document models

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

getLanguage

public java.lang.String getLanguage(java.lang.String uri)

Answer the representation of the ontology document with the given URI, if known.

Parameters:

uri - The ontology document to lookup

Returns:

The URI of the representation language, or null.

getPrefixForURI

public java.lang.String getPrefixForURI(java.lang.String uri)

Answer the prefix for the qnames in the given document, if known.

Parameters:

uri - The ontology document to lookup

Returns:

The string to use as a prefix when serialising qnames in the given document's namespace, or null if not known

getURIForPrefix

public java.lang.String getURIForPrefix(java.lang.String prefix)

Answer the base URI for qnames with the given prefix, if known.

Parameters:

prefix - A prefix string

Returns:

The basename that the prefix expands to, or null

getModel

public Model getModel(java.lang.String uri)

Answer the cached model corresponding to the given document, if known.

Parameters:

uri - The ontology document to lookup

Returns:

The model for the document, or null if the model is not known.

useDeclaredPrefixes

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.

Returns:

True if pre-declared prefixes should be added to the models

setUseDeclaredPrefixes

public void setUseDeclaredPrefixes(boolean useDeclaredPrefixes)

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 held by this document manager.

getDeclaredPrefixMapping

public com.hp.hpl.jena.shared.PrefixMapping getDeclaredPrefixMapping()

Answer the namespace prefix map that contains the shared prefixes managed by this document manager.

Returns:

The namespace prefix mapping

addPrefixMapping

public void addPrefixMapping(java.lang.String uri,
                             java.lang.String prefix)

Add a prefix mapping between the given public base URI and the given prefix.

Parameters:

uri - The base URI that prefix expands to

prefix - A qname prefix

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

Parameters:

docURI - The public URI of the ontology document

model - A model containing the triples from the document

addLanguageEntry

public void addLanguageEntry(java.lang.String docURI,
                             java.lang.String language)

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

language - A string defining the URI of the language

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 Model 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.

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 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.