package de.uka.ipd.consensus.foundation.schema;

import java.io.Serializable;

import de.uka.ipd.consensus.foundation.ontology.OntologyManagerException;
import de.uka.ipd.consensus.foundation.rights.DynamicRightsManagerException;

/**
 * This interface represents an occurrence of a topic.
 * @author Thomas Much
 * @version 2006-06-14
 * @see Topic
 * @see Topic#addOccurrence(User, String, Topic)
 */
public interface Occurrence extends Serializable, Comparable {
	
	/**
	 * Returns the id of the occurrence.
	 * @return the id of the occurrence that is computed automatically at creation time
	 */
	public String getId();
	
	
	/**
	 * Returns the topic that this occurrence belongs to.
	 * @return the Topic object
	 */
	public Topic getTopic();

	
	/**
	 * Returns the value of this occurrence.
	 * This may be some kind of a comment or a URL of a web resource.
	 * @return the value of the occurrence (may be the empty string, never <code>null</code>)
	 */
	public String getData();
	
	
	/**
	 * Changes the value of the occurrence.
	 * @param setter the user who wants to change the value
	 * @param data the new value
	 * @throws OntologyManagerException if the value could not be changed
	 * @throws DynamicRightsManagerException if the user is not allowed to change the value
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayChangeOccurrence(User)
	 */
	public void setData(User setter, String data) throws OntologyManagerException,DynamicRightsManagerException;

	
	/**
	 * Returns the type topic of this occurrence.
	 * @return the type topic or <code>null</code> if the occurrence does not have a type
	 */
	public Topic getType();
	
	
	/**
	 * Sets the type of the occurrence. If the implementation supports classes, the type must be a class topic.
	 * @param setter the user who wants to set the type
	 * @param type the type topic (or <code>null</code> to remove the type)
	 * @throws OntologyManagerException if the type could not be set
	 * @throws DynamicRightsManagerException if the user is not allowed to change the type
	 * @see Topic#isClassTopic()
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayChangeOccurrence(User)
	 */
	public void setType(User setter, Topic type) throws OntologyManagerException,DynamicRightsManagerException;
	
	
	/**
	 * Checks if this occurrence is of the given type.
	 * @param type the type topic,  including <code>null</code> for typeless occurrences
	 * @return <code>true</code> if the occurrence is of the specified type, <code>false</code> otherwise
	 */
	public boolean isOfType(Topic type);

}
