/*
 *  Copyright 2010 Anyware Services
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.ametys.cms.contenttype;

import java.util.List;
import java.util.Map;
import java.util.Set;

import org.xml.sax.ContentHandler;
import org.xml.sax.SAXException;

import org.ametys.cms.contenttype.indexing.IndexingModel;
import org.ametys.cms.repository.Content;
import org.ametys.plugins.repository.AmetysRepositoryException;

/**
 * This class represents a type of content.
 */
public interface ContentType extends ContentTypeDescriptor, MetadataDefinitionHolder
{
    /** Tag for private content type */
    public static final String TAG_PRIVATE = "private";
    
    /** Tag for simple content type */
    public static final String TAG_SIMPLE = "simple";
    
    /** Tag for simple content type */
    public static final String TAG_MIXIN = "mixin";
    
    /**
     * Called by the extension point when the content type hierarchy has been computed.
     * Can be used to do more initialization, checks, ...
     * @throws Exception if an error occurs of if an additional check fails.
     */
    void postInitialize() throws Exception;
    
    /**
     * Retrieves the potential global validators.
     * @return the global validators or an empty List if none.
     */
    List<ContentValidator> getGlobalValidators();
    
    /**
     * Retrieves the RichText updater
     * @return the RichText updater or <code>null</code> if none.
     */
    RichTextUpdater getRichTextUpdater();
    
    /**
     * Get the indexing model
     * @return the indexing model
     */
    IndexingModel getIndexingModel();
    
    /** 
     * Retrieves the definition of a given metadata by its path. 
     * @param metadataPath the metadata path, separated by '/'
     * @return the metadata definition or <code>null</code> if not found 
     */ 
    MetadataDefinition getMetadataDefinitionByPath(String metadataPath);
    
    /**
     * Determines if the definition of a given metadata exists.
     * @param metadataName the metadata name.
     * @return <code>true</code> if the metadata definition exists
     */
    boolean hasMetadataDefinition(String metadataName);
    
    /**
     * Determine whether a metadata can be read at this time.
     * @param metadataDef the metadata definition
     * @param content The content where metadata is to be read on. Can be null, on content creation. 
     * @return <code>true</code> if the current user is allowed to read the metadata of this content.
     * @throws AmetysRepositoryException if an error occurs while accessing the content.
     */
    public boolean canRead(Content content, MetadataDefinition metadataDef) throws AmetysRepositoryException;

    /**
     * Determine whether a metadata can be written at this time.
     * @param metadataDef the metadata definition
     * @param content The content where metadata is to be written on. Can be null, on content creation. 
     * @return <code>true</code> if the current user is allowed to write the metadata of this content.
     * @throws AmetysRepositoryException if an error occurs while accessing the content.
     */
    public boolean canWrite(Content content, MetadataDefinition metadataDef) throws AmetysRepositoryException;
    
    /**
     * Get the registered tags for this content types
     * @return the tags
     */
    public Set<String> getTags ();
    
    /**
     * Determines if the content type has the given tag
     * @param tagName The tag name
     * @return true if the content type is tagged with the given tag name
     */
    public boolean hasTag (String tagName);
    
    /**
     * Get whether the content type is private, i.e. should not be created by
     * the regular content interface.
     * @return true if the content is private, false if it is public.
     */
    public boolean isPrivate();
    
    /**
     * Get whether the content type is simple, i.e. should contains only simple metadata type to be edited in a grid.
     * @return true if the content is simple, false otherwise
     */
    public boolean isSimple();
    
    /**
     * Get whether the content type is abstract, i.e. should not be created by the regular content interface.
     * @return true if the content is abstract, false otherwise.
     */
    public boolean isAbstract();
    
    /**
     * Get whether the content type is a mixin, i.e. should used to add metadata to a existing content.
     * @return true if the content is mixin, false otherwise.
     */
    public boolean isMixin();
    
    /**
     * Get the right needed to create a content of this type.
     * @return the right needed to create a content of this type. If null is returned, no right is needed.
     */
    public String getRight();
    
    /**
     * SAX the additional content data linked to its {@link ContentType}
     * These additional data will be available in content view
     * @param contentHandler The handler to SAX into
     * @param content The content
     * @throws AmetysRepositoryException if an error occurs while accessing the content.
     * @throws SAXException if an error occurs while SAXing
     */
    public void saxContentTypeAdditionalData (ContentHandler contentHandler, Content content) throws AmetysRepositoryException, SAXException;
    
    /**
     * Get the additional data relative to its {@link ContentType}.
     * These additional data are delivered to client side.
     * @param content The content
     * @return the additional properties in a Map
     */
    public Map<String, Object> getAdditionalData (Content content);
}