1 /*

     2  * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 package jdk.tools.jlink.plugin;

    26 

    27 import java.util.Collections;

    28 import java.util.EnumSet;

    29 import java.util.Map;

    30 import java.util.Set;

    31 import jdk.tools.jlink.internal.plugins.PluginsResourceBundle;

    32 

    33 /**

    34  * Base interface that jlink plugins should implement.

    35  */

    36 public interface Plugin {

    37 

    38     /**

    39      * Order of categories matches the plugin sort order.

    40      * <ol>

    41      * <li>FILTER: Filter in/out resources or files.</li>

    42      * <li>TRANSFORMER: Transform resources or files(eg: refactoring, bytecode

    43      * manipulation).</li>

    44      * <li>MODULEINFO_TRANSFORMER: Transform only module-info.class</li>

    45      * <li>SORTER: Sort resources within the resource container.</li>

    46      * <li>METAINFO_ADDER: Added meta info (like release, copyright etc.)</li>

    47      * <li>COMPRESSOR: Compress resource within the resouce containers.</li>

    48      * <li>VERIFIER: Does some image verification.</li>

    49      * <li>PROCESSOR: Does some post processing on image.</li>

    50      * <li>PACKAGER: Final processing</li>

    51      * </ol>

    52      */

    53     public enum Category {

    54         FILTER("FILTER"),

    55         TRANSFORMER("TRANSFORMER"),

    56         MODULEINFO_TRANSFORMER("MODULEINFO_TRANSFORMER"),

    57         SORTER("SORTER"),

    58         METAINFO_ADDER("METAINFO_ADDER"),

    59         COMPRESSOR("COMPRESSOR"),

    60         VERIFIER("VERIFIER"),

    61         PROCESSOR("PROCESSOR"),

    62         PACKAGER("PACKAGER");

    63 

    64         private final String name;

    65 

    66         Category(String name) {

    67             this.name = name;

    68         }

    69 

    70         public String getName() {

    71             return name;

    72         }

    73     }

    74 

    75     /**

    76      * Plugin state:

    77      * <ul>

    78      * <li>DISABLED: The plugin is not exposed in help and will be not called.</li>

    79      * <li>AUTO_ENABLED: The plugin is enabled by default. It doesn't require its

    80      * option to be present to be called.<li>

    81      * <li>FUNCTIONAL: The plugin is properly configured and can operate.

    82      * Non functional plugin must advertise their status in the

    83      * {@link #getStateDescription() getStateDescription} method</li>

    84      * </ul>

    85      */

    86     public enum State {

    87         DISABLED,

    88         AUTO_ENABLED,

    89         FUNCTIONAL

    90     }

    91 

    92     /**

    93      * The type of this plugin.

    94      *

    95      * @return The type of this plugin

    96      */

    97     public default Category getType() {

    98         return Category.TRANSFORMER;

    99     }

   100 

   101     /**

   102      * The Plugin set of states.

   103      * @return The set of states.

   104      */

   105     public default Set<State> getState() {

   106         return EnumSet.of(State.FUNCTIONAL);

   107     }

   108 

   109     /**

   110      * The plugin name.

   111      * @return The name.

   112      */

   113     public default String getName() {

   114         return getClass().getName().replace('.', '-');

   115     }

   116 

   117     /**

   118      * The plugin description.

   119      * @return  The description.

   120      */

   121     public default String getDescription() {

   122         return "";

   123     }

   124 

   125     /**

   126      * The option that identifies this plugin. This may be null.

   127      * "--" is prefixed to the String (when non-null) when invoking

   128      * this plugin from jlink command line.

   129      *

   130      * @return The plugin option.

   131      */

   132     public default String getOption() {

   133         return getName();

   134     }

   135 

   136     /**

   137      * Has this plugin require one or more arguments?

   138      * A plugin can have one or more optional arguments.

   139      * <br>

   140      * A plugin option with a single argument is specified as follows:

   141      * <pre>

   142      *     --plugin-option=arg_value

   143      * </pre>

   144      * If there are more than arguments, command line option looks like:

   145      * <pre>

   146      *     --plugin-option=arg_value:arg2=value2:arg3=value3...

   147      *</pre>

   148      *

   149      * @return true if arguments are needed.

   150      */

   151     public default boolean hasArguments() {

   152         return false;

   153     }

   154 

   155     /**

   156      * The plugin argument(s) description.

   157      * @return  The argument(s) description.

   158      */

   159     public default String getArgumentsDescription() {

   160         return "";

   161     }

   162 

   163     /**

   164      * Return a message indicating the status of the provider.

   165      *

   166      * @return A status description.

   167      */

   168     public default String getStateDescription() {

   169         return getState().contains(State.FUNCTIONAL)

   170                 ? PluginsResourceBundle.getMessage("main.status.ok")

   171                 : PluginsResourceBundle.getMessage("main.status.not.ok");

   172     }

   173 

   174     /**

   175      * Configure the plugin based on the passed configuration.

   176      * This method is called prior to invoke the plugin.

   177      *

   178      * @param config The plugin configuration.

   179      * @throws IllegalArgumentException if a mandatory argument is missing or

   180      * if an argument has invalid value.

   181      */

   182     public default void configure(Map<String, String> config) {

   183     }

   184 

   185     /**

   186      * Visit the content of the modules that are composing the image.

   187      *

   188      * @param in Read only content.

   189      * @param out The pool to fill with content. This pool must contain

   190      * the result of the visit.

   191      *

   192      * @throws PluginException

   193      */

   194     public ResourcePool transform(ResourcePool in, ResourcePoolBuilder out);

   195 }