Module java.base
Package java.lang.module

Class Configuration

  • public final classConfigurationextendsObject
    A configuration that is the result of resolution or resolution withservice binding.

    A configuration encapsulates thereadability graph that is the output of resolution. A readability graph is a directed graph whose vertices are of typeResolvedModule and the edges represent the readability amongst the modules.Configuration defines themodules() method to get the set of resolved modules in the graph. ResolvedModule defines thereads() method to get the set of modules that a resolved module reads. The modules that are read may be in the same configuration or may be inparent configurations.

    Configuration defines theresolve method to resolve a collection of root modules, and theresolveAndBind method to do resolution with service binding. There are instance and static variants of both methods. The instance methods create a configuration with the receiver as the parent configuration. The static methods are for more advanced cases where there can be more than one parent configuration.

    Eachlayer of modules in the Java virtual machine is created from a configuration. The configuration for theboot layer is obtained by invoking ModuleLayer.boot().configuration(). The configuration for the boot layer will often be the parent when creating new configurations.

    Example

    The following example uses theresolve method to resolve a module namedmyapp with the configuration for the boot layer as the parent configuration. It prints the name of each resolved module and the names of the modules that each module reads.

        ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);    Configuration parent = ModuleLayer.boot().configuration();    Configuration cf = parent.resolve(finder, ModuleFinder.of(), Set.of("myapp"));    cf.modules().forEach(m -> {        System.out.format("%s -> %s%n",            m.name(),            m.reads().stream()                .map(ResolvedModule::name)                .collect(Collectors.joining(", ")));    });
    Since:
    9
    See Also:
    ModuleLayer

    • Method Detail

      • resolve

        public Configuration resolve​(ModuleFinder before,ModuleFinder after,Collection<String> roots)
        Resolves a collection of root modules, with this configuration as its parent, to create a new configuration. This method works exactly as specified by the staticresolve method when invoked with this configuration as the parent. In other words, if this configuration iscf then this method is equivalent to invoking:
             Configuration.resolve(before, List.of(cf), after, roots);
        Parameters:
        before - Thebefore module finder to find modules
        after - Theafter module finder to locate modules when not located by thebefore module finder or in parent configurations
        roots - The possibly-empty collection of module names of the modules to resolve
        Returns:
        The configuration that is the result of resolving the given root modules
        Throws:
        FindException - If resolution fails for any of the observability-related reasons specified by the staticresolve method
        ResolutionException - If resolution fails any of the consistency checks specified by the staticresolve method
        SecurityException - If locating a module is denied by the security manager

      • resolveAndBind

        public Configuration resolveAndBind​(ModuleFinder before,ModuleFinder after,Collection<String> roots)
        Resolves a collection of root modules, with service binding, and with this configuration as its parent, to create a new configuration. This method works exactly as specified by the staticresolveAndBind method when invoked with this configuration as the parent. In other words, if this configuration iscf then this method is equivalent to invoking:
             Configuration.resolveAndBind(before, List.of(cf), after, roots);
        Parameters:
        before - Thebefore module finder to find modules
        after - Theafter module finder to locate modules when not located by thebefore module finder or in parent configurations
        roots - The possibly-empty collection of module names of the modules to resolve
        Returns:
        The configuration that is the result of resolving, with service binding, the given root modules
        Throws:
        FindException - If resolution fails for any of the observability-related reasons specified by the staticresolve method
        ResolutionException - If resolution fails any of the consistency checks specified by the staticresolve method
        SecurityException - If locating a module is denied by the security manager

      • resolve

        public static Configuration resolve​(ModuleFinder before,List<Configuration> parents,ModuleFinder after,Collection<String> roots)
        Resolves a collection of root modules to create a configuration.

        Each root module is located using the givenbefore module finder. If a module is not found then it is located in the parent configuration as if by invoking thefindModule method on each parent in iteration order. If not found then the module is located using the givenafter module finder. The same search order is used to locate transitive dependences. Root modules or dependences that are located in a parent configuration are resolved no further and are not included in the resulting configuration.

        When all modules have been enumerated then a readability graph is computed, and in conjunction with the module exports and service use, checked for consistency.

        Resolution may fail withFindException for the followingobservability-related reasons:

        • A root module, or a direct or transitive dependency, is not found.

        • An error occurs when attempting to find a module. Possible errors include I/O errors, errors detected parsing a module descriptor (module-info.class) or two versions of the same module are found in the same directory.

        Resolution may fail withResolutionException if any of the following consistency checks fail:

        • A cycle is detected, say where modulem1 requires modulem2 andm2 requiresm1.

        • A module reads two or more modules with the same name. This includes the case where a module reads another with the same name as itself.

        • Two or more modules in the configuration export the same package to a module that reads both. This includes the case where a moduleM containing packagep reads another module that exportsp toM.

        • A moduleM declares that it "uses p.S" or "provides p.S with ..." but packagep is neither in moduleM nor exported toM by any module thatM reads.

        Implementation Note:
        In the implementation then observability of modules may depend on referential integrity or other checks that ensure different builds of tightly coupled modules or modules for specific operating systems or architectures are not combined in the same configuration.
        Parameters:
        before - Thebefore module finder to find modules
        parents - The list parent configurations in search order
        after - Theafter module finder to locate modules when not located by thebefore module finder or in parent configurations
        roots - The possibly-empty collection of module names of the modules to resolve
        Returns:
        The configuration that is the result of resolving the given root modules
        Throws:
        FindException - If resolution fails for any of observability-related reasons specified above
        ResolutionException - If resolution fails for any of the consistency checks specified above
        IllegalArgumentException - If the list of parents is empty, or the list has two or more parents with modules for different target operating systems, architectures, or versions
        SecurityException - If locating a module is denied by the security manager

      • resolveAndBind

        public static Configuration resolveAndBind​(ModuleFinder before,List<Configuration> parents,ModuleFinder after,Collection<String> roots)
        Resolves a collection of root modules, with service binding, to create configuration.

        This method works exactly as specified byresolve except that the graph of resolved modules is augmented with modules induced by the service-use dependence relation.

        More specifically, the root modules are resolved as if by callingresolve. The resolved modules, and all modules in the parent configurations, withservice dependences are then examined. All modules found by the given module finders thatprovide an implementation of one or more of the service types are added to the module graph and then resolved as if by calling the resolve method. Adding modules to the module graph may introduce new service-use dependences and so the process works iteratively until no more modules are added.

        As service binding involves resolution then it may fail with FindException orResolutionException for exactly the same reasons specified inresolve.

        Parameters:
        before - Thebefore module finder to find modules
        parents - The list parent configurations in search order
        after - Theafter module finder to locate modules when not located by thebefore module finder or in parent configurations
        roots - The possibly-empty collection of module names of the modules to resolve
        Returns:
        The configuration that is the result of resolving, with service binding, the given root modules
        Throws:
        FindException - If resolution fails for any of the observability-related reasons specified by the staticresolve method
        ResolutionException - If resolution fails any of the consistency checks specified by the staticresolve method
        IllegalArgumentException - If the list of parents is empty, or the list has two or more parents with modules for different target operating systems, architectures, or versions
        SecurityException - If locating a module is denied by the security manager

      • empty

        public static Configuration empty()
        Returns theempty configuration. There are no modules in the empty configuration. It has no parents.
        Returns:
        The empty configuration

      • parents

        public List<Configuration> parents()
        Returns an unmodifiable list of this configuration's parents, in search order. If this is theempty configuration then an empty list is returned.
        Returns:
        A possibly-empty unmodifiable list of this parent configurations

      • modules

        public Set<ResolvedModule> modules()
        Returns an immutable set of the resolved modules in this configuration.
        Returns:
        A possibly-empty unmodifiable set of the resolved modules in this configuration

      • findModule

        public Optional<ResolvedModule> findModule​(String name)
        Finds a resolved module in this configuration, or if not in this configuration, theparent configurations. Finding a module in parent configurations is equivalent to invokingfindModule on each parent, in search order, until the module is found or all parents have been searched. In atree of configurations then this is equivalent to a depth-first search.
        Parameters:
        name - The module name of the resolved module to find
        Returns:
        The resolved module with the given name or an empty Optional if there isn't a module with this name in this configuration or any parent configurations

      • toString

        public String toString()
        Returns a string describing this configuration.
        Overrides:
        toString in class Object
        Returns:
        A possibly empty string describing this configuration