001/* 002 * (C) Copyright 2006-2007 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 * $Id: MimetypeRegistry.java 20731 2007-06-18 15:13:32Z ogrisel $ 020 */ 021package org.nuxeo.ecm.platform.mimetype.interfaces; 022 023import java.io.File; 024import java.io.InputStream; 025import java.util.List; 026 027import org.nuxeo.ecm.core.api.Blob; 028import org.nuxeo.ecm.platform.mimetype.MimetypeDetectionException; 029import org.nuxeo.ecm.platform.mimetype.MimetypeNotFoundException; 030 031/** 032 * MimetypeEntry registry. 033 * <p> 034 * Flexible registry of mimetypes. 035 * 036 * @author <a href="ja@nuxeo.com">Julien Anguenot</a> 037 */ 038public interface MimetypeRegistry { 039 040 String DEFAULT_MIMETYPE = "application/octet-stream"; 041 042 /** 043 * Returns the mime type from a given stream. 044 * 045 * @return String mimetype name. 046 * @throws MimetypeNotFoundException if mimetype sniffing failed to identify a registered mime type 047 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 048 */ 049 String getMimetypeFromStream(InputStream stream) throws MimetypeNotFoundException, MimetypeDetectionException; 050 051 /** 052 * Returns the mime type from a given stream. 053 * 054 * @return String mimetype name. 055 * @throws MimetypeNotFoundException if mimetype sniffing failed to identify a registered mime type 056 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 057 */ 058 String getMimetypeFromBlob(Blob blob) throws MimetypeNotFoundException, MimetypeDetectionException; 059 060 /** 061 * Finds the mimetype of a Blob content and returns provided default if not possible. 062 * 063 * @param blob content to be analyzed 064 * @param defaultMimetype defaultMimeType to be used if no found 065 * @return the string mimetype 066 * @throws MimetypeDetectionException 067 */ 068 String getMimetypeFromBlobWithDefault(Blob blob, String defaultMimetype) throws MimetypeDetectionException; 069 070 /** 071 * Returns the mime type from a given stream or provided default if not possible. 072 * 073 * @throws MimetypeDetectionException 074 */ 075 String getMimetypeFromStreamWithDefault(InputStream is, String defaultMimetype) throws MimetypeDetectionException; 076 077 /** 078 * Returns the mime type from a given filename. 079 */ 080 String getMimetypeFromFilename(String filename); 081 082 /** 083 * Returns the mime type given a file. 084 * 085 * @return string containing the mime type 086 * @throws MimetypeNotFoundException if mimetype sniffing failed 087 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 088 */ 089 String getMimetypeFromFile(File file) throws MimetypeNotFoundException, MimetypeDetectionException; 090 091 /** 092 * Returns the extension for given mimetype. 093 * 094 * @param mimetypeName the mimetype name. 095 * @return a list of strings containing the possible extensions. 096 */ 097 List<String> getExtensionsFromMimetypeName(String mimetypeName); 098 099 /** 100 * Gets a mimetype entry by name. 101 * 102 * @param name the mimetype name. 103 * @return mimetype instance 104 */ 105 MimetypeEntry getMimetypeEntryByName(String name); 106 107 /** 108 * Gets a mimetype entry given the normalized mimetype. 109 * 110 * @param mimetype the normalized mimetype 111 * @return mimetype instance 112 */ 113 MimetypeEntry getMimetypeEntryByMimeType(String mimetype); 114 115 /** 116 * Finds the mimetype of some content according to its filename and / or binary content. 117 * 118 * @param filename extension to analyze 119 * @param blob content to be analyzed if filename is ambiguous 120 * @param defaultMimetype defaultMimeType to be used if no found 121 * @return the string mimetype 122 * @throws MimetypeDetectionException 123 */ 124 String getMimetypeFromFilenameAndBlobWithDefault(String filename, Blob blob, String defaultMimetype) 125 throws MimetypeDetectionException; 126 127 /** 128 * Finds the mimetype of some content according to its filename or binary mime type or binary content. 129 * 130 * @param filename extension to analyze 131 * @param blob content to be analyzed if filename is ambiguous 132 * @param defaultMimetype defaultMimeType to be used if no found 133 * @return the string mimetype 134 * @throws MimetypeDetectionException 135 * @since 8.4 136 */ 137 String getMimetypeFromFilenameWithBlobMimetypeFallback(String filename, Blob blob, String defaultMimetype) 138 throws MimetypeDetectionException; 139 140 /** 141 * Update the mimetype field of a Blob based on the provided filename with fallback to binary. If the embedded 142 * filename is null, the provided filename is embedded into the blob as well. 143 * 144 * @param blob content to be analyzed if filename is ambiguous 145 * @param filename with extension to analyze 146 * @param withBlobMimetypeFallback to consider blob mimetype as fallback or not 147 * @return updated blob (persisted if necessary) 148 * @throws MimetypeDetectionException 149 * @since 8.4 150 */ 151 Blob updateMimetype(Blob blob, String filename, Boolean withBlobMimetypeFallback) throws MimetypeDetectionException; 152 153 /** 154 * Update the mimetype field of a Blob based on the provided filename with fallback to binary sniffing. If the 155 * embedded filename is null, the provided filename is embedded into the blob as well. 156 * 157 * @param blob content to be analyzed if filename is ambiguous 158 * @param filename with extension to analyze 159 * @return updated blob (persisted if necessary) 160 * @throws MimetypeDetectionException 161 */ 162 Blob updateMimetype(Blob blob, String filename) throws MimetypeDetectionException; 163 164 /** 165 * Update the mimetype field of a Blob based on the embedded filename with fallback to binary sniffing. This method 166 * should not be called if the embedded filename is null for performance reasons (+ the fact that binary sniffing is 167 * no very reliable). 168 * 169 * @param blob content to be analyzed if filename is ambiguous 170 * @return updated blob (persisted if necessary) 171 * @throws MimetypeDetectionException 172 */ 173 Blob updateMimetype(Blob blob) throws MimetypeDetectionException; 174 175 /** 176 * Returns the mime type from a given extension. 177 * 178 * @since 7.3 179 */ 180 String getMimetypeFromExtension(String extension) throws MimetypeNotFoundException; 181 182}