|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.hp.hpl.jena.ontology.OntDocumentManager
public class OntDocumentManager
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() );
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.
Nested Class Summary | |
---|---|
static class |
OntDocumentManager.DefaultReadHook
The default implementation of OntDocumentManager.ReadHook makes no changes. |
static interface |
OntDocumentManager.ReadFailureHandler
Interface defining a handler call-back in the case that the OntDocumentManager
fails in an attempt to read the contents of a URL into a model. |
static interface |
OntDocumentManager.ReadHook
Interface denoting a handler class that can intervene in the process of reading a source document into a model. |
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 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(FileManager fileMgr,
Model config)
Initialise a document manager with the given configuration model. |
|
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. |
|
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 |
addModel(String docURI,
Model model)
Add an entry that model is the appropriate model to use
for the given ontology document. |
void |
addModel(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. |
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. |
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. |
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. |
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(String uri)
Answer true if the given URI is one that will be ignored during imports |
Iterator<String> |
listDocuments()
Answer an iterator over the ontology document URI's that this document manager knows to re-direct to other URL's. |
Iterator<String> |
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 |
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(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,
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 |
---|
public static final String DEFAULT_METADATA_PATH
public static final String NS
public static final String ANCHOR
public static final Resource ONTOLOGY_SPEC
public static final Property PUBLIC_URI
public static final Property ALT_URL
public static final Property PREFIX
public static final Property LANGUAGE
public static final Resource DOC_MGR_POLICY
public static final Property CACHE_MODELS
public static final Property PROCESS_IMPORTS
public static final Property IGNORE_IMPORT
public static final Property USE_DECLARED_NS_PREFIXES
Constructor Detail |
---|
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.
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 (;).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.
path
- The search path to search for initial metadataOntDocumentManager(String)
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.
config
- An RDF model containing configuration information for this document manager.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.
fileMgr
- A file manager to use when locating source files for ontologiesconfig
- An RDF model containing configuration information for this document manager.Method Detail |
---|
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 FileManager getFileManager()
Answer the file manager instance being used by this document manager.
public OntDocumentManager.ReadHook setReadHook(OntDocumentManager.ReadHook hook)
hook
- The new read hook
IllegalArgumentException
- if the new read hook is nullpublic OntDocumentManager.ReadHook getReadHook()
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).
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).
fileMgr
- The new file managerpublic 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.
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.
path
- The new metadata search path (see getMetadataSearchPath()
for format)replace
- If true, clear existing mappings firstpublic void setReadFailureHandler(OntDocumentManager.ReadFailureHandler rfHandler)
rfHandler
- The new handler for failed document read attempts.public OntDocumentManager.ReadFailureHandler getReadFailureHandler()
public void configure(Model config)
Configure this document manager using the given configuration information, after first resetting the model back to all default values.
config
- Document manager configuration as an RDF modelconfigure( Model, boolean )
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.
config
- Document manager configuration as an RDF modelreset
- If true, reset the document manager to default values, before
attempting to configure the document manager using the given model.reset(boolean)
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.
reload
- If true, reload the configuration file from the
search path.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.
reset( boolean )
public Iterator<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.
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.
uri
- The ontology document to lookup
uri
otherwisepublic Model getModel(String uri)
Answer the cached model corresponding to the given document, if known.
uri
- The ontology document to lookup
getOntology(java.lang.String, com.hp.hpl.jena.ontology.OntModelSpec)
public void addAltEntry(String docURI, String locationURL)
Add an entry for an alternative copy of the document with the given document URI.
docURI
- The public URI of the ontology documentlocationURL
- A locally resolvable URL where an alternative copy of the
ontology document can be foundpublic void addModel(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).
docURI
- The public URI of the ontology documentmodel
- A model containing the triples from the documentpublic void addModel(String docURI, Model model, boolean replace)
Add an entry that model
is the appropriate model to use
for the given ontology document
docURI
- The public URI of the ontology documentmodel
- A model containing the triples from the documentreplace
- If true, replace any existing entry with this one.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.
docURI
- The public URI for an ontology documentpublic 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.
uri
- Identifies the model to load.spec
- Specifies the structure of the ontology model to create
getModel(java.lang.String)
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 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 void setProcessImports(boolean processImports)
Set the policy flag for processing imports of loaded ontologies.
processImports
- If true, load imported ontologies during loadgetProcessImports()
public void setCacheModels(boolean cacheModels)
Set the policy flag that indicates whether loaded models are cached by URI
cacheModels
- If true, models will be cached by URIgetCacheModels()
public void addIgnoreImport(String uri)
Add the given URI to the set of URI's we ignore in imports statements
uri
- A URI to ignore when importingpublic void removeIgnoreImport(String uri)
Remove the given URI from the set of URI's we ignore in imports statements
uri
- A URI to ignore no longer when importingpublic Iterator<String> listIgnoredImports()
Answer an iterator over the set of URI's we're ignoring
public boolean ignoringImport(String uri)
Answer true if the given URI is one that will be ignored during imports
uri
- A URI to test
public void clearCache()
Remove all entries from the model cache
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.
model
- An ontology model whose imports are to be loaded.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.
model
- A model to import intouri
- The URI of a document to importpublic void unloadImport(OntModel model, String uri)
Remove from the given model the import denoted by the given URI.
model
- A modeluri
- The URI of a document to no longer importpublic 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.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |