1 /*

     2  * Copyright (c) 2010, 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.dyn;

    27 

    28 import java.lang.annotation.*;

    29 

    30 /**

    31  * Annotation on InvokeDynamic method calls which requests the JVM to use a specific

    32  * <a href="package-summary.html#bsm">bootstrap method</a>

    33  * to link the call.  This annotation is not retained as such in the class file,

    34  * but is transformed into a constant-pool entry for the invokedynamic instruction which

    35  * specifies the desired bootstrap method.

    36  * <p>

    37  * If only the <code>value</code> is given, it must name a subclass of {@link CallSite}

    38  * with a constructor which accepts a class, string, and method type.

    39  * If the <code>value</code> and <code>name</code> are both given, there must be

    40  * a static method in the given class of the given name which accepts a class, string,

    41  * and method type, and returns a reference coercible to {@link CallSite}.

    42  * <p>

    43  * This annotation can be placed either on the return type of a single {@link InvokeDynamic}

    44  * call (see examples) or else it can be placed on an enclosing class or method, where it

    45  * determines a default bootstrap method for any {@link InvokeDynamic} calls which are not

    46  * specifically annotated with a bootstrap method.

    47  * Every {@link InvokeDynamic} call must be given a bootstrap method.

    48  * <p>

    49  * Examples:

    50 <blockquote><pre>

    51 @BootstrapMethod(value=MyLanguageRuntime.class, name="bootstrapDynamic")

    52 String x = (String) InvokeDynamic.greet();

    53 //BSM => MyLanguageRuntime.bootstrapDynamic(Here.class, "greet", methodType(String.class))

    54 @BootstrapMethod(MyCallSite.class)

    55 void example() throws Throwable {

    56     InvokeDynamic.greet();

    57     //BSM => new MyCallSite(Here.class, "greet", methodType(void.class))

    58 }

    59 </pre></blockquote>

    60  * <p>

    61  */

    62 @Target({ElementType.TYPE_USE,

    63             // For defaulting every indy site within a class or method; cf. @SuppressWarnings:

    64             ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR

    65             })

    66 @Retention(RetentionPolicy.SOURCE)

    67 public @interface BootstrapMethod {

    68     /** The class containing the bootstrap method. */

    69     Class<?> value();

    70 

    71     /** The name of the bootstrap method.

    72      *  If this is the empty string, an instance of the bootstrap class is created,

    73      *  and a constructor is invoked.

    74      *  Otherwise, there must be a static method of the required name.

    75      */

    76     String name() default "";  // empty string denotes a constructor with 'new'

    77 

    78     /** The argument types of the bootstrap method, as passed out by the JVM.

    79      *  There is usually no reason to override the default.

    80      */

    81     Class<?>[] arguments() default {Class.class, String.class, MethodType.class};

    82 }