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 is a mixin interface for attributeable elements of the ontology.
 * With the current schema definition, only topics are attributeable.
 * @author Thomas Much
 * @version 2006-06-14
 * @see Topic
 */
public interface Attributeable extends Serializable {

	/**
	 * Adds an attribute object to the attributeable element.
	 * @param setter the user who wants to add the attribute
	 * @param attr the Attribute object
	 * @throws OntologyManagerException if the attribute could not be added
	 * @throws DynamicRightsManagerException if the user is not allowed to add the attribute
     * @see de.uka.ipd.consensus.foundation.ontology.OntologyManager#createAttribute(User, String, String, String, Topic)
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayAddAttribute(User, Attribute, Attributeable)
	 */
	public void addAttribute(User setter, Attribute attr) throws OntologyManagerException,DynamicRightsManagerException;
	
	
	/**
	 * Removes the given attribute, if the object is an attribute of this element (otherwise, the call is ignored).
	 * @param remover the user who wants to remove the attribute
	 * @param attr the Attribute object to be removed
	 * @throws OntologyManagerException if the attribute could not be removed
	 * @throws DynamicRightsManagerException if the user is not allowed to remove the attribute
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayRemoveAttribute(User, Attribute)
	 */
	public void removeAttribute(User remover, Attribute attr) throws OntologyManagerException,DynamicRightsManagerException;

	
	/**
	 * Returns a collection of all Attribute objects of this element that the user may see.
	 * @param getter the user who wants to see the attributes
	 * @return a possibly empty collection, never <code>null</code>
	 * @see Attribute
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayViewAttribute(User, Attribute)
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayViewTopic(User, Topic)
	 */
	public Collection getAttributes(User getter);
	
	
	/**
	 * Returns a collection of all Attribute objects of the given type.
	 * @param getter the user who wants to see the attributes
	 * @param type type the type topic of the attributes, including <code>null</code> for the typeless attributes
	 * @return a possibly empty collection, never <code>null</code>
	 * @see Attribute
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayViewAttribute(User, Attribute)
	 */
	public Collection getAttributes(User getter, Topic type);
	
	
	/**
	 * Returns the attribute of a given id.
	 * @param getter the user who wants to get the attribute
	 * @param id the id in question
	 * @return the attribute with the id or <code>null</code> if this element does not have an attribute with the id
	 * @see Concept#getId()
	 * @see de.uka.ipd.consensus.foundation.rights.DynamicRightsManager#mayViewAttribute(User, Attribute)
	 */
	public Attribute  getAttribute(User getter, String id);

}
