< prev index next >
src/java.base/share/classes/java/lang/module/ModuleFinder.java
Print this page
*** 1,7 ****
/*
! * Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved.
* 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
--- 1,7 ----
/*
! * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
* 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
*** 46,57 ****
import jdk.internal.module.SystemModuleFinder;
import sun.security.action.GetPropertyAction;
/**
* A finder of modules. A {@code ModuleFinder} is used to find modules during
! * <a href="Configuration.html#resolution">resolution</a> or
! * <a href="Configuration.html#servicebinding">service binding</a>.
*
* <p> A {@code ModuleFinder} can only find one module with a given name. A
* {@code ModuleFinder} that finds modules in a sequence of directories, for
* example, will locate the first occurrence of a module of a given name and
* will ignore other modules of that name that appear in directories later in
--- 46,57 ----
import jdk.internal.module.SystemModuleFinder;
import sun.security.action.GetPropertyAction;
/**
* A finder of modules. A {@code ModuleFinder} is used to find modules during
! * <a href="package-summary.html#resolution">resolution</a> or
! * <a href="package-summary.html#servicebinding">service binding</a>.
*
* <p> A {@code ModuleFinder} can only find one module with a given name. A
* {@code ModuleFinder} that finds modules in a sequence of directories, for
* example, will locate the first occurrence of a module of a given name and
* will ignore other modules of that name that appear in directories later in
*** 83,92 ****
--- 83,93 ----
* thrown. </p>
*
* <p> A {@code ModuleFinder} is not required to be thread safe. </p>
*
* @since 9
+ * @spec JPMS
*/
public interface ModuleFinder {
/**
*** 122,133 ****
* ModuleReference} element in the returned set then it is guaranteed that
* {@link #find find} will locate the {@code ModuleReference} if invoked
* to find that module. </p>
*
* @apiNote This is important to have for methods such as {@link
! * Configuration#resolveRequiresAndUses resolveRequiresAndUses} that need
! * to scan the module path to find modules that provide a specific service.
*
* @return The set of all module references that this finder locates
*
* @throws FindException
* If an error occurs finding all modules
--- 123,134 ----
* ModuleReference} element in the returned set then it is guaranteed that
* {@link #find find} will locate the {@code ModuleReference} if invoked
* to find that module. </p>
*
* @apiNote This is important to have for methods such as {@link
! * Configuration#resolveAndBind resolveAndBind} that need to scan the
! * module path to find modules that provide a specific service.
*
* @return The set of all module references that this finder locates
*
* @throws FindException
* If an error occurs finding all modules
*** 196,224 ****
* occurrence of a module with a given name and ignores other modules of
* that name that appear later in the sequence.
*
* <p> If an element is a path to a directory of modules then each entry in
* the directory is a packaged module or the top-level directory of an
! * exploded module. The module finder's {@link #find(String) find} or
! * {@link #findAll() findAll} methods throw {@link FindException} if a
! * directory containing more than one module with the same name is
! * encountered. </p>
! *
! * <p> If an element in the array is a path to a directory, and that
! * directory contains a file named {@code module-info.class}, then the
* directory is treated as an exploded module rather than a directory of
* modules. </p>
*
* <p> The module finder returned by this method supports modules that are
* packaged as JAR files. A JAR file with a {@code module-info.class} in
* the top-level directory of the JAR file (or overridden by a versioned
* entry in a {@link java.util.jar.JarFile#isMultiRelease() multi-release}
* JAR file) is a modular JAR and is an <em>explicit module</em>.
* A JAR file that does not have a {@code module-info.class} in the
! * top-level directory is an {@link ModuleDescriptor#isAutomatic automatic}
! * module. The {@link ModuleDescriptor} for an automatic module is created as
! * follows:
*
* <ul>
*
* <li><p> The module {@link ModuleDescriptor#name() name}, and {@link
* ModuleDescriptor#version() version} if applicable, is derived from
--- 197,220 ----
* occurrence of a module with a given name and ignores other modules of
* that name that appear later in the sequence.
*
* <p> If an element is a path to a directory of modules then each entry in
* the directory is a packaged module or the top-level directory of an
! * exploded module. It it an error if a directory contains more than one
! * module with the same name. If an element is a path to a directory, and
! * that directory contains a file named {@code module-info.class}, then the
* directory is treated as an exploded module rather than a directory of
* modules. </p>
*
* <p> The module finder returned by this method supports modules that are
* packaged as JAR files. A JAR file with a {@code module-info.class} in
* the top-level directory of the JAR file (or overridden by a versioned
* entry in a {@link java.util.jar.JarFile#isMultiRelease() multi-release}
* JAR file) is a modular JAR and is an <em>explicit module</em>.
* A JAR file that does not have a {@code module-info.class} in the
! * top-level directory is created as an automatic module. The components
! * for the automatic module are derived as follows:
*
* <ul>
*
* <li><p> The module {@link ModuleDescriptor#name() name}, and {@link
* ModuleDescriptor#version() version} if applicable, is derived from
*** 246,295 ****
* named {@code foo-1.2.3-SNAPSHOT.jar} will derive a module name
* {@code foo} and {@code 1.2.3-SNAPSHOT} as the version. </p></li>
*
* </ul></li>
*
! * <li><p> It {@link ModuleDescriptor#requires() requires} {@code
! * java.base}. </p></li>
! *
! * <li><p> The set of packages in the module is derived from the names
! * of non-directory entries in the JAR file. A candidate package name
! * is derived from an entry using the characters up to, but not
! * including, the last forward slash. All remaining forward slashes are
! * replaced with dot ({@code "."}). If the resulting string is a valid
! * Java identifier then it is assumed to be a package name. For example,
! * if the JAR file contains an entry "{@code p/q/Foo.class}" then the
! * package name derived is "{@code p.q}". All packages are {@link
! * ModuleDescriptor#exports() exported}. </p></li>
*
* <li><p> The contents of entries starting with {@code
* META-INF/services/} are assumed to be service configuration files
* (see {@link java.util.ServiceLoader}). If the name of a file
! * (that follows {@code META-INF/services/}) is a legal Java identifier
! * then it is assumed to be the fully-qualified binary name of a
! * service type. The entries in the file are assumed to be the
! * fully-qualified binary names of provider classes. </p></li>
*
* <li><p> If the JAR file has a {@code Main-Class} attribute in its
! * main manifest then its value is the {@link
* ModuleDescriptor#mainClass() main class}. </p></li>
*
* </ul>
*
* <p> If a {@code ModuleDescriptor} cannot be created (by means of the
* {@link ModuleDescriptor.Builder ModuleDescriptor.Builder} API) for an
! * automatic module then {@code FindException} is thrown. This can arise,
! * for example, when a legal Java identifier name cannot be derived from
! * the file name of the JAR file or where the JAR file contains a {@code
! * .class} in the top-level directory of the JAR file. </p>
*
* <p> In addition to JAR files, an implementation may also support modules
! * that are packaged in other implementation specific module formats. When
! * a file is encountered that is not recognized as a packaged module then
! * {@code FindException} is thrown. An implementation may choose to ignore
! * some files, {@link java.nio.file.Files#isHidden hidden} files for
! * example. Paths to files that do not exist are always ignored. </p>
*
* <p> As with automatic modules, the contents of a packaged or exploded
* module may need to be <em>scanned</em> in order to determine the packages
* in the module. If a {@code .class} file (other than {@code
* module-info.class}) is found in the top-level directory then it is
--- 242,293 ----
* named {@code foo-1.2.3-SNAPSHOT.jar} will derive a module name
* {@code foo} and {@code 1.2.3-SNAPSHOT} as the version. </p></li>
*
* </ul></li>
*
! * <li><p> The set of packages in the module is derived from the
! * non-directory entries in the JAR file that have names ending in
! * "{@code .class}". A candidate package name is derived from the name
! * using the characters up to, but not including, the last forward slash.
! * All remaining forward slashes are replaced with dot ({@code "."}). If
! * the resulting string is a legal package name then it is assumed to be
! * a package name. For example, if the JAR file contains the entry
! * "{@code p/q/Foo.class}" then the package name derived is
! * "{@code p.q}".</p></li>
*
* <li><p> The contents of entries starting with {@code
* META-INF/services/} are assumed to be service configuration files
* (see {@link java.util.ServiceLoader}). If the name of a file
! * (that follows {@code META-INF/services/}) is a legal class name
! * then it is assumed to be the fully-qualified class name of a service
! * type. The entries in the file are assumed to be the fully-qualified
! * class names of provider classes. </p></li>
*
* <li><p> If the JAR file has a {@code Main-Class} attribute in its
! * main manifest then its value is the module {@link
* ModuleDescriptor#mainClass() main class}. </p></li>
*
* </ul>
*
* <p> If a {@code ModuleDescriptor} cannot be created (by means of the
* {@link ModuleDescriptor.Builder ModuleDescriptor.Builder} API) for an
! * automatic module then {@code FindException} is thrown. This can arise
! * when a legal module name cannot be derived from the file name of the JAR
! * file, where the JAR file contains a {@code .class} in the top-level
! * directory of the JAR file, where an entry in a service configuration
! * file is not a legal class name or its package name is not in the set of
! * packages derived for the module, or where the module main class is not
! * a legal class name or its package is not in the module. </p>
*
* <p> In addition to JAR files, an implementation may also support modules
! * that are packaged in other implementation specific module formats. If
! * an element in the array specified to this method is a path to a directory
! * of modules then entries in the directory that not recognized as modules
! * are ignored. If an element in the array is a path to a packaged module
! * that is not recognized then a {@code FindException} is thrown when the
! * file is encountered. Paths to files that do not exist are always ignored.
! * </p>
*
* <p> As with automatic modules, the contents of a packaged or exploded
* module may need to be <em>scanned</em> in order to determine the packages
* in the module. If a {@code .class} file (other than {@code
* module-info.class}) is found in the top-level directory then it is
< prev index next >