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}