Source for file Topic.interface.php

<?php
/**
 * @package org.phptmapi.core
*/
require_once('TopicMapObject.interface.php');
/**
 * @package org.tmapi.core
*/
/**
 * Interface TopicInterface: Represents the topic map topic construct.
 *
 * @author Johannes Schmidt, Andreas Stephan - t8d <kontakt@t8d.de>
*/
interface TopicInterface extends TopicMapObjectInterface{
    /**
    * addSubjectLocator: Adds the specified locator to the locators that reference the subject-constituting resources of this topic.
    * @param string $subjectLocator 
    * @access public
    * @return void 
    * @throws ModelConstraintException - if the XTM 1.0 processor model is enabled and this Topic already has one Locator in the subjectLocator set.
    * @throws MergeException - if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason.
    *  <code>
    *      public function addSubjectLocator($subjectLocator){
    *         throw new ModelConstraintException('Exception in '.__method__);
    *          throw new MergeException('Exception in '.__method__);
    *      }
    *  </code>
    */
    public function addSubjectLocator($subjectLocator);
    
    /**
    * addType: Adds a type to this topic.
    * @access public
    * @param object TopicInterface $type The type-defining topic to be added.
    * @return void 
    */
    public function addType(TopicInterface $type);
    
    /**
    * createOccurrence: Creates a new occurrence as a contained object in this topic.
    * @access public
    * @param string $value The occurrence data.
    * @param string $datatype An XML Schema Datatype.
    * @param object TopicInterface $type The occurrence type. If null, then the occurrence will be untyped.
    * @param array $scope An array of TopicInterface objects. If null, the occurrence will be in the unconstrained scope.
    * @return object OccurrenceInterface 
    */
    public function createOccurrence($value, $datatype, $type, $scope);        
 
    /**
    * createUntypedTopicName: Creates a new untyped name for this topic.
    * @access public
    * @param string $value The string value of the topic name. Pass null to create a topic name with no name value.
    * @param array $scope An array of TopicInterface objects. If null, the topic name will be in the unconstrained scope.
    * @return object TopicNameInterface 
    * @throws MergeException - if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason. NOTE: This method will not raise this exception if the XTM 1.1 model is enabled, as untyped names do not cause merging under XTM 1.1.
    *  <code>
    *      public function createTopicName($value, $scope){
    *          throw new MergeException('Exception in '.__method__);
    *      }
    *  </code>
    */
    public function createUntypedTopicName($value, $scope);
    
    /**
    * createTopicName: Creates a new typed topic name for this topic.
    * @access public
    * @param string $value The string value of the topic name. Pass null to create a topic name with no name value.
    * @param object TopicInterface $type A TopicInterface instance or null.
    * @param array $scope An array of TopicInterface objects. If null, the topic name will be in the unconstrained scope.
    * @return object TopicNameInterface 
    * @throws MergeException - if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason.
    * @throws UnsupportedOperationException - if the processor does not support the XTM 1.1 model.
    *  <code>
    *      public function createTopicName($value, $scope){
    *          throw new MergeException('Exception in '.__method__);
    *      }
    *      public function createTopicName($value, $scope){
    *          throw new UnsupportedOperationException('Exception in '.__method__);
    *      }
    *  </code>
    */
    public function createTopicName($value, $type, $scope);
 
    /**
    * getOccurrences: Returns the occurrences defined for this topic. The return value may be an empty array, but is never null.
    * @access public
    * @return array An unmodifiable array of OccurrenceInterface objects.
    */
    public function getOccurrences();
 
    /**
    * getReified: Returns an array of TopicMapObjectInterface instances that are subject of this topic. The return value may be an empty array, but is never null.
    * @access public
    * @return array 
    */
    public function getReified();
 
    /**
    * Returns the association roles in which this topic is a player. The return value may be an empty array, but is never null.
    * @access public
    * @return array An unmodifiable array of AssociationRoleInterface objects.
    */
    public function getRolesPlayed();
 
    /**
    * getSubjectIdentifiers: Returns the locators which reference the subject-indicating resources of this topic. The return value may be an empty array, but is never null.
    * @access public
    * @return array An unmodifiable array of locators.
    */
    public function getSubjectIdentifiers();
 
    /**
    * getSubjectLocators: Returns locators which reference the subject-constituting resources of this topic. The return value may be an empty array, but is never null.
    * @access public
    * @return array An unmodifiable array of locators.
    */
    public function getSubjectLocators();
 
    /**
    * getTopicNames: Returns the topic names defined for this topic. The return value may be an empty array, but is never null.
    * @access public
    * @return array An unmodifiable array of TopicNameInterface objects.
    */
    public function getTopicNames();
 
    /**
    * Returns the topics which define the types of this topic. The return value may be an empty array, but is never null.
    * @access public
    * @return array An unmodifiable array of TopicInterface objects.
    */
    public function getTypes();
    
    /**
    * mergeIn: Merges another topic into this topic. Merging a topic into this topic causes this topic to gain all of the characteristics of the other topic and to replace the other topic wherever it is used as a typing or scoping topic. After this method completes, other  will have been removed from the topic map. NOTE: The other topic MUST belong to the same topic map instance as this topic!
    * @access public
    * @param object TopicInterface $other 
    * @return void 
    * @throws MergeException
    * @throws SubjectLocatorClashException if this topic and other have different, non-null values for the subject locator property and the XTM 1.0 processing model is enabled.
    *  <code>
    *     public function mergeIn(TopicInterface $other){
    *         throw new MergeException('Exception in '.__method__);
    *          throw new SubjectLocatorClashException('Exception in '.__method__);
    *     }
    *  </code>
    */
    public function mergeIn(TopicInterface $other);
    
    /**
    * addSubjectIdentifier: Adds the specified locator to the locators that reference the subject-indicating resources of this topic.
    * @access public
    * @param string $subjectIdentifier 
    * @return void 
    * @throws MergeException if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason.
    *  <code>
    *      public function addSubjectIdentifier($subjectIdentifier){
    *         throw new MergeException('Exception in '.__method__);
    *      }
    *  </code>
    */
    public function addSubjectIdentifier($subjectIdentifier);
 
    /**
    * removeSubjectIdentifier: Removes the specified locator from the set of locators that reference the subject-indicating resources of this topic.
    * @access public
    * @param string $subjectIdentifier 
    * @return void 
    */
    public function removeSubjectIdentifier($subjectIdentifier);
 
    /**
    * removeSubjectLocator: Removes the specified locator from the set of locators that reference the subject-constituting resources of this topic.
    * @access public
    * @param string $subjectLocator 
    * @return void 
    */
    public function removeSubjectLocator($subjectLocator);
 
    /**
    * removeType: Removes a type from this topic.
    * @access public
    * @param object TopicInterface $type 
    * @return void 
    */
    public function removeType(TopicInterface $type);
}
?>