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
77
78
79
80
81
82
83
84
85

** 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 4.0 so the jar
  asm-all-4.0.jar must be in the same directory.  


** How to run the backport agent **

  There is four execution modes:
    online/offline weaving and with or without an optimizer

  - Online weaving:
    The bytecode is weaved at runtime by a VM agent.
    So the retro-compilation is done on the fly.
    
      java -javaagent:lib/jsr292-backport.jar YourClass    
    
  - Offline weaving:
    An Ant task takes a jar and retro-weave the code and produce another jar.
    
      <taskdef name="jsr292-backport" classname="jsr292.weaver.BackportTask" classpath="${lib}/jsr292-backport.jar" />
      <jsr292-backport file="${phpreboot.jar}" dependency="${lib}/asm-all-3.2.jar"/>
    
  - The runtime optimizer
    The backport comes with a runtime optimizer which is able to recompile method handle calls
    and invokedynamic calls to provide performance as par as jdk7 runtime.
    This optimizer works by retransforming classes on the fly.
    It can be disable on platform that doesn't support class retransformation
    like by example the google appengine or android.
    
      java -javaagent:lib/jsr292-backport.jar -Djsr292.backport.optimizer=false 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:mock/jsr292-mock.jar -source 1.7 YourClass.java


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

  You can use ASM 4.0 or later (at http://asm.ow2.org).


** 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 other 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.
    - MethodHandles.collect/spread doesn't support varargs of primitive types


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

  To be able to optimize 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