1 /* 2 * Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang.module; 27 28 import java.io.IOException; 29 import java.net.URI; 30 import java.util.Objects; 31 import java.util.Optional; 32 33 34 /** 35 * A reference to a module's content. 36 * 37 * <p> A module reference is a concrete implementation of this class that 38 * implements the abstract methods defined by this class. It contains the 39 * module's descriptor and its location, if known. It also has the ability to 40 * create a {@link ModuleReader} in order to access the module's content, which 41 * may be inside the Java run-time system itself or in an artifact such as a 42 * modular JAR file. 43 * 44 * @see ModuleFinder 45 * @see ModuleReader 46 * @since 9 47 */ 48 49 public abstract class ModuleReference { 50 51 private final ModuleDescriptor descriptor; 52 private final URI location; 53 54 /** 55 * Constructs a new instance of this class. 56 * 57 * @param descriptor 58 * The module descriptor 59 * @param location 60 * The module location or {@code null} if not known 61 */ ModuleReference(ModuleDescriptor descriptor, URI location)62 protected ModuleReference(ModuleDescriptor descriptor, URI location) { 63 this.descriptor = Objects.requireNonNull(descriptor); 64 this.location = location; 65 } 66 67 /** 68 * Returns the module descriptor. 69 * 70 * @return The module descriptor 71 */ descriptor()72 public final ModuleDescriptor descriptor() { 73 return descriptor; 74 } 75 76 /** 77 * Returns the location of this module's content, if known. 78 * 79 * <p> This URI, when present, can be used as the {@linkplain 80 * java.security.CodeSource#getLocation location} value of a {@link 81 * java.security.CodeSource CodeSource} so that a module's classes can be 82 * granted specific permissions when loaded by a {@link 83 * java.security.SecureClassLoader SecureClassLoader}. 84 * 85 * @return The location or an empty {@code Optional} if not known 86 */ location()87 public final Optional<URI> location() { 88 return Optional.ofNullable(location); 89 } 90 91 /** 92 * Opens the module content for reading. 93 * 94 * @return A {@code ModuleReader} to read the module 95 * 96 * @throws IOException 97 * If an I/O error occurs 98 * @throws SecurityException 99 * If denied by the security manager 100 */ open()101 public abstract ModuleReader open() throws IOException; 102 } 103