001/*
002 * (C) Copyright 2006-20012 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Nuxeo - initial API and implementation
016 *
017 */
018
019package org.nuxeo.template.api.adapters;
020
021import java.util.List;
022
023import org.nuxeo.ecm.core.api.Blob;
024import org.nuxeo.ecm.core.api.DocumentModel;
025import org.nuxeo.ecm.core.api.PropertyException;
026import org.nuxeo.template.api.TemplateInput;
027import org.nuxeo.template.api.TemplateProcessor;
028
029/**
030 * It is mainly the source used by {@link TemplateBasedDocument} to handle the rendering.
031 *
032 * @author Tiry (tdelprat@nuxeo.com)
033 */
034public interface TemplateSourceDocument {
035
036    public static final String INIT_DONE_FLAG = "TEMPLATE_INIT_DONE";
037
038    /**
039     * Return the String representation of the parameters of the template
040     *
041     * @return
042     * @throws PropertyException
043     */
044    public String getParamsAsString() throws PropertyException;
045
046    /**
047     * Add or update a {@link TemplateInput} to the list of template parameters.
048     *
049     * @param input
050     * @return
051     */
052    public List<TemplateInput> addInput(TemplateInput input);
053
054    /**
055     * Return the template Type (i.e. the associated {@link TemplateProcessor} name.
056     *
057     * @return {@link TemplateProcessor} name if any, null otherwise
058     */
059    public String getTemplateType();
060
061    /**
062     * Initialize the DocumentModel
063     * <ul>
064     * <li>finds associated TemplateProcessor</li>
065     * <li>extract Template parameters</li>
066     * </ul>
067     *
068     * @param save flag to indicate if target DocumentModel must be saved or not
069     */
070    public void initTemplate(boolean save);
071
072    /**
073     * Initialize the Types2Template binding
074     */
075    public void initTypesBindings();
076
077    /**
078     * Retrieve the Blob holding the template file
079     *
080     * @return
081     * @throws PropertyException
082     */
083    public Blob getTemplateBlob() throws PropertyException;
084
085    /**
086     * Retrieve the parameters associated to the Template file
087     *
088     * @return
089     * @throws PropertyException
090     */
091    public List<TemplateInput> getParams() throws PropertyException;
092
093    /**
094     * Save parameters changes
095     *
096     * @param params the updated list of parameters
097     * @param save flag to indicate if target DocumentModel must be saved or not
098     * @return the updated DocumentModel
099     */
100    public DocumentModel saveParams(List<TemplateInput> params, boolean save);
101
102    /**
103     * Return the underlying adapted {@link DocumentModel}s
104     *
105     * @return
106     */
107    public DocumentModel getAdaptedDoc();
108
109    /**
110     * Save changes in the underlying {@link DocumentModel}
111     *
112     * @return
113     */
114    public DocumentModel save();
115
116    /**
117     * Return flag to indicate if Documents associated to this template can override parametes value
118     *
119     * @return
120     */
121    public boolean allowInstanceOverride();
122
123    /**
124     * Indicate of the associated Template has editable parameters or not
125     *
126     * @return
127     */
128    public boolean hasEditableParams();
129
130    /**
131     * Get List of Document Types than can be associated to this Template.
132     *
133     * @return List of Document Types or an empty List
134     */
135    public List<String> getApplicableTypes();
136
137    /**
138     * Get List of Document Types that must be automatically bound to this template at creation time
139     *
140     * @return List of Document Types or an empty List
141     */
142    public List<String> getForcedTypes();
143
144    /**
145     * Get the list of {@link TemplateBasedDocument}s associated to this template
146     *
147     * @return
148     */
149    public List<TemplateBasedDocument> getTemplateBasedDocuments();
150
151    /**
152     * Remove Type mapping for this template
153     *
154     * @param type
155     * @param save
156     */
157    public void removeForcedType(String type, boolean save);
158
159    /**
160     * Update the Type mapping for this template
161     *
162     * @param forcedTypes
163     * @param save
164     */
165    public void setForcedTypes(String[] forcedTypes, boolean save);
166
167    /**
168     * Sets the expected output mime-type. If the expected mime-type is different from the output of the rendering,
169     * converters will be applied.
170     *
171     * @param mimetype
172     * @param save
173     */
174    public void setOutputFormat(String mimetype, boolean save);
175
176    /**
177     * Return the expected mime-type of the resulting rendering
178     *
179     * @return
180     */
181    public String getOutputFormat();
182
183    /**
184     * Indicate if the template can be used as main blob in the {@link TemplateBasedDocument} (i.e. if the template is
185     * editable by the end user)
186     *
187     * @return
188     */
189    public boolean useAsMainContent();
190
191    /**
192     * Shortcut to access the underlying {@link DocumentModel} name
193     *
194     * @return
195     */
196    public String getName();
197
198    /**
199     * Shortcut to access the underlying {@link Blob} filename
200     *
201     * @return name
202     */
203    public String getFileName();
204
205    /**
206     * Shortcut to access the underlying {@link DocumentModel} title
207     *
208     * @return template filename
209     */
210    public String getTitle();
211
212    /**
213     * Shortcut to access the underlying {@link DocumentModel} versionLabel
214     *
215     * @return versionLabel
216     */
217    public String getVersionLabel();
218
219    /**
220     * Shortcut to access the underlying {@link DocumentModel} uuid
221     *
222     * @return UUID
223     */
224    public String getId();
225
226    /**
227     * Return label key used for template
228     *
229     * @return
230     */
231    public String getLabel();
232
233    /**
234     * Associate Template to a Rendition
235     *
236     * @param renditionName
237     * @param save
238     */
239    public void setTargetRenditioName(String renditionName, boolean save);
240
241    /**
242     * Get the associated Rendition if any
243     *
244     * @return Rendition name or null
245     */
246    public String getTargetRenditionName();
247
248    /**
249     * Write accessor to the {@link Blob} used to store the template
250     *
251     * @param blob
252     * @param save
253     */
254    public void setTemplateBlob(Blob blob, boolean save);
255
256}