001/*
002 * (C) Copyright 2006-2011 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 */
020package org.nuxeo.ecm.core.convert.api;
021
022import java.io.Serializable;
023import java.util.List;
024import java.util.Map;
025
026import org.nuxeo.ecm.core.api.blobholder.BlobHolder;
027
028/**
029 * Interface for the Conversion Service.
030 *
031 * @author tiry
032 */
033public interface ConversionService {
034
035    /**
036     * Gets the convertName given a source and destination MimeType.
037     */
038    String getConverterName(String sourceMimeType, String destinationMimeType);
039
040    /**
041     * Gets the available convertNames given a source and destination MimeType.
042     */
043    List<String> getConverterNames(String sourceMimeType, String destinationMimeType);
044
045    /**
046     * Converts a Blob given a converter name.
047     */
048    BlobHolder convert(String converterName, BlobHolder blobHolder, Map<String, Serializable> parameters)
049            throws ConversionException;
050
051    /**
052     * Converts a Blob given a target destination MimeType.
053     */
054    BlobHolder convertToMimeType(String destinationMimeType, BlobHolder blobHolder, Map<String, Serializable> parameters)
055            throws ConversionException;
056
057    /**
058     * Returns the names of the registered converters.
059     */
060    List<String> getRegistredConverters();
061
062    /**
063     * Checks for converter availability.
064     * <p>
065     * Result can be:
066     * <ul>
067     * <li>{@link ConverterNotRegistered} if converter is not registered.
068     * <li>Error Message / Installation message if converter dependencies are not available an successful check.
069     * </ul>
070     */
071    ConverterCheckResult isConverterAvailable(String converterName, boolean refresh) throws ConverterNotRegistered;
072
073    /**
074     * Checks for converter availability.
075     * <p>
076     * Result can be:
077     * <ul>
078     * <li>{@link ConverterNotRegistered} if converter is not registered.
079     * <li>Error Message / Installation message if converter dependencies are not available an successful check.
080     * </ul>
081     * <p>
082     * Result can be taken from an internal cache.
083     */
084    ConverterCheckResult isConverterAvailable(String converterName) throws ConversionException;
085
086    /**
087     * Returns true if the converter supports the given {@code sourceMimeType}, false otherwise.
088     *
089     * @since 5.8
090     */
091    boolean isSourceMimeTypeSupported(String converterName, String sourceMimeType);
092
093    /**
094     * Schedules a conversion given a converter name.
095     * <p>
096     * Returns a conversion id to be used by {@link #getConversionResult(String, boolean)}.
097     *
098     * @since 7.4
099     */
100    String scheduleConversion(String converterName, BlobHolder blobHolder, Map<String, Serializable> parameters);
101
102    /**
103     * Schedules a conversion given a target mime type.
104     * <p>
105     * Returns a conversion id to be used by {@link #getConversionResult(String, boolean)}.
106     *
107     * @since 7.10
108     */
109    String scheduleConversionToMimeType(String destinationMimeType, BlobHolder blobHolder, Map<String, Serializable> parameters);
110
111    /**
112     * Returns the status of a scheduled conversion given its {@code id}, or {@code null} if no conversion scheduled.
113     *
114     * @since 7.4
115     */
116    ConversionStatus getConversionStatus(String id);
117
118    /**
119     * Returns the conversion result for the given {@code id} if any, {@code null} otherwise.
120     *
121     * @since 7.4
122     */
123    BlobHolder getConversionResult(String id, boolean cleanTransientStoreEntry);
124}