de.uka.ipd.consensus.foundation.ontology
Interface OntologyManager

All Superinterfaces:
ConsensusFoundationModule
All Known Implementing Classes:
OntologyManagerImpl

public interface OntologyManager
extends ConsensusFoundationModule

The OntologyManager is the central component as it manages the elements of the ontology. It is reponsible for loading an existing ontology from a persistent backend store on application startup, and it must initialize the QueryEngine as well as export and import handlers.

The OntologyManager implementation can be configured with the key cf.ontologymanager in the ConsensusFoundation.properties configuration file. It's a core component and not optional.

The implementation is loaded by the ConsensusFoundation constructor. For successful instantiation, the OntologyManager implementation must provide a default constructor without arguments.

Version:
2006-06-14
Author:
Thomas Much
See Also:
QueryEngine, ImportHandler, ExportHandler, ConsensusFoundation, EvolutionManager

Method Summary
 void abortTransaction(Object scope, Object ta)
          This is a "quick rollback" for the transaction if no changes have been made to the ontology.
 void addExportHandler(ExportHandler handler)
          Registers an ExportHandler instance with the OntologyManager.
 void addImportHandler(ImportHandler handler)
          Registers an ImportHandler instance with the OntologyManager.
 void addOntologyListener(OntologyListener listener)
          Registers a new OntologyListener.
 Rateable checkInternalRateable(Rateable rateable)
          Checks the given rateable object if it is a special association that is usually wrapped inside a TypeInstance, SuperSubclass or Synonym.
 void commitTransaction(Object scope, Object ta)
          Commits the transaction for the given scope.
 Association createAssociation(User creator, String id, String name, Topic type)
          Creates an association of the given type.
 Attribute createAttribute(User creator, String id, String name, String value, Topic type)
          Creates an attribute of the given type.
 Topic createClassTopic(User creator, String id, String name, Topic cls)
          Creates a class topic as a subclass of the given superclass topic.
 Topic createInternalTopic(User creator, String id, String name, Topic type)
          Creates an internal topic that is not visible through the topic collections, only by id query.
 Topic createTopic(User creator, String id, String name, Topic type)
          Creates a topic of the given type.
 void deleteAssociation(Association assoc)
          Deletes an association permanently from the ontology.
 void deleteAttribute(Attribute attr)
          Deletes an attribute permanently from the ontology.
 void deleteTopic(Topic topic)
          Deletes a topic permanently from the ontology.
 ExportHandler getExportHandler(String format)
          Returns an export handler for a certain file format.
 int getExportHandlerCount()
          Returns the number of registered export handlers.
 Iterator getExportHandlers()
          Returns all export handlers.
 ImportHandler getImportHandler(String format)
          Returns an import handler for a certain file format.
 int getImportHandlerCount()
          Returns the number of registered import handlers.
 Iterator getImportHandlers()
          Returns all import handlers.
 ImportHandler getMergeHandler(String format)
          Returns an import handler for a certain file format that can merge ontologies in this format.
 int getMergeHandlerCount()
          Returns the number of registered import handlers that can merge ontologies.
 Iterator getMergeHandlers()
          Returns all import handlers that can merge ontologies.
 QueryEngine getQueryEngine()
          Returns the QueryEngine that is part of the OntologyManager.
 void init(Properties config, LoggingManager logging, UserManager users)
          This method is called by the ConsensusFoundation constructor to initialize the OntologyManager.
 Object openTransaction(Object scope)
          Opens a transaction for the ontology backend.
 void removeOntologyListener(OntologyListener listener)
          Removes an OntologyListener, if it is registered with the OntologyManager (otherwise this call is ignored).
 boolean reorg()
          If the ontology needs reorganization from time to time, the implementation can clean up the ontology when an application calls this method.
 void rollbackTransaction(Object scope, Object ta)
          Rolls the transaction back for the given scope.
 
Methods inherited from interface de.uka.ipd.consensus.foundation.ConsensusFoundationModule
getConsensusFoundationManager, getVersion, initCompleted, shutdown
 

Method Detail

init

public void init(Properties config,
                 LoggingManager logging,
                 UserManager users)
          throws Exception

This method is called by the ConsensusFoundation constructor to initialize the OntologyManager.

An implementation can use this method to restore an existing ontology from a persistent backend or to load a new ontology from a file (and replace an existing ontology). Import and export handlers should be initialized here, too.

Parameters:
config - all entries from ConsensusFoundation.properties
logging - the successfully initialized LoggingManager instance
users - the the successfully initialized UserManager instance
Throws:
Exception - if any error occurs (startup of the application is aborted in this case)
See Also:
ConsensusFoundation.ConsensusFoundation()

createTopic

public Topic createTopic(User creator,
                         String id,
                         String name,
                         Topic type)
                  throws OntologyManagerException,
                         DynamicRightsManagerException
Creates a topic of the given type. If the implementation supports classes, the type must be a class topic.

Parameters:
creator - the user who wants to create the topic
id - the id (must not be empty) or (usually) null for an automatically computed id
name - the topic's name (must not be empty or null)
type - the type topic for the topic or null for a typeless topic
Returns:
the newly created topic
Throws:
OntologyManagerDuplicateIdException - if the id parameter is not null and is already used within the ontology
OntologyManagerException - if the topic could not be created
DynamicRightsManagerException - if the user is not allowed to create topics of the given type
See Also:
Topic.isClassTopic(), DynamicRightsManager.mayCreateTopic(User, Topic)

createClassTopic

public Topic createClassTopic(User creator,
                              String id,
                              String name,
                              Topic cls)
                       throws OntologyManagerException,
                              DynamicRightsManagerException
Creates a class topic as a subclass of the given superclass topic. Only supported if the implementation supports classes.

Topic.setClassTopic(true) is called after creation automatically.

Parameters:
creator - the user who wants to create the class topic
id - the id (must not be empty) or (usually) null for an automatically computed id
name - the topic's name (must not be empty or null)
cls - the superclass topic for the new class topic or null for a root class topic
Returns:
the newly created class topic
Throws:
OntologyManagerDuplicateIdException - if the id parameter is not null and is already used within the ontology
OntologyManagerException - if the class topic could not be created
DynamicRightsManagerException - if the user is not allowed to create class topics of the given type
UnsupportedOperationException - if the implementation does not support classes
See Also:
Topic.isClassTopic(), Topic.setClassTopic(boolean), DynamicRightsManager.mayCreateClassTopic(User, Topic)

createInternalTopic

public Topic createInternalTopic(User creator,
                                 String id,
                                 String name,
                                 Topic type)
                          throws OntologyManagerException
Creates an internal topic that is not visible through the topic collections, only by id query. If the implementation supports classes, the type must be a class topic.

If an id is given and an internal topic already exists with that id, the existing topic is returned instead of a newly created one.

Topic.setClassTopic(true) is called after creation automatically if the implementation uses classes.

Parameters:
creator - the user who wants to create the internal topic
id - the id (must not be empty), null for an automatically computed id
name - the topic's name (must not be empty or null)
type - the type topic for the new topic or null for a typeless topic
Returns:
the newly created topic or an existing one with the given id
Throws:
OntologyManagerException - if the topic could not be created
See Also:
Topic.isClassTopic(), Topic.setClassTopic(boolean)

createAssociation

public Association createAssociation(User creator,
                                     String id,
                                     String name,
                                     Topic type)
                              throws OntologyManagerException,
                                     DynamicRightsManagerException
Creates an association of the given type. If the implementation supports classes, the type must be a class topic.

Parameters:
creator - the user who wants to create the association
id - the id (must not be empty) or (usually) null for an automatically computed id
name - the association's name (null is treated as the empty string)
type - the type topic for the association or null for a typeless association
Returns:
the newly created association
Throws:
OntologyManagerDuplicateIdException - if the id parameter is not null and is already used within the ontology
OntologyManagerException - if the association could not be created
DynamicRightsManagerException - if the user is not allowed to create associations of the given type
See Also:
Topic.isClassTopic(), DynamicRightsManager.mayCreateAssociation(User, Topic)

createAttribute

public Attribute createAttribute(User creator,
                                 String id,
                                 String name,
                                 String value,
                                 Topic type)
                          throws OntologyManagerException,
                                 DynamicRightsManagerException
Creates an attribute of the given type. If the implementation supports classes, the type must be a class topic.

Parameters:
creator - the user who wants to create the attribute
id - the id (must not be empty) or (usually) null for an automatically computed id
name - the attribute's name (must not be empty or null)
value - the attribute's value (null is treated as the empty string)
type - the type topic for the attribute or null for a typeless attribute
Returns:
the newly created attribute
Throws:
OntologyManagerDuplicateIdException - if the id parameter is not null and is already used within the ontology
OntologyManagerException - if the attribute could not be created
DynamicRightsManagerException - if the user is not allowed to create attributes of the given type
See Also:
Attributeable.addAttribute(User, Attribute), Topic.isClassTopic(), DynamicRightsManager.mayCreateAttribute(User, Topic)

checkInternalRateable

public Rateable checkInternalRateable(Rateable rateable)
Checks the given rateable object if it is a special association that is usually wrapped inside a TypeInstance, SuperSubclass or Synonym. If it is, the association is wrapped and one of the three mentioned types is returned. Otherwise, the rateable object is returned unchanged.

Parameters:
rateable - the rateable object to be checked if it is a special internal association
Returns:
the wrapped association if it is a special internal one, or the unchanged parameter
See Also:
TypeInstance, SuperSubclass, Synonym

deleteTopic

public void deleteTopic(Topic topic)
                 throws OntologyManagerException
Deletes a topic permanently from the ontology. This is done without other steps that might be necessary, for example deleting associations or other elements that are useless without this topic.

To delete topics in an application, use the EvolutionManager that keeps the ontology consistent and checks the user's rights. The EvolutionManager will then use this method to do the actual deleting.

Parameters:
topic - the topic to be deleted
Throws:
OntologyManagerException - if the topic cannot be deleted without making the ontology inconsistent
See Also:
EvolutionManager

deleteAssociation

public void deleteAssociation(Association assoc)
                       throws OntologyManagerException
Deletes an association permanently from the ontology. This is done without other steps that might be necessary, for example deleting topics or other elements that are useless without this association.

To delete associations in an application, use the EvolutionManager that keeps the ontology consistent and checks the user's rights. The EvolutionManager will then use this method to do the actual deleting.

Parameters:
assoc - the association to be deleted
Throws:
OntologyManagerException - if the association cannot be deleted without making the ontology inconsistent
See Also:
EvolutionManager

deleteAttribute

public void deleteAttribute(Attribute attr)
                     throws OntologyManagerException
Deletes an attribute permanently from the ontology. This is done without other steps that might be necessary, for example deleting associations or other elements that are useless without this attribute.

To delete attributes in an application, use the EvolutionManager that keeps the ontology consistent and checks the user's rights. The EvolutionManager will then use this method to do the actual deleting.

Parameters:
attr - the attribute to be deleted
Throws:
OntologyManagerException - if the attribute cannot be deleted without making the ontology inconsistent
See Also:
EvolutionManager

getQueryEngine

public QueryEngine getQueryEngine()
Returns the QueryEngine that is part of the OntologyManager.

Note that the engine might be available only after initCompleted() has finished.

Returns:
the QueryEngine instance

openTransaction

public Object openTransaction(Object scope)
                       throws OntologyManagerException
Opens a transaction for the ontology backend. Pass a suitable scope object, for example a HTTP request object.

The return value is a transaction object if this call started a new transaction or null if another transaction is already running for this scope. You'll have to pass the exact return value to the commit/rollback method.

Note that the implementation is not required to use the scope information if the backend does not support scoped transactions. If the backend does not support transactions at all, you'll always get null as the return value, which you can safely pass to the other transaction methods.

Parameters:
scope - the scope how long the transaction will probably last
Returns:
a transaction object or null
Throws:
OntologyManagerException - if the transaction could not be opened

commitTransaction

public void commitTransaction(Object scope,
                              Object ta)
                       throws OntologyManagerException
Commits the transaction for the given scope. You must pass the exact return value from openTransaction() to this method.

Parameters:
scope - the scope for this transaction
ta - the return value from openTransaction()
Throws:
OntologyManagerException - if the transaction could not be committed successfully
See Also:
openTransaction(Object)

rollbackTransaction

public void rollbackTransaction(Object scope,
                                Object ta)
                         throws OntologyManagerException
Rolls the transaction back for the given scope. You must pass the exact return value from openTransaction() to this method.

Parameters:
scope - the scope for this transaction
ta - the return value from openTransaction()
Throws:
OntologyManagerException - if the transaction could not be rolled back successfully
See Also:
openTransaction(Object)

abortTransaction

public void abortTransaction(Object scope,
                             Object ta)
This is a "quick rollback" for the transaction if no changes have been made to the ontology. Use with caution, especially if the implementation does not support scopes and other scopes might have changed the ontology.

Parameters:
scope - the scope for this transaction
ta - the return value from openTransaction()
See Also:
openTransaction(Object)

addExportHandler

public void addExportHandler(ExportHandler handler)
Registers an ExportHandler instance with the OntologyManager. Usually you don't call this method explicitely but declare the handler classes in ConsensusFoundation.properties.

For each file format, only one export handler can be registered. Registering a format again replaces the older handler.

Parameters:
handler - the ExportHandler to be added to the OntologyManager's list of export handlers
See Also:
ExportHandler

getExportHandler

public ExportHandler getExportHandler(String format)
Returns an export handler for a certain file format.

Parameters:
format - the required file format (e.g. "xtm")
Returns:
the ExportHandler or null if no export handler exists for the required format
See Also:
addExportHandler(ExportHandler)

getExportHandlers

public Iterator getExportHandlers()
Returns all export handlers.

Returns:
an Iterator over all export handlers
See Also:
addExportHandler(ExportHandler)

getExportHandlerCount

public int getExportHandlerCount()
Returns the number of registered export handlers.

Returns:
the number of export handlers
See Also:
addExportHandler(ExportHandler)

addImportHandler

public void addImportHandler(ImportHandler handler)
Registers an ImportHandler instance with the OntologyManager. Usually you don't call this method explicitely but declare the handler classes in ConsensusFoundation.properties.

For each file format, only one import handler can be registered. Registering a format again replaces the older handler.

Parameters:
handler - the ImportHandler to be added to the OntologyManager's list of import and merge handlers
See Also:
ImportHandler

getImportHandler

public ImportHandler getImportHandler(String format)
Returns an import handler for a certain file format.

Parameters:
format - the required file format (e.g. "xtm")
Returns:
the ImportHandler or null if no import handler exists for the required format
See Also:
addImportHandler(ImportHandler)

getMergeHandler

public ImportHandler getMergeHandler(String format)
Returns an import handler for a certain file format that can merge ontologies in this format.

Parameters:
format - the required file format (e.g. "xtm")
Returns:
the ImportHandler or null if no import handler exists that can merge ontologies in the required format
See Also:
addImportHandler(ImportHandler)

getImportHandlers

public Iterator getImportHandlers()
Returns all import handlers.

Returns:
an Iterator over all import handlers
See Also:
addImportHandler(ImportHandler)

getMergeHandlers

public Iterator getMergeHandlers()
Returns all import handlers that can merge ontologies.

Returns:
an Iterator over all import handlers that can merge ontologies
See Also:
addImportHandler(ImportHandler)

getImportHandlerCount

public int getImportHandlerCount()
Returns the number of registered import handlers.

Returns:
the number of import handlers
See Also:
addImportHandler(ImportHandler)

getMergeHandlerCount

public int getMergeHandlerCount()
Returns the number of registered import handlers that can merge ontologies.

Returns:
the number of import handlers that can merge ontologies
See Also:
addImportHandler(ImportHandler)

reorg

public boolean reorg()
              throws OntologyManagerException
If the ontology needs reorganization from time to time, the implementation can clean up the ontology when an application calls this method. The implementation should try to reorganize the ontology asynchronously and not to pause the running application.

Returns:
true if the reorganization was started due to this call or false if an older reorganization is still running
Throws:
OntologyManagerException - if the reorganization could not be finished successfully

addOntologyListener

public void addOntologyListener(OntologyListener listener)
Registers a new OntologyListener.

Parameters:
listener - the OntologyListener to be added

removeOntologyListener

public void removeOntologyListener(OntologyListener listener)
Removes an OntologyListener, if it is registered with the OntologyManager (otherwise this call is ignored).

Parameters:
listener - the OntologyListener to be removed