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