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}