Class Configuration

java.lang.Object
java.lang.module.Configuration
public final classConfigurationextendsObject
A configuration that is the result ofresolution or resolution withservice binding.

A configuration encapsulates thereadability graph that is theoutput of resolution. A readability graph is a directed graph whose verticesare of typeResolvedModule and the edges represent the readabilityamongst the modules.Configuration defines themodules() method to get the set of resolved modules in the graph.ResolvedModule defines thereads() method toget the set of modules that a resolved module reads. The modules that areread may be in the same configuration or may be inparentconfigurations.

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

Eachlayer of modules in the Java virtualmachine is created from a configuration. The configuration for theboot layer is obtained by invokingModuleLayer.boot().configuration(). The configuration for the boot layerwill often be the parent when creating new configurations.

Optional Services

Resolution requires that if a moduleM 'uses' a service or'provides' an implementation of a service, then the service must be availabletoM at run time, either becauseM itself contains the service'spackage or becauseM reads another module that exports the service's package.However, it is sometimes desirable for the service's package to come from a modulethat is optional at run time, as indicated by the use of 'requires static' in thisexample:
   module M {       requires static Y;       uses p.S;   }   module Y {      exports p;   }
Resolution is resilient when a service's package comes from a module that is optionalat run time. That is, if a moduleM has an optional dependency on some moduleY, butY is not needed at run time (Y might be observable butno-one reads it), then resolution at run timeassumes thatY exportedthe service's package at compile time. Resolution at run time does not attempt tocheck whetherY is observable or (if it is observable) whetherYexports the service's package.

The module that 'uses' the service, or 'provides' an implementationof it, may depend directly on the optional module, asM does above, or maydepend indirectly on the optional module, as shown here:

    module M {        requires X;        uses p.S;    }    module X {        requires static transitive Y;    }    module Y {        exports p;    }
In effect, the service thatM 'uses', or 'provides' animplementation of, is optional if it comes from an optional dependency. In this case,code inM must be prepared to deal with the class or interface that denotesthe service being unavailable at run time. This is distinct from the more regularcase where the service is available but no implementations of the service areavailable.

Example

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

   Path dir1 = ..., dir2 = ..., dir3 = ...;   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:

  • Method Details

    • resolve

      public Configuration resolve(ModuleFinder before,ModuleFinder after,Collection<String> roots)
      Resolves a collection of root modules, with this configuration as itsparent, to create a new configuration. This method works exactly asspecified by the staticresolvemethod when invoked with this configuration as the parent. In other words,if this configuration iscf then this method is equivalent toinvoking:
          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

    • resolveAndBind

      public Configuration resolveAndBind(ModuleFinder before,ModuleFinder after,Collection<String> roots)
      Resolves a collection of root modules, with service binding, and withthis configuration as its parent, to create a new configuration.This method works exactly as specified by the staticresolveAndBind method when invoked with this configurationas the parent. In other words, if this configuration iscf thenthis 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

    • 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 modulefinder. If a module is not found then it is located in the parentconfiguration as if by invoking thefindModule method on each parent in iteration order. If not found thenthe module is located using the givenafter module finder. Thesame search order is used to locate transitive dependences. Root modulesor dependences that are located in a parent configuration are resolvedno further and are not included in the resulting configuration.

      When all modules have been enumerated then a readability graphis 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 thefollowing 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 the packagep is neither in moduleM nor exported toM by any module thatM reads. Additionally, neither of the following istrue:

        • M declares 'requires static' for at least one module that is not in the readability graph.
        • M reads another module that declares 'requires transitive static' for at least one module that is not in the readability graph.

      Implementation Note:
      In the implementation then observability of modules may dependon referential integrity or other checks that ensure different builds oftightly coupled modules or modules for specific operating systems orarchitectures 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

    • 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 createconfiguration.

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

      More specifically, the root modules areresolved as if by callingresolve. The resolved modules, andall modules in the parent configurations, withservice dependences are then examined. All modules found by the givenmodule finders thatprovide animplementation of one or more of the service types are added to themodule graph and then resolved as if by calling theresolve method. Adding modules to the module graph may introduce newservice-use dependences and so the process works iteratively until nomore modules are added.

      As service binding involves resolution then it may fail withFindException orResolutionException for exactly the samereasons 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

    • empty

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

    • parents

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

    • modules

      public Set<ResolvedModule> modules()
      Returns an unmodifiable 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 thisconfiguration, theparent configurations.Finding a module in parent configurations is equivalent to invokingfindModule on each parent, in search order, until the moduleis found or all parents have been searched. In atree ofconfigurations 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