Home » openjdk-7 » java.lang.invoke » [javadoc | source]

    1   /*
    2    * Copyright (c) 2010, 2011, 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.lang.invoke;
   27   
   28   /**
   29    * A {@code ConstantCallSite} is a {@link CallSite} whose target is permanent, and can never be changed.
   30    * An {@code invokedynamic} instruction linked to a {@code ConstantCallSite} is permanently
   31    * bound to the call site's target.
   32    * @author John Rose, JSR 292 EG
   33    */
   34   public class ConstantCallSite extends CallSite {
   35       private final boolean isFrozen;
   36   
   37       /**
   38        * Creates a call site with a permanent target.
   39        * @param target the target to be permanently associated with this call site
   40        * @throws NullPointerException if the proposed target is null
   41        */
   42       public ConstantCallSite(MethodHandle target) {
   43           super(target);
   44           isFrozen = true;
   45       }
   46   
   47       /**
   48        * Creates a call site with a permanent target, possibly bound to the call site itself.
   49        * <p>
   50        * During construction of the call site, the {@code createTargetHook} is invoked to
   51        * produce the actual target, as if by a call of the form
   52        * {@code (MethodHandle) createTargetHook.invoke(this)}.
   53        * <p>
   54        * Note that user code cannot perform such an action directly in a subclass constructor,
   55        * since the target must be fixed before the {@code ConstantCallSite} constructor returns.
   56        * <p>
   57        * The hook is said to bind the call site to a target method handle,
   58        * and a typical action would be {@code someTarget.bindTo(this)}.
   59        * However, the hook is free to take any action whatever,
   60        * including ignoring the call site and returning a constant target.
   61        * <p>
   62        * The result returned by the hook must be a method handle of exactly
   63        * the same type as the call site.
   64        * <p>
   65        * While the hook is being called, the new {@code ConstantCallSite}
   66        * object is in a partially constructed state.
   67        * In this state,
   68        * a call to {@code getTarget}, or any other attempt to use the target,
   69        * will result in an {@code IllegalStateException}.
   70        * It is legal at all times to obtain the call site's type using the {@code type} method.
   71        *
   72        * @param targetType the type of the method handle to be permanently associated with this call site
   73        * @param createTargetHook a method handle to invoke (on the call site) to produce the call site's target
   74        * @throws WrongMethodTypeException if the hook cannot be invoked on the required arguments,
   75        *         or if the target returned by the hook is not of the given {@code targetType}
   76        * @throws NullPointerException if the hook returns a null value
   77        * @throws ClassCastException if the hook returns something other than a {@code MethodHandle}
   78        * @throws Throwable anything else thrown by the the hook function
   79        */
   80       protected ConstantCallSite(MethodType targetType, MethodHandle createTargetHook) throws Throwable {
   81           super(targetType, createTargetHook);
   82           isFrozen = true;
   83       }
   84   
   85       /**
   86        * Returns the target method of the call site, which behaves
   87        * like a {@code final} field of the {@code ConstantCallSite}.
   88        * That is, the the target is always the original value passed
   89        * to the constructor call which created this instance.
   90        *
   91        * @return the immutable linkage state of this call site, a constant method handle
   92        * @throws IllegalStateException if the {@code ConstantCallSite} constructor has not completed
   93        */
   94       @Override public final MethodHandle getTarget() {
   95           if (!isFrozen)  throw new IllegalStateException();
   96           return target;
   97       }
   98   
   99       /**
  100        * Always throws an {@link UnsupportedOperationException}.
  101        * This kind of call site cannot change its target.
  102        * @param ignore a new target proposed for the call site, which is ignored
  103        * @throws UnsupportedOperationException because this kind of call site cannot change its target
  104        */
  105       @Override public final void setTarget(MethodHandle ignore) {
  106           throw new UnsupportedOperationException();
  107       }
  108   
  109       /**
  110        * Returns this call site's permanent target.
  111        * Since that target will never change, this is a correct implementation
  112        * of {@link CallSite#dynamicInvoker CallSite.dynamicInvoker}.
  113        * @return the immutable linkage state of this call site, a constant method handle
  114        * @throws IllegalStateException if the {@code ConstantCallSite} constructor has not completed
  115        */
  116       @Override
  117       public final MethodHandle dynamicInvoker() {
  118           return getTarget();
  119       }
  120   }

Home » openjdk-7 » java.lang.invoke » [javadoc | source]