001/*
002 * (C) Copyright 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 *     Thierry Delprat
018 */
019package org.nuxeo.template.api;
020
021import java.util.Collection;
022import java.util.List;
023import java.util.Map;
024
025import org.nuxeo.ecm.core.api.Blob;
026import org.nuxeo.ecm.core.api.CoreSession;
027import org.nuxeo.ecm.core.api.DocumentModel;
028import org.nuxeo.template.api.adapters.TemplateBasedDocument;
029import org.nuxeo.template.api.adapters.TemplateSourceDocument;
030import org.nuxeo.template.api.context.DocumentWrapper;
031import org.nuxeo.template.api.descriptor.ContextExtensionFactoryDescriptor;
032import org.nuxeo.template.api.descriptor.OutputFormatDescriptor;
033import org.nuxeo.template.api.descriptor.TemplateProcessorDescriptor;
034
035/**
036 * This is the service interface to manage {@link TemplateProcessor} and associated templates.
037 *
038 * @author <a href="mailto:tdelprat@nuxeo.com">Tiry</a>
039 */
040public interface TemplateProcessorService {
041
042    /**
043     * Finds the template processor name for a given {@link Blob}. The template processor is found based on mime-types.
044     *
045     * @param templateBlob
046     * @return the {@link TemplateProcessor} name
047     */
048    String findProcessorName(Blob templateBlob);
049
050    /**
051     * Finds the {@link TemplateProcessor} for a given {@link Blob}. The template processor is found based on
052     * mime-types.
053     *
054     * @param templateBlob
055     * @return the {@link TemplateProcessor}
056     */
057    TemplateProcessor findProcessor(Blob templateBlob);
058
059    /**
060     * Get a {@link TemplateProcessor} by it's name. Name is defined in the associated descriptor.
061     *
062     * @param name
063     * @return the {@link TemplateProcessor}
064     */
065    TemplateProcessor getProcessor(String name);
066
067    /**
068     * Returns all registered {@link TemplateProcessor}s
069     *
070     * @return collection of registered {@link TemplateProcessorDescriptor}
071     */
072    Collection<TemplateProcessorDescriptor> getRegisteredTemplateProcessors();
073
074    /**
075     * Find {@link TemplateSourceDocument}s that can be bound to a given doc type.
076     *
077     * @param session
078     * @param targetType the target Document Type
079     * @return List of applicable DocumentModel
080     */
081    List<DocumentModel> getAvailableTemplateDocs(CoreSession session, String targetType);
082
083    /**
084     * Find {@link TemplateSourceDocument}s that can be bound to a given doc type.
085     *
086     * @param session
087     * @param targetType the target Document Type
088     * @return List of applicable {@link TemplateSourceDocument}
089     */
090    List<TemplateSourceDocument> getAvailableTemplates(CoreSession session, String targetType);
091
092    /**
093     * Returns a template with a given templateName.
094     *
095     * @param session
096     * @param name the name of the template
097     * @return
098     *
099     * @since 9.1
100     */
101    DocumentModel getTemplateDoc(CoreSession session, String name);
102
103    /**
104     * Retrieve the {@link TemplateSourceDocument} that can be used as an Office template (i.e that support to store the
105     * template file as main blob of target DocumentModel)
106     *
107     * @param session
108     * @param targetType
109     * @return
110     */
111    List<TemplateSourceDocument> getAvailableOfficeTemplates(CoreSession session, String targetType);
112
113    /**
114     * Retrieve the DocumentModels using a given {@link TemplateSourceDocument}
115     *
116     * @param source the {@link TemplateSourceDocument}
117     * @return
118     */
119    List<TemplateBasedDocument> getLinkedTemplateBasedDocuments(DocumentModel source);
120
121    /**
122     * Retrieve the Map used for mapping Document Types to Template Names. This Map represent the Templates that must be
123     * automatically bound at creation time for each Document Type.
124     *
125     * @return the Type2Template mapping
126     */
127    Map<String, List<String>> getTypeMapping();
128
129    /**
130     * Update Type2Template Mapping from the data contained in the source DocumentModel.
131     *
132     * @param doc
133     */
134    void registerTypeMapping(DocumentModel doc);
135
136    /**
137     * Associate a {@link DocumentModel} to a {@link TemplateSourceDocument}. If the DocumentModel is not already a
138     * {@link TemplateBasedDocument}, the associated facet will be automatically added.
139     *
140     * @param targetDoc the DocumentModel to associate to a template
141     * @param sourceTemplateDoc the DocumentModel holding the template
142     * @param save flag to indicate if target DocumentModel must be saved or not
143     * @return the updated DocumentModel
144     */
145    DocumentModel makeTemplateBasedDocument(DocumentModel targetDoc, DocumentModel sourceTemplateDoc, boolean save);
146
147    /**
148     * Detach a Template from a {@link DocumentModel}
149     *
150     * @param targetDoc the DocumentModel to detach
151     * @param templateName the name of the template to detach
152     * @param save save flag to indicate if target DocumentModel must be saved or not
153     * @return the updated DocumentModel
154     */
155    DocumentModel detachTemplateBasedDocument(DocumentModel targetDoc, String templateName, boolean save);
156
157    void addContextExtensions(DocumentModel currentDocument, DocumentWrapper wrapper, Map<String, Object> ctx);
158
159    Map<String, ContextExtensionFactoryDescriptor> getRegistredContextExtensions();
160
161    List<String> getReservedContextKeywords();
162
163    /**
164     * @return the list of registered Ouput formats used to convert output of a rendered document.
165     */
166    Collection<OutputFormatDescriptor> getOutputFormats();
167
168    /**
169     * The returned {@link OutputFormatDescriptor} contains either an operation chain or a mime-type use to convert the
170     * output of a rendered document.
171     *
172     * @param outputFormatId
173     * @return {@link OutputFormatDescriptor}
174     */
175    OutputFormatDescriptor getOutputFormatDescriptor(String outputFormatId);
176
177}