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