001/* 002 * (C) Copyright 2006-2019 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 * Julien Anguenot <ja@nuxeo.com> 019 * Estelle Giuly <egiuly@nuxeo.com> 020 */ 021package org.nuxeo.ecm.platform.mimetype.interfaces; 022 023import java.io.File; 024import java.util.List; 025import java.util.Optional; 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 * Allows the management of the mime type entry registry. 033 * <p> 034 * Flexible registry of mime types. 035 */ 036public interface MimetypeRegistry { 037 038 String DEFAULT_MIMETYPE = "application/octet-stream"; 039 040 String PDF_MIMETYPE = "application/pdf"; 041 042 String PDF_EXTENSION = ".pdf"; 043 044 /** 045 * Returns the mime type from a given stream. 046 * 047 * @return String mime type name. 048 * @throws MimetypeNotFoundException if mime type sniffing failed to identify a registered mime type 049 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 050 */ 051 String getMimetypeFromBlob(Blob blob); 052 053 /** 054 * Finds the mime type of a Blob content and returns provided default if not possible. 055 * 056 * @param blob content to be analyzed 057 * @param defaultMimetype defaultMimeType to be used if no found 058 * @return the mime type for the given blob if it exists, otherwise it returns {@code defaultMimetype} 059 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 060 */ 061 String getMimetypeFromBlobWithDefault(Blob blob, String defaultMimetype); 062 063 /** 064 * Returns the mime type from a given filename. 065 * 066 * @param filename the file name for which we are looking for the mime type 067 * @return the mime type that matches the {@code filename} 068 * @throws MimetypeNotFoundException if mime type sniffing failed to identify a registered mime type 069 */ 070 String getMimetypeFromFilename(String filename); 071 072 /** 073 * Returns the mime type from a given file. 074 * 075 * @return the mime type of the given file 076 * @throws MimetypeNotFoundException if mime type sniffing failed to identify a registered mime type 077 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 078 */ 079 String getMimetypeFromFile(File file); 080 081 /** 082 * Returns the extension for given mime type. 083 * 084 * @param mimetypeName the mime type name. 085 * @return a list of strings containing the possible extensions. 086 */ 087 List<String> getExtensionsFromMimetypeName(String mimetypeName); 088 089 /** 090 * Gets a mime type entry by name. 091 * 092 * @param name the mime type name 093 * @return the mime type entry that matches the mime type name if it exists, {@code null} otherwise 094 */ 095 MimetypeEntry getMimetypeEntryByName(String name); 096 097 /** 098 * Gets the {@link MimetypeEntry} for a given mime type. 099 * 100 * @param mimetype the mime type for which we are looking for the mime type entry 101 * @return the mime type entry if it exists, {@link #DEFAULT_MIMETYPE} otherwise 102 */ 103 MimetypeEntry getMimetypeEntryByMimeType(String mimetype); 104 105 /** 106 * Finds the mime type of some content according to its filename and / or binary content. 107 * 108 * @param filename extension to analyze 109 * @param blob content to be analyzed if filename is ambiguous 110 * @param defaultMimetype defaultMimeType to be used if no found 111 * @return the mime type 112 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 113 */ 114 String getMimetypeFromFilenameAndBlobWithDefault(String filename, Blob blob, String defaultMimetype); 115 116 /** 117 * Finds the mime type of some content according to its filename or binary mime type or binary content. 118 * 119 * @param filename extension to analyze 120 * @param blob content to be analyzed if filename is ambiguous 121 * @param defaultMimetype defaultMimeType to be used if no found 122 * @return the mime type 123 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 124 * @since 8.4 125 */ 126 String getMimetypeFromFilenameWithBlobMimetypeFallback(String filename, Blob blob, String defaultMimetype); 127 128 /** 129 * Updates the mime type field of a Blob based on the provided filename with fallback to binary. If the embedded 130 * filename is {@code null}, the provided filename is embedded into the blob as well. 131 * 132 * @param blob content to be analyzed if filename is ambiguous 133 * @param filename with extension to analyze 134 * @param withBlobMimetypeFallback to consider blob mime type as fallback or not 135 * @return updated blob (persisted if necessary) 136 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 137 * @since 8.4 138 */ 139 Blob updateMimetype(Blob blob, String filename, Boolean withBlobMimetypeFallback); 140 141 /** 142 * Updates the mime type field of a Blob based on the provided filename with fallback to binary sniffing. If the 143 * embedded filename is {@code null}, the provided filename is embedded into the blob as well. 144 * 145 * @param blob content to be analyzed if filename is ambiguous 146 * @param filename with extension to analyze 147 * @return updated blob (persisted if necessary) 148 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 149 */ 150 Blob updateMimetype(Blob blob, String filename); 151 152 /** 153 * Updates the mime type field of a Blob based on the embedded filename with fallback to binary sniffing. This 154 * method should not be called if the embedded filename is {@code null} for performance reasons (+ the fact that 155 * binary sniffing is no very reliable). 156 * 157 * @param blob content to be analyzed if filename is ambiguous 158 * @return updated blob (persisted if necessary) 159 * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected 160 */ 161 Blob updateMimetype(Blob blob); 162 163 /** 164 * Returns the mime type from a given extension. 165 * 166 * @param extension the extension for which we are looking for the mime type 167 * @return the mime type for the given extension if it exists 168 * @throws MimetypeNotFoundException if mime type sniffing failed to identify a registered mime type 169 * @since 7.3 170 */ 171 String getMimetypeFromExtension(String extension); 172 173 /** 174 * Retrieves the normalized mime type for the given {@code mimeType}. 175 * 176 * @param mimeType the mime for which we are looking for the normalized one 177 * @return an {@code Optional} with a present value if the normalized mime type can be found, otherwise an 178 * empty {@code Optional} 179 * @since 11.1 180 */ 181 Optional<String> getNormalizedMimeType(String mimeType); 182 183 /** 184 * Checks if the given {@code mimeType} is a normalized one. 185 * 186 * @param mimeType the mime type to check 187 * @return {@code true} if {@code mimeType} is normalized, {@code false} otherwise 188 * @since 11.1 189 */ 190 boolean isMimeTypeNormalized(String mimeType); 191 192}