001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Nuxeo - initial API and implementation
011 *
012 */
013package org.nuxeo.ecm.core.convert.api;
014
015import java.io.Serializable;
016import java.util.List;
017import java.util.Map;
018
019import org.nuxeo.ecm.core.api.blobholder.BlobHolder;
020
021/**
022 * Interface for the Conversion Service.
023 *
024 * @author tiry
025 */
026public interface ConversionService {
027
028    /**
029     * Gets the convertName given a source and destination MimeType.
030     */
031    String getConverterName(String sourceMimeType, String destinationMimeType);
032
033    /**
034     * Gets the available convertNames given a source and destination MimeType.
035     */
036    List<String> getConverterNames(String sourceMimeType, String destinationMimeType);
037
038    /**
039     * Converts a Blob given a converter name.
040     */
041    BlobHolder convert(String converterName, BlobHolder blobHolder, Map<String, Serializable> parameters)
042            throws ConversionException;
043
044    /**
045     * Converts a Blob given a target destination MimeType.
046     */
047    BlobHolder convertToMimeType(String destinationMimeType, BlobHolder blobHolder, Map<String, Serializable> parameters)
048            throws ConversionException;
049
050    /**
051     * Returns the names of the registered converters.
052     */
053    List<String> getRegistredConverters();
054
055    /**
056     * Checks for converter availability.
057     * <p>
058     * Result can be:
059     * <ul>
060     * <li>{@link ConverterNotRegistered} if converter is not registered.
061     * <li>Error Message / Installation message if converter dependencies are not available an successful check.
062     * </ul>
063     */
064    ConverterCheckResult isConverterAvailable(String converterName, boolean refresh) throws ConverterNotRegistered;
065
066    /**
067     * Checks for converter availability.
068     * <p>
069     * Result can be:
070     * <ul>
071     * <li>{@link ConverterNotRegistered} if converter is not registered.
072     * <li>Error Message / Installation message if converter dependencies are not available an successful check.
073     * </ul>
074     * <p>
075     * Result can be taken from an internal cache.
076     */
077    ConverterCheckResult isConverterAvailable(String converterName) throws ConversionException;
078
079    /**
080     * Returns true if the converter supports the given {@code sourceMimeType}, false otherwise.
081     *
082     * @since 5.8
083     */
084    boolean isSourceMimeTypeSupported(String converterName, String sourceMimeType);
085
086    /**
087     * Schedules a conversion given a converter name.
088     * <p>
089     * Returns a conversion id to be used by {@link #getConversionResult(String, boolean)}.
090     *
091     * @since 7.4
092     */
093    String scheduleConversion(String converterName, BlobHolder blobHolder, Map<String, Serializable> parameters);
094
095    /**
096     * Schedules a conversion given a target mime type.
097     * <p>
098     * Returns a conversion id to be used by {@link #getConversionResult(String, boolean)}.
099     *
100     * @since 7.10
101     */
102    String scheduleConversionToMimeType(String destinationMimeType, BlobHolder blobHolder, Map<String, Serializable> parameters);
103
104    /**
105     * Returns the status of a scheduled conversion given its {@code id}, or {@code null} if no conversion scheduled.
106     *
107     * @since 7.4
108     */
109    ConversionStatus getConversionStatus(String id);
110
111    /**
112     * Returns the conversion result for the given {@code id} if any, {@code null} otherwise.
113     *
114     * @since 7.4
115     */
116    BlobHolder getConversionResult(String id, boolean cleanTransientStoreEntry);
117}