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

import java.io.Serializable;
import java.util.Collection;

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

/**
 * This interface represents one role of an association.
 * @author Thomas Much
 * @version 2006-06-14
 * @see Association
 */
public interface AssociationRole extends Serializable,Comparable {

	/**
	 * Returns the association that this role belongs to.
	 * @return the association that this role belongs to, never <code>null</code>
	 */
	public Association getAssociation();

	
	/**
	 * Returns the type topic of this role.
	 * @return the type topic or <code>null</code> if the role does not have a type
	 */
	public Topic getType();

	
	/**
	 * Sets the type of the role. 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#mayChangeAssociation(User, Association)
	 */
	public void setType(User setter, Topic type) throws OntologyManagerException,DynamicRightsManagerException;

	
	/**
	 * Checks if this role is of the given type.
	 * @param type the type topic,  including <code>null</code> for the typeless role
	 * @return <code>true</code> if the role is of the specified type, <code>false</code> otherwise
	 */
	public boolean isOfType(Topic type);


	/**
	 * Returns the name of this role's type.
	 * @return the name of this role's type or the empty string if this role does not have a type (never <code>null</code>)
	 * @see Concept#getName()
	 */
	public String getName();

	
	/**
	 * Returns the player Topic objects of this role.
	 * @param user the user who wants to see the topics
	 * @return a possibly empty collection, never <code>null</code>
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayViewTopic(User, Topic)
	 */
	public Collection getTopics(User user);
	
	
	/**
	 * Adds a topic to this role.
	 * @param adder the user who wants to add the topic
	 * @param topic the topic to be added
	 * @throws OntologyManagerException if the topic could not be added
	 * @throws DynamicRightsManagerException if the user is not allowed to add the topic
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayChangeAssociation(User, Association)
	 */
	public void addTopic(User adder, Topic topic) throws OntologyManagerException,DynamicRightsManagerException;
	
	
	/**
	 * Removes a topic from this role.
	 * @param remover the user who wants to remove the topic.
	 * @param topic the topic to be removed
	 * @throws OntologyManagerException if the topic could not be removed
	 * @throws DynamicRightsManagerException if the user is not allowed to remove the topic
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayChangeAssociation(User, Association)
	 */
	public void removeTopic(User remover, Topic topic) throws OntologyManagerException,DynamicRightsManagerException;
	
	
	/**
	 * Checks if the given topic is a player of this role.
	 * @param topic the topic in question
	 * @return <code>true</code> if the topic is player of this role, <code>false</code> otherwise
	 */
	public boolean hasTopic(Topic topic);

}
