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.xml.sax.ContentHandler;
024import org.xml.sax.SAXException;
025
026import org.ametys.cms.content.references.OutgoingReferences;
027import org.ametys.core.user.UserIdentity;
028import org.ametys.plugins.explorer.resources.ResourceCollection;
029import org.ametys.plugins.repository.AmetysRepositoryException;
030import org.ametys.plugins.repository.ModifiableACLAmetysObject;
031import org.ametys.plugins.repository.data.UnknownDataException;
032import org.ametys.plugins.repository.data.ametysobject.ModelAwareDataAwareAmetysObject;
033import org.ametys.plugins.repository.data.holder.DataHolder;
034import org.ametys.plugins.repository.data.holder.ModifiableModelLessDataHolder;
035import org.ametys.plugins.repository.dublincore.DublinCoreAwareAmetysObject;
036import org.ametys.plugins.repository.metadata.MetadataAwareAmetysObject;
037import org.ametys.plugins.repository.tag.TagAwareAmetysObject;
038import org.ametys.runtime.model.View;
039
040/**
041 * Content abstraction defined by the following properties:
042 * <dl>
043 *   <dt>type
044 *   <dd>the content type (can only be set on creation)
045 *   <dt>language
046 *   <dd>the language (can only be set on creation)
047 *   <dt>title
048 *   <dd>the title
049 *   <dt>creator
050 *   <dd>the login of the creator
051 *   <dt>creationDate
052 *   <dd>the date when the content was created
053 *   <dt>lastContributor
054 *   <dd>the login of the last contributor
055 *   <dt>lastModified
056 *   <dd>the date when the last modification takes place
057 * </dl>
058 */
059public interface Content extends ModelAwareDataAwareAmetysObject, MetadataAwareAmetysObject, DublinCoreAwareAmetysObject, TagAwareAmetysObject, ModifiableACLAmetysObject
060{
061    /** Constants for title attribute */
062    public static final String ATTRIBUTE_TITLE = "title";
063    
064    /** 
065     * Constants for title Metadata 
066     * Use ATTRIBUTE_TITLE
067     */
068    @Deprecated
069    public static final String METADATA_TITLE = "title";
070
071    /**
072     * Retrieves the type identifiers of this content.
073     * @return the type identifiers of this content.
074     * @throws AmetysRepositoryException if an error occurs.
075     */
076    public String[] getTypes() throws AmetysRepositoryException;
077    
078    /**
079     * Set the type of this content
080     * @param type the type to set
081     * @throws AmetysRepositoryException if an error occurs.
082     */
083    public void setType(String type) throws AmetysRepositoryException;
084    
085    /**
086     * Set the types of this Content.<br>
087     * @param types the types of this content.
088     * @throws AmetysRepositoryException if an error occurs.
089     */
090    public void setTypes(String[] types) throws AmetysRepositoryException;
091    
092    /**
093     * Retrieves the mixin type identifiers of this content.
094     * @return the mixin type identifiers of this content.
095     * @throws AmetysRepositoryException  if an error occurs.
096     */
097    public String[] getMixinTypes() throws AmetysRepositoryException;
098    
099    /**
100     * Set the mixins of this Content.<br>
101     * @param mixins the mixins of this content.
102     * @throws AmetysRepositoryException if an error occurs.
103     */
104    public void setMixinTypes(String[] mixins) throws AmetysRepositoryException;
105    
106    /**
107     * Retrieves the language of this content.<br>
108     * @return the language of this content or <code>null</code> if the content is a multilingual content
109     * @throws AmetysRepositoryException if an error occurs.
110     */
111    public String getLanguage() throws AmetysRepositoryException;
112
113    /**
114     * Set the type of this Content.<br>
115     * This method may only be called on a new Content, ie. before its first save.
116     * @param language the language of this content.
117     * @throws AmetysRepositoryException if an error occurs.
118     */
119    public void setLanguage(String language) throws AmetysRepositoryException;
120    
121    /**
122     * Retrieves the title for the given locale. If the locale is null or does not exist, the first locale will be used.
123     * @param locale The locale. Can be null if the content is not a multilingual content or to get the title in the default locale.
124     * @return the title.
125     * @throws UnknownDataException if this property does not exist.
126     * @throws AmetysRepositoryException if an error occurs.
127     */
128    public String getTitle(Locale locale) throws UnknownDataException, AmetysRepositoryException;
129    
130    /**
131     * Retrieves the title.
132     * This method is same as {@link #getTitle(Locale)} with a null locale.
133     * Use this method only if you are manipulating no-multilingual content. If not sure, use {@link #getTitle(Locale)} instead.
134     * @return the title.
135     * @throws UnknownDataException if this property does not exist.
136     * @throws AmetysRepositoryException if an error occurs.
137     */
138    public String getTitle() throws UnknownDataException, AmetysRepositoryException;
139
140    /**
141     * Retrieves the login of the creator.
142     * @return the login of the creator.
143     * @throws UnknownDataException if this property does not exist.
144     * @throws AmetysRepositoryException if an error occurs.
145     */
146    public UserIdentity getCreator() throws UnknownDataException, AmetysRepositoryException;
147    
148    /**
149     * Retrieves the creation date.
150     * @return the creation date.
151     * @throws UnknownDataException if this property does not exist.
152     * @throws AmetysRepositoryException if an error occurs.
153     */
154    public Date getCreationDate() throws UnknownDataException, AmetysRepositoryException;
155    
156    /**
157     * Retrieves the login of the last contributor.
158     * @return the login of the last contributor.
159     * @throws UnknownDataException if this property does not exist.
160     * @throws AmetysRepositoryException if an error occurs.
161     */
162    public UserIdentity getLastContributor() throws UnknownDataException, AmetysRepositoryException;
163    
164    /**
165     * Retrieves the last modification date.
166     * @return the last modification date.
167     * @throws UnknownDataException if this property does not exist.
168     * @throws AmetysRepositoryException if an error occurs.
169     */
170    public Date getLastModified() throws UnknownDataException, AmetysRepositoryException;
171
172    /**
173     * Retrieves the first validation date
174     * @return the first validation date
175     * @throws UnknownDataException if this property does not exist.
176     * @throws AmetysRepositoryException if an error occurs.
177     */
178    public Date getFirstValidationDate() throws UnknownDataException, AmetysRepositoryException;
179    
180    /**
181     * Retrieves the last validation date
182     * @return the last validation date
183     * @throws UnknownDataException if this property does not exist.
184     * @throws AmetysRepositoryException if an error occurs.
185     */
186    public Date getLastValidationDate() throws UnknownDataException, AmetysRepositoryException;
187    
188    /**
189     * Retrieves the last validation date resulting from a major modification. At least this is the first validation date
190     * @return the last validation date resulting from a major modification
191     * @throws UnknownDataException if this property does not exist.
192     * @throws AmetysRepositoryException if an error occurs.
193     */
194    public Date getLastMajorValidationDate () throws UnknownDataException, AmetysRepositoryException;
195    
196    /**
197     * Returns all Contents referencing this Content (as a metadata).
198     * @return all Contents referencing this Content.
199     * @throws AmetysRepositoryException if an error occurs.
200     */
201    public Collection<Content> getReferencingContents() throws AmetysRepositoryException;
202    
203    /**
204     * Returns <code>true</code> if there is at least one Content referencing this Content (as a metadata).
205     * @return <code>true</code> if there is at least one Content referencing this Content.
206     * @throws AmetysRepositoryException if an error occurs.
207     */
208    public boolean hasReferencingContents() throws AmetysRepositoryException;
209    
210    /**
211     * Get the stored outgoing references of the content. This references can be used for different purposes, such as testing link consistency for example.
212     * @return A non null map of outgoing references grouped by metadata (key are metadata path)
213     * @throws AmetysRepositoryException if an error occurs.
214     */
215    public Map<String, OutgoingReferences> getOutgoingReferences() throws AmetysRepositoryException;
216
217    /**
218     * Retrieves the attachments root node
219     * @return The attachments root node, or null if the content is working on
220     * an (unmodifiable) old version and the attachments root is missing.
221     * @throws AmetysRepositoryException if an error occurs.
222     */
223    public ResourceCollection getRootAttachments() throws AmetysRepositoryException;
224    
225    /**
226     * Generates SAX events representing this Content.
227     * @param contentHandler the {@link ContentHandler} that will receive the SAX events.
228     * @param locale the {@link Locale} to use for eg. multilingual attributes.
229     * @param view the associated View, or null to generate SAX events for all attributes from the model.
230     * @param saxWorkflowStep if true, also generates SAX events for the current workflow step.
231     * @throws SAXException if an error occurs during the SAX events generation.
232     */
233    public void toSAX(ContentHandler contentHandler, Locale locale, View view, boolean saxWorkflowStep) throws SAXException;
234    
235    /**
236     * Returns the {@link DataHolder} for internal data of this {@link Content}.
237     * @return the {@link DataHolder} for internal data of this {@link Content}
238     */
239    public ModifiableModelLessDataHolder getInternalDataHolder();
240}