Skip to content

Commit dd94bda

Browse files
vsilaevvsilaev
authored
Update README.md
1 parent 3d2d343 commit dd94bda

File tree

1 file changed

+57
-57
lines changed

1 file changed

+57
-57
lines changed

‎README.md

Lines changed: 57 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -30,47 +30,47 @@ The project is based on the completely reworked Apache Jakarta-Commons JavaFlow
3030

3131
You have to add the following configuration to enable build-time instrumentation of classes during Maven build:
3232
```xml
33-
<dependencies>
34-
<dependency>
33+
<dependencies>
34+
<dependency>
35+
<groupId>net.tascalate.javaflow</groupId>
36+
<artifactId>net.tascalate.javaflow.api</artifactId>
37+
<version>2.7.3</version>
38+
</dependency>
39+
<!-- Add-on for Java 8 and above -->
40+
<dependency>
41+
<groupId>net.tascalate.javaflow</groupId>
42+
<artifactId>net.tascalate.javaflow.extras</artifactId>
43+
<version>2.4.2</version>
44+
</dependency>
45+
...
46+
</dependencies>
47+
48+
<build>
49+
<plugins>
50+
<plugin>
51+
<groupId>org.apache.maven.plugins</groupId>
52+
<artifactId>maven-compiler-plugin</artifactId>
53+
<configuration>
54+
<!-- versions 1.6 -- 17 are supported -->
55+
<source>1.6</source>
56+
<target>1.6</target>
57+
</configuration>
58+
</plugin>
59+
<plugin>
3560
<groupId>net.tascalate.javaflow</groupId>
36-
<artifactId>net.tascalate.javaflow.api</artifactId>
61+
<artifactId>net.tascalate.javaflow.tools.maven</artifactId>
3762
<version>2.7.3</version>
38-
</dependency>
39-
<!-- Add-on for Java 8 and above -->
40-
<dependency>
41-
<groupId>net.tascalate.javaflow</groupId>
42-
<artifactId>net.tascalate.javaflow.extras</artifactId>
43-
<version>2.4.2</version>
44-
</dependency>
45-
...
46-
</dependencies>
47-
48-
<build>
49-
<plugins>
50-
<plugin>
51-
<groupId>org.apache.maven.plugins</groupId>
52-
<artifactId>maven-compiler-plugin</artifactId>
53-
<configuration>
54-
<!-- versions 1.6 -- 17 are supported -->
55-
<source>1.6</source>
56-
<target>1.6</target>
57-
</configuration>
58-
</plugin>
59-
<plugin>
60-
<groupId>net.tascalate.javaflow</groupId>
61-
<artifactId>net.tascalate.javaflow.tools.maven</artifactId>
62-
<version>2.7.3</version>
63-
<executions>
64-
<execution>
65-
<phase>process-classes</phase>
66-
<goals>
67-
<goal>javaflow-enhance</goal>
68-
</goals>
69-
</execution>
70-
</executions>
71-
</plugin>
72-
</plugins>
73-
</build>
63+
<executions>
64+
<execution>
65+
<phase>process-classes</phase>
66+
<goals>
67+
<goal>javaflow-enhance</goal>
68+
</goals>
69+
</execution>
70+
</executions>
71+
</plugin>
72+
</plugins>
73+
</build>
7474
```
7575
Note that if you are using continuations with Java 1.8 lambdas then you need to add [Tascalate JavaFlow instrumentation agent](https://github.com/vsilaev/tascalate-javaflow/releases/download/2.7.3/javaflow.instrument-continuations.jar) at run-time as command-line option, while lambda-related classes are generated by JVM on the fly and there is no other way to instrument them. If this is not an option, then you can de-sugar all lambdas with [RetroLambda](https://github.com/luontola/retrolambda) Maven plugin at build-time (RetroLambda output is supported by Tascalate JavaFlow 2.3.2 or higher).
7676

@@ -82,28 +82,28 @@ There is a separate Ant task for applying JavaFlow instrumentation at build-time
8282

8383
It's possibe to instrument compiled Java classes as below:
8484
```xml
85-
<target name="instrument-classes" description="JavaFlow Instrumentation" depends="compile">
86-
<taskdef name="javaflow" classname="org.apache.commons.javaflow.tools.ant.ContinuableClassesInstrumentationTask"
87-
classpathref="ant-lib-classpath"/>
88-
<echo message="JavaFlow instrumentation of compiled classes in ${classes.dir}" />
89-
<javaflow srcdir="${classes.dir}" destdir="${i-classes.dir}" classpathref="classpath"/>
90-
</target>
85+
<target name="instrument-classes" description="JavaFlow Instrumentation" depends="compile">
86+
<taskdef name="javaflow" classname="org.apache.commons.javaflow.tools.ant.ContinuableClassesInstrumentationTask"
87+
classpathref="ant-lib-classpath"/>
88+
<echo message="JavaFlow instrumentation of compiled classes in ${classes.dir}" />
89+
<javaflow srcdir="${classes.dir}" destdir="${i-classes.dir}" classpathref="classpath"/>
90+
</target>
9191
```
9292
... as well as re-write packaged JAR file:
9393
```xml
94-
<target name="instrument-jar" description="JavaFlow Instrumentation" depends="jar">
95-
<taskdef name="javaflow" classname="org.apache.commons.javaflow.tools.ant.ContinuableClassesInstrumentationTask"
96-
classpathref="ant-lib-classpath"/>
97-
<echo message="JavaFlow instrumentation of compiled classes in ${jar.dir}/${ant.project.name}.jar" />
98-
<javaflow srcdir="${jar.dir}" destdir="${i-jar.dir}" classpathref="classpath"/>
99-
</target>
94+
<target name="instrument-jar" description="JavaFlow Instrumentation" depends="jar">
95+
<taskdef name="javaflow" classname="org.apache.commons.javaflow.tools.ant.ContinuableClassesInstrumentationTask"
96+
classpathref="ant-lib-classpath"/>
97+
<echo message="JavaFlow instrumentation of compiled classes in ${jar.dir}/${ant.project.name}.jar" />
98+
<javaflow srcdir="${jar.dir}" destdir="${i-jar.dir}" classpathref="classpath"/>
99+
</target>
100100
```
101101
You may download a complete [examples project setup](https://github.com/vsilaev/tascalate-javaflow-examples/releases/download/1.0.10/tascalate-javaflow-ant-project-setup1.zip) from [the latest release](https://github.com/vsilaev/tascalate-javaflow-examples/releases/tag/1.0.10) for complete configuration template. Please pay attention to <code>ant-lib</code> folder with Ant TaskDef and <code>lib</code> folders with compile-/runtime-dependencies.
102102

103103
# Java Instrumentation Agent (Runt-time Instrumentation)
104104
As an alternative to compile-time bytecode instrumentation, you MAY use [Tascalate JavaFlow Instrumentation Agent](https://github.com/vsilaev/tascalate-javaflow/releases/download/2.7.3/javaflow.instrument-continuations.jar) from [the latest release](https://github.com/vsilaev/tascalate-javaflow/releases/tag/2.7.3) to enable continuations support at class-loading time. Please note, that if you are using Java 8 and creating continuable lambda functions (either anonymous or/and as method references), and you don't replace them with tools like [RetroLambda](https://github.com/luontola/retrolambda) as mentioned above, then you SHOULD use this instrumentation agent always: as long as Java run-time generates implementation of functional interfaces on the fly there is no other option to instrument them. To enable Tascalate JavaFlow Instrumentation Agent please add the following arguments to Java command line:
105105
```bash
106-
java -javaagent:<path-to-jar>/javaflow.instrument-continuations.jar <rest-of arguments>
106+
java -javaagent:<path-to-jar>/javaflow.instrument-continuations.jar <rest-of arguments>
107107
```
108108
The agent JAR file includes all necessary dependencies and requires no additional CLASSPATH settings. It's recommended to use this agent in conjunction with either Maven or Ant build tools supplied to minimize the associated overhead of the instrumentation during class-loading process at run-time.
109109

@@ -113,20 +113,20 @@ Another useful application of the instrumentation agent is to apply it for debug
113113
It's possible to use a stand-alone command-line utility [JavaFlowRewriteJar.jar](https://github.com/vsilaev/tascalate-javaflow/releases/download/2.7.3/JavaFlowRewriteJar.jar) to instrument JAR archives containing continuable classes. Please use the following command:
114114

115115
```bash
116-
java -jar JavaFlowRewriteJar.jar src1.jar dst1.jar src2.jar dst2.jar...
116+
java -jar JavaFlowRewriteJar.jar src1.jar dst1.jar src2.jar dst2.jar...
117117
```
118118
Note, that the source and the destination should be different files.
119119

120120
# CDI Support
121121
To work correctly in CDI environment continuable methods should be advised only by continuation-aware CDI proxies (interceptors, scope proxies, etc). Obviously, generation of these proxies is out of our control. Plus, major CDI containers (JBoss Weld and Apache OpenWebBeans) generates such proxies dynamically at run-time. Therefore if you plan to use Tascalate JavaFlow continuations with managed beans' methods then it's necessary to instrument CDI-specific proxies with [javaflow.instrument-proxies.jar](https://github.com/vsilaev/tascalate-javaflow/releases/download/2.7.3/javaflow.instrument-proxies.jar) Java Agent:
122122
```bash
123-
java -javaagent:<path-to-jar>/javaflow.instrument-proxies.jar <rest-of arguments>
123+
java -javaagent:<path-to-jar>/javaflow.instrument-proxies.jar <rest-of arguments>
124124
```
125125
Please note, that CDI-specific agent neither requires javaflow.instrument-continuations.jar to operate correctly nor provides class file transformers for continuable methods. So if your project runs with CDI environment AND uses Java 8 lambdas then you have to add 2 Java agents, every serving different purpose:
126126
```bash
127-
java -javaagent:<path-to-jar>/javaflow.instrument-continuations.jar \
128-
-javaagent:<path-to-jar>/javaflow.instrument-proxies.jar \
129-
<rest-of arguments>
127+
java -javaagent:<path-to-jar>/javaflow.instrument-continuations.jar \
128+
-javaagent:<path-to-jar>/javaflow.instrument-proxies.jar \
129+
<rest-of arguments>
130130
```
131131
CDI functionality is tested with JBoss Weld 2.x - 3.1.7, 4.0.x and Apache OpenWebBeans 1.6.x - 2.0.23. Contribution for other CDI/CDI-like containers (Spring, Google Guice, etc) is welcome.
132132

0 commit comments

Comments
 (0)