Package eu.medsea.mimeutil

Class MimeUtil2

  • public class MimeUtil2
extends java.lang.Object

    The MimeUtil2 is a utility class that allows applications to detect, work with and manipulate MIME types.

    A MIME or "Multipurpose Internet Mail Extension" type is an Internet standard that is important outside of just e-mail use. MIME is used extensively in other communications protocols such as HTTP for web communications. IANA "Internet Assigned Numbers Authority" is responsible for the standardisation and publication of MIME types. Basically any resource on any computer that can be located via a URL can be assigned a MIME type. So for instance, JPEG images have a MIME type of image/jpg. Some resources can have multiple MIME types associated with them such as files with an XML extension have the MIME types text/xml and application/xml and even specialised versions of xml such as image/svg+xml for SVG image files.

    To do this MimeUtil2 uses registered MimeDetector(s) that are delegated too in sequence to actually perform the detection. There are several MimeDetector implementations that come with the utility and you can register and unregister them to perform detection based on file extensions, file globing and magic number detection.
    Their is also a fourth MimeDetector that is registered by default that detects text files and encodings. Unlike the other MimeDetector(s) or any MimeDetector(s) you may choose to implement, the TextMimeDetector cannot be registered or unregistered by your code. It is advisable that you read the java doc for the TextMimeDetector as it can be modified in several ways to make it perform better and or detect more specific types.
    Please refer to the java doc for each of these MimeDetector(s) for a description of how they actually perform their particular detection process.

    It is important to note that MIME matching is not an exact science, meaning that a positive match does not guarantee that the returned MIME type is actually correct. It is a best guess method of matching and the matched MIME types should be used with this in mind.

    New MimeDetector(s) can easily be created and registered with MimeUtil2 to extend it's functionality beyond these initial detection strategies by extending the AbstractMimeDetector class. To see how to implement your own MimeDetector take a look at the java doc and source code for the ExtensionMimeDetector, MagicMimeMimeDetector and OpendesktopMimeDetector classes. To register and unregister MimeDetector(s) use the [un]registerMimeDetector(...) methods of this class.

    The order that the MimeDetector(s) are executed is defined by the order each MimeDetector is registered.

    The resulting Collection of mime types returned in response to a getMimeTypes(...) call is a normalised list of the accumulation of MIME types returned by each of the registered MimeDetector(s) that implement the specified getMimeTypesXXX(...) methods.

    All methods in this class that return a Collection object containing MimeType(s) actually return a MimeTypeHashSet that implements both the Set and Collection interfaces.

    Since:
    2.1

    • Constructor Summary

      Constructors 
      Constructor Description
      MimeUtil2()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void addKnownMimeType​(MimeType mimeType)
      While MimeType(s) are being loaded by the MimeDetector(s) they should be added to the list of known MIME types.
      static void addKnownMimeType​(java.lang.String mimeType)
      While MimeType(s) are being loaded by the MimeDetector(s) they should be added to the list of known MIME types.
      static java.lang.String getExtension​(java.io.File file)
      Get the extension part of a file name defined by the file parameter.
      static java.lang.String getExtension​(java.lang.String fileName)
      Get the extension part of a file name defined by the fileName parameter.
      static MimeType getFirstMimeType​(java.lang.String mimeTypes)
      Get the first in a comma separated list of mime types.
      static java.io.InputStream getInputStreamForURL​(java.net.URL url)
      Utility method to get the InputStream from a URL.
      static java.util.Collection getKnownMimeTypes()
      Returns a copy of the Collection of currently known MIME types as strings that have been registered either by the initialisation methods of the MimeDetector(s) or by the user.
      static java.lang.String getMediaType​(java.lang.String mimeType)
      Utility method to get the major or media part of a mime type i.e.
      MimeDetector getMimeDetector​(java.lang.String name)
      Get a registered MimeDetector by name.
      static double getMimeQuality​(java.lang.String mimeType)
      Utility method to get the quality part of a mime type.
      java.util.Collection getMimeTypes​(byte[] data)
      Get a Collection of possible MimeType(s) that this byte array could represent according to the registered MimeDetector(s).
      java.util.Collection getMimeTypes​(byte[] data, MimeType unknownMimeType)
      Get a Collection of possible MimeType(s) that this byte array could represent according to the registered MimeDetector(s).
      java.util.Collection getMimeTypes​(java.io.File file)
      Get all of the matching mime types for this file object.
      java.util.Collection getMimeTypes​(java.io.File file, MimeType unknownMimeType)
      Get all of the matching mime types for this file object.
      java.util.Collection getMimeTypes​(java.io.InputStream in)
      Get all of the matching mime types for this InputStream object.
      java.util.Collection getMimeTypes​(java.io.InputStream in, MimeType unknownMimeType)
      Get all of the matching mime types for this InputStream object.
      java.util.Collection getMimeTypes​(java.lang.String fileName)
      Get all of the matching mime types for this file name.
      java.util.Collection getMimeTypes​(java.lang.String fileName, MimeType unknownMimeType)
      Get all of the matching mime types for this file name .
      java.util.Collection getMimeTypes​(java.net.URL url)
      Get all of the matching mime types for this URL object.
      java.util.Collection getMimeTypes​(java.net.URL url, MimeType unknownMimeType)  
      static MimeType getMostSpecificMimeType​(java.util.Collection mimeTypes)
      Get the most specific match of the Collection of mime types passed in.
      static java.nio.ByteOrder getNativeOrder()
      Get the native byte order of the OS on which you are running.
      static MimeType getPreferedMimeType​(java.lang.String accept, java.lang.String canProvide)
      Gives you the best match for your requirements.
      static double getQuality​(java.lang.String mimeType)
      Get the quality parameter of this mime type i.e.
      static java.lang.String getSubType​(java.lang.String mimeType)
      Utility method to get the minor part of a mime type i.e.
      static boolean isMimeTypeKnown​(MimeType mimeType)
      Check to see if this mime type is one of the types seen during initialisation or has been added at some later stage using addKnownMimeType(...)
      static boolean isMimeTypeKnown​(java.lang.String mimeType)
      Check to see if this mime type is one of the types seen during initialisation or has been added at some later stage using addKnownMimeType(...)
      static boolean isTextMimeType​(MimeType mimeType)
      Utility convenience method to check if a particular MimeType instance is actually a TextMimeType.
      MimeDetector registerMimeDetector​(java.lang.String mimeDetector)
      Register a MimeDetector and add it to the MimeDetector registry.
      MimeDetector unregisterMimeDetector​(MimeDetector mimeDetector)
      Remove a previously registered MimeDetector
      MimeDetector unregisterMimeDetector​(java.lang.String mimeDetector)
      Remove a previously registered MimeDetector

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • DIRECTORY_MIME_TYPE

        public static final MimeType DIRECTORY_MIME_TYPE
        Mime type used to identify a directory

      • UNKNOWN_MIME_TYPE

        public static final MimeType UNKNOWN_MIME_TYPE
        Mime type used to identify an unknown MIME type

    • Constructor Detail

      • MimeUtil2

        public MimeUtil2()

    • Method Detail

      • addKnownMimeType

        public static void addKnownMimeType​(MimeType mimeType)
        While MimeType(s) are being loaded by the MimeDetector(s) they should be added to the list of known MIME types. It is not mandatory for MimeDetector(s) to do so but they should where possible so that the list is as complete as possible. You can add other MIME types to this list using this method. You can then use the isMimeTypeKnown(...) utility methods to see if a MIME type you have matches one that the utility has already seen.

        This can be used to limit the mime types you work with i.e. if its not been loaded then don't bother using it as it won't match. This is no guarantee that a match will not be found as it is possible that a particular MimeDetector does not have an initialisation phase that loads all of the MIME types it will match.

        For instance if you had a MIME type of abc/xyz and passed this to isMimeTypeKnown(...) it would return false unless you specifically add this to the know MIME types using this method.

        Parameters:
        mimeType - a MIME type you want to add to the known MIME types. Duplicates are ignored.
        See Also:
        isMimeTypeKnown(String mimeType), isMimeTypeKnown(MimeType mimetType)

      • addKnownMimeType

        public static void addKnownMimeType​(java.lang.String mimeType)
        While MimeType(s) are being loaded by the MimeDetector(s) they should be added to the list of known MIME types. It is not mandatory for MimeDetector(s) to do so but they should where possible so that the list is as complete as possible. You can add other MIME types to this list using this method. You can then use the isMimeTypeKnown(...) utility methods to see if a MIME type you have matches one that the utility has already seen.

        This can be used to limit the mime types you work with i.e. if its not been loaded then don't bother using it as it won't match. This is no guarantee that a match will not be found as it is possible that a particular MimeDetector does not have an initialisation phase that loads all of the MIME types it will match.

        For instance if you had a MIME type of abc/xyz and passed this to isMimeTypeKnown(...) it would return false unless you specifically add this to the know MIME types using this method.

        Parameters:
        mimeType - a MIME type you want to add to the known MIME types. Duplicates are ignored.
        See Also:
        isMimeTypeKnown(String mimetype), isMimeTypeKnown(MimeType mimetType)

      • getKnownMimeTypes

        public static java.util.Collection getKnownMimeTypes()
        Returns a copy of the Collection of currently known MIME types as strings that have been registered either by the initialisation methods of the MimeDetector(s) or by the user.

      • registerMimeDetector

        public MimeDetector registerMimeDetector​(java.lang.String mimeDetector)
        Register a MimeDetector and add it to the MimeDetector registry. MimeDetector(s) are effectively singletons as they are keyed against their fully qualified class name.
        Parameters:
        mimeDetector - . This must be the fully qualified name of a concrete instance of an AbstractMimeDetector class. This enforces that all custom MimeDetector(s) extend the AbstractMimeDetector.
        See Also:
        MimeDetector

      • getExtension

        public static java.lang.String getExtension​(java.io.File file)
        Get the extension part of a file name defined by the file parameter.
        Parameters:
        file - a file object
        Returns:
        the file extension or null if it does not have one.

      • getExtension

        public static java.lang.String getExtension​(java.lang.String fileName)
        Get the extension part of a file name defined by the fileName parameter. There may be no extension or it could be a single part extension such as .bat or a multi-part extension such as .tar.gz
        Parameters:
        fileName - a relative or absolute path to a file
        Returns:
        the file extension or null if it does not have one.

      • getFirstMimeType

        public static MimeType getFirstMimeType​(java.lang.String mimeTypes)
        Get the first in a comma separated list of mime types. Useful when using extension mapping that can return multiple mime types separate by commas and you only want the first one.
        Parameters:
        mimeTypes - comma separated list of mime types
        Returns:
        first in a comma separated list of mime types or null if the mimeTypes string is null or empty

      • getMediaType

        public static java.lang.String getMediaType​(java.lang.String mimeType)
                                     throws MimeException
        Utility method to get the major or media part of a mime type i.e. the bit before the '/' character
        Parameters:
        mimeType - you want to get the media part from
        Returns:
        media type of the mime type
        Throws:
        MimeException - if you pass in an invalid mime type structure

      • getMimeQuality

        public static double getMimeQuality​(java.lang.String mimeType)
                             throws MimeException
        Utility method to get the quality part of a mime type. If it does not exist then it is always set to q=1.0 unless it's a wild card. For the major component wild card the value is set to 0.01 For the minor component wild card the value is set to 0.02

        Thanks to the Apache organisation for these settings.

        Parameters:
        mimeType - a valid mime type string with or without a valid q parameter
        Returns:
        the quality value of the mime type either calculated from the rules above or the actual value defined.
        Throws:
        MimeException - this is thrown if the mime type pattern is invalid.

      • getMimeDetector

        public MimeDetector getMimeDetector​(java.lang.String name)
        Get a registered MimeDetector by name.
        Parameters:
        name - the name of a registered MimeDetector. This is always the fully qualified name of the class implementing the MimeDetector.
        Returns:

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(byte[] data)
                                        throws MimeException
        Get a Collection of possible MimeType(s) that this byte array could represent according to the registered MimeDetector(s). If no MimeType(s) are detected then the returned Collection will contain only the UNKNOWN_MIME_TYPE
        Parameters:
        data -
        Returns:
        all matching MimeType(s)
        Throws:
        MimeException

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(byte[] data,
                                               MimeType unknownMimeType)
                                        throws MimeException
        Get a Collection of possible MimeType(s) that this byte array could represent according to the registered MimeDetector(s). If no MimeType(s) are detected then the returned Collection will contain only the passed in unknownMimeType
        Parameters:
        data -
        unknownMimeType - used if the registered MimeDetector(s) fail to match any MimeType(s)
        Returns:
        all matching MimeType(s)
        Throws:
        MimeException

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(java.io.File file)
                                        throws MimeException
        Get all of the matching mime types for this file object. The method delegates down to each of the registered MimeHandler(s) and returns a normalised list of all matching mime types. If no matching mime types are found the returned Collection will contain the default UNKNOWN_MIME_TYPE
        Parameters:
        file - the File object to detect.
        Returns:
        collection of matching MimeType(s)
        Throws:
        MimeException - if there are problems such as reading files generated when the MimeHandler(s) executed.

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(java.io.File file,
                                               MimeType unknownMimeType)
                                        throws MimeException
        Get all of the matching mime types for this file object. The method delegates down to each of the registered MimeHandler(s) and returns a normalised list of all matching mime types. If no matching mime types are found the returned Collection will contain the unknownMimeType passed in.
        Parameters:
        file - the File object to detect.
        unknownMimeType - .
        Returns:
        the Collection of matching mime types. If the collection would be empty i.e. no matches then this will contain the passed in parameter unknownMimeType
        Throws:
        MimeException - if there are problems such as reading files generated when the MimeHandler(s) executed.

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(java.io.InputStream in)
                                        throws MimeException
        Get all of the matching mime types for this InputStream object. The method delegates down to each of the registered MimeHandler(s) and returns a normalised list of all matching mime types. If no matching mime types are found the returned Collection will contain the default UNKNOWN_MIME_TYPE
        Parameters:
        in - InputStream to detect.
        Returns:
        Throws:
        MimeException - if there are problems such as reading files generated when the MimeHandler(s) executed.

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(java.io.InputStream in,
                                               MimeType unknownMimeType)
                                        throws MimeException
        Get all of the matching mime types for this InputStream object. The method delegates down to each of the registered MimeHandler(s) and returns a normalised list of all matching mime types. If no matching mime types are found the returned Collection will contain the unknownMimeType passed in.
        Parameters:
        in - the InputStream object to detect.
        unknownMimeType - .
        Returns:
        the Collection of matching mime types. If the collection would be empty i.e. no matches then this will contain the passed in parameter unknownMimeType
        Throws:
        MimeException - if there are problems such as reading files generated when the MimeHandler(s) executed.

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(java.lang.String fileName)
                                        throws MimeException
        Get all of the matching mime types for this file name. The method delegates down to each of the registered MimeHandler(s) and returns a normalised list of all matching mime types. If no matching mime types are found the returned Collection will contain the default UNKNOWN_MIME_TYPE
        Parameters:
        fileName - the name of a file to detect.
        Returns:
        collection of matching MimeType(s)
        Throws:
        MimeException - if there are problems such as reading files generated when the MimeHandler(s) executed.

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(java.lang.String fileName,
                                               MimeType unknownMimeType)
                                        throws MimeException
        Get all of the matching mime types for this file name . The method delegates down to each of the registered MimeHandler(s) and returns a normalised list of all matching mime types. If no matching mime types are found the returned Collection will contain the unknownMimeType passed in.
        Parameters:
        fileName - the name of a file to detect.
        unknownMimeType - .
        Returns:
        the Collection of matching mime types. If the collection would be empty i.e. no matches then this will contain the passed in parameter unknownMimeType
        Throws:
        MimeException - if there are problems such as reading files generated when the MimeHandler(s) executed.

      • getMimeTypes

        public final java.util.Collection getMimeTypes​(java.net.URL url)
                                        throws MimeException
        Get all of the matching mime types for this URL object. The method delegates down to each of the registered MimeHandler(s) and returns a normalised list of all matching mime types. If no matching mime types are found the returned Collection will contain the default UNKNOWN_MIME_TYPE
        Parameters:
        url - a URL to detect.
        Returns:
        Collection of matching MimeType(s)
        Throws:
        MimeException - if there are problems such as reading files generated when the MimeHandler(s) executed.

      • getNativeOrder

        public static java.nio.ByteOrder getNativeOrder()
        Get the native byte order of the OS on which you are running. It will be either big or little endian. This is used internally for the magic mime rules mapping.
        Returns:
        ByteOrder

      • getPreferedMimeType

        public static MimeType getPreferedMimeType​(java.lang.String accept,
                                           java.lang.String canProvide)
        Gives you the best match for your requirements.

        You can pass the accept header from a browser request to this method along with a comma separated list of possible mime types returned from say getExtensionMimeTypes(...) and the best match according to the accept header will be returned.

        The following is typical of what may be specified in an HTTP Accept header:

        Accept: text/xml, application/xml, application/xhtml+xml, text/html;q=0.9, text/plain;q=0.8, video/x-mng, image/png, image/jpeg, image/gif;q=0.2, text/css, */*;q=0.1

        The quality parameter (q) indicates how well the user agent handles the MIME type. A value of 1 indicates the MIME type is understood perfectly, and a value of 0 indicates the MIME type isn't understood at all.

        The reason the image/gif MIME type contains a quality parameter of 0.2, is to indicate that PNG & JPEG are preferred over GIF if the server is using content negotiation to deliver either a PNG or a GIF to user agents. Similarly, the text/html quality parameter has been lowered a little, to ensure that the XML MIME types are given in preference if content negotiation is being used to serve an XHTML document.

        Parameters:
        accept - is a comma separated list of mime types you can accept including QoS parameters. Can pass the Accept: header directly.
        canProvide - is a comma separated list of mime types that can be provided such as that returned from a call to getExtensionMimeTypes(...)
        Returns:
        the best matching mime type possible.

      • getMostSpecificMimeType

        public static MimeType getMostSpecificMimeType​(java.util.Collection mimeTypes)
        Get the most specific match of the Collection of mime types passed in. The Collection
        Parameters:
        mimeTypes - this should be the Collection of mime types returned from a getMimeTypes(...) call.
        Returns:
        the most specific MimeType. If more than one of the mime types in the Collection have the same value then the first one found with this value in the Collection is returned.

      • getSubType

        public static java.lang.String getSubType​(java.lang.String mimeType)
                                   throws MimeException
        Utility method to get the minor part of a mime type i.e. the bit after the '/' character
        Parameters:
        mimeType - you want to get the minor part from
        Returns:
        sub type of the mime type
        Throws:
        MimeException - if you pass in an invalid mime type structure

      • isMimeTypeKnown

        public static boolean isMimeTypeKnown​(MimeType mimeType)
        Check to see if this mime type is one of the types seen during initialisation or has been added at some later stage using addKnownMimeType(...)
        Parameters:
        mimeType -
        Returns:
        true if the mimeType is in the list else false is returned
        See Also:
        addKnownMimeType(String mimetype)

      • isMimeTypeKnown

        public static boolean isMimeTypeKnown​(java.lang.String mimeType)
        Check to see if this mime type is one of the types seen during initialisation or has been added at some later stage using addKnownMimeType(...)
        Parameters:
        mimeType -
        Returns:
        true if the mimeType is in the list else false is returned
        See Also:
        addKnownMimeType(String mimetype)

      • isTextMimeType

        public static boolean isTextMimeType​(MimeType mimeType)
        Utility convenience method to check if a particular MimeType instance is actually a TextMimeType. Used when iterating over a collection of MimeType's to help with casting to enable access the the TextMimeType methods not available to a standard MimeType. Can also use instanceof.
        Parameters:
        mimeType -
        Returns:
        true if the passed in instance is a TextMimeType
        See Also:
        MimeType, TextMimeType

      • unregisterMimeDetector

        public MimeDetector unregisterMimeDetector​(MimeDetector mimeDetector)
        Remove a previously registered MimeDetector
        Parameters:
        mimeDetector -
        Returns:
        the MimeDetector that was removed from the registry else null.

      • unregisterMimeDetector

        public MimeDetector unregisterMimeDetector​(java.lang.String mimeDetector)
        Remove a previously registered MimeDetector
        Parameters:
        mimeDetector -
        Returns:
        the MimeDetector that was removed from the registry else null.

      • getQuality

        public static double getQuality​(java.lang.String mimeType)
                         throws MimeException
        Get the quality parameter of this mime type i.e. the q= property. This method implements a value system similar to that used by the apache server i.e. if the media type is a * then it's q value is set to 0.01 and if the sub type is a * then the q value is set to 0.02 unless a specific q value is specified. If a q property is set it is limited to a max value of 1.0
        Parameters:
        mimeType -
        Returns:
        the quality value as a double between 0.0 and 1.0
        Throws:
        MimeException

      • getInputStreamForURL

        public static java.io.InputStream getInputStreamForURL​(java.net.URL url)
                                                throws java.lang.Exception
        Utility method to get the InputStream from a URL. Handles several schemes, for instance, if the URL points to a jar entry it will get a proper usable stream from the URL
        Parameters:
        url -
        Returns:
        Throws:
        java.lang.Exception