Japedo User Manual 0.4

Overview

Japedo is a tool for generating documentation of the complete persistence layer of a Java application. It creates documentation of the database scheme as classical database documentation tools do and in addition a full documentation of the JPA layer based on source code analysis. Brought together, it gives complete information about the persistent domain objects, their relations and persistent properties, their representation in the database scheme together with all properties of tables and columns. Together with descriptions of the persistent items the generated documentation is not only interesting for database admins but also for software developers, system analysts and other roles that need to understand the basic principles of the application.

Setup

This tool requires Java version 11 or higher.

The distribution zip contains the Japedo jar library, the license, a configuration file and this user manual. Unzip into a directory and adapt the configuration file japedo.properties as described below. The tool is started with:

java -cp <classpath> com.logitags.japedo.core.Main

with <classpath> including the current directory, japedo.jar and the database driver library, for example:

java -cp .;japedo.jar;h2-1.4.200.jar com.logitags.japedo.core.Main

Configuration properties

Most configuration properties have defaults and are optional.

Property Desciption Default

charset

the charset to be used to parse the sources

UTF-8

classpath

This is an alternative possibility to provide the dependencies of the application by directly providing the classpath.

dependencies

The analysis of the sources require a compilation, therefore the dependencies of the application must be made available to Japedo. Dependencies could be provided in various formats as a semicolon- separated list:

  • a directory of .java files (exploded sources)

  • a directory of .class files (exploded binaries)

  • jar library of the compiled classes

  • jar library of the source files

  • a .war file

  • a directory mixing the above

dbConnectionUrl

The database connection URL. If not set database scheme analysis is skipped and only the source code is analysed.

dbDriverClassName

database driver class name

dbUsername

database user name

dbPassword

database password

dbSchema

the schema name to analyze. Must be defined only when Japedo cannot detect it itself. Newer jdbc drivers can resolve the schema name. If the schema could not be detected and is not given as a configuration parameter an exception will be thrown.

dbNbThreads

number of threads to use for database inspection (default is 4)

htmlFilename

name of the generated html file in targetDirectory

DataReport.html

logLevel

log level (DEBUG, INFO, WARN, ERROR)

INFO

longDescriptionTarget

If entity attribute descriptions don’t fit into the table column, they can be displayed in a POPUP window or in the lower right PANEL.

POPUP

showAttributesOfHierarchy

flag for indicating that the entity attribute table should display also inherited attributes from super classes.

false

sources

the sources of the application as a semicolon- separated list. If not set, JPA analysis is skipped and only database documentation is generated. The source code can be provided in many formats:

  • one or more jar files

  • one or more zip files

  • a directory of .java files (exploded sources)

  • a directory mixing the above

targetDirectory

directory where Japedo will generate the documentation

current directory

timeout

Timeout for the tool in sec. If the tool needs more time to finish the documentation generation, set to -1 or increase this value. If it is set to -1 there is no timeout

-1

Representation

The results of database and Java persistence documentation are represented as one html page in the configured output directory. When displaying this page in a browser it will look similar to the representation of JavaDoc. On the left side are two windows with the general database and Java persistence artefact types in the upper and the special artefacts of the selected type in the lower window.

On the right side are two windows which display the details of a selected artifact. When selecting an artifact in the lower left window, the details will be displayed always in the upper right window. When following links in the upper right window, the respective details are displayed in the lower right window.

Java Persistence Perspective

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

When clicking the Application item, content of all MANIFEST.MF files found in the source directory is displayed. Only relevant attributes of the MANIFEST.MF files are listed like version and names. Additionally, it is possible to add a Japedo-specific property in the MANIFEST.MF ‘Description’ where the application or library could be described in detail. Beware that new lines must start with a space if the description is distributed over more than one line.

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]:

Attribute property Description

ID

This attribute is the unique id of the entity. Normally it is mapped to a primary key column in the database. An entity could have more than one ID attribute.

Generation type

The mode how ID attributes and corresponding columns are set. The following types exist:

  • IDENTITY: Indicates that the value is set using a database identity column

  • SEQUENCE: Indicates that the value is set using a database sequence.

  • TABLE: Indicates that the value is set using an underlying database table to ensure uniqueness.

  • AUTO: Indicates that the persistence provider should pick an appropriate strategy for the particular database.

  • CODE: Indicates that the application is responsible to set a unique value.

Replicated from super class

Indicates that an ID column is replicated from a super class when the inheritance strategy id JOINED and no discriminator column is defined. In this case, JPA expects a primary key column in the child class which contains the same value as the primary key column of the super class. The primary key column in the child class has no corresponding attribute in the entity.

Version

Specifies the attribute of an entity class that serves as its optimistic lock value. The version is used to ensure integrity when performing the merge operation and for optimistic concurrency control.

Enum as STRING/ORDINAL

Defines for attributes of type Enum if the corresponding column contains the name or the ordinal number of the Enum

Temporal as DATE/TIME/TIMESTAMP

Defines for attributes of type Date if the corresponding column contains date, time or timestamp values.

Discriminator values

Specifies the possible values of a discriminator column for the SINGLE_TABLE and JOINED inheritance strategies. The discriminator column has no corresponding attribute in the entity.

Relation

Defines the relation type when the attribute type is a list or map. The following relation types are possible:

  • n:m is a many to many relation

  • n:1 is a many to one relation

  • 1:n is a one to many relation

  • 1:1 is a one to one relation

  • List is a relation to a list of instances of a basic type or embeddable class.

  • Map is a relation to map of instances of a basic type, embeddable or entity class as keys and/or values

Mapped by

Specifies that the relation described in the [Table/Column] column is derived from the target entity specified in the [Type] column. The target entity is the owner of the relation.

Fetch type

Specifies the strategy for fetching data from the database, mostly relevant for relations. EAGER means the attribute values are loaded together with the parent entity. LAZY means the values are loaded only when they are first accessed in the application.

Cascading

Defines the cascadable operations that are propagated to the associated entity(s) in a relation-type attribute. Possible values are PERSIST, MERGE, REMOVE, REFRESH, DETACH

Not optional

Defines that the relation is not optional. A non-null relationship must always exist. If not specified, the relation is optional.

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:

  • The column is in a parent class of the entity

  • A secondary table is defined for the entity and the column is in a secondary table.

  • The attribute is a relation

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

1:1 relations

This type of relation could be mapped to different database implementations:

  • Join table: The join table contains a column that references the owner entity of the relation and a column referencing the target entity. The [Table/Column] column specifies both these columns and the referencing columns in owner and target entities.

  • Foreign key: The foreign key column is in the table of the relation owner. The [Table/Column] column specifies this column and which column it references in the target entity

  • Shared primary key: The primary key of the owner entity is also the foreign key to the target entity. The [Table/Column] column specifies the same column name as the ID attribute referring to the primary key column of the target entity.

n:1 relations

In this kind of relations, the foreign key is on the owning side of the relationship which is normally the n side. The [Table/Column] column specifies the column representing the foreign key and which column it references in the target entity. Same as with a 1:1 relationship, a shared primary key could be used.

n:m relations

Many to many relations have always a join table containing a column that references the owner entity of the relation and a column referencing the target entity. The [Table/Column] column specifies both these columns and the referencing columns in owner and target entities. n:m relations with a map as type are special and described below.

1:n relations

Such relations could be implemented with

  • A foreign key column in the table of the target entity. The [Table/Column] column specifies the column representing the foreign key and which column it references in the table of the owning entity

  • A join table where the [Table/Column] column specifies both the foreign key columns and the referencing columns in owner and target entities. 1:m relations with a map as type are special and described below.

List relations

List relations are lists of either a basic type or an Embeddable. Both cases are implemented using a join table. In the first case the [Table/Column] column specifies the column in the join table that refers to the primary key of the owning entity and the column that contains the basic type. When the list type is an Embeddable, the [Table/Column] column specifies only the column in the join table that refers to the primary key of the owning entity. When the attribute row is expanded by clicking the plus sign, the [Table/Column] column displays the column names for each attribute of the Embeddable.

Map relations

Relations that have in the [Type] column a map as Java type can be of type Map, 1:n or n:m. In the first case, the map value is of a basic type or an Embeddable. 1:n and n:m maps have an Entity as map value. The map key can in any case be of a basic type, an Embeddable, an Enum or an Entity. Such relations are implemented using a join table or by using foreign key columns in the table of the target entity. The [Table/Column] column for map relations specifies mostly three columns:

  • The foreign key to the owner of the relationship referencing the primary key column of the owner entity

  • A key column that holds the map key, labeled with ‘Key’. This column could be a foreign key if the map key is an entity. If the map key is an embeddable, the [Table/Column] column lists the columns for all attributes of the embeddable as keys.

  • A value column that holds the map value, labeled with ‘Value’. This column could be a foreign key if the map value is a (target) entity. If the map value is a (target) entity and the relation is mapped to the entity table instead of a join table, the [Table/Column] column does not contain a value column.

Ordering

OneToMany, ManyToMany and element collection relations can specify an ordering column that is used to maintain the persistent order of a list. The persistence provider is responsible for maintaining the order upon retrieval and in the database. The order column has no corresponding attribute in the entity. In the [Table/Column] column an optional order column is noted with label ‘Ordered by’.

Database Perspective

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

  • Domain Object Tables/Views: map directly to a JPA entity or embeddable. The attributes of the entity or embeddable are mapped to the columns of the table. It is possible that multiple entities map to the same table, for example the members of an entity hierarchy with a single-table inheritance strategy. The mapping entities are listed under ‘Mapping Entities’

  • Association Tables: map to an association between JPA entities or embeddables that use a join table. The participating entities are listed under ‘Associating Entities’

  • Utility Tables/Views: do not map to a JPA entity. They serve other purposes like providing non-normalized views for optimized database queries or managing unique identifier generation.

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.

  • NO ACTION: Delete and Update not allowed. Error message is generated.

  • CASCADE: Foreign key row is also deleted or updated

  • SET NULL: Foreign key is set to null

  • SET DEFAULT: Foreign key is set to its default value. The primary key in the referenced table should also have a default value for this option.