001/*
002 * (C) Copyright 2006-2007 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Nuxeo - initial API and implementation
016 *
017 * $Id: MimetypeRegistry.java 20731 2007-06-18 15:13:32Z ogrisel $
018 */
019package org.nuxeo.ecm.platform.mimetype.interfaces;
020
021import java.io.File;
022import java.io.InputStream;
023import java.util.List;
024
025import org.nuxeo.ecm.core.api.Blob;
026import org.nuxeo.ecm.platform.mimetype.MimetypeDetectionException;
027import org.nuxeo.ecm.platform.mimetype.MimetypeNotFoundException;
028
029/**
030 * MimetypeEntry registry.
031 * <p>
032 * Flexible registry of mimetypes.
033 *
034 * @author <a href="ja@nuxeo.com">Julien Anguenot</a>
035 */
036public interface MimetypeRegistry {
037
038    String DEFAULT_MIMETYPE = "application/octet-stream";
039
040    /**
041     * Returns the mime type from a given stream.
042     *
043     * @return String mimetype name.
044     * @throws MimetypeNotFoundException if mimetype sniffing failed to identify a registered mime type
045     * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected
046     */
047    String getMimetypeFromStream(InputStream stream) throws MimetypeNotFoundException, MimetypeDetectionException;
048
049    /**
050     * Returns the mime type from a given stream.
051     *
052     * @return String mimetype name.
053     * @throws MimetypeNotFoundException if mimetype sniffing failed to identify a registered mime type
054     * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected
055     */
056    String getMimetypeFromBlob(Blob blob) throws MimetypeNotFoundException, MimetypeDetectionException;
057
058    /**
059     * Returns the mime type from a given blob or provided default if not possible.
060     *
061     * @throws MimetypeDetectionException
062     */
063    String getMimetypeFromBlobWithDefault(Blob blob, String defaultMimetype) throws MimetypeDetectionException;
064
065    /**
066     * Returns the mime type from a given stream or provided default if not possible.
067     *
068     * @throws MimetypeDetectionException
069     */
070    String getMimetypeFromStreamWithDefault(InputStream is, String defaultMimetype) throws MimetypeDetectionException;
071
072    /**
073     * Returns the mime type from a given filename.
074     */
075    String getMimetypeFromFilename(String filename);
076
077    /**
078     * Returns the mime type given a file.
079     *
080     * @return string containing the mime type
081     * @throws MimetypeNotFoundException if mimetype sniffing failed
082     * @throws MimetypeDetectionException if unexpected problem prevent the detection to work as expected
083     */
084    String getMimetypeFromFile(File file) throws MimetypeNotFoundException, MimetypeDetectionException;
085
086    /**
087     * Returns the extension for given mimetype.
088     *
089     * @param mimetypeName the mimetype name.
090     * @return a list of strings containing the possible extensions.
091     */
092    List<String> getExtensionsFromMimetypeName(String mimetypeName);
093
094    /**
095     * Gets a mimetype entry by name.
096     *
097     * @param name the mimetype name.
098     * @return mimetype instance
099     */
100    MimetypeEntry getMimetypeEntryByName(String name);
101
102    /**
103     * Gets a mimetype entry given the normalized mimetype.
104     *
105     * @param mimetype the normalized mimetype
106     * @return mimetype instance
107     */
108    MimetypeEntry getMimetypeEntryByMimeType(String mimetype);
109
110    /**
111     * Finds the mimetype of some content according to its filename and / or binary content.
112     *
113     * @param filename extension to analyze
114     * @param blob content to be analyzed if filename is ambiguous
115     * @param defaultMimetype defaultMimeType to be used if no found
116     * @return the string mimetype
117     * @throws MimetypeDetectionException
118     */
119    String getMimetypeFromFilenameAndBlobWithDefault(String filename, Blob blob, String defaultMimetype)
120            throws MimetypeDetectionException;
121
122    /**
123     * Update the mimetype field of a Blob based on the provided filename with fallback to binary sniffing. If the
124     * embedded filename is null, the provided filename is embedded into the blob as well.
125     *
126     * @param blob content to be analyzed if filename is ambiguous
127     * @param filename with extension to analyze
128     * @return updated blob (persisted if necessary)
129     * @throws MimetypeDetectionException
130     */
131    Blob updateMimetype(Blob blob, String filename) throws MimetypeDetectionException;
132
133    /**
134     * Update the mimetype field of a Blob based on the embedded filename with fallback to binary sniffing. This method
135     * should not be called if the embedded filename is null for performance reasons (+ the fact that binary sniffing is
136     * no very reliable).
137     *
138     * @param blob content to be analyzed if filename is ambiguous
139     * @return updated blob (persisted if necessary)
140     * @throws MimetypeDetectionException
141     */
142    Blob updateMimetype(Blob blob) throws MimetypeDetectionException;
143
144    /**
145     * Returns the mime type from a given extension.
146     *
147     * @since 7.3
148     */
149    String getMimetypeFromExtension(String extension) throws MimetypeNotFoundException;
150
151}