/*
 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.activation;

import java.util.Map;
import java.util.WeakHashMap;


The CommandMap class provides an interface to a registry of
command objects available in the system.
Developers are expected to either use the CommandMap
implementation included with this package (MailcapCommandMap) or
develop their own. Note that some of the methods in this class are
abstract.
Since:
1.6/**
 * The CommandMap class provides an interface to a registry of
 * command objects available in the system.
 * Developers are expected to either use the CommandMap
 * implementation included with this package (MailcapCommandMap) or
 * develop their own. Note that some of the methods in this class are
 * abstract.
 *
 * @since 1.6
 */
public abstract class CommandMap {
    private static CommandMap defaultCommandMap = null;
    private static Map<ClassLoader,CommandMap> map =
                                new WeakHashMap<ClassLoader,CommandMap>();

    
Get the default CommandMap.

 In cases where a CommandMap instance has been previously set
     to some value (via setDefaultCommandMap)
 return the CommandMap.
 In cases where no CommandMap has been set, the CommandMap creates an instance of MailcapCommandMap and set that to the default, returning its value. 
Returns:
the CommandMap/**
     * Get the default CommandMap.
     *
     * <ul>
     * <li> In cases where a CommandMap instance has been previously set
     *      to some value (via <i>setDefaultCommandMap</i>)
     *  return the CommandMap.
     * <li>
     *  In cases where no CommandMap has been set, the CommandMap
     *       creates an instance of {@code MailcapCommandMap} and
     *       set that to the default, returning its value.
     *
     * </ul>
     *
     * @return the CommandMap
     */
    public static synchronized CommandMap getDefaultCommandMap() {
        if (defaultCommandMap != null)
            return defaultCommandMap;

        // fetch per-thread-context-class-loader default
        ClassLoader tccl = SecuritySupport.getContextClassLoader();
        CommandMap def = map.get(tccl);
        if (def == null) {
            def = new MailcapCommandMap();
            map.put(tccl, def);
        }
        return def;
    }

    
Set the default CommandMap. Reset the CommandMap to the default by calling this method with null. 
Params:
commandMap – The new default CommandMap.
Throws:
SecurityException – if the caller doesn't have permission
                                 to change the default/**
     * Set the default CommandMap. Reset the CommandMap to the default by
     * calling this method with {@code null}.
     *
     * @param commandMap The new default CommandMap.
     * @exception SecurityException if the caller doesn't have permission
     *                                  to change the default
     */
    public static synchronized void setDefaultCommandMap(CommandMap commandMap) {
        SecurityManager security = System.getSecurityManager();
        if (security != null) {
            try {
                // if it's ok with the SecurityManager, it's ok with me...
                security.checkSetFactory();
            } catch (SecurityException ex) {
                // otherwise, we also allow it if this code and the
                // factory come from the same (non-system) class loader (e.g.,
                // the JAF classes were loaded with the applet classes).
                ClassLoader cl = CommandMap.class.getClassLoader();
                if (cl == null || cl.getParent() == null ||
                    cl != commandMap.getClass().getClassLoader()) {
                    throw ex;
                }
            }
        }
        // remove any per-thread-context-class-loader CommandMap
        map.remove(SecuritySupport.getContextClassLoader());
        defaultCommandMap = commandMap;
    }

    
Get the preferred command list from a MIME Type. The actual semantics
are determined by the implementation of the CommandMap.
Params:
mimeType –  the MIME type
Returns:
the CommandInfo classes that represent the command Beans./**
     * Get the preferred command list from a MIME Type. The actual semantics
     * are determined by the implementation of the CommandMap.
     *
     * @param mimeType  the MIME type
     * @return the CommandInfo classes that represent the command Beans.
     */
    abstract public  CommandInfo[] getPreferredCommands(String mimeType);

    
Get the preferred command list from a MIME Type. The actual semantics
are determined by the implementation of the CommandMap. 
 The DataSource provides extra information, such as the file name, that a CommandMap implementation may use to further refine the list of commands that are returned. The implementation in this class simply calls the getPreferredCommands method that ignores this argument. 
Params:
mimeType –  the MIME type
ds –        a DataSource for the data
Returns:
the CommandInfo classes that represent the command Beans.
Since:
  1.6, JAF 1.1/**
     * Get the preferred command list from a MIME Type. The actual semantics
     * are determined by the implementation of the CommandMap. <p>
     *
     * The {@code DataSource} provides extra information, such as
     * the file name, that a CommandMap implementation may use to further
     * refine the list of commands that are returned.  The implementation
     * in this class simply calls the {@code getPreferredCommands}
     * method that ignores this argument.
     *
     * @param mimeType  the MIME type
     * @param ds        a DataSource for the data
     * @return the CommandInfo classes that represent the command Beans.
     * @since   1.6, JAF 1.1
     */
    public CommandInfo[] getPreferredCommands(String mimeType, DataSource ds) {
        return getPreferredCommands(mimeType);
    }

    
Get all the available commands for this type. This method
should return all the possible commands for this MIME type.
Params:
mimeType –  the MIME type
Returns:
the CommandInfo objects representing all the commands./**
     * Get all the available commands for this type. This method
     * should return all the possible commands for this MIME type.
     *
     * @param mimeType  the MIME type
     * @return the CommandInfo objects representing all the commands.
     */
    abstract public CommandInfo[] getAllCommands(String mimeType);

    
Get all the available commands for this type. This method
should return all the possible commands for this MIME type. 
 The DataSource provides extra information, such as the file name, that a CommandMap implementation may use to further refine the list of commands that are returned. The implementation in this class simply calls the getAllCommands method that ignores this argument. 
Params:
mimeType –  the MIME type
ds –        a DataSource for the data
Returns:
the CommandInfo objects representing all the commands.
Since:
  1.6, JAF 1.1/**
     * Get all the available commands for this type. This method
     * should return all the possible commands for this MIME type. <p>
     *
     * The {@code DataSource} provides extra information, such as
     * the file name, that a CommandMap implementation may use to further
     * refine the list of commands that are returned.  The implementation
     * in this class simply calls the {@code getAllCommands}
     * method that ignores this argument.
     *
     * @param mimeType  the MIME type
     * @param ds        a DataSource for the data
     * @return the CommandInfo objects representing all the commands.
     * @since   1.6, JAF 1.1
     */
    public CommandInfo[] getAllCommands(String mimeType, DataSource ds) {
        return getAllCommands(mimeType);
    }

    
Get the default command corresponding to the MIME type.
Params:
mimeType –  the MIME type
cmdName –   the command name
Returns:
the CommandInfo corresponding to the command./**
     * Get the default command corresponding to the MIME type.
     *
     * @param mimeType  the MIME type
     * @param cmdName   the command name
     * @return the CommandInfo corresponding to the command.
     */
    abstract public CommandInfo getCommand(String mimeType, String cmdName);

    
Get the default command corresponding to the MIME type. 
 The DataSource provides extra information, such as the file name, that a CommandMap implementation may use to further refine the command that is chosen. The implementation in this class simply calls the getCommand method that ignores this argument. 
Params:
mimeType –  the MIME type
cmdName –   the command name
ds –        a DataSource for the data
Returns:
the CommandInfo corresponding to the command.
Since:
  1.6, JAF 1.1/**
     * Get the default command corresponding to the MIME type. <p>
     *
     * The {@code DataSource} provides extra information, such as
     * the file name, that a CommandMap implementation may use to further
     * refine the command that is chosen.  The implementation
     * in this class simply calls the {@code getCommand}
     * method that ignores this argument.
     *
     * @param mimeType  the MIME type
     * @param cmdName   the command name
     * @param ds        a DataSource for the data
     * @return the CommandInfo corresponding to the command.
     * @since   1.6, JAF 1.1
     */
    public CommandInfo getCommand(String mimeType, String cmdName,
                                DataSource ds) {
        return getCommand(mimeType, cmdName);
    }

    
Locate a DataContentHandler that corresponds to the MIME type.
The mechanism and semantics for determining this are determined
by the implementation of the particular CommandMap.
Params:
mimeType –  the MIME type
Returns:
         the DataContentHandler for the MIME type/**
     * Locate a DataContentHandler that corresponds to the MIME type.
     * The mechanism and semantics for determining this are determined
     * by the implementation of the particular CommandMap.
     *
     * @param mimeType  the MIME type
     * @return          the DataContentHandler for the MIME type
     */
    abstract public DataContentHandler createDataContentHandler(String
                                                                mimeType);

    
Locate a DataContentHandler that corresponds to the MIME type.
The mechanism and semantics for determining this are determined
by the implementation of the particular CommandMap. 
 The DataSource provides extra information, such as the file name, that a CommandMap implementation may use to further refine the choice of DataContentHandler. The implementation in this class simply calls the createDataContentHandler method that ignores this argument. 
Params:
mimeType –  the MIME type
ds –        a DataSource for the data
Returns:
         the DataContentHandler for the MIME type
Since:
  1.6, JAF 1.1/**
     * Locate a DataContentHandler that corresponds to the MIME type.
     * The mechanism and semantics for determining this are determined
     * by the implementation of the particular CommandMap. <p>
     *
     * The {@code DataSource} provides extra information, such as
     * the file name, that a CommandMap implementation may use to further
     * refine the choice of DataContentHandler.  The implementation
     * in this class simply calls the {@code createDataContentHandler}
     * method that ignores this argument.
     *
     * @param mimeType  the MIME type
     * @param ds        a DataSource for the data
     * @return          the DataContentHandler for the MIME type
     * @since   1.6, JAF 1.1
     */
    public DataContentHandler createDataContentHandler(String mimeType,
                                DataSource ds) {
        return createDataContentHandler(mimeType);
    }

    
Get all the MIME types known to this command map.
If the command map doesn't support this operation,
null is returned.
Returns:
         array of MIME types as strings, or null if not supported
Since:
  1.6, JAF 1.1/**
     * Get all the MIME types known to this command map.
     * If the command map doesn't support this operation,
     * null is returned.
     *
     * @return          array of MIME types as strings, or null if not supported
     * @since   1.6, JAF 1.1
     */
    public String[] getMimeTypes() {
        return null;
    }
}