1 /*
   2  * Copyright (c) 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 jdk.internal.loader;
  27 
  28 import java.util.Objects;
  29 import java.util.function.BiFunction;
  30 
  31 /**
  32  * root-ClassLoaderValue. Each instance defines a separate namespace for
  33  * associated values.
  34  * <p>
  35  * ClassLoaderValue allows associating a
  36  * {@link #computeIfAbsent(ClassLoader, BiFunction) computed} non-null value with
  37  * a {@code (ClassLoader, keys...)} tuple. The associated value, as well as the
  38  * keys are strongly reachable from the associated ClassLoader so care should be
  39  * taken to use such keys and values that only reference types resolvable from
  40  * the associated ClassLoader. Failing that, ClassLoader leaks are inevitable.
  41  * <p>
  42  * Example usage:
  43  * <pre>{@code
  44  * // create a root instance which represents a namespace and declares the type of
  45  * // associated values (Class instances in this example)
  46  * static final ClassLoaderValue<Class<?>> proxyClasses = new ClassLoaderValue<>();
  47  *
  48  * // create a compound key composed of a Module and a list of interfaces
  49  * Module module = ...;
  50  * List<Class<?>> interfaces = ...;
  51  * ClassLoaderValue<Class<?>>.Sub<Module>.Sub<List<Class<?>>> key =
  52  *     proxyClasses.sub(module).sub(interfaces);
  53  *
  54  * // use the compound key together with ClassLoader to lazily associate
  55  * // the value with tuple (loader, module, interfaces) and return it
  56  * ClassLoader loader = ...;
  57  * Class<?> proxyClass = key.computeIfAbsent(loader, (ld, ky) -> {
  58  *     List<Class<?>> intfcs = ky.key();
  59  *     Module m = ky.parent().key();
  60  *     Class<?> clazz = defineProxyClass(ld, m, intfcs);
  61  *     return clazz;
  62  * });
  63  * }</pre>
  64  * <p>
  65  * {@code classLoaderValue.<operation>(classLoader, ...)} represents an operation
  66  * to {@link #get}, {@link #putIfAbsent}, {@link #computeIfAbsent} or {@link #remove}
  67  * a value associated with a (classLoader, classLoaderValue) tuple. ClassLoader
  68  * instances and root-{@link ClassLoaderValue} instances are compared using
  69  * identity equality while {@link Sub sub}-ClassLoaderValue instances define
  70  * {@link #equals(Object) equality} in terms of equality of its
  71  * {@link Sub#parent() parent} ClassLoaderValue and its
  72  * {@link #key() key} component.
  73  *
  74  * @param <V> the type of value(s) associated with the root-ClassLoaderValue and
  75  *            all its {@link #sub(Object) descendants}.
  76  * @author Peter Levart
  77  * @since 9
  78  */
  79 public final class ClassLoaderValue<V>
  80     extends AbstractClassLoaderValue<ClassLoaderValue<V>, V> {
  81 
  82     /**
  83      * Constructs new root-ClassLoaderValue representing its own namespace.
  84      */
  85     public ClassLoaderValue() {}
  86 
  87     /**
  88      * @return the key component of this root-ClassLoaderValue (itself).
  89      */
  90     @Override
  91     public ClassLoaderValue<V> key() {
  92         return this;
  93     }
  94 
  95     /**
  96      * root-ClassLoaderValue can only be equal to itself and has no predecessors.
  97      */
  98     @Override
  99     public boolean isEqualOrDescendantOf(AbstractClassLoaderValue<?, V> clv) {
 100         return equals(Objects.requireNonNull(clv));
 101     }
 102 }