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 * @spec JPMS 48 */ 49 50 public abstract class ModuleReference { 51 52 private final ModuleDescriptor descriptor; 53 private final URI location; 54 55 /** 56 * Constructs a new instance of this class. 57 * 58 * @param descriptor 59 * The module descriptor 60 * @param location 61 * The module location or {@code null} if not known 62 */ 63 protected ModuleReference(ModuleDescriptor descriptor, URI location) { 64 this.descriptor = Objects.requireNonNull(descriptor); 65 this.location = location; 66 } 67 68 /** 69 * Returns the module descriptor. 70 * 71 * @return The module descriptor 72 */ 73 public final ModuleDescriptor descriptor() { 74 return descriptor; 75 } 76 77 /** 78 * Returns the location of this module's content, if known. 79 * 80 * <p> This URI, when present, can be used as the {@linkplain 81 * java.security.CodeSource#getLocation location} value of a {@link 82 * java.security.CodeSource CodeSource} so that a module's classes can be 83 * granted specific permissions when loaded by a {@link 84 * java.security.SecureClassLoader SecureClassLoader}. 85 * 86 * @return The location or an empty {@code Optional} if not known 87 */ 88 public final Optional<URI> location() { 89 return Optional.ofNullable(location); 90 } 91 92 /** 93 * Opens the module content for reading. 94 * 95 * @return A {@code ModuleReader} to read the module 96 * 97 * @throws IOException 98 * If an I/O error occurs 99 * @throws SecurityException 100 * If denied by the security manager 101 */ 102 public abstract ModuleReader open() throws IOException; 103 }