public class StringConcatFactory extends Object
Methods to facilitate the creation of String concatenation methods, that
can be used to efficiently concatenate a known number of arguments of known
types, possibly after type adaptation and partial evaluation of arguments.
These methods are typically used as bootstrap methods for invokedynamic
call sites, to support the string concatenation
feature of the Java Programming Language.
Indirect access to the behavior specified by the provided MethodHandle
proceeds in order through two phases:
CallSite
holds the MethodHandle
pointing to the
exact concatenation method. The concatenation methods may be shared among
different CallSite
s, e.g. if linkage methods produce them as pure
functions.MethodHandle
is invoked with the static arguments and any additional dynamic
arguments provided on invocation, as if by MethodHandle.invoke(Object...)
. This class provides two forms of linkage methods: a simple version
(makeConcat(java.lang.invoke.MethodHandles.Lookup, String,
MethodType)
) using only the dynamic arguments, and an advanced version
(makeConcatWithConstants(java.lang.invoke.MethodHandles.Lookup,
String, MethodType, String, Object...)
using the advanced forms of capturing
the constant arguments. The advanced strategy can produce marginally better
invocation bytecode, at the expense of exploding the number of shapes of
string concatenation methods present at runtime, because those shapes would
include constant static arguments as well.
There is a JVM limit (classfile structural constraint): no method
can call with more than 255 slots. This limits the number of static and
dynamic arguments one can pass to bootstrap method. Since there are potential
concatenation strategies that use MethodHandle
combinators, we need
to reserve a few empty slots on the parameter lists to to capture the
temporal results. This is why bootstrap methods in this factory do not accept
more than 200 argument slots. Users requiring more than 200 argument slots in
concatenation are expected to split the large concatenation in smaller
expressions.
Modifier and Type | Method and Description |
---|---|
static CallSite |
makeConcat(MethodHandles.Lookup lookup,
String name,
MethodType concatType)
Facilitates the creation of optimized String concatenation methods, that
can be used to efficiently concatenate a known number of arguments of
known types, possibly after type adaptation and partial evaluation of
arguments.
|
static CallSite |
makeConcatWithConstants(MethodHandles.Lookup lookup,
String name,
MethodType concatType,
String recipe,
Object... constants)
Facilitates the creation of optimized String concatenation methods, that
can be used to efficiently concatenate a known number of arguments of
known types, possibly after type adaptation and partial evaluation of
arguments.
|
public static CallSite makeConcat(MethodHandles.Lookup lookup, String name, MethodType concatType) throws StringConcatException
invokedynamic
call sites, to support the string concatenation
feature of the Java Programming Language.
When the target of the CallSite
returned from this method is
invoked, it returns the result of String concatenation, taking all
function arguments passed to the linkage method as inputs for
concatenation. The target signature is given by concatType
.
The arguments are concatenated as per requirements stated in JLS 15.18.1
"String Concatenation Operator +". Notably, the inputs are converted as
per JLS 5.1.11 "String Conversion", and combined from left to right.
Assume the linkage arguments are as follows:
concatType
, describing the CallSite
signatureThen the following linkage invariants must hold:
concatType
is less than or equal to 200concatType
is assignable from String
lookup
- Represents a lookup context with the accessibility
privileges of the caller. When used with invokedynamic
, this is stacked automatically by the VM.name
- The name of the method to implement. This name is
arbitrary, and has no meaning for this linkage method.
When used with invokedynamic
, this is provided by
the NameAndType
of the InvokeDynamic
structure and is stacked automatically by the VM.concatType
- The expected signature of the CallSite
. The
parameter types represent the types of concatenation
arguments; the return type is always assignable from String
. When used with invokedynamic
,
this is provided by the NameAndType
of the InvokeDynamic
structure and is stacked automatically by
the VM.concatType
.StringConcatException
- If any of the linkage invariants described
here are violated.NullPointerException
- If any of the incoming arguments is null.
This will never happen when a bootstrap method
is called with invokedynamic.public static CallSite makeConcatWithConstants(MethodHandles.Lookup lookup, String name, MethodType concatType, String recipe, Object... constants) throws StringConcatException
invokedynamic
call sites, to support the string concatenation
feature of the Java Programming Language.
When the target of the CallSite
returned from this method is
invoked, it returns the result of String concatenation, taking all
function arguments and constants passed to the linkage method as inputs for
concatenation. The target signature is given by concatType
, and
does not include constants. The arguments are concatenated as per requirements
stated in JLS 15.18.1 "String Concatenation Operator +". Notably, the inputs
are converted as per JLS 5.1.11 "String Conversion", and combined from left
to right.
The concatenation recipe is a String description for the way to construct a concatenated String from the arguments and constants. The recipe is processed from left to right, and each character represents an input to concatenation. Recipe characters mean:
toString
to perform a one-time String conversion.Assume the linkage arguments are as follows:
concatType
, describing the CallSite
signaturerecipe
, describing the String recipeconstants
, the vararg array of constantsThen the following linkage invariants must hold:
concatType
is less than or equal to
200concatType
equals to number of \1 tags
in recipe
concatType
is assignable
from String
, and matches the return type of the
returned MethodHandle
constants
equals to number of \2
tags in recipe
lookup
- Represents a lookup context with the accessibility
privileges of the caller. When used with invokedynamic
, this is stacked automatically by the
VM.name
- The name of the method to implement. This name is
arbitrary, and has no meaning for this linkage method.
When used with invokedynamic
, this is provided
by the NameAndType
of the InvokeDynamic
structure and is stacked automatically by the VM.concatType
- The expected signature of the CallSite
. The
parameter types represent the types of dynamic concatenation
arguments; the return type is always assignable from String
. When used with invokedynamic
, this is provided by the NameAndType
of the InvokeDynamic
structure and
is stacked automatically by the VM.recipe
- Concatenation recipe, described above.constants
- A vararg parameter representing the constants passed to
the linkage method.concatType
.StringConcatException
- If any of the linkage invariants described
here are violated.NullPointerException
- If any of the incoming arguments is null, or
any constant in recipe
is null.
This will never happen when a bootstrap method
is called with invokedynamic. Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.
DRAFT internal-b00