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 */
25package jdk.tools.jlink.plugin;
26
27import java.util.Collections;
28import java.util.EnumSet;
29import java.util.Map;
30import java.util.Set;
31import jdk.tools.jlink.internal.plugins.PluginsResourceBundle;
32
33/**
34 * Base interface that jlink plugins should implement.
35 */
36public 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}
196