/*

 * 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 java.lang;

import java.lang.module.Configuration;

import java.lang.module.ModuleDescriptor;

import java.lang.module.ResolvedModule;

import java.util.ArrayDeque;

import java.util.ArrayList;

import java.util.Collections;

import java.util.Deque;

import java.util.HashMap;

import java.util.HashSet;

import java.util.List;

import java.util.Map;

import java.util.Objects;

import java.util.Optional;

import java.util.Set;

import java.util.concurrent.CopyOnWriteArrayList;

import java.util.function.Function;

import java.util.stream.Collectors;

import java.util.stream.Stream;

import jdk.internal.loader.ClassLoaderValue;

import jdk.internal.loader.Loader;

import jdk.internal.loader.LoaderPool;

import jdk.internal.module.ServicesCatalog;

import sun.security.util.SecurityConstants;

/**

 * A layer of modules in the Java virtual machine.

 *

 * <p> A layer is created from a graph of modules in a {@link Configuration}

 * and a function that maps each module to a {@link ClassLoader}.

 * Creating a layer informs the Java virtual machine about the classes that

 * may be loaded from the modules so that the Java virtual machine knows which

 * module that each class is a member of. </p>

 *

 * <p> Creating a layer creates a {@link Module} object for each {@link

 * ResolvedModule} in the configuration. For each resolved module that is

 * {@link ResolvedModule#reads() read}, the {@code Module} {@link

 * Module#canRead reads} the corresponding run-time {@code Module}, which may

 * be in the same layer or a {@link #parents() parent} layer. </p>

 *

 * <p> The {@link #defineModulesWithOneLoader defineModulesWithOneLoader} and

 * {@link #defineModulesWithManyLoaders defineModulesWithManyLoaders} methods

 * provide convenient ways to create a module layer where all modules are

 * mapped to a single class loader or where each module is mapped to its own

 * class loader. The {@link #defineModules defineModules} method is for more

 * advanced cases where modules are mapped to custom class loaders by means of

 * a function specified to the method. Each of these methods has an instance

 * and static variant. The instance methods create a layer with the receiver

 * as the parent layer. The static methods are for more advanced cases where

 * there can be more than one parent layer or where a {@link

 * ModuleLayer.Controller Controller} is needed to control modules in the layer

 * </p>

 *

 * <p> A Java virtual machine has at least one non-empty layer, the {@link

 * #boot() boot} layer, that is created when the Java virtual machine is

 * started. The boot layer contains module {@code java.base} and is the only

 * layer in the Java virtual machine with a module named "{@code java.base}".

 * The modules in the boot layer are mapped to the bootstrap class loader and

 * other class loaders that are <a href="ClassLoader.html#builtinLoaders">

 * built-in</a> into the Java virtual machine. The boot layer will often be

 * the {@link #parents() parent} when creating additional layers. </p>

 *

 * <p> Each {@code Module} in a layer is created so that it {@link

 * Module#isExported(String) exports} and {@link Module#isOpen(String) opens}

 * the packages described by its {@link ModuleDescriptor}. Qualified exports

 * (where a package is exported to a set of target modules rather than all

 * modules) are reified when creating the layer as follows: </p>

 * <ul>

 *     <li> If module {@code X} exports a package to {@code Y}, and if the

 *     runtime {@code Module} {@code X} reads {@code Module} {@code Y}, then

 *     the package is exported to {@code Module} {@code Y} (which may be in

 *     the same layer as {@code X} or a parent layer). </li>

 *

 *     <li> If module {@code X} exports a package to {@code Y}, and if the

 *     runtime {@code Module} {@code X} does not read {@code Y} then target

 *     {@code Y} is located as if by invoking {@link #findModule(String)

 *     findModule} to find the module in the layer or its parent layers. If

 *     {@code Y} is found then the package is exported to the instance of

 *     {@code Y} that was found. If {@code Y} is not found then the qualified

 *     export is ignored. </li>

 * </ul>

 *

 * <p> Qualified opens are handled in same way as qualified exports. </p>

 *

 * <p> As when creating a {@code Configuration},

 * {@link ModuleDescriptor#isAutomatic() automatic} modules receive special

 * treatment when creating a layer. An automatic module is created in the

 * Java virtual machine as a {@code Module} that reads every unnamed {@code

 * Module} in the Java virtual machine. </p>

 *

 * <p> Unless otherwise specified, passing a {@code null} argument to a method

 * in this class causes a {@link NullPointerException NullPointerException} to

 * be thrown. </p>

 *

 * <h3> Example usage: </h3>

 *

 * <p> This example creates a configuration by resolving a module named

 * "{@code myapp}" with the configuration for the boot layer as the parent. It

 * then creates a new layer with the modules in this configuration. All modules

 * are defined to the same class loader. </p>

 *

 * <pre>{@code

 *     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

 *

 *     ModuleLayer parent = ModuleLayer.boot();

 *

 *     Configuration cf = parent.configuration().resolve(finder, ModuleFinder.of(), Set.of("myapp"));

 *

 *     ClassLoader scl = ClassLoader.getSystemClassLoader();

 *

 *     ModuleLayer layer = parent.defineModulesWithOneLoader(cf, scl);

 *

 *     Class<?> c = layer.findLoader("myapp").loadClass("app.Main");

 * }</pre>

 *

 * @since 9

 * @spec JPMS

 * @see Module#getLayer()

 */

public final class ModuleLayer {

    // the empty layer

    private static final ModuleLayer EMPTY_LAYER

        = new ModuleLayer(Configuration.empty(), List.of(), null);

    // the configuration from which this layer was created

    private final Configuration cf;

    // parent layers, empty in the case of the empty layer

    private final List<ModuleLayer> parents;

    // maps module name to jlr.Module

    private final Map<String, Module> nameToModule;

    /**

     * Creates a new module layer from the modules in the given configuration.

     */

    private ModuleLayer(Configuration cf,

                        List<ModuleLayer> parents,

                        Function<String, ClassLoader> clf)

    {

        this.cf = cf;

        this.parents = parents; // no need to do defensive copy

        Map<String, Module> map;

        if (parents.isEmpty()) {

            map = Map.of();

        } else {

            map = Module.defineModules(cf, clf, this);

        }

        this.nameToModule = map; // no need to do defensive copy

    }

    /**

     * Controls a module layer. The static methods defined by {@link ModuleLayer}

     * to create module layers return a {@code Controller} that can be used to

     * control modules in the layer.

     *

     * <p> Unless otherwise specified, passing a {@code null} argument to a

     * method in this class causes a {@link NullPointerException

     * NullPointerException} to be thrown. </p>

     *

     * @apiNote Care should be taken with {@code Controller} objects, they

     * should never be shared with untrusted code.

     *

     * @since 9

     * @spec JPMS

     */

    public static final class Controller {

        private final ModuleLayer layer;

        Controller(ModuleLayer layer) {

            this.layer = layer;

        }

        /**

         * Returns the layer that this object controls.

         *

         * @return the module layer

         */

        public ModuleLayer layer() {

            return layer;

        }

        private void ensureInLayer(Module source) {

            if (source.getLayer() != layer)

                throw new IllegalArgumentException(source + " not in layer");

        }

        /**

         * Updates module {@code source} in the layer to read module

         * {@code target}. This method is a no-op if {@code source} already

         * reads {@code target}.

         *

         * @implNote <em>Read edges</em> added by this method are <em>weak</em>

         * and do not prevent {@code target} from being GC'ed when {@code source}

         * is strongly reachable.

         *

         * @param  source

         *         The source module

         * @param  target

         *         The target module to read

         *

         * @return This controller

         *

         * @throws IllegalArgumentException

         *         If {@code source} is not in the module layer

         *

         * @see Module#addReads

         */

        public Controller addReads(Module source, Module target) {

            ensureInLayer(source);

            source.implAddReads(target);

            return this;

        }

        /**

         * Updates module {@code source} in the layer to export a package to

         * module {@code target}. This method is a no-op if {@code source}

         * already exports the package to at least {@code target}.

         *

         * @param  source

         *         The source module

         * @param  pn

         *         The package name

         * @param  target

         *         The target module

         *

         * @return This controller

         *

         * @throws IllegalArgumentException

         *         If {@code source} is not in the module layer or the package

         *         is not in the source module

         *

         * @see Module#addExports

         */

        public Controller addExports(Module source, String pn, Module target) {

            ensureInLayer(source);

            source.implAddExports(pn, target);

            return this;

        }

        /**

         * Updates module {@code source} in the layer to open a package to

         * module {@code target}. This method is a no-op if {@code source}

         * already opens the package to at least {@code target}.

         *

         * @param  source

         *         The source module

         * @param  pn

         *         The package name

         * @param  target

         *         The target module

         *

         * @return This controller

         *

         * @throws IllegalArgumentException

         *         If {@code source} is not in the module layer or the package

         *         is not in the source module

         *

         * @see Module#addOpens

         */

        public Controller addOpens(Module source, String pn, Module target) {

            ensureInLayer(source);

            source.implAddOpens(pn, target);

            return this;

        }

    }

    /**

     * Creates a new module layer, with this layer as its parent, by defining the

     * modules in the given {@code Configuration} to the Java virtual machine.

     * This method creates one class loader and defines all modules to that

     * class loader. The {@link ClassLoader#getParent() parent} of each class

     * loader is the given parent class loader. This method works exactly as

     * specified by the static {@link

     * #defineModulesWithOneLoader(Configuration,List,ClassLoader)

     * defineModulesWithOneLoader} method when invoked with this layer as the

     * parent. In other words, if this layer is {@code thisLayer} then this

     * method is equivalent to invoking:

     * <pre> {@code

     *     ModuleLayer.defineModulesWithOneLoader(cf, List.of(thisLayer), parentLoader).layer();

     * }</pre>

     *

     * @param  cf

     *         The configuration for the layer

     * @param  parentLoader

     *         The parent class loader for the class loader created by this

     *         method; may be {@code null} for the bootstrap class loader

     *

     * @return The newly created layer

     *

     * @throws IllegalArgumentException

     *         If the given configuration has more than one parent or the parent

     *         of the configuration is not the configuration for this layer

     * @throws LayerInstantiationException

     *         If the layer cannot be created for any of the reasons specified

     *         by the static {@code defineModulesWithOneLoader} method

     * @throws SecurityException

     *         If {@code RuntimePermission("createClassLoader")} or

     *         {@code RuntimePermission("getClassLoader")} is denied by

     *         the security manager

     *

     * @see #findLoader

     */

    public ModuleLayer defineModulesWithOneLoader(Configuration cf,

                                                  ClassLoader parentLoader) {

        return defineModulesWithOneLoader(cf, List.of(this), parentLoader).layer();

    }

    /**

     * Creates a new module layer, with this layer as its parent, by defining the

     * modules in the given {@code Configuration} to the Java virtual machine.

     * Each module is defined to its own {@link ClassLoader} created by this

     * method. The {@link ClassLoader#getParent() parent} of each class loader

     * is the given parent class loader. This method works exactly as specified

     * by the static {@link

     * #defineModulesWithManyLoaders(Configuration,List,ClassLoader)

     * defineModulesWithManyLoaders} method when invoked with this layer as the

     * parent. In other words, if this layer is {@code thisLayer} then this

     * method is equivalent to invoking:

     * <pre> {@code

     *     ModuleLayer.defineModulesWithManyLoaders(cf, List.of(thisLayer), parentLoader).layer();

     * }</pre>

     *

     * @param  cf

     *         The configuration for the layer

     * @param  parentLoader

     *         The parent class loader for each of the class loaders created by

     *         this method; may be {@code null} for the bootstrap class loader

     *

     * @return The newly created layer

     *

     * @throws IllegalArgumentException

     *         If the given configuration has more than one parent or the parent

     *         of the configuration is not the configuration for this layer

     * @throws LayerInstantiationException

     *         If the layer cannot be created for any of the reasons specified

     *         by the static {@code defineModulesWithManyLoaders} method

     * @throws SecurityException

     *         If {@code RuntimePermission("createClassLoader")} or

     *         {@code RuntimePermission("getClassLoader")} is denied by

     *         the security manager

     *

     * @see #findLoader

     */

    public ModuleLayer defineModulesWithManyLoaders(Configuration cf,

                                                    ClassLoader parentLoader) {

        return defineModulesWithManyLoaders(cf, List.of(this), parentLoader).layer();

    }

    /**

     * Creates a new module layer, with this layer as its parent, by defining the

     * modules in the given {@code Configuration} to the Java virtual machine.

     * Each module is mapped, by name, to its class loader by means of the

     * given function. This method works exactly as specified by the static

     * {@link #defineModules(Configuration,List,Function) defineModules}

     * method when invoked with this layer as the parent. In other words, if

     * this layer is {@code thisLayer} then this method is equivalent to

     * invoking:

     * <pre> {@code

     *     ModuleLayer.defineModules(cf, List.of(thisLayer), clf).layer();

     * }</pre>

     *

     * @param  cf

     *         The configuration for the layer

     * @param  clf

     *         The function to map a module name to a class loader

     *

     * @return The newly created layer

     *

     * @throws IllegalArgumentException

     *         If the given configuration has more than one parent or the parent

     *         of the configuration is not the configuration for this layer

     * @throws LayerInstantiationException

     *         If the layer cannot be created for any of the reasons specified

     *         by the static {@code defineModules} method

     * @throws SecurityException

     *         If {@code RuntimePermission("getClassLoader")} is denied by

     *         the security manager

     */

    public ModuleLayer defineModules(Configuration cf,

                                     Function<String, ClassLoader> clf) {

        return defineModules(cf, List.of(this), clf).layer();

    }

    /**

     * Creates a new module layer by defining the modules in the given {@code

     * Configuration} to the Java virtual machine. This method creates one

     * class loader and defines all modules to that class loader.

     *

     * <p> The class loader created by this method implements <em>direct

     * delegation</em> when loading classes from modules. If the {@link

     * ClassLoader#loadClass(String, boolean) loadClass} method is invoked to

     * load a class then it uses the package name of the class to map it to a

     * module. This may be a module in this layer and hence defined to the same

     * class loader. It may be a package in a module in a parent layer that is

     * exported to one or more of the modules in this layer. The class

     * loader delegates to the class loader of the module, throwing {@code

     * ClassNotFoundException} if not found by that class loader.

     * When {@code loadClass} is invoked to load classes that do not map to a

     * module then it delegates to the parent class loader. </p>

     *

     * <p> The class loader created by this method locates resources

     * ({@link ClassLoader#getResource(String) getResource}, {@link

     * ClassLoader#getResources(String) getResources}, and other resource

     * methods) in all modules in the layer before searching the parent class

     * loader. </p>

     *

     * <p> Attempting to create a layer with all modules defined to the same

     * class loader can fail for the following reasons:

     *

     * <ul>

     *

     *     <li><p> <em>Overlapping packages</em>: Two or more modules in the

     *     configuration have the same package. </p></li>

     *

     *     <li><p> <em>Split delegation</em>: The resulting class loader would

     *     need to delegate to more than one class loader in order to load

     *     classes in a specific package. </p></li>

     *

     * </ul>

     *

     * <p> In addition, a layer cannot be created if the configuration contains

     * a module named "{@code java.base}", or a module contains a package named

     * "{@code java}" or a package with a name starting with "{@code java.}". </p>

     *

     * <p> If there is a security manager then the class loader created by

     * this method will load classes and resources with privileges that are

     * restricted by the calling context of this method. </p>

     *

     * @param  cf

     *         The configuration for the layer

     * @param  parentLayers

     *         The list of parent layers in search order

     * @param  parentLoader

     *         The parent class loader for the class loader created by this

     *         method; may be {@code null} for the bootstrap class loader

     *

     * @return A controller that controls the newly created layer

     *

     * @throws IllegalArgumentException

     *         If the parent(s) of the given configuration do not match the

     *         configuration of the parent layers, including order

     * @throws LayerInstantiationException

     *         If all modules cannot be defined to the same class loader for any

     *         of the reasons listed above

     * @throws SecurityException

     *         If {@code RuntimePermission("createClassLoader")} or

     *         {@code RuntimePermission("getClassLoader")} is denied by

     *         the security manager

     *

     * @see #findLoader

     */

    public static Controller defineModulesWithOneLoader(Configuration cf,

                                                        List<ModuleLayer> parentLayers,

                                                        ClassLoader parentLoader)

    {

        List<ModuleLayer> parents = new ArrayList<>(parentLayers);

        checkConfiguration(cf, parents);

        checkCreateClassLoaderPermission();

        checkGetClassLoaderPermission();

        try {

            Loader loader = new Loader(cf.modules(), parentLoader);

            loader.initRemotePackageMap(cf, parents);

            ModuleLayer layer = new ModuleLayer(cf, parents, mn -> loader);

            return new Controller(layer);

        } catch (IllegalArgumentException | IllegalStateException e) {

            throw new LayerInstantiationException(e.getMessage());

        }

    }

    /**

     * Creates a new module layer by defining the modules in the given {@code

     * Configuration} to the Java virtual machine. Each module is defined to

     * its own {@link ClassLoader} created by this method. The {@link

     * ClassLoader#getParent() parent} of each class loader is the given parent

     * class loader.

     *

     * <p> The class loaders created by this method implement <em>direct

     * delegation</em> when loading classes from modules. If the {@link

     * ClassLoader#loadClass(String, boolean) loadClass} method is invoked to

     * load a class then it uses the package name of the class to map it to a

     * module. The package may be in the module defined to the class loader.

     * The package may be exported by another module in this layer to the

     * module defined to the class loader. It may be in a package exported by a

     * module in a parent layer. The class loader delegates to the class loader

     * of the module, throwing {@code ClassNotFoundException} if not found by