1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

** How to create the backport jar **

  You need a Java Development Kit version 1.5 or above.
  And just type:  
     ant jar

  A jar containing the backport will be generated in lib.
  This jar as a dependency to ASM 3.2 so the jar
  asm-all-3.2.jar must be in the same directory.  


** How to run the backport agent **

  java -javaagent:lib/jsr292-backport.jar YourClass


** How to compile my code that use JSR 292 ? **

  The best is to build a patched VM/JDK using the latest patch queues
  from mlvm repository: http://wikis.sun.com/display/mlvm/Building

  But you can also download lastest JDK 7 binaries
    http://download.java.net/jdk7/binaries/
  to get a javac able to emit 1.7 compatible bytecode
  and compile using the JSR 292 stub jar provided by the backport :

    jdk1.7.0/bin/javac -Xbootclasspath/p:stub/jsr292-stub.jar -source 1.7 YourClass.java


** How can I generate JSR 292 invokedynamic bytecode **

  You can use ASM 3.2 (at http://asm.ow2.org).


** How to disable the backport optimizer **
  
  A flag allows you to disable the backport optimizer:
  java -javaagent:lib/jsr292-backport.jar -Djsr292.backport.optimizer=false YourClass


** Known Compatibility Glitches **

  - With other Java agents:
    The JSR 292 backport use an agent which is known to be compatible
    with agents that use 1.6 instrumentation API (retransform and not redefine).
    The JSR 292 backport is not compatible with agents using 1.5 instrumentation API.

  - with JSR 292 API
    - MethodHandles.lookup().findSuper is not implemented
    - Lookup on a MethodHandle to find an invoke method doesn't work:
      MethodHandles.lookup().findVirtual(MethodHandle.class, "invoke", type);
      Use MethodHandles.exactInvoker() instead.
    - all lookups use access checking rules defined in VM spec and not
      those defined in JLS so
      access between an inner class and its enclosing class is not valid. 
    - JavaMethodHandle constructors that take an entry point name
      use weird rules to find the entry point method.
      This kind of lookup is not implemented in the backport.
    - MethodHandles.collect/spread doesn't support varargs of primitive types


** Codes known as not optimizable by the backport optimizer **

  To be able to JIT an invokedynamic call site or a method handle adapters tree,
  the runtime of the backport has the following limitations:

  - direct method handle (get by findVirtual, findStatic etc.) must reference
    a visible method of a visible class from the call site.
  - methods used by unreflect must be visible and own by a visible class from the call site.
  - constructors of unreflectConstructor must be visible and own by a visible class.
  - field of unreflectGetter/unreflectSetter must also be visible and in a visible class from the call site 
  - argument of insertArguments must be instance of a public class to be at full speed, else
    the backport will insert a supplementary cast
  - JavaMethodHandle subclasses must be visible and entry point must be visible from the call site.