001/*
002 * (C) Copyright 2010-2019 Nuxeo (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 */
019package org.nuxeo.ecm.platform.rendition.service;
020
021import java.io.Serializable;
022import java.util.List;
023import java.util.Map;
024
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.api.DocumentRef;
027import org.nuxeo.ecm.platform.rendition.Rendition;
028
029/**
030 * Service handling Rendition Definitions and actual render based on a Rendition Definition
031 *
032 * @author <a href="mailto:troger@nuxeo.com">Thomas Roger</a>
033 * @author <a href="mailto:tdelprat@nuxeo.com">Tiry</a>
034 * @since 5.4.1
035 */
036public interface RenditionService {
037
038    /**
039     * Returns a {@code List} of registered {@code RenditionDefinition}. The order of the List does not depend on the
040     * registering order.
041     */
042    List<RenditionDefinition> getDeclaredRenditionDefinitions();
043
044    /**
045     * Returns a {@code List} of registered {@code RenditionDefinition} matching a given provider type
046     *
047     * @deprecated since 7.2 because unused, except in JSF
048     */
049    @Deprecated
050    List<RenditionDefinition> getDeclaredRenditionDefinitionsForProviderType(String providerType);
051
052    /**
053     * Returns a {@code List} of {@code RenditionDefinition} available on the given Document. The order of the List does
054     * not depend on the registering order.
055     */
056    List<RenditionDefinition> getAvailableRenditionDefinitions(DocumentModel doc);
057
058    /**
059     * Returns the {@code RenditionDefinition} available on the given document for the given rendition definition name.
060     *
061     * @since 10.10
062     */
063    RenditionDefinition getAvailableRenditionDefinition(DocumentModel doc, String renditionName);
064
065    /**
066     * Render a document based on the given rendition definition name and returns the stored Rendition
067     * {@link DocumentRef}.
068     * <p>
069     * Only the user launching the render operation has the Read right on the returned document.
070     *
071     * @param sourceDocument the document to render
072     * @param renditionDefinitionName the rendition definition to use
073     * @return the {@code DocumentRef} of the newly created Rendition document.
074     */
075    DocumentRef storeRendition(DocumentModel sourceDocument, String renditionDefinitionName);
076
077    /**
078     * Return the {@link Rendition} object for the given {@link DocumentModel} and a rendition definition name.
079     * <p>
080     * A stored rendition is returned if found and up to date, a new Rendition is created otherwise.
081     *
082     * @param doc the document to render
083     * @param renditionName the name of the rendition definition
084     * @return the {@link Rendition} object
085     */
086    Rendition getRendition(DocumentModel doc, String renditionName);
087
088    /**
089     * Same as {@link #getDefaultRendition(DocumentModel, String, boolean, Map)} with store parameter set to false.
090     *
091     * @param doc the document to render
092     * @param reason the reason the rendition is being rendered (optional)
093     * @param extendedInfos map of extended info added in the default rendition computation (optional)
094     * @since 9.10
095     * @return the default {@link Rendition} object
096     */
097    Rendition getDefaultRendition(DocumentModel doc, String reason, Map<String, Serializable> extendedInfos);
098
099    /**
100     * Return the default {@link Rendition} object for the given {@link DocumentModel}.
101     * <p>
102     * A stored rendition is returned if found and up to date, a new Rendition is created otherwise.
103     *
104     * @param doc the document to render
105     * @param reason the reason the rendition is being rendered (optional)
106     * @param store indicates if the rendition must be stored
107     * @param extendedInfos map of extended info added in the default rendition computation (optional)
108     * @since 10.3
109     * @return the default {@link Rendition} object
110     */
111    Rendition getDefaultRendition(DocumentModel doc, String reason, boolean store,
112            Map<String, Serializable> extendedInfos);
113
114    /**
115     * Return the {@link Rendition} object for the given {@link DocumentModel} and a rendition definition name.
116     * <p>
117     * A stored rendition is returned if found and up to date, a new (live) Rendition is created and returned otherwise.
118     * <p>
119     * If store parameter is true, the new created rendition is stored too unless it is marked as stale.
120     *
121     * @param doc the document to render
122     * @param renditionName the name of the rendition definition
123     * @param store indicates if the rendition must be stored
124     * @return the {@link Rendition} object
125     */
126    Rendition getRendition(DocumentModel doc, String renditionName, boolean store);
127
128    /**
129     * Returns a {@code List} of {@code Rendition} available on the given Document.
130     * <p>
131     * The order of the List does not depend on the registering order.
132     * <p>
133     * The returned rendition may be live or stored
134     */
135    List<Rendition> getAvailableRenditions(DocumentModel doc);
136
137    /**
138     * Returns a {@code List} of {@code Rendition} available on the given Document.
139     * <p>
140     * If {@code onlyVisible} is true, returns only the rendition marked as visible.
141     * <p>
142     * The order of the List does not depend on the registering order.
143     * <p>
144     * The returned rendition may be live or stored
145     *
146     * @since 7.2
147     */
148    List<Rendition> getAvailableRenditions(DocumentModel doc, boolean onlyVisible);
149
150    /**
151     * Query and delete stored renditions where the related version or live document does not exist anymore.
152     *
153     * @since 8.4
154     */
155    void deleteStoredRenditions(String repositoryName);
156
157    /**
158     * Publish a document's rendition. If the rendition name is not given, it publishes its default rendition obtained
159     * from {@link #getDefaultRendition(DocumentModel, String, Map)}.
160     *
161     * @param doc the document to be published
162     * @param target the location where to publish
163     * @param renditionName the rendition to be published
164     * @param override if true, will remove existing publication of the document
165     * @return the published document
166     * @since 10.3
167     */
168    DocumentModel publishRendition(DocumentModel doc, DocumentModel target, String renditionName, boolean override);
169}