Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD