com.hp.hpl.jena.ontology
Class OntDocumentManager

java.lang.Object
  extended by com.hp.hpl.jena.ontology.OntDocumentManager

public class OntDocumentManager
extends 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.42 2004/12/07 10:04:18 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 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 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 String NS
          Namespace for ontology metadata resources and properties
static Resource ONTOLOGY_SPEC
          rdf:type for ontology specification nodes in meta-data file
static 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(Model config)
          Initialise a document manager with the given configuration model.
OntDocumentManager(String path)
           Initialise a document manager by searching the given path for ontology metadata about known ontologies cached locally.
 
Method Summary
 void addAltEntry(String docURI, String locationURL)
           Add an entry for an alternative copy of the document with the given document URI.
 void addIgnoreImport(String uri)
          Add the given URI to the set of URI's we ignore in imports statements
 void addLanguageEntry(String docURI, String language)
           Add an entry that language is the URI defining the representation language for the given document
 void addModel(String docURI, Model model)
           Add an entry that model is the appropriate model to use for the given ontology document
 void addPrefixMapping(String uri, 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
 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.
 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.
 void forget(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.
 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.
 String getLanguage(String uri)
           Answer the representation of the ontology document with the given URI, if known.
 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.
 String getMetadataSearchPath()
           Answer the path used to search for the ontology metadata to load.
 Model getModel(String uri)
           Answer the cached model corresponding to the given document, if known.
 OntModel getOntology(String uri, OntModelSpec spec)
           Answer the ontology model that results from loading the document with the given URI.
 String getPrefixForURI(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.
 String getURIForPrefix(String prefix)
           Answer the base URI for qnames with the given prefix, if known.
 boolean ignoringImport(String uri)
          Answer true if the given URI is one that will be ignored during imports
 Iterator listDocuments()
           Answer an iterator over the ontology documents this document mananger is managing.
 Iterator listIgnoredImports()
          Answer an iterator over the set of URI's we're ignoring
 void loadImport(OntModel model, 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(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 setMetadataSearchPath(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.
 void unloadImport(OntModel model, String uri)
          Remove from the given model the import denoted by the given URI.
 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 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 String PATH_DELIMITER
Delimiter between path entries

See Also:
Constant Field Values

NS

public static final String NS
Namespace for ontology metadata resources and properties

See Also:
Constant Field Values

ANCHOR

public static final 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(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 the PATH_DELIMITER, which defaults to semi-colon (;).

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.

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

getMetadataSearchPath

public 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(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

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.

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.


listDocuments

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

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

getLanguage

public String getLanguage(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 String getPrefixForURI(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 String getURIForPrefix(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(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.
See Also:
getOntology(java.lang.String, com.hp.hpl.jena.ontology.OntModelSpec)

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 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(String uri,
                             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(String docURI,
                        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(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(String docURI,
                             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(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(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(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(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 Iterator listIgnoredImports()

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

Returns:
An iterator over ignored imports

ignoringImport

public boolean ignoringImport(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,
                       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,
                         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 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.


Copyright © 2000, 2001, 2002, 2003, 2004 Hewlett-Packard Development Company, LP