If your persistence project is a Maven project, the easiest way to integrate Japedo is with the Japedo Maven plugin. This version of Japedo requires Japedo Maven plugin in version 1.3 or higher. Please see the documentation for the configuration.

Most configuration properties have defaults and are optional.

An execution of Japedo can analyse multiple applications/databases at the same time. These are configured in element <applications>. An application must have a unique name and can be either configured by the <java> and/or <database> element or by the <dataFile> element, which defines the full path to the application file of a previous execution of Japedo. The *-app.js file is created in the output directory. In the html page that Japedo creates these applications can then be compared. This may be useful if you want to compare two different installation environments or two release versions of an application.

Java types include application, entities, embeddables, mapped super classes, enums and ID generators.

When clicking the Application item, content of all MANIFEST.MF files found in the source directory and for the dependencies is displayed.

The lists of embeddables and mapped super classes can have duplicate entries because an embeddable could be embedded in more than one entity and mapped super classes can be the parent of more than one entity. Therefore it is mentioned, which entity is embedding an embeddable or is a child of a mapped super class.

Regarding the Enums, only classes that have relevance for persistence are displayed. The details of an enum are simple: it’s just the enum description and the names, ordinal numbers and descriptions of the enum values.

The details of entities, embeddables and mapped super classes include the class hierarchy, the respective main table (or tables if secondary tables are defined) and the names, java types, descriptions, the mapped tables and column definitions and additional properties of the class attributes.

Columns [Name], [Type] and [Description] are self-explaining but columns [Properties] and [Table/Column] need some explanation. In order to fully understand the meanings of these columns a good understanding of the Java Persistence API is necessary.

The following attribute properties are listed optionally in column [Properties]:

The [Table/Column] column contains the defined column name of an attribute. If the column is not in the main table of the entity, the table is additionally specified. A column may not be in the main table in three cases:

While the first two cases are easy to understand, the third case needs more explanation:

The set of effective classes managed by the persistence unit is the union of these sources. In the details of a JPA type it is listed which persistence units manage this type.

The database scheme perspective includes some general database properties, tables, views, their indexes and constraints and sequences. We distinguish three types of tables and views:

For each table/view the columns, indexes and constraints are listed with their corresponding properties. The settings for Delete and Update Rule of foreign key constraints need maybe some explanation. They define what happens to the foreign key when the referenced primary key in the referenced table is deleted or updated.

Even if already about 20 years old, the concept of domain driven design (DDD) by Eric Evans is still popular in the world of microservices and modular components. Many applications are more or less designed following the principles of bounded contexts, entity and value objects and applying a ubiquitous language for naming models. The design perspective tries to give an idea of the application’s design and architecture making use of principles of DDD though the application must not necessarily be built on those concepts. It is meant for designers and software architects who are interested in the overall conception of the business domain. Also for those who know the business, the requirements, the customers, the business rules and processes but lack the technical background this perspective reveals valuable insight. In this category may fall for example project managers, project owners, business analysts and business delivery.

This perspective uses the following assumptions:

By default, the package name is used as the domain name. This could be changed either to give it a more speaking name or to combine several packages in the same domain: In the package, add a package-info.java file and add in the JavaDoc comment a line with

The design perspective presents the entity objects in the sense of DDD. The emphasis lies on the non-technical view of the business domain that is presented by the persistence objects. Only a minimum of technical details is shown and the domain information concentrates on the important domain objects, their attributes, types, descriptions and the relations between them. Please note the following explanations:

Each detail view of a table or JPA types includes a graphical representation. For a table the tables related by a foreign key constraint are also displayed. For JPA types, the class hierarchy and the directly associated JPA entities and Enum types are displayed. Clicking on a table or entity title with mouse click or Alt key + mouse click opens the details view of the item.

The application and database overview diagrams include in addition the graphical representation of the complete persistence layer and database structure. These graphics can be zoomed and panned. For the overview diagrams there is a button to display a rectangle which can be used to magnify parts of the diagram. The size and scaling of the rectangle can be modified and it can be dragged around with the mouse. The part of the diagram outlined by the rectangle can be cut (use the Alt key to display the cut part in the lower window). The cut diagram sections can then be downloaded. The following overall diagrams are shown:

The complete picture of application persistence is obtained when database properties are studied together with corresponding domain object and JPA properties. For this purpose, table columns can be directly linked with JPA entity and domain object attributes. The three types are distinguished by their colors:

Linking database columns with corresponding entity attributes is the most complicated linkage because it is a 1 to 0..n relationship. A column can have zero, one or many links to entity attributes.

The default case is visible in the example application with table CIB_CONTROLLABLE: When clicking the link icon of a column, it is highlighted together with its corresponding entity attribute. This is the one-to-one relationship.

One example of a one-to-many relationship can be seen in table CIB_ARCHIVE: When clicking the link icon of column ARCHIVEID, two attributes of the Archive entity are highlighted. This is because the primary key of Archive is at the same time the foreign key to the Resource entity which is mandated by the @PrimaryKeyJoinColumn annotation.

Another example of a one-to-many relationship is in table BOOK2: When clicking the link on column ID, two lines in the Book2 entity are highlighted. The primary key column from table PUBLICATION is duplicated in table BOOK2 because the inheritance strategy is JOINED. In the entity, however the attribute is not duplicated.

There are many other situations, where one column is mapped to multiple entity attributes, for example:

The last point needs some more explanations: When an entity hierarchy is mapped to a single table (InheritanceType = SINGLE_TABLE) the columns of this table can be mapped to the different entities in this hierarchy. When clicking the link icon, the entity must therefore be selected to which the column shall be mapped. In this case, a dialog pops up which lists the possible entities which map the column. The entity can also be selected before clicking the link icon from the table’s list of mapped or associated entities.

Some columns do not have a corresponding entity attribute. This is the case for example for columns of utility tables like a table for generating sequences. Order columns of one-to-many relations (annotation @OrderColumn) also do not have a relation to an attribute.

The mapping from Jpa attributes to the corresponding columns is a 1 to 1..n relationship. The normal mapping is that an attribute maps to one column. In case of an attribute that represents an entity association which is mapped in an association table, both foreign key columns are mapped to that attribute. When an entity defines an order column (annotation @OrderColumn) for a Collection-type attribute, the order column is also mapped to that attribute. Another example for a 1 to n mapping is for attributes of Map type. In this case the foreign key column, the map value column and the map key column are mapped to that attribute if they are all in the same table.

Japedo can detect errors, mismatches between Java implementation and database, non-compliances to the JPA specification and many other flaws and disregards of common persistence rules and conventions. These are listed in the issue report with CRITICAL, MAJOR and MINOR error level. BLOCKER issues prevent Japedo from execution and are listed already in the execution log. The issue message contains links to the Java class or database table that produced the issue. The details view of the listed issues contain a more detailed explanation and a possible solution to the problem.

Issues that will not be fixed or are false-positives can be ignored so that they do not appear anymore on the issue report. To achieve this, set the unique issue number in property 'ignoredIssues' of the configuration file.

If more than one application is configured in japedoConfig.xml or in the Maven plugin Japedo compares the different databases and Java applications. An application can be a specific deployment installation of an application, for example in production and test environment or a specific release version of an application. With the Japedo Maven plugin the application version can be configured and the version is downloaded from the distribution repository. It is also possible to configure only databases or only sources in a application, then only the databases or sources are compared.

After execution of the Japedo analysis, the compare functionality can be accessed from the main menu of the generated html page. The compare page displays differences for database and Java source separately. For database differences, the table and column/constraint/index where a difference has been detected are listed. If a table/column/constraint/index is present in one database scheme and not in the other the entry lists where it is present and where not. The column 'Modified property' is empty in this case. If a property of a table/column/constraint/index differs, the column 'Modified property' is set and the entry lists the different properties.

Similarly the differences in the Java sources are listed with information about classes and class attributes present or not and the differing values of class or attribute properties.