001/*
002 * (C) Copyright 2006-2016 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 *     Estelle Giuly <egiuly@nuxeo.com>
019 *
020 */
021package org.nuxeo.ecm.core.convert.api;
022
023import java.io.IOException;
024import java.io.Serializable;
025import java.util.List;
026import java.util.Map;
027
028import org.nuxeo.ecm.core.api.Blob;
029import org.nuxeo.ecm.core.api.blobholder.BlobHolder;
030
031/**
032 * Interface for the Conversion Service.
033 *
034 * @author tiry
035 */
036public interface ConversionService {
037
038    /**
039     * Returns the converter name for the given {@code sourceMimeType} and {@code destinationMimeType}.
040     * <p>
041     * Follows the algorithm of {@link #getConverterNames(String, String)}.
042     *
043     * @see #getConverterNames(String, String)
044     * @see #getConverterName(String, String, boolean)
045     */
046    default String getConverterName(String sourceMimeType, String destinationMimeType) {
047        return getConverterName(sourceMimeType, destinationMimeType, true);
048    }
049
050    /**
051     * Returns the converter name for the given {@code sourceMimeType} and {@code destinationMimeType}.
052     * <p>
053     * Follows the algorithm of {@link #getConverterNames(String, String, boolean)}.
054     *
055     * @since 11.1
056     * @see #getConverterNames(String, String, boolean)
057     */
058    String getConverterName(String sourceMimeType, String destinationMimeType, boolean allowWildcard);
059
060    /**
061     * Returns the list of converter names handling the given {@code sourceMimeType} and {@code destinationMimeType}.
062     *
063     * @see #getConverterNames(String, String, boolean)
064     */
065    default List<String> getConverterNames(String sourceMimeType, String destinationMimeType) {
066        return getConverterNames(sourceMimeType, destinationMimeType, true);
067    }
068
069    /**
070     * Returns the list of converter names handling the given {@code sourceMimeType} and {@code destinationMimeType}.
071     * <p>
072     * Finds the converter names based on the following algorithm:
073     * <ul>
074     * <li>Find the converters exactly matching the given {@code sourceMimeType}</li>
075     * <li>If no converter found, find the converters matching a wildcard subtype based on the {@code sourceMimeType},
076     * such has "image/*"</li>
077     * <li>If no converter found and {@code allowWildcard} is {@code true}, find the converters matching a wildcard
078     * source mime type "*"</li>
079     * <li>Then, filter only the converters matching the given {@code destinationMimeType}</li>
080     * </ul>
081     *
082     * @param allowWildcard {@code true} to allow returning converters with '*' as source mime type.
083     * @since 11.1
084     */
085    List<String> getConverterNames(String sourceMimeType, String destinationMimeType, boolean allowWildcard);
086
087    /**
088     * Converts a Blob given a converter name.
089     */
090    BlobHolder convert(String converterName, BlobHolder blobHolder, Map<String, Serializable> parameters)
091            throws ConversionException;
092
093    /**
094     * Converts a Blob given a target destination MimeType.
095     */
096    BlobHolder convertToMimeType(String destinationMimeType, BlobHolder blobHolder,
097            Map<String, Serializable> parameters) throws ConversionException;
098
099    /**
100     * Converts a Blob to PDF. If the blob has inner blobs such as images, they will be correctly rendered in the PDF.
101     *
102     * @since 9.1
103     * @deprecated since 9.2, use {@link #convertToMimeType(String, BlobHolder, Map)} with the PDF mimetype as
104     *             destination instead
105     */
106    @Deprecated
107    Blob convertBlobToPDF(Blob blob) throws IOException;
108
109    /**
110     * Returns the names of the registered converters.
111     */
112    List<String> getRegistredConverters();
113
114    /**
115     * Checks for converter availability.
116     * <p>
117     * Result can be:
118     * <ul>
119     * <li>{@link ConverterNotRegistered} if converter is not registered.
120     * <li>Error Message / Installation message if converter dependencies are not available an successful check.
121     * </ul>
122     */
123    ConverterCheckResult isConverterAvailable(String converterName, boolean refresh) throws ConverterNotRegistered;
124
125    /**
126     * Checks for converter availability.
127     * <p>
128     * Result can be:
129     * <ul>
130     * <li>{@link ConverterNotRegistered} if converter is not registered.
131     * <li>Error Message / Installation message if converter dependencies are not available an successful check.
132     * </ul>
133     * <p>
134     * Result can be taken from an internal cache.
135     */
136    ConverterCheckResult isConverterAvailable(String converterName) throws ConversionException;
137
138    /**
139     * Returns true if the converter supports the given {@code sourceMimeType}, false otherwise.
140     *
141     * @since 5.8
142     */
143    boolean isSourceMimeTypeSupported(String converterName, String sourceMimeType);
144
145    /**
146     * Schedules a conversion given a converter name.
147     * <p>
148     * Returns a conversion id to be used by {@link #getConversionResult(String, boolean)}.
149     *
150     * @since 7.4
151     */
152    String scheduleConversion(String converterName, BlobHolder blobHolder, Map<String, Serializable> parameters);
153
154    /**
155     * Schedules a conversion given a target mime type.
156     * <p>
157     * Returns a conversion id to be used by {@link #getConversionResult(String, boolean)}.
158     *
159     * @since 7.10
160     */
161    String scheduleConversionToMimeType(String destinationMimeType, BlobHolder blobHolder,
162            Map<String, Serializable> parameters);
163
164    /**
165     * Returns the status of a scheduled conversion given its {@code id}, or {@code null} if no conversion scheduled.
166     *
167     * @since 7.4
168     */
169    ConversionStatus getConversionStatus(String id);
170
171    /**
172     * Returns the conversion result for the given {@code id} if any, {@code null} otherwise.
173     *
174     * @since 7.4
175     */
176    BlobHolder getConversionResult(String id, boolean cleanTransientStoreEntry);
177
178}