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