If you don't remember your password, you can reset it by entering your email address and clicking the Reset Password button. You will then receive an email that contains a secure link for resetting your password
If the address matches a valid account an email will be sent to __email__ with instructions for resetting your password
Novel software visualization tool to display code annotations distribution and usage in java target software.
•
Generates the visualization using a circle packing approach.
•
Web application written in Java, with SpringBoot and TypeScript, with React.
Abstract
The Annotation Visualizer (AVisualizer) is a software visualization tool for displaying code annotations distribution in a given target Java-based software system. Implemented as a web application, it can extract annotations usage from the target source code and display it using a hierarchical circle packing approach. Using a dedicated suite of software metrics, it can display size-related information and code responsibilities associated with annotations usage. The tool provides three different views of the analyzed system, each with different granularity. The AVisualizer is a tool that helps improve code comprehension.
Code annotations are Java programming language feature to configure custom metadata directly on programming elements, such as methods and classes. Since annotations are inserted directly into the source code, they are a convenient and quick alternative to configure metadata. Our study performed in Java open source projects [
] demonstrated that there is a relationship between code responsibility and code annotations.
In this context, the Annotation Visualizer (AVisualizer) is a tool that implements the CADV (Code Annotations Distribution Visualization), a software visualization approach for code annotations defined and validated in our companion work [
]. The CADV uses a circle-packing approach to display code annotations usage and distribution in a Java system under analysis, as well as the underlying hierarchical structure of packages and classes. It also uses colors to differentiate the annotations by their package and groups the code annotations according to the structure of the system under analysis.
] comments that developers spend most of their time comprehending software before adding and maintaining features. To overcome this, one of the main goals of the CADV is to aid in software comprehension through software visualization. We implemented the AVisualizer as a web application. We also extended and developed a plugin integrated with the IntelliJ IDE [
Even though code annotations are a popular feature, we could not find any software visualization approaches or tools focusing on them. The AVisualizer was developed to implement and validate the CADV approach in our companion work [
]. All empirical evaluations conducted for this approach used the AVisualizer web application.
2. Software description
The AVisualizer is a web application divided into two main components: (i) the backend responsible for extracting annotation metrics values from the target project; and (ii) the frontend responsible for rendering the circle packing (the CADV approach) using these metrics values. To render the circle packing, we used the D3.js JavaScript library [
]. Fig. 1 presents the basic building blocks of the AVisualizer. The backend is wrapped as a SpringBoot application, and the frontend is a React application. We configured a maven build to generate a single executable jar file with the application. Information about the build process is available in the public repository.
], seen in the left part of Fig. 1. Our research group developed the ASniffer to collect code annotation metrics from Java source code. These are a suite of 7 metrics that extract code annotations size, complexity, coupling, and annotation schema. They were defined and validated in our previous work [
]. The ASniffer is an independent component used as a dependency in the backend of the AVisualizer.
An annotation schema of a code annotation is an important concept since it greatly influences the frontend of the AVisualizer tool. An annotation-based API, or metadata-based framework, define and expose a set of annotations so application developers can use them to configure programming elements and execute the desired behavior. This set of annotations that define a metadata structure of a given domain for an API is defined as annotation schema [
]. The code in Fig. 2 presents a Java class responsible for executing unit tests using the JUnit 4 framework. The annotations @Test, @After, @Before belong to the package org.junit. In this case, we refer to this annotation set as part of the org.junit annotation schema. In practical terms, an automated approach for extracting the annotation schemas is to identify imported packages for annotations. Another example of a popular annotation schema is the javax.persistence.
2.2 CADV rendering
After extracting the metrics values in the backend, the tool generates a JSON report suitable to serve the frontend module, the right part of Fig. 1. Developed using the React library and D3.Js, it reads this JSON report and builds the CADV visualization.
The CADV comprises three different software visualization views, each displaying the software under analysis in different granularity and scope. The (i) System View displays the complete system and annotations distributed by packages. The (ii) Package View displays a single package (and nested packages) with annotations distributed in the classes of the displayed package. Finally, the (iii) Class View displays a single class and the distribution of annotations in the code elements within this class. The views use colors to differentiate the type and grouping of annotations, i.e., the annotation schema. The size of these circles follows a chosen code annotation metric value. Our companion paper [
project. The navigation bar has a Demonstration option with two other projects the user can display. The AVisualizer has three main areas that convey the information to the user: (i) The Header, (ii) The View, (iii) and The Annotation Schema Table.
The Header contains information to guide the user on what it is seeing and what part of the project it is currently inspecting. It informs what package/class is being displayed, what annotation metric is being used to determine the circle size, and which of the three views of CADV are currently being rendered, i.e., the System, Packge or Class View.
The View is the area that displays the actual visualization, being located below the Header. The System View is the visualization open as a default. Each dashed-line circle represents a package from the source code, and each colored circle represents an annotation, or group of annotations, from a specific annotation schema. Each annotation schema is assigned a color. The user can click on packages (dashed-line circles) or annotations (colored circles) to zoom in. During the zoom process, the visualization is changed to either the Package View or Class View, depending on how far the user is currently exploring. As mentioned, each view has different characteristics that complement each other for completeness in the visualization process. The AVisualizer tool allows navigating between all three views.
The Annotation Schema Table is a table with the annotation schemas found in the project under analysis. It displays the colors assigned to each annotation schema and the total number of annotations from that annotation schema in the project. The tool allows users to select only the annotation schemas they wish to visualize.
The user can visualize their own project by clicking on “Select your project” and informing the path to where the project resides on the local machine. It currently requires a Java project as input, and having a maven or gradle build file is not mandatory.
], code annotations are a popular feature, actively maintained, and helps to understand the role or responsibility of a class or package. Furthermore, languages such as Kotlin, C#, and TypeScript have similar features, reinforcing that this is a popular programming style not only for Java developers.
However, as mentioned, we could not find a tool or software visualization approach that targets the comprehension of how code annotations are used in a project. The visualizations in the literature focus on displaying size, complexity, and cohesion, with the types (classes, interfaces, enums) representing the main elements. Our approach using colors to identify and differentiate annotation schemas, according to our empirical study results [
], allowed developers to identify code responsibilities and architectural roles, not just size or complexity.
The AVisualizer tool is essential to our companion work and helped evaluate the benefits of visualizing code annotations. With the AVisualizer, we could evaluate that visualizing the annotations helps developers further improve their system knowledge, which helps maintenance and evolution. In short, the AVisualizer helped us achieve our primary goal of improving software comprehension through software visualization, focusing on an important language feature neglected by other tools.
4. Limitations and future improvements
The AVisualizer is focused on displaying code annotations, so it is suitable for Java systems that use APIs based on them. Even though they are popular, some Java projects do not use them. In this case, the AVisualizer will not contribute to the comprehension process. On the other hand, web applications are an example of applications that would benefit from our tool since they are notorious for extensively using annotations-based frameworks and APIs, such as Spring, JPA, CDI, etc.
The AVisualizer tool is an ongoing work with different types of limitations. The first one is related to the rendering of the Class View, which presents several low-level details of the class. This limitation comes from the CADV approach and not the tool itself. However, the tool can minimize such limitations by allowing users to choose the information they want in this view. In short, the tool should provide more customization. The other limitation is that there is no way to navigate from the visualization to the source code directly. We will tackle this from the plugin version of AVisualizer available for IntelliJ IDE.
We would like to thank the support granted by Brazilian funding agency FAPESP (São Paulo Research Foundation)
grant 2019/12743-4.
Declaration of competing interest
The authors declare that they have no known competing financial interests or personal relationships that could have appeared to influence the work reported in this paper.
Appendix A. Supplementary data
The following is the Supplementary material related to this article.
00028-3&id=gr1.jpg){kind=link}
00028-3&id=gr2.jpg){kind=link}
00028-3&id=gr3.jpg){kind=link}