001/*
002 *  Copyright 2010 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.cms.repository;
017
018import java.util.Collection;
019import java.util.Date;
020import java.util.Locale;
021import java.util.Map;
022
023import org.ametys.cms.content.references.OutgoingReferences;
024import org.ametys.core.user.UserIdentity;
025import org.ametys.plugins.explorer.resources.ResourceCollection;
026import org.ametys.plugins.repository.AmetysRepositoryException;
027import org.ametys.plugins.repository.ModifiableACLAmetysObject;
028import org.ametys.plugins.repository.data.UnknownDataException;
029import org.ametys.plugins.repository.data.ametysobject.ModelAwareDataAwareAmetysObject;
030import org.ametys.plugins.repository.data.holder.ModelAwareDataHolder;
031import org.ametys.plugins.repository.dublincore.DublinCoreAwareAmetysObject;
032import org.ametys.plugins.repository.metadata.MetadataAwareAmetysObject;
033import org.ametys.runtime.model.ModelItem;
034
035/**
036 * Content abstraction defined by the following properties:
037 * <dl>
038 *   <dt>type
039 *   <dd>the content type (can only be set on creation)
040 *   <dt>language
041 *   <dd>the language (can only be set on creation)
042 *   <dt>title
043 *   <dd>the title
044 *   <dt>creator
045 *   <dd>the login of the creator
046 *   <dt>creationDate
047 *   <dd>the date when the content was created
048 *   <dt>lastContributor
049 *   <dd>the login of the last contributor
050 *   <dt>lastModified
051 *   <dd>the date when the last modification takes place
052 * </dl>
053 */
054public interface Content extends ModelAwareDataAwareAmetysObject, MetadataAwareAmetysObject, DublinCoreAwareAmetysObject, TagAwareAmetysObject, ModifiableACLAmetysObject
055{
056    /** Constants for title attribute */
057    public static final String ATTRIBUTE_TITLE = "title";
058    
059    /** 
060     * Constants for title Metadata 
061     * Use ATTRIBUTE_TITLE
062     */
063    @Deprecated
064    public static final String METADATA_TITLE = "title";
065
066    /**
067     * Retrieves the types of this content.
068     * @return the types of this content.
069     * @throws AmetysRepositoryException if an error occurs.
070     */
071    public String[] getTypes() throws AmetysRepositoryException;
072    
073    /**
074     * Retrieves the mixin types of this content.
075     * @return the mixin types of this content.
076     * @throws AmetysRepositoryException  if an error occurs.
077     */
078    public String[] getMixinTypes() throws AmetysRepositoryException;
079    
080    /**
081     * Retrieves the language of this content.<br>
082     * @return the language of this content or <code>null</code> if the content is a multilingual content
083     * @throws AmetysRepositoryException if an error occurs.
084     */
085    public String getLanguage() throws AmetysRepositoryException;
086    
087    /**
088     * Retrieves the title for the given locale. If the locale is null or does not exist, the first locale will be used.
089     * @param locale The locale. Can be null if the content is not a multilingual content or to get the title in the default locale.
090     * @return the title.
091     * @throws UnknownDataException if this property does not exist.
092     * @throws AmetysRepositoryException if an error occurs.
093     */
094    public String getTitle(Locale locale) throws UnknownDataException, AmetysRepositoryException;
095    
096    /**
097     * Retrieves the title.
098     * This method is same as {@link #getTitle(Locale)} with a null locale.
099     * Use this method only if you are manipulating no-multilingual content. If not sure, use {@link #getTitle(Locale)} instead.
100     * @return the title.
101     * @throws UnknownDataException if this property does not exist.
102     * @throws AmetysRepositoryException if an error occurs.
103     */
104    public String getTitle() throws UnknownDataException, AmetysRepositoryException;
105
106    /**
107     * Retrieves the login of the creator.
108     * @return the login of the creator.
109     * @throws UnknownDataException if this property does not exist.
110     * @throws AmetysRepositoryException if an error occurs.
111     */
112    public UserIdentity getCreator() throws UnknownDataException, AmetysRepositoryException;
113    
114    /**
115     * Retrieves the creation date.
116     * @return the creation date.
117     * @throws UnknownDataException if this property does not exist.
118     * @throws AmetysRepositoryException if an error occurs.
119     */
120    public Date getCreationDate() throws UnknownDataException, AmetysRepositoryException;
121    
122    /**
123     * Retrieves the login of the last contributor.
124     * @return the login of the last contributor.
125     * @throws UnknownDataException if this property does not exist.
126     * @throws AmetysRepositoryException if an error occurs.
127     */
128    public UserIdentity getLastContributor() throws UnknownDataException, AmetysRepositoryException;
129    
130    /**
131     * Retrieves the last modification date.
132     * @return the last modification date.
133     * @throws UnknownDataException if this property does not exist.
134     * @throws AmetysRepositoryException if an error occurs.
135     */
136    public Date getLastModified() throws UnknownDataException, AmetysRepositoryException;
137
138    /**
139     * Retrieves the first validation date
140     * @return the first validation date
141     * @throws UnknownDataException if this property does not exist.
142     * @throws AmetysRepositoryException if an error occurs.
143     */
144    public Date getFirstValidationDate() throws UnknownDataException, AmetysRepositoryException;
145    
146    /**
147     * Retrieves the last validation date
148     * @return the last validation date
149     * @throws UnknownDataException if this property does not exist.
150     * @throws AmetysRepositoryException if an error occurs.
151     */
152    public Date getLastValidationDate() throws UnknownDataException, AmetysRepositoryException;
153    
154    /**
155     * Retrieves the last validation date resulting from a major modification. At least this is the first validation date
156     * @return the last validation date resulting from a major modification
157     * @throws UnknownDataException if this property does not exist.
158     * @throws AmetysRepositoryException if an error occurs.
159     */
160    public Date getLastMajorValidationDate () throws UnknownDataException, AmetysRepositoryException;
161    
162    /**
163     * Returns all Contents referencing this Content (as a metadata).
164     * @return all Contents referencing this Content.
165     * @throws AmetysRepositoryException if an error occurs.
166     */
167    public Collection<Content> getReferencingContents() throws AmetysRepositoryException;
168    
169    /**
170     * Returns <code>true</code> if there is at least one Content referencing this Content (as a metadata).
171     * @return <code>true</code> if there is at least one Content referencing this Content.
172     * @throws AmetysRepositoryException if an error occurs.
173     */
174    public boolean hasReferencingContents() throws AmetysRepositoryException;
175    
176    /**
177     * Get the stored outgoing references of the content. This references can be used for different purposes, such as testing link consistency for example.
178     * @return A non null map of outgoing references grouped by metadata (key are metadata path)
179     * @throws AmetysRepositoryException if an error occurs.
180     */
181    public Map<String, OutgoingReferences> getOutgoingReferences() throws AmetysRepositoryException;
182
183    /**
184     * Retrieves the attachments root node
185     * @return The attachments root node, or null if the content is working on
186     * an (unmodifiable) old version and the attachments root is missing.
187     * @throws AmetysRepositoryException if an error occurs.
188     */
189    public ResourceCollection getRootAttachments() throws AmetysRepositoryException;
190    
191    /**
192     * Retrieves the definition of the data at the given path
193     * @param dataPath path of the data
194     * @return the definition of the data. <code>null</code> if there is no item defined at this path.
195     * TODO NEWATTRIBUTEAPI_CONTENT: Move this method in {@link ModelAwareDataHolder}
196     */
197    public ModelItem getDefinition(String dataPath);
198}