MailcapCommandMap (Java SE 9 & JDK 9 )
Keywords: javax.activation.MailcapCommandMap class

Module java.activation
Package javax.activation

## Class MailcapCommandMap

- java.lang.Object
- - javax.activation.CommandMap
  - - javax.activation.MailcapCommandMap

-     public class MailcapCommandMap
      extends CommandMap

  MailcapCommandMap extends the CommandMap abstract class. It implements a CommandMap whose configuration is based on mailcap files (RFC 1524). The MailcapCommandMap can be configured both programmatically and via configuration files.

  Mailcap file search order:

  The MailcapCommandMap looks in various places in the user's system for mailcap file entries. When requests are made to search for commands in the MailcapCommandMap, it searches mailcap files in the following order:

  1. Programatically added entries to the MailcapCommandMap instance.
  2. The file `.mailcap` in the user's home directory.
  3. The file `mailcap` in the Java runtime.
  4. The file or resources named `META-INF/mailcap`.
  5. The file or resource named `META-INF/mailcap.default` (usually found only in the `activation.jar` file).

  (The current implementation looks for the `mailcap` file in the Java runtime in the directory java.home`/conf` if it exists, and otherwise in the directory java.home`/lib`, where java.home is the value of the "java.home" System property. Note that the "conf" directory was introduced in JDK 9.)

  Mailcap file format:

  Mailcap files must conform to the mailcap file specification (RFC 1524, A User Agent Configuration Mechanism For Multimedia Mail Format Information). The file format consists of entries corresponding to particular MIME types. In general, the specification specifies applications for clients to use when they themselves cannot operate on the specified MIME type. The MailcapCommandMap extends this specification by using a parameter mechanism in mailcap files that allows JavaBeans(tm) components to be specified as corresponding to particular commands for a MIME type.

  When a mailcap file is parsed, the MailcapCommandMap recognizes certain parameter signatures, specifically those parameter names that begin with `x-java-`. The MailcapCommandMap uses this signature to find command entries for inclusion into its registries. Parameter names with the form `x-java-<name>` are read by the MailcapCommandMap as identifying a command with the name name. When the name is `content-handler` the MailcapCommandMap recognizes the class signified by this parameter as a DataContentHandler. All other commands are handled generically regardless of command name. The command implementation is specified by a fully qualified class name of a JavaBean(tm) component. For example; a command for viewing some data can be specified as: `x-java-view=com.foo.ViewBean`.

  When the command name is `fallback-entry`, the value of the command may be `true` or `false`. An entry for a MIME type that includes a parameter of `x-java-fallback-entry=true` defines fallback commands for that MIME type that will only be used if no non-fallback entry can be found. For example, an entry of the form `text/*; ; x-java-fallback-entry=true; x-java-view=com.sun.TextViewer` specifies a view command to be used for any text MIME type. This view command would only be used if a non-fallback view command for the MIME type could not be found.

  MailcapCommandMap aware mailcap files have the following general form:

       # Comments begin with a '#' and continue to the end of the line.
       <mime type>; ; <parameter list>
       # Where a parameter list consists of one or more parameters,
       # where parameters look like: x-java-view=com.sun.TextViewer
       # and a parameter list looks like:
       text/plain; ; x-java-view=com.sun.TextViewer; x-java-edit=com.sun.TextEdit
       # Note that mailcap entries that do not contain 'x-java' parameters
       # and comply to RFC 1524 are simply ignored:
       image/gif; /usr/dt/bin/sdtimage %s

  Since:
    1.6

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MailcapCommandMap​()` | The default Constructor.
    `MailcapCommandMap​(InputStream is)` | Constructor that allows the caller to specify an InputStream containing a mailcap file.
    `MailcapCommandMap​(String fileName)` | Constructor that allows the caller to specify the path of a mailcap file.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addMailcap​(String mail_cap)` | Add entries to the registry.
    `DataContentHandler` | `createDataContentHandler​(String mimeType)` | Return the DataContentHandler for the specified MIME type.
    `CommandInfo[]` | `getAllCommands​(String mimeType)` | Get all the available commands in all mailcap files known to this instance of MailcapCommandMap for this MIME type.
    `CommandInfo` | `getCommand​(String mimeType, String cmdName)` | Get the command corresponding to `cmdName` for the MIME type.
    `String[]` | `getMimeTypes​()` | Get all the MIME types known to this command map.
    `String[]` | `getNativeCommands​(String mimeType)` | Get the native commands for the given MIME type.
    `CommandInfo[]` | `getPreferredCommands​(String mimeType)` | Get the preferred command list for a MIME Type.

    - ### Methods inherited from class javax.activation.CommandMap

      `createDataContentHandler, getAllCommands, getCommand, getDefaultCommandMap, getPreferredCommands, setDefaultCommandMap`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### MailcapCommandMap

          public MailcapCommandMap​()

      The default Constructor.

    - #### MailcapCommandMap

          public MailcapCommandMap​(String fileName)
                            throws IOException

      Constructor that allows the caller to specify the path of a mailcap file.
      Parameters:
        `fileName` - The name of the mailcap file to open
      Throws:
        `IOException` - if the file can't be accessed

    - #### MailcapCommandMap

          public MailcapCommandMap​(InputStream is)

      Constructor that allows the caller to specify an InputStream containing a mailcap file.
      Parameters:
        `is` - InputStream of the mailcap file to open

  - ### Method Detail

    - #### getPreferredCommands

          public CommandInfo[] getPreferredCommands​(String mimeType)

      Get the preferred command list for a MIME Type. The MailcapCommandMap searches the mailcap files as described above under Mailcap file search order.

      The result of the search is a proper subset of available commands in all mailcap files known to this instance of MailcapCommandMap. The first entry for a particular command is considered the preferred command.

      Specified by:
        `getPreferredCommands` in class `CommandMap`
      Parameters:
        `mimeType` - the MIME type
      Returns:
        the CommandInfo objects representing the preferred commands.

    - #### getAllCommands

          public CommandInfo[] getAllCommands​(String mimeType)

      Get all the available commands in all mailcap files known to this instance of MailcapCommandMap for this MIME type.
      Specified by:
        `getAllCommands` in class `CommandMap`
      Parameters:
        `mimeType` - the MIME type
      Returns:
        the CommandInfo objects representing all the commands.

    - #### getCommand

          public CommandInfo getCommand​(String mimeType,
                                        String cmdName)

      Get the command corresponding to `cmdName` for the MIME type.
      Specified by:
        `getCommand` in class `CommandMap`
      Parameters:
        `mimeType` - the MIME type
        `cmdName` - the command name
      Returns:
        the CommandInfo object corresponding to the command.

    - #### addMailcap

          public void addMailcap​(String mail_cap)

      Add entries to the registry. Programmatically added entries are searched before other entries.

      The string that is passed in should be in mailcap format.

      Parameters:
        `mail_cap` - a correctly formatted mailcap string

    - #### createDataContentHandler

          public DataContentHandler createDataContentHandler​(String mimeType)

      Return the DataContentHandler for the specified MIME type.
      Specified by:
        `createDataContentHandler` in class `CommandMap`
      Parameters:
        `mimeType` - the MIME type
      Returns:
        the DataContentHandler

    - #### getMimeTypes

          public String[] getMimeTypes​()

      Get all the MIME types known to this command map.
      Overrides:
        `getMimeTypes` in class `CommandMap`
      Returns:
        array of MIME types as strings
      Since:
        1.6, JAF 1.1

    - #### getNativeCommands

          public String[] getNativeCommands​(String mimeType)

      Get the native commands for the given MIME type. Returns an array of strings where each string is an entire mailcap file entry. The application will need to parse the entry to extract the actual command as well as any attributes it needs. See RFC 1524 for details of the mailcap entry syntax. Only mailcap entries that specify a view command for the specified MIME type are returned.
      Parameters:
        `mimeType` - the MIME type
      Returns:
        array of native command entries
      Since:
        1.6, JAF 1.1