/*
 * Copyright (c) 2015, 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 jdk.tools.jlink.plugin;

import java.util.Collections;
import java.util.EnumSet;
import java.util.Map;
import java.util.Set;
import jdk.tools.jlink.internal.plugins.PluginsResourceBundle;

Base interface that jlink plugins should implement.
/**
 * Base interface that jlink plugins should implement.
 */
public interface Plugin {

    
Order of categories matches the plugin sort order.

FILTER: Filter in/out resources or files.
TRANSFORMER: Transform resources or files(eg: refactoring, bytecode
manipulation).
MODULEINFO_TRANSFORMER: Transform only module-info.class
SORTER: Sort resources within the resource container.
METAINFO_ADDER: Added meta info (like release, copyright etc.)
COMPRESSOR: Compress resource within the resouce containers.
VERIFIER: Does some image verification.
PROCESSOR: Does some post processing on image.
PACKAGER: Final processing

/**
     * Order of categories matches the plugin sort order.
     * <ol>
     * <li>FILTER: Filter in/out resources or files.</li>
     * <li>TRANSFORMER: Transform resources or files(eg: refactoring, bytecode
     * manipulation).</li>
     * <li>MODULEINFO_TRANSFORMER: Transform only module-info.class</li>
     * <li>SORTER: Sort resources within the resource container.</li>
     * <li>METAINFO_ADDER: Added meta info (like release, copyright etc.)</li>
     * <li>COMPRESSOR: Compress resource within the resouce containers.</li>
     * <li>VERIFIER: Does some image verification.</li>
     * <li>PROCESSOR: Does some post processing on image.</li>
     * <li>PACKAGER: Final processing</li>
     * </ol>
     */
    public enum Category {
        FILTER("FILTER"),
        TRANSFORMER("TRANSFORMER"),
        MODULEINFO_TRANSFORMER("MODULEINFO_TRANSFORMER"),
        SORTER("SORTER"),
        METAINFO_ADDER("METAINFO_ADDER"),
        COMPRESSOR("COMPRESSOR"),
        VERIFIER("VERIFIER"),
        PROCESSOR("PROCESSOR"),
        PACKAGER("PACKAGER");

        private final String name;

        Category(String name) {
            this.name = name;
        }

        public String getName() {
            return name;
        }
    }

    
Plugin state:

DISABLED: The plugin is not exposed in help and will be not called.
AUTO_ENABLED: The plugin is enabled by default. It doesn't require its
option to be present to be called.

FUNCTIONAL: The plugin is properly configured and can operate. Non functional plugin must advertise their status in the getStateDescription method

/**
     * Plugin state:
     * <ul>
     * <li>DISABLED: The plugin is not exposed in help and will be not called.</li>
     * <li>AUTO_ENABLED: The plugin is enabled by default. It doesn't require its
     * option to be present to be called.<li>
     * <li>FUNCTIONAL: The plugin is properly configured and can operate.
     * Non functional plugin must advertise their status in the
     * {@link #getStateDescription() getStateDescription} method</li>
     * </ul>
     */
    public enum State {
        DISABLED,
        AUTO_ENABLED,
        FUNCTIONAL
    }

    
The type of this plugin.
Returns:
The type of this plugin/**
     * The type of this plugin.
     *
     * @return The type of this plugin
     */
    public default Category getType() {
        return Category.TRANSFORMER;
    }

    
The Plugin set of states.
Returns:
The set of states./**
     * The Plugin set of states.
     * @return The set of states.
     */
    public default Set<State> getState() {
        return EnumSet.of(State.FUNCTIONAL);
    }

    
The plugin name.
Returns:
The name./**
     * The plugin name.
     * @return The name.
     */
    public default String getName() {
        return getClass().getName().replace('.', '-');
    }

    
The plugin description.
Returns:
 The description./**
     * The plugin description.
     * @return  The description.
     */
    public default String getDescription() {
        return "";
    }

    
The option that identifies this plugin. This may be null.
"--" is prefixed to the String (when non-null) when invoking
this plugin from jlink command line.
Returns:
The plugin option./**
     * The option that identifies this plugin. This may be null.
     * "--" is prefixed to the String (when non-null) when invoking
     * this plugin from jlink command line.
     *
     * @return The plugin option.
     */
    public default String getOption() {
        return getName();
    }

    
Has this plugin require one or more arguments?
A plugin can have one or more optional arguments.


A plugin option with a single argument is specified as follows:
    --plugin-option=arg_value

If there are more than arguments, command line option looks like:
    --plugin-option=arg_value:arg2=value2:arg3=value3...

Returns:
true if arguments are needed./**
     * Has this plugin require one or more arguments?
     * A plugin can have one or more optional arguments.
     * <br>
     * A plugin option with a single argument is specified as follows:
     * <pre>
     *     --plugin-option=arg_value
     * </pre>
     * If there are more than arguments, command line option looks like:
     * <pre>
     *     --plugin-option=arg_value:arg2=value2:arg3=value3...
     *</pre>
     *
     * @return true if arguments are needed.
     */
    public default boolean hasArguments() {
        return false;
    }

    
The plugin argument(s) description.
Returns:
 The argument(s) description./**
     * The plugin argument(s) description.
     * @return  The argument(s) description.
     */
    public default String getArgumentsDescription() {
        return "";
    }

    
Return a message indicating the status of the provider.
Returns:
A status description./**
     * Return a message indicating the status of the provider.
     *
     * @return A status description.
     */
    public default String getStateDescription() {
        return getState().contains(State.FUNCTIONAL)
                ? PluginsResourceBundle.getMessage("main.status.ok")
                : PluginsResourceBundle.getMessage("main.status.not.ok");
    }

    
Configure the plugin based on the passed configuration.
This method is called prior to invoke the plugin.
Params:
config – The plugin configuration.
Throws:
IllegalArgumentException – if a mandatory argument is missing or
if an argument has invalid value./**
     * Configure the plugin based on the passed configuration.
     * This method is called prior to invoke the plugin.
     *
     * @param config The plugin configuration.
     * @throws IllegalArgumentException if a mandatory argument is missing or
     * if an argument has invalid value.
     */
    public default void configure(Map<String, String> config) {
    }

    
Visit the content of the modules that are composing the image.
Params:
in – Read only content.
out – The pool to fill with content. This pool must contain
the result of the visit.
Throws:
PluginException – /**
     * Visit the content of the modules that are composing the image.
     *
     * @param in Read only content.
     * @param out The pool to fill with content. This pool must contain
     * the result of the visit.
     *
     * @throws PluginException
     */
    public ResourcePool transform(ResourcePool in, ResourcePoolBuilder out);
}