jcabi-aspects: cross-cutting behaviour as annotations in Java

The idea in one annotation

The jcabi-aspects module contains a collection of useful AOP aspects, which allow you to modify the behavior of a Java application without writing a line of code.

The readme's example is the clearest possible statement of the trade. If you want to retry HTTP resource downloading in case of failure, you can implement a full do/while cycle yourself, or you can annotate your method with @RetryOnFailure and let one of the AOP aspects do the work for you:

import com.jcabi.aspects.RetryOnFailure;

public class MyResource {
    @RetryOnFailure
    public String load(final URL url) {
        return url.openConnection().getContent();
    }
}

Look closely at what is not in that method. There is no loop, no counter, no exception handling, no delay, no logging of the attempt. The method says what it does and the annotation says what should happen around it. The retry cycle, whatever the aspect decides that means, is entirely elsewhere.

That is the classic argument for aspect-oriented programming, and the project exists to make it available as a set of ready-made concerns rather than as a framework you write your own aspects in. The full list of AOP annotations is in the documentation at aspects.jcabi.com, and the described set includes logging, caching and validation.

The project is Java, its homepage is aspects.jcabi.com, and it is published to Maven Central under the com.jcabi group as com.jcabi:jcabi-aspects, with the Javadoc on javadoc.io.

What the repository actually contains

The top level of the repository is small and mostly configuration, which tells you that the code is not where the complexity lives.

There is a pom.xml, the Maven build, a src/ directory with the aspects themselves, and a README.md. Then there is the machinery that makes this a serious project rather than a weekend experiment.

The .0pdd.yml and .pdd entries relate to PDD, a puzzle-driven development system where issues in the tracker become puzzles to solve. The .rultor.yml is for Rultor, the service that merges pull requests and deploys releases automatically. There is a renovate.json for dependency updates, a REUSE.toml for machine-readable licensing metadata, a LICENSES/ directory, and a LICENSE.txt.

The badge row in the readme gives the rest of the picture. There is a Maven build badge, a PDD status badge, a Javadoc badge, a Maven Central badge, a codecov badge, and two that are unusual. One is a badge stating that EO principles are respected here, which refers to the Elegant Objects principles, a set of design guidelines from the same author that treat every object as a true object with a name and a responsibility. The other is the DevOps By Rultor badge, which is the automation of the release process.

The IntelliJ IDEA badge is a recommendation of the editor, which for a project using AspectJ is not a casual suggestion, because weaving aspects and seeing the effect in an IDE requires the right plugin.

The releases tell you the pace. 0.26.0 with Java 21 support from 2024-02-23, 0.25.1 with a FakeValidationProvider from 2023-05-30, and 0.24.1 from 2022-07-12. The last push was on 2026-10-18, so the code is being worked on even though the last tagged release is a couple of years old.

Building it, and the Qulice profile

The contributing section is short and asks for one thing in particular.

Fork the repository, make changes, submit a pull request, and the project promises to review changes the same day and apply them to the master branch if they look correct.

Before submitting, the readme asks you to run the Maven build:

mvn clean install -Pqulice

The -Pqulice profile is the interesting part, and it is a jcabi convention across their projects. Qulice is their static analysis and quality enforcement tool, and running it as a profile rather than as the default build means the checks are opt-in for contributors but can be run locally before you push. In practice it is closer to a house style enforcement than a suggestion, because a pull request that fails the quality profile will not merge.

The build itself is a standard Maven lifecycle with a single command, and the readme does not document anything else about it, which for a library whose entire surface is annotations is reasonable. There is no application to run, no configuration file to wire up and no service to start. You add a dependency and an annotation.

That simplicity is the point of the project, and it is also why the quality tooling carries so much of the weight. When the code you contribute is a small advice around someone else's method, the only things that can go wrong are the aspects themselves, and the review process plus the static analysis are what keep them correct.

What aspects buy you and what they cost

The value of this approach is easiest to see by imagining the alternative, which the readme spells out for the retry case: implementing a full do/while cycle yourself.

If a dozen classes each need to retry, each of them now carries a loop, a counter, a delay and a log line. That code is duplicated, it is slightly different in each place because it was written at a different time, and it is invisible when you read the method. The aspect version moves all of that into one place and leaves the method readable.

There is a second benefit that is less obvious. Because the concern is applied at the boundary of the method rather than inside it, it applies uniformly. Every method annotated with @RetryOnFailure gets the same behaviour, and a method that is added later and annotated gets it automatically. There is no way for one call site to be missed.

The costs are the well known ones, and a reader evaluating this project should have them in mind. The behaviour of a method is no longer visible in its source, which means understanding what a call actually does requires knowing the annotations and the aspect that implements them. The interception happens at weave time or through a load-time weaver, so the build needs the AspectJ compiler plugin and a different debugging experience. And aspects applied to many methods at once can make a stack trace harder to read, because the frames are not the frames you wrote.

The project's own documentation reflects that balance. The readme points to a blog post on Java method logging with AOP and annotations, and to the full annotation list in the documentation, on the assumption that you need to know what the aspects do rather than discovering it by reading the code of the method you called. The name of the blog post is telling, because logging is the aspect most people meet first and the one where the trade-off is easiest to judge.

The set of concerns the collection covers

The repository description names the areas the aspects address, and it is worth reading that list as a statement of what a team ends up writing by hand.

The description says the collection facilitates aspect-oriented programming patterns: logging, caching, validating, etc. Those three are the classic candidates, and each has a characteristic shape that makes it a poor fit for hand-written code and a good fit for an aspect.

Logging is the obvious one. Every method that does something worth recording wants the same treatment, log the entry, log the exit, log the exception, and the treatment is identical everywhere. The readme points at a blog post specifically on Java method logging with AOP and annotations, which suggests it is the aspect people start with.

Caching has the same character. A cache lookup at the start of a method, and a store at the end, is a fixed shape that you do not want to write ten times, and a cache that is applied consistently is also a cache whose semantics you can reason about. An aspect applies the same policy to every annotated method rather than to whichever ones somebody remembered.

Validation is the third, and it is the one where the aspect pattern has the most to gain, because validation tends to accumulate. Each method grows its own checks, in its own style, and a new field on an input object means hunting down every method that takes that object. A validation aspect moves the rules to one place.

The word etc. in the description is doing real work, and the readme confirms the full list is in the documentation at aspects.jcabi.com rather than in the readme itself. The readme also mentions a FakeValidationProvider in the 0.25.1 release, which is a clue about how the validation side is designed: the provider is an abstraction, so the same validation aspect can be pointed at different implementations.

Editorial conclusion

Adopt jcabi-aspects if you have a Java codebase where the same cross-cutting concern is copy-pasted into many classes, since an annotation moves that concern into one place without changing the method signatures. Do not adopt it as a general logging or caching library, because the value comes from the aspect weaving rather than from any single feature. Before you commit, read the documentation for the annotations you intend to use, because the aspect has to be woven by the AspectJ compiler plugin and the build change is part of the cost.

Frequently asked questions

Official sources

1. Issues
2. jcabi/jcabi-aspects on GitHub
3. Project website
4. README
5. Releases