rev 58769 : [mq]: type-descriptor-name

   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.invoke;
  26 
  27 import java.util.List;
  28 
  29 /**
  30  * An entity that has a type descriptor.



  31  *
  32  * @since 12
  33  */
  34 public interface TypeDescriptor {
  35     /**
  36      * Returns the descriptor string for this {@code TypeDescriptor} object.
  37      *
  38      * If this {@code TypeDescriptor} object can be described in nominal form,
  39      * then this method returns a type descriptor as specified in JVMS {@jvms 4.3}.
  40      * The result descriptor string can be used to produce
  41      * a {@linkplain java.lang.constant.ConstantDesc nominal descriptor}.
  42      *
  43      * Otherwise, the result string is not a type descriptor.
  44      * No {@linkplain java.lang.constant.ConstantDesc nominal descriptor}
  45      * can be produced from the result string.
  46      *
  47      * @return the descriptor string for this {@code TypeDescriptor} object
  48      * @jvms 4.3.2 Field Descriptors
  49      * @jvms 4.3.3 Method Descriptors
  50      */
  51     String descriptorString();
  52 
  53 
  54     /**
  55      * An entity that has a field type descriptor.
  56      * Field descriptors conforming to JVMS {@jvms 4.3.2} can be described
  57      * nominally via {@link Class#describeConstable Class::describeConstable};
  58      * otherwise they cannot be described nominally.
  59      *
  60      * @param <F> the class implementing {@linkplain TypeDescriptor.OfField}
  61      * @jvms 4.3.2 Field Descriptors
  62      * @since 12
  63      */
  64     interface OfField<F extends TypeDescriptor.OfField<F>> extends TypeDescriptor {
  65         /**
  66          * Does this field descriptor describe an array type?
  67          * @return whether this field descriptor describes an array type
  68          */
  69         boolean isArray();
  70 
  71         /**
  72          * Does this field descriptor describe a primitive type (including void.)
  73          *
  74          * @return whether this field descriptor describes a primitive type
  75          */
  76         boolean isPrimitive();
  77 
  78         /**
  79          * If this field descriptor describes an array type, return
  80          * a descriptor for its component type, otherwise return {@code null}.
  81          * @return the component type, or {@code null} if this field descriptor does
  82          * not describe an array type
  83          */
  84         F componentType();
  85 
  86         /**
  87          * Return a descriptor for the array type whose component type is described by this
  88          * descriptor
  89          * @return the descriptor for the array type
  90          */
  91         F arrayType();
  92     }
  93 
  94 
  95     /**
  96      * An entity that has a method type descriptor
  97      * Method descriptors conforming to JVMS {@jvms 4.3.3} can be described
  98      * nominally via {@link MethodType#describeConstable MethodType::describeConstable};
  99      * otherwise they cannot be described nominally.
 100      *
 101      * @param <F> the type representing field type descriptors
 102      * @param <M> the class implementing {@linkplain TypeDescriptor.OfMethod}
 103      * @jvms 4.3.2 Field Descriptors
 104      * @jvms 4.3.3 Method Descriptors
 105      * @since 12
 106      */
 107     interface OfMethod<F extends TypeDescriptor.OfField<F>, M extends TypeDescriptor.OfMethod<F, M>>
 108             extends TypeDescriptor {
 109 
 110         /**
 111          * Return the number of parameters in the method type
 112          * @return the number of parameters
 113          */
 114         int parameterCount();
 115 
 116         /**
 117          * Return a field descriptor describing the requested parameter of the method type
 118          * described by this descriptor
 119          * @param i the index of the parameter
 120          * @return a field descriptor for the requested parameter type
 121          * @throws IndexOutOfBoundsException if the index is outside the half-open
 122          * range {[0, parameterCount)}
 123          */
 124         F parameterType(int i);
 125 
 126         /**
 127          * Return a field descriptor describing the return type of the method type described
 128          * by this descriptor
 129          * @return a field descriptor for the return type
 130          */
 131         F returnType();
 132 
 133         /**
 134          * Return an array of field descriptors for the parameter types of the method type
 135          * described by this descriptor
 136          * @return field descriptors for the parameter types
 137          */
 138         F[] parameterArray();
 139 
 140         /**
 141          * Return an immutable list of field descriptors for the parameter types of the method type
 142          * described by this descriptor
 143          * @return field descriptors for the parameter types
 144          */
 145         List<F> parameterList();
 146 
 147         /**
 148          * Return a method descriptor that is identical to this one, except that the return
 149          * type has been changed to the specified type
 150          *
 151          * @param newReturn a field descriptor for the new return type
 152          * @throws NullPointerException if any argument is {@code null}
 153          * @return the new method descriptor
 154          */
 155         M changeReturnType(F newReturn);
 156 
 157         /**
 158          * Return a method descriptor that is identical to this one,
 159          * except that a single parameter type has been changed to the specified type.
 160          *
 161          * @param index the index of the parameter to change
 162          * @param paramType a field descriptor describing the new parameter type
 163          * @return the new method descriptor
 164          * @throws NullPointerException if any argument is {@code null}
 165          * @throws IndexOutOfBoundsException if the index is outside the half-open
 166          * range {[0, parameterCount)}
 167          */
 168         M changeParameterType(int index, F paramType);
 169 
 170         /**
 171          * Return a method descriptor that is identical to this one,
 172          * except that a range of parameter types have been removed.
 173          *
 174          * @param start the index of the first parameter to remove
 175          * @param end the index after the last parameter to remove
 176          * @return the new method descriptor
 177          *
 178          * @throws IndexOutOfBoundsException if {@code start} is outside the half-open
 179          * range {@code [0, parameterCount)}, or {@code end} is outside the closed range
 180          * {@code [0, parameterCount]}, or if {@code start > end}
 181          */
 182         M dropParameterTypes(int start, int end);
 183 
 184         /**
 185          * Return a method descriptor that is identical to this one,
 186          * except that a range of additional parameter types have been inserted.
 187          *
 188          * @param pos the index at which to insert the first inserted parameter
 189          * @param paramTypes field descriptors describing the new parameter types
 190          *                   to insert
 191          * @return the new method descriptor
 192          * @throws NullPointerException if any argument is {@code null}
 193          * @throws IndexOutOfBoundsException if {@code pos} is outside the closed
 194          * range {[0, parameterCount]}
 195          */
 196         @SuppressWarnings("unchecked")
 197         M insertParameterTypes(int pos, F... paramTypes);
 198     }
 199 }
--- EOF ---