Java tutorial
/* * Copyright (c) 1997, 2019, 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; import java.lang.annotation.Annotation; import java.lang.reflect.AnnotatedElement; import java.net.MalformedURLException; import java.net.URI; import java.net.URL; import java.security.AccessController; import java.security.PrivilegedAction; import java.util.Objects; import jdk.internal.loader.BootLoader; import jdk.internal.reflect.CallerSensitive; import jdk.internal.reflect.Reflection; /** * Represents metadata about a run-time package associated with a class loader. * Metadata includes annotations, versioning, and sealing. * <p> * Annotations for the run-time package are read from {@code package-info.class} * at the same code source as classes in the run-time package. * <p> * The set of classes that make up the run-time package may implement a * particular specification. The specification title, version, and vendor * (indicating the owner/maintainer of the specification) can be provided * when the {@code Package} is defined. An application can ask if the * {@code Package} is compatible with a particular specification version * by using the {@link #isCompatibleWith Package.isCompatibleWith(String)} * method. In addition, information about the actual classes that make up the * run-time package can be provided when the Package is defined. * This information consists of an implementation title, version, and vendor * (indicating the supplier of the classes). * <p> * A {@code Package} may be explicitly defined with * the {@link ClassLoader#definePackage(String, String, String, String, * String, String, String, URL)} method. * The caller supplies the specification and implementation titles, versions, and * vendors. The caller also indicates whether the package is * {@linkplain java.util.jar.Attributes.Name#SEALED sealed}. * If a {@code Package} is not explicitly defined for a run-time package when * a class in that run-time package is defined, then a {@code Package} is * automatically defined by the class's defining class loader, as follows. * <p> * A {@code Package} automatically defined for classes in a named module has * the following properties: * <ul> * <li>The name of the package is derived from the {@linkplain Class#getName() binary names} * of the classes. Since classes in a named module must be in a named package, * the derived name is never empty.</li> * <li>The package is sealed with the {@linkplain java.lang.module.ModuleReference#location() * module location} as the code source, if known.</li> * <li>The specification and implementation titles, versions, and vendors * are unspecified.</li> * <li>Any annotations on the package are read from {@code package-info.class} * as specified above.</li> * </ul> * <p> * A {@code Package} automatically defined for classes in an unnamed module * has the following properties: * <ul> * <li>The name of the package is either {@code ""} (for classes in an unnamed package) * or derived from the {@linkplain Class#getName() binary names} of the classes * (for classes in a named package).</li> * <li>The package is not sealed.</li> * <li>The specification and implementation titles, versions, and vendors * are unspecified.</li> * <li>Any annotations on the package are read from {@code package-info.class} * as specified above.</li> * </ul> * * <p> * A {@code Package} can be obtained with the {@link Package#getPackage * Package.getPackage(String)} and {@link ClassLoader#getDefinedPackage * ClassLoader.getDefinedPackage(String)} methods. * Every {@code Package} defined by a class loader can be obtained * with the {@link Package#getPackages Package.getPackages()} and * {@link ClassLoader#getDefinedPackages} methods. * * @implNote * The <a href="ClassLoader.html#builtinLoaders">builtin class loaders</a> * do not explicitly define {@code Package} objects for packages in * <em>named modules</em>. Instead those packages are automatically defined * and have no specification and implementation versioning information. * * @jvms 5.3 Creation and Loading * @see <a href="{@docRoot}/../specs/jar/jar.html#package-sealing"> * The JAR File Specification: Package Sealing</a> * @see ClassLoader#definePackage(String, String, String, String, String, String, String, URL) * * @since 1.2 * @revised 9 * @spec JPMS */ public class Package extends NamedPackage implements java.lang.reflect.AnnotatedElement { /** * Return the name of this package. * * @return The fully-qualified name of this package as defined in section 6.5.3 of * <cite>The Java™ Language Specification</cite>, * for example, {@code java.lang} */ public String getName() { return packageName(); } /** * Return the title of the specification that this package implements. * @return the specification title, {@code null} is returned if it is not known. */ public String getSpecificationTitle() { return versionInfo.specTitle; } /** * Returns the version number of the specification * that this package implements. * This version string must be a sequence of non-negative decimal * integers separated by "."'s and may have leading zeros. * When version strings are compared the most significant * numbers are compared. * * * <p>Specification version numbers use a syntax that consists of non-negative * decimal integers separated by periods ".", for example "2.0" or * "1.2.3.4.5.6.7". This allows an extensible number to be used to represent * major, minor, micro, etc. versions. The version specification is described * by the following formal grammar: * <blockquote> * <dl> * <dt><i>SpecificationVersion:</i> * <dd><i>Digits RefinedVersion<sub>opt</sub></i> * <dt><i>RefinedVersion:</i> * <dd>{@code .} <i>Digits</i> * <dd>{@code .} <i>Digits RefinedVersion</i> * * <dt><i>Digits:</i> * <dd><i>Digit</i> * <dd><i>Digits</i> * * <dt><i>Digit:</i> * <dd>any character for which {@link Character#isDigit} returns {@code true}, * e.g. 0, 1, 2, ... * </dl> * </blockquote> * * @return the specification version, {@code null} is returned if it is not known. */ public String getSpecificationVersion() { return versionInfo.specVersion; } /** * Return the name of the organization, vendor, * or company that owns and maintains the specification * of the classes that implement this package. * @return the specification vendor, {@code null} is returned if it is not known. */ public String getSpecificationVendor() { return versionInfo.specVendor; } /** * Return the title of this package. * @return the title of the implementation, {@code null} is returned if it is not known. */ public String getImplementationTitle() { return versionInfo.implTitle; } /** * Return the version of this implementation. It consists of any string * assigned by the vendor of this implementation and does * not have any particular syntax specified or expected by the Java * runtime. It may be compared for equality with other * package version strings used for this implementation * by this vendor for this package. * @return the version of the implementation, {@code null} is returned if it is not known. */ public String getImplementationVersion() { return versionInfo.implVersion; } /** * Returns the vendor that implemented this package, {@code null} * is returned if it is not known. * @return the vendor that implemented this package, {@code null} * is returned if it is not known. * * @revised 9 * @spec JPMS */ public String getImplementationVendor() { return versionInfo.implVendor; } /** * Returns true if this package is sealed. * * @return true if the package is sealed, false otherwise */ public boolean isSealed() { return module().isNamed() || versionInfo.sealBase != null; } /** * Returns true if this package is sealed with respect to the specified * code source {@code url}. * * @param url the code source URL * @return true if this package is sealed with respect to the given {@code url} */ public boolean isSealed(URL url) { Objects.requireNonNull(url); URL sealBase = null; if (versionInfo != VersionInfo.NULL_VERSION_INFO) { sealBase = versionInfo.sealBase; } else { try { URI uri = location(); sealBase = uri != null ? uri.toURL() : null; } catch (MalformedURLException e) { } } return url.equals(sealBase); } /** * Compare this package's specification version with a * desired version. It returns true if * this packages specification version number is greater than or equal * to the desired version number. <p> * * Version numbers are compared by sequentially comparing corresponding * components of the desired and specification strings. * Each component is converted as a decimal integer and the values * compared. * If the specification value is greater than the desired * value true is returned. If the value is less false is returned. * If the values are equal the period is skipped and the next pair of * components is compared. * * @param desired the version string of the desired version. * @return true if this package's version number is greater * than or equal to the desired version number * * @exception NumberFormatException if the current version is not known or * the desired or current version is not of the correct dotted form. */ public boolean isCompatibleWith(String desired) throws NumberFormatException { if (versionInfo.specVersion == null || versionInfo.specVersion.length() < 1) { throw new NumberFormatException("Empty version string"); } String[] sa = versionInfo.specVersion.split("\\.", -1); int[] si = new int[sa.length]; for (int i = 0; i < sa.length; i++) { si[i] = Integer.parseInt(sa[i]); if (si[i] < 0) throw NumberFormatException.forInputString("" + si[i], 10); } String[] da = desired.split("\\.", -1); int[] di = new int[da.length]; for (int i = 0; i < da.length; i++) { di[i] = Integer.parseInt(da[i]); if (di[i] < 0) throw NumberFormatException.forInputString("" + di[i], 10); } int len = Math.max(di.length, si.length); for (int i = 0; i < len; i++) { int d = (i < di.length ? di[i] : 0); int s = (i < si.length ? si[i] : 0); if (s < d) return false; if (s > d) return true; } return true; } /** * Finds a package by name in the caller's class loader and its * ancestors. * <p> * If the caller's class loader defines a {@code Package} of the given name, * the {@code Package} is returned. Otherwise, the ancestors of the * caller's class loader are searched recursively (parent by parent) * for a {@code Package} of the given name. * <p> * Calling this method is equivalent to calling {@link ClassLoader#getPackage} * on a {@code ClassLoader} instance which is the caller's class loader. * * @param name A package name, such as "{@code java.lang}". * @return The {@code Package} of the given name defined by the caller's * class loader or its ancestors, or {@code null} if not found. * * @throws NullPointerException * if {@code name} is {@code null}. * * @deprecated * If multiple class loaders delegate to each other and define classes * with the same package name, and one such loader relies on the lookup * behavior of {@code getPackage} to return a {@code Package} from * a parent loader, then the properties exposed by the {@code Package} * may not be as expected in the rest of the program. * For example, the {@code Package} will only expose annotations from the * {@code package-info.class} file defined by the parent loader, even if * annotations exist in a {@code package-info.class} file defined by * a child loader. A more robust approach is to use the * {@link ClassLoader#getDefinedPackage} method which returns * a {@code Package} for the specified class loader. * * @see ClassLoader#getDefinedPackage * * @revised 9 * @spec JPMS */ @CallerSensitive @Deprecated(since = "9") @SuppressWarnings("deprecation") public static Package getPackage(String name) { ClassLoader l = ClassLoader.getClassLoader(Reflection.getCallerClass()); return l != null ? l.getPackage(name) : BootLoader.getDefinedPackage(name); } /** * Returns all of the {@code Package}s defined by the caller's class loader * and its ancestors. The returned array may contain more than one * {@code Package} object of the same package name, each defined by * a different class loader in the class loader hierarchy. * <p> * Calling this method is equivalent to calling {@link ClassLoader#getPackages} * on a {@code ClassLoader} instance which is the caller's class loader. * * @return The array of {@code Package} objects defined by this * class loader and its ancestors * * @see ClassLoader#getDefinedPackages * * @revised 9 * @spec JPMS */ @CallerSensitive public static Package[] getPackages() { ClassLoader cl = ClassLoader.getClassLoader(Reflection.getCallerClass()); return cl != null ? cl.getPackages() : BootLoader.packages().toArray(Package[]::new); } /** * Return the hash code computed from the package name. * @return the hash code computed from the package name. */ @Override public int hashCode() { return packageName().hashCode(); } /** * Returns the string representation of this Package. * Its value is the string "package " and the package name. * If the package title is defined it is appended. * If the package version is defined it is appended. * @return the string representation of the package. */ @Override public String toString() { String spec = versionInfo.specTitle; String ver = versionInfo.specVersion; if (spec != null && !spec.isEmpty()) spec = ", " + spec; else spec = ""; if (ver != null && !ver.isEmpty()) ver = ", version " + ver; else ver = ""; return "package " + packageName() + spec + ver; } private Class<?> getPackageInfo() { if (packageInfo == null) { // find package-info.class defined by loader String cn = packageName() + ".package-info"; Module module = module(); PrivilegedAction<ClassLoader> pa = module::getClassLoader; ClassLoader loader = AccessController.doPrivileged(pa); Class<?> c; if (loader != null) { c = loader.loadClass(module, cn); } else { c = BootLoader.loadClass(module, cn); } if (c != null) { packageInfo = c; } else { // store a proxy for the package info that has no annotations class PackageInfoProxy { } packageInfo = PackageInfoProxy.class; } } return packageInfo; } /** * @throws NullPointerException {@inheritDoc} * @since 1.5 */ public <A extends Annotation> A getAnnotation(Class<A> annotationClass) { return getPackageInfo().getAnnotation(annotationClass); } /** * {@inheritDoc} * @throws NullPointerException {@inheritDoc} * @since 1.5 */ @Override public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) { return AnnotatedElement.super.isAnnotationPresent(annotationClass); } /** * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @Override public <A extends Annotation> A[] getAnnotationsByType(Class<A> annotationClass) { return getPackageInfo().getAnnotationsByType(annotationClass); } /** * @since 1.5 */ public Annotation[] getAnnotations() { return getPackageInfo().getAnnotations(); } /** * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @Override public <A extends Annotation> A getDeclaredAnnotation(Class<A> annotationClass) { return getPackageInfo().getDeclaredAnnotation(annotationClass); } /** * @throws NullPointerException {@inheritDoc} * @since 1.8 */ @Override public <A extends Annotation> A[] getDeclaredAnnotationsByType(Class<A> annotationClass) { return getPackageInfo().getDeclaredAnnotationsByType(annotationClass); } /** * @since 1.5 */ public Annotation[] getDeclaredAnnotations() { return getPackageInfo().getDeclaredAnnotations(); } /** * Construct a package instance for an unnamed module * with the specified version information. * * @apiNote * This method should not be called to define a Package for named module. * * @param name the name of the package * @param spectitle the title of the specification * @param specversion the version of the specification * @param specvendor the organization that maintains the specification * @param impltitle the title of the implementation * @param implversion the version of the implementation * @param implvendor the organization that maintains the implementation * @param sealbase code source where this Package comes from * @param loader defining class loader */ Package(String name, String spectitle, String specversion, String specvendor, String impltitle, String implversion, String implvendor, URL sealbase, ClassLoader loader) { super(Objects.requireNonNull(name), loader != null ? loader.getUnnamedModule() : BootLoader.getUnnamedModule()); this.versionInfo = VersionInfo.getInstance(spectitle, specversion, specvendor, impltitle, implversion, implvendor, sealbase); } Package(String name, Module module) { super(name, module); this.versionInfo = VersionInfo.NULL_VERSION_INFO; } /* * Versioning information. Only for packages in unnamed modules. */ static class VersionInfo { static final VersionInfo NULL_VERSION_INFO = new VersionInfo(null, null, null, null, null, null, null); private final String specTitle; private final String specVersion; private final String specVendor; private final String implTitle; private final String implVersion; private final String implVendor; private final URL sealBase; static VersionInfo getInstance(String spectitle, String specversion, String specvendor, String impltitle, String implversion, String implvendor, URL sealbase) { if (spectitle == null && specversion == null && specvendor == null && impltitle == null && implversion == null && implvendor == null && sealbase == null) { return NULL_VERSION_INFO; } return new VersionInfo(spectitle, specversion, specvendor, impltitle, implversion, implvendor, sealbase); } private VersionInfo(String spectitle, String specversion, String specvendor, String impltitle, String implversion, String implvendor, URL sealbase) { this.implTitle = impltitle; this.implVersion = implversion; this.implVendor = implvendor; this.specTitle = spectitle; this.specVersion = specversion; this.specVendor = specvendor; this.sealBase = sealbase; } } private final VersionInfo versionInfo; private Class<?> packageInfo; }