See how Java frameworks like Spring work with your code

Spring + Your Code = ❤️ Most of the time!

The one criticism that sticks to the Spring framework (and other big web frameworks, to be honest), is that Spring does so much for you it can be hard to understand what's really going on. Sometimes, we can just follow the doc and tutorials and watch the magic happen. But sometimes, we really need
to understand how Spring, and related packages, actually work. And even more importantly, how they work with our code.

You're already familiar with using debuggers - and Java has an excellent debugger compared to some other languages. When you use a debugger, you take an "inside-out" approach to troubleshooting. You choose a point in your code where you want to start, and then you can explore outwards from
there. But while you can get a lot of detailed information that way, it's hard to build an understanding of what's going on overall in the codebase.

To build that kind of high-level understanding, you need more of an "outside-in" approach. Here's a cookbook you can follow to see how your code works with Spring and other Java libraries, starting from the widest scope and narrowing in on details. To do that, I will show you how to use an open
source tool called AppMap. AppMap records the runtime behavior of your code and stores it as JSON files called AppMaps. Then you can open AppMaps files in your code editor (VSCode or IntelliJ) and view and search dependency maps and execution trace diagrams.

Here's how you use it:

1. Install the appmap-java agent

Follow the quick start guide for VSCode or IntelliJ.
Here's a quick checklist:

• Add the appmap Java agent to your Maven or Gradle configuration - or just download the JAR file from https://github.com/applandinc/appmap-java/releases
• Create appmap.yml and configure your project name and primary package names.

2. Add additional package names, such as org.springframework.web, to appmap.yml

Here's an example appmap.yml that I use with my fork of the Spring Pet Clinic.

3. Record the AppMap of code execution

You have several choices of how to record your code:

Option 1: Test case(s)

If you have JUnit or TestNG tests that cover your app, run your tests with the AppMap Gradle or Maven integration enabled.

Option 2: Record user actions and API requests

If you don't have a test that does what you need, you can use your app and get an AppMap of all the actions you perform. This is called “remote recording,” and to use it, you run your web server with the flag -javaagent:appmap.jar. If your app is an API server, run the server and send API requests. Either way, you'll get an appmap.json file when the server exits.

Option 3: Record the entire server run, including startup and shutdown

The AppMap Java agent supports a System property appmap.recording.auto. If you set this property
to true, the server process is recorded from start to finish, and the results are written to a timestamped appmap.json file when the process exits.

4. View the diagrams

The AppMap extension for VSCode and IntelliJ enables you to open any *.appmap.json and explore it visually. To open AppMaps in the code editor, open the AppMaps “Tool Window” (IntelliJ) or AppMaps sidebar (VSCode).

Click on an AppMap to view the Dependency map in your code editor window. From there, you can search,
browse, and drill down into the Trace view.

Demo - Pet Clinic + org.springframework.web

As I indicated above, AppMap is a flexible tool and there are several ways to use it. Let’s start with a fairly simple, but quite useful and illustrative example.

A Spring Controller is a pretty complex mixture of methods and annotations - even the simple Pet Clinic “OwnerController” has at least 5 different annotations used in multiple different ways. Code like this is powerful, but unlike “normal” procedural or functional code, there’s no information in the code about how the functions are used, how they fit together, or which ones are used in a particular use case.

@Controller
class OwnerController {

    private static final String VIEWS_OWNER_CREATE_OR_UPDATE_FORM = "owners/createOrUpdateOwnerForm";

    private final OwnerRepository owners;

    private VisitRepository visits;

    public OwnerController(OwnerRepository clinicService, VisitRepository visits) {
        this.owners = clinicService;
        this.visits = visits;
    }

    @InitBinder
    public void setAllowedFields(WebDataBinder dataBinder) {
        dataBinder.setDisallowedFields("id");
    }

    @GetMapping("/owners/new")
    public String initCreationForm(Map<String, Object> model) {
        Owner owner = new Owner();
        model.put("owner", owner);
        return VIEWS_OWNER_CREATE_OR_UPDATE_FORM;
    }

    @PostMapping("/owners/new")
    public String processCreationForm(@Valid Owner owner, BindingResult result) {
        if (result.hasErrors()) {
            return VIEWS_OWNER_CREATE_OR_UPDATE_FORM;
        }
        else {
            this.owners.save(owner);
            return "redirect:/owners/" + owner.getId();
        }
    }

    @GetMapping("/owners/find")
    public String initFindForm(Map<String, Object> model) {
        model.put("owner", new Owner());
        return "owners/findOwners";
    }

The org.springframework.web is a package that orchestrates these snippets of Java code based on their annotations.

To get a map of how an Owner request works, I’ll run the Pet Clinic with remote recording enabled, then use the AppMap extension for IntelliJ to create a recording of a web request. This is a bit easier to watch than to explain, so check out the video above for a walkthrough of all this.

To recreate this yourself, check out the appmap-e2e branch of
https://github.com/land-of-apps/spring-petclinic

To record and review your own runtime code maps directly in your code editor, download the free AppMap plugin for JetBrains here: https://plugins.jetbrains.com/plugin/16701-appmap