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}