APIdia Launch Partner
Top Description Fields Constructors Methods
java.lang.invoke

public abstract sealed Class CallSite

extends Object
permits ConstantCallSite, MutableCallSite, VolatileCallSite
Class Inheritance
Known Direct Subclasses
java.lang.invoke.ConstantCallSite, java.lang.invoke.MutableCallSite, java.lang.invoke.VolatileCallSite
Static Imports
java.lang.invoke.MethodHandleStatics.*, .MethodHandles.Lookup.IMPL_LOOKUP

A CallSite is a holder for a variable MethodHandle, which is called its target. An invokedynamic instruction linked to a CallSite delegates all calls to the site's current target. A CallSite may be associated with several invokedynamic instructions, or it may be "free floating", associated with none. In any case, it may be invoked through an associated method handle called its dynamic invoker.

CallSite is an abstract sealed class which does not allow direct subclassing by users. It has three immediate, concrete non-sealed subclasses that may be either instantiated or subclassed.

A non-constant call site may be relinked by changing its target. The new target must have the same type as the previous target. Thus, though a call site can be relinked to a series of successive targets, it cannot change its type.

Here is a sample use of call sites and bootstrap methods which links every dynamic call site to print its arguments:

static void test() throws Throwable {
    // THE FOLLOWING LINE IS PSEUDOCODE FOR A JVM INSTRUCTION
    InvokeDynamic[#bootstrapDynamic].baz("baz arg", 2, 3.14);
}
private static void printArgs(Object... args) {
  System.out.println(java.util.Arrays.deepToString(args));
}
private static final MethodHandle printArgs;
static {
  MethodHandles.Lookup lookup = MethodHandles.lookup();
  Class thisClass = lookup.lookupClass();  // (who am I?)
  printArgs = lookup.findStatic(thisClass,
      "printArgs", MethodType.methodType(void.class, Object[].class));
}
private static CallSite bootstrapDynamic(MethodHandles.Lookup caller, String name, MethodType type) {
  // ignore caller and name, but match the type:
  return new ConstantCallSite(printArgs.asType(type));
}
Author
John Rose, JSR 292 EG
Since
1.7

Field Summary

Modifier and TypeField and Description
private static MethodHandle
pack-priv final MethodHandle
private static long
private static MethodHandle

Constructor Summary

AccessConstructor and Description
pack-priv
CallSite(MethodType type)

Make a blank call site object with the given method type.

pack-priv
CallSite(MethodHandle
the method handle which will be the initial target of the call site
target
)

Make a call site object equipped with an initial target method handle.

pack-priv
CallSite(MethodType
the desired type of the call site
targetType
,
MethodHandle
a hook which will bind the call site to the target method handle
createTargetHook
)

Make a call site object equipped with an initial target method handle.

Method Summary

Modifier and TypeMethod and Description
private void
public abstract MethodHandle

Returns:

a method handle which always invokes this call site's current target
dynamicInvoker
()

Produces a method handle equivalent to an invokedynamic instruction which has been linked to this call site.

public abstract MethodHandle

Returns:

the current linkage state of the call site, its target method handle
getTarget
()

Returns the target method of the call site, according to the behavior defined by this call site's specific class.

private static MethodHandle
private static long
pack-priv final MethodHandle
pack-priv MethodHandle
pack-priv static CallSite
makeSite(MethodHandle bootstrapMethod, String name, MethodType type, Object info, Class<?> callerClass)

private MethodHandle
public abstract void
setTarget(MethodHandle
the new target
newTarget
)

Updates the target method of this call site, according to the behavior defined by this call site's specific class.

pack-priv final void
pack-priv final void
public MethodType

Returns:

the type of the current target, which is also the type of any future target
type
()

Returns the type of this call site's target.

private static Object
uninitializedCallSite(Object... ignore)

This guy is rolled into the default target if a MethodType is supplied to the constructor.

private static MethodHandle
private static WrongMethodTypeException
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

GET_TARGETback to summary
private static MethodHandle GET_TARGET
Annotations
@Stable
targetback to summary
pack-priv final MethodHandle target
TARGET_OFFSETback to summary
private static long TARGET_OFFSET
Annotations
@Stable
THROW_UCSback to summary
private static MethodHandle THROW_UCS
Annotations
@Stable

Constructor Detail

CallSiteback to summary
pack-priv CallSite(MethodType type)

Make a blank call site object with the given method type. An initial target method is supplied which will throw an IllegalStateException if called.

Before this CallSite object is returned from a bootstrap method, it is usually provided with a more useful target method, via a call to setTarget.

Exceptions
NullPointerException:
if the proposed type is null
CallSiteback to summary
pack-priv CallSite(MethodHandle target)

Make a call site object equipped with an initial target method handle.

Parameters
target:MethodHandle

the method handle which will be the initial target of the call site

Exceptions
NullPointerException:
if the proposed target is null
CallSiteback to summary
pack-priv CallSite(MethodType targetType, MethodHandle createTargetHook) throws Throwable

Make a call site object equipped with an initial target method handle.

Parameters
targetType:MethodType

the desired type of the call site

createTargetHook:MethodHandle

a hook which will bind the call site to the target method handle

Exceptions
Throwable:
anything else thrown by the hook function
WrongMethodTypeException:
if the hook cannot be invoked on the required arguments, or if the target returned by the hook is not of the given targetType
NullPointerException:
if the hook returns a null value
ClassCastException:
if the hook returns something other than a MethodHandle

Method Detail

checkTargetChangeback to summary
private void checkTargetChange(MethodHandle newTarget)
dynamicInvokerback to summary
public abstract MethodHandle dynamicInvoker()

Produces a method handle equivalent to an invokedynamic instruction which has been linked to this call site.

This method is equivalent to the following code:

MethodHandle getTarget, invoker, result;
getTarget = MethodHandles.publicLookup().bind(this, "getTarget", MethodType.methodType(MethodHandle.class));
invoker = MethodHandles.exactInvoker(this.type());
result = MethodHandles.foldArguments(invoker, getTarget)
Returns:MethodHandle

a method handle which always invokes this call site's current target

getTargetback to summary
public abstract MethodHandle getTarget()

Returns the target method of the call site, according to the behavior defined by this call site's specific class. The immediate subclasses of CallSite document the class-specific behaviors of this method.

Returns:MethodHandle

the current linkage state of the call site, its target method handle

See Also
ConstantCallSite, VolatileCallSite, setTarget, ConstantCallSite#getTarget, MutableCallSite#getTarget, VolatileCallSite#getTarget
getTargetHandleback to summary
private static MethodHandle getTargetHandle()
getTargetOffsetback to summary
private static long getTargetOffset()
getTargetVolatileback to summary
pack-priv final MethodHandle getTargetVolatile()
makeDynamicInvokerback to summary
pack-priv MethodHandle makeDynamicInvoker()
makeSiteback to summary
pack-priv static CallSite makeSite(MethodHandle bootstrapMethod, String name, MethodType type, Object info, Class<?> callerClass)
makeUninitializedCallSiteback to summary
private MethodHandle makeUninitializedCallSite(MethodType targetType)
setTargetback to summary
public abstract void setTarget(MethodHandle newTarget)

Updates the target method of this call site, according to the behavior defined by this call site's specific class. The immediate subclasses of CallSite document the class-specific behaviors of this method.

The type of the new target must be equal to the type of the old target.

Parameters
newTarget:MethodHandle

the new target

Exceptions
NullPointerException:
if the proposed new target is null
WrongMethodTypeException:
if the proposed new target has a method type that differs from the previous target
See Also
CallSite#getTarget, ConstantCallSite#setTarget, MutableCallSite#setTarget, VolatileCallSite#setTarget
setTargetNormalback to summary
pack-priv final void setTargetNormal(MethodHandle newTarget)
setTargetVolatileback to summary
pack-priv final void setTargetVolatile(MethodHandle newTarget)
typeback to summary
public MethodType type()

Returns the type of this call site's target. Although targets may change, any call site's type is permanent, and can never change to an unequal type. The setTarget method enforces this invariant by refusing any new target that does not have the previous target's type.

Returns:MethodType

the type of the current target, which is also the type of any future target

uninitializedCallSiteback to summary
private static Object uninitializedCallSite(Object... ignore)

This guy is rolled into the default target if a MethodType is supplied to the constructor.

uninitializedCallSiteHandleback to summary
private static MethodHandle uninitializedCallSiteHandle()
wrongTargetTypeback to summary
private static WrongMethodTypeException wrongTargetType(MethodHandle target, MethodType type)