/* * Copyright (c) 2015, 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 * 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.module; import java.io.Closeable; import java.io.IOException; import java.io.InputStream; import java.net.URI; import java.nio.ByteBuffer; import java.util.Objects; import java.util.Optional; import java.util.stream.Stream; /** * Provides access to the content of a module. * *
A module reader is intended for cases where access to the resources in a * module is required, regardless of whether the module has been loaded. * A framework that scans a collection of packaged modules on the file system, * for example, may use a module reader to access a specific resource in each * module. A module reader is also intended to be used by {@code ClassLoader} * implementations that load classes and resources from modules.
* *A resource in a module is identified by an abstract name that is a * '{@code /}'-separated path string. For example, module {@code java.base} may * have a resource "{@code java/lang/Object.class}" that, by convention, is the * class file for {@code java.lang.Object}.
* *A {@code ModuleReader} is {@linkplain ModuleReference#open open} upon * creation and is closed by invoking the {@link #close close} method. Failure * to close a module reader may result in a resource leak. The {@code * try-with-resources} statement provides a useful construct to ensure that * module readers are closed.
* *A {@code ModuleReader} implementation may require permissions to access * resources in the module. Consequently the {@link #find find}, {@link #open * open}, {@link #read read}, and {@link #list list} methods may throw {@code * SecurityException} if access is denied by the security manager.
* * @implSpec Implementations of {@code ModuleReader} should take great care * when translating an abstract resource name to the location of a resource in * a packaged module or on the file system. Implementations are advised to * treat resource names with elements such as '{@code .}, '{@code ..}', * elements containing file separators, or empty elements as "not found". More * generally, if the resource name is not in the stream of elements that the * {@code list} method returns then the resource should be treated as "not * found" to avoid inconsistencies. * * @see ModuleReference * @since 9 * @spec JPMS */ public interface ModuleReader extends Closeable { /** * Finds a resource, returning a URI to the resource in the module. * * @param name * The name of the resource to open for reading * * @return A URI to the resource; an empty {@code Optional} if the resource * is not found or a URI cannot be constructed to locate the * resource * * @throws IOException * If an I/O error occurs or the module reader is closed * @throws SecurityException * If denied by the security manager * * @see ClassLoader#getResource(String) */ OptionalThe behavior of the input stream when used after the module reader * is closed is implementation specific and therefore not specified.
* * @implSpec The default implementation invokes the {@link #find(String) * find} method to get a URI to the resource. If found, then it attempts * to construct a {@link java.net.URL URL} and open a connection to the * resource. * * @param name * The name of the resource to open for reading * * @return An input stream to read the resource or an empty * {@code Optional} if not found * * @throws IOException * If an I/O error occurs or the module reader is closed * @throws SecurityException * If denied by the security manager */ default OptionalIn lazy implementations then an {@code IOException} may be thrown * when using the stream to list the module contents. If this occurs then * the {@code IOException} will be wrapped in an {@link * java.io.UncheckedIOException} and thrown from the method that caused the * access to be attempted. {@code SecurityException} may also be thrown * when using the stream to list the module contents and access is denied * by the security manager.
* *The behavior of the stream when used after the module reader is * closed is implementation specific and therefore not specified.
* * @return A stream of elements that are the names of all resources * in the module * * @throws IOException * If an I/O error occurs or the module reader is closed * @throws SecurityException * If denied by the security manager */ StreamA module reader is not required to be asynchronously closeable. If a * thread is reading a resource and another thread invokes the close method, * then the second thread may block until the read operation is complete.
*/ @Override void close() throws IOException; }