Merge pull request #367 from l3r8yJ/210

210

Author: yegor256

src/site/apt/example-weaving-gradle.apt.vm

@@ -0,0 +1,82 @@
+ ------
+ Weaving Java Binaries
+ ------
+ Ivan Ivanchuk
+ ------
+ 2024-01-16
+ ------
+
+~~
+~~ Copyright (c) 2012-2024, jcabi.com
+~~ All rights reserved.
+~~
+~~ Redistribution and use in source and binary forms, with or without
+~~ modification, are permitted provided that the following conditions
+~~ are met: 1) Redistributions of source code must retain the above
+~~ copyright notice, the list of conditions and the following
+~~ disclaimer. 2) Redistributions in binary form must reproduce the above
+~~ copyright notice, the list of conditions and the following
+~~ disclaimer in the documentation and/or other materials provided
+~~ with the distribution. 3) Neither the name of the jcabi.com, nor
+~~ the names of its contributors may be used to endorse or promote
+~~ products derived from this software without specific prior written
+~~ permission.
+~~
+~~ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+~~ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING, BUT
+~~ NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+~~ FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+~~ THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+~~ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, CONSEQUENTIAL DAMAGES
+~~ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+~~ SERVICES, LOSS OF USE, DATA, PROFITS, OR BUSINESS INTERRUPTION)
+~~ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+~~ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+~~ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+~~ OF THE POSSIBILITY OF SUCH DAMAGE.
+~~
+## @todo #210:30/DEV Add an integration test
+##  We need to add an integration test that will
+##  show how to work with gradle using show how to
+##  work with Gradle project and jcabi-aspects.
+
+Weaving Java Binaries
+
+  {{{http://en.wikipedia.org/wiki/Aspect_weaver}Aspect weaving}} is a process
+  of modifying binary <<<.class>>> files after compilation in order
+  to inject AOP advice at certain join points.
+
+  First of all, you annotate your classes and methods, and then compile. Then
+  you run AspectJ weaver which modifies <<<.class>>> files, producing
+  new "weaved" versions of them.
+
+  Luckily, these steps can be automated.
+  All you need to do to start using our AOP aspects is
+  add these two artifacts to your <<<build.gradle.kts>>>:
+
++--
+dependencies {
+  implementation("com.jcabi:jcabi-aspects:${latestVersion}")
+}
++--
+
+  Then, you use
+  {{{https://plugins.gradle.org/plugin/io.freefair.aspectj.post-compile-weaving}post-compile-weaving}}
+  plugin which executes AspectJ weaver to modify your <<<.class>>> files:
+
++--
+plugins {
+  id("io.freefair.aspectj.post-compile-weaving") version "${latestVersion}"
+}
+
+dependencies {
+  implementation("com.jcabi:jcabi-aspects:${latestVersion}")
+  aspect("com.jcabi:jcabi-aspects:${latestVersion}")
+}
++--
+  Also, don't forget to mark jcabi dependency as <<<aspect>>>
+
+  {{{./example-weaving-eclipse.html}Additional configuration for eclipse
+  users}}.
+
+  That's it. {{{https://www.l3r8y.ru/2024/01/15/how-to-use-jcabi-aspects-with-gradle}Link to original post}}.