1 /*
   2  * Copyright (c) 2018, 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 package java.lang.constant;
  26 
  27 import java.lang.invoke.MethodHandle;
  28 import java.lang.invoke.MethodHandles;
  29 import java.lang.invoke.MethodType;
  30 
  31 import jdk.internal.lang.annotation.Foldable;
  32 
  33 import static java.lang.constant.ConstantDescs.CD_void;
  34 import static java.lang.constant.DirectMethodHandleDesc.Kind.CONSTRUCTOR;
  35 
  36 /**
  37  * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
  38  * {@link MethodHandle} constant.
  39  *
  40  * @apiNote In the future, if the Java language permits, {@linkplain MethodHandleDesc}
  41  * may become a {@code sealed} interface, which would prohibit subclassing except
  42  * by explicitly permitted types.  Non-platform classes should not implement
  43  * {@linkplain MethodHandleDesc} directly.
  44  *
  45  * @since 12
  46  */
  47 public interface MethodHandleDesc
  48         extends ConstantDesc, Constable {
  49 
  50     /**
  51      * Creates a {@linkplain MethodHandleDesc} corresponding to an invocation of a
  52      * declared method, invocation of a constructor, or access to a field.
  53      *
  54      * <p>The lookup descriptor string has the same format as for the various
  55      * variants of {@code CONSTANT_MethodHandle_info} and for the lookup
  56      * methods on {@link MethodHandles.Lookup}.  For a method or constructor
  57      * invocation, it is interpreted as a method type descriptor; for field
  58      * access, it is interpreted as a field descriptor.  If {@code kind} is
  59      * {@code CONSTRUCTOR}, the {@code name} parameter is ignored and the return
  60      * type of the lookup descriptor must be {@code void}.  If {@code kind}
  61      * corresponds to a virtual method invocation, the lookup type includes the
  62      * method parameters but not the receiver type.
  63      *
  64      * @param kind The kind of method handle to be described
  65      * @param owner a {@link ClassDesc} describing the class containing the
  66      *              method, constructor, or field
  67      * @param name the unqualified name of the method or field (ignored if
  68      *             {@code kind} is {@code CONSTRUCTOR})
  69      * @param lookupDescriptor a method descriptor string the lookup type,
  70      *                         if the request is for a method invocation, or
  71      *                         describing the invocation type, if the request is
  72      *                         for a field or constructor
  73      * @return the {@linkplain MethodHandleDesc}
  74      * @throws NullPointerException if any of the non-ignored arguments are null


  75      * @jvms 4.4.8 The CONSTANT_MethodHandle_info Structure
  76      * @jvms 4.2.2 Unqualified Names
  77      * @jvms 4.3.2 Field Descriptors
  78      * @jvms 4.3.3 Method Descriptors
  79      */
  80     @Foldable
  81     static DirectMethodHandleDesc of(DirectMethodHandleDesc.Kind kind,
  82                                      ClassDesc owner,
  83                                      String name,
  84                                      String lookupDescriptor) {
  85         switch (kind) {
  86             case GETTER:
  87             case SETTER:
  88             case STATIC_GETTER:
  89             case STATIC_SETTER:
  90                 return ofField(kind, owner, name, ClassDesc.ofDescriptor(lookupDescriptor));
  91             default:
  92                 return new DirectMethodHandleDescImpl(kind, owner, name, MethodTypeDesc.ofDescriptor(lookupDescriptor));
  93         }
  94     }
  95 
  96     /**
  97      * Creates a {@linkplain MethodHandleDesc} corresponding to an invocation of a
  98      * declared method or constructor.
  99      *
 100      * <p>The lookup descriptor string has the same format as for the lookup
 101      * methods on {@link MethodHandles.Lookup}.  If {@code kind} is
 102      * {@code CONSTRUCTOR}, the name is ignored and the return type of the lookup
 103      * type must be {@code void}.  If {@code kind} corresponds to a virtual method
 104      * invocation, the lookup type includes the method parameters but not the
 105      * receiver type.
 106      *
 107      * @param kind The kind of method handle to be described; must be one of
 108      *             {@code SPECIAL, VIRTUAL, STATIC, INTERFACE_SPECIAL,
 109      *             INTERFACE_VIRTUAL, INTERFACE_STATIC, CONSTRUCTOR}
 110      * @param owner a {@link ClassDesc} describing the class containing the
 111      *              method or constructor
 112      * @param name the unqualified name of the method (ignored if {@code kind}
 113      *             is {@code CONSTRUCTOR})
 114      * @param lookupMethodType a {@link MethodTypeDesc} describing the lookup type
 115      * @return the {@linkplain MethodHandleDesc}
 116      * @throws NullPointerException if any non-ignored arguments are null
 117      * @throws IllegalArgumentException if the {@code name} has the incorrect
 118      * format, or the kind is invalid
 119      * @jvms 4.2.2 Unqualified Names
 120      */
 121     @Foldable
 122     static DirectMethodHandleDesc ofMethod(DirectMethodHandleDesc.Kind kind,
 123                                            ClassDesc owner,
 124                                            String name,
 125                                            MethodTypeDesc lookupMethodType) {
 126         switch (kind) {
 127             case GETTER:
 128             case SETTER:
 129             case STATIC_GETTER:
 130             case STATIC_SETTER:
 131                 throw new IllegalArgumentException(kind.toString());
 132             case VIRTUAL:
 133             case SPECIAL:
 134             case INTERFACE_VIRTUAL:
 135             case INTERFACE_SPECIAL:
 136             case INTERFACE_STATIC:
 137             case STATIC:
 138             case CONSTRUCTOR:
 139                 return new DirectMethodHandleDescImpl(kind, owner, name, lookupMethodType);
 140             default:
 141                 throw new IllegalArgumentException(kind.toString());
 142         }
 143     }
 144 
 145     /**
 146      * Creates a {@linkplain MethodHandleDesc} corresponding to a method handle
 147      * that accesses a field.
 148      *
 149      * @param kind the kind of the method handle to be described; must be one of {@code GETTER},
 150      *             {@code SETTER}, {@code STATIC_GETTER}, or {@code STATIC_SETTER}
 151      * @param owner a {@link ClassDesc} describing the class containing the field
 152      * @param fieldName the unqualified name of the field
 153      * @param fieldType a {@link ClassDesc} describing the type of the field
 154      * @return the {@linkplain MethodHandleDesc}
 155      * @throws NullPointerException if any of the arguments are null
 156      * @throws IllegalArgumentException if the {@code kind} is not one of the
 157      * valid values or if the field name is not valid
 158      * @jvms 4.2.2 Unqualified Names
 159      */
 160     @Foldable
 161     static DirectMethodHandleDesc ofField(DirectMethodHandleDesc.Kind kind,
 162                                           ClassDesc owner,
 163                                           String fieldName,
 164                                           ClassDesc fieldType) {
 165         MethodTypeDesc mtr;
 166         switch (kind) {
 167             case GETTER: mtr = MethodTypeDesc.of(fieldType, owner); break;
 168             case SETTER: mtr = MethodTypeDesc.of(CD_void, owner, fieldType); break;
 169             case STATIC_GETTER: mtr = MethodTypeDesc.of(fieldType); break;
 170             case STATIC_SETTER: mtr = MethodTypeDesc.of(CD_void, fieldType); break;
 171             default:
 172                 throw new IllegalArgumentException(kind.toString());
 173         }
 174         return new DirectMethodHandleDescImpl(kind, owner, fieldName, mtr);
 175     }
 176 
 177     /**
 178      * Returns a {@linkplain MethodHandleDesc} corresponding to invocation of a constructor
 179      *
 180      * @param owner a {@link ClassDesc} describing the class containing the
 181      *              constructor
 182      * @param paramTypes {@link ClassDesc}s describing the parameter types of
 183      *                   the constructor
 184      * @return the {@linkplain MethodHandleDesc}
 185      * @throws NullPointerException if any of the arguments are null
 186      */
 187     @Foldable
 188     static DirectMethodHandleDesc ofConstructor(ClassDesc owner,
 189                                                 ClassDesc... paramTypes) {
 190         return MethodHandleDesc.ofMethod(CONSTRUCTOR, owner, ConstantDescs.DEFAULT_NAME,
 191                                          MethodTypeDesc.of(CD_void, paramTypes));
 192     }
 193 
 194     /**
 195      * Returns a {@linkplain MethodHandleDesc} that describes this method handle
 196      * adapted to a different type, as if by {@link MethodHandle#asType(MethodType)}.
 197      *
 198      * @param type a {@link MethodHandleDesc} describing the new method type
 199      * @return a {@linkplain MethodHandleDesc} for the adapted method handle

 200      */
 201     @Foldable
 202     default MethodHandleDesc asType(MethodTypeDesc type) {
 203         return (invocationType().equals(type)) ? this : new AsTypeMethodHandleDesc(this, type);
 204     }
 205 
 206     /**
 207      * Returns a {@link MethodTypeDesc} describing the invocation type of the
 208      * method handle described by this nominal descriptor.  The invocation type
 209      * describes the full set of stack values that are consumed by the invocation
 210      * (including the receiver, if any).
 211      *
 212      * @return a {@linkplain MethodHandleDesc} describing the method handle type
 213      */
 214     @Foldable
 215     MethodTypeDesc invocationType();
 216 
 217     /**
 218      * Compares the specified object with this descriptor for equality.  Returns
 219      * {@code true} if and only if the specified object is also a
 220      * {@linkplain MethodHandleDesc}, and both encode the same nominal description
 221      * of a method handle.
 222      *
 223      * @param o the other object
 224      * @return whether this descriptor is equal to the other object
 225      */
 226     boolean equals(Object o);
 227 }
--- EOF ---