JCodeOdor CLI documentation

The CLI relies on JCommander to define the command syntax. It is a library that contains a Java syntax to define some CLI parameters. This CLI syntax is widely used by most of the tools which have a CLI interface. The tool’s syntax is a superset of the syntax specified by the Berkeley Software Distribution (BSD). This syntax is an extension of the Institute of Electrical and Electronics Engineers (IEEE) Standard 1003.1-2001 (“POSIX.1”).

The following code shows the synopsis of the command.

java -jar JCodeOdor-Launcher-1.0-standalone.jar
        [Parameters]
        

java is the JDK command used to start the main method in the byte-code. MetricDetector is the class file which starts the analysis. The way to specify a parameter is to insert a hyphen near the specified value. Parameters are explained in the following.
Some parameters have been designed to accomplish the users’ needs. They are divided in:

• Parser parameters;
• Output parameters;
• DFMC4J parameters.

Parameters may be in any order.

In this subsection, the CLI’s parser parameters are described. Most of them are the same parameters that all Java compilation tools use. This could help the user to understand the CLI’s syntax. In fact, the user is a Java developer and he should know which the Java files, the Jar files and the Java versions are. The parser will start once initialized.

It allows to select the input strategy to give the parameters. This parameter refers only to the parser parameters, in fact there are many ways to store the parsing parameters. For instance, Maven¹⁾ stores the informations in the Pom file. The parameter accepts only the value manualnow, but it will accept various input in the future releases (e.g. input from Maven project). The future releases will probably need some new parameters, such as -root parameter.
The default of this parameter is the manual value. Some examples of this input method are explained in . Some parameters configuration are also shown in the same section.

It represents a list of directories. These directories contain all the Java files that the user wants to analyse. As specified in JCommanderdocumentation, the list’s elements are separated by a space character.
The program will autonomously collect all the Java files stored in the directories, and it will use them to initialize the analysis. The -sourcevalues will be used to set the files path parameter and the source path parameter. The files path refers to all the Java files contained in the source directories, while the source path refers to the directory where the Java files are stored.
The paths could be absolute or relative. The relative path is solved with the position where the command is launched.
-source is the only required parameter: an analysis can’t start without something to analyse.

It represents the list of paths where the libraries are stored. The tool will autonomously collect all the Jar files in the directory if there are some directories among the parameters, else it takes the Jar files. I have designed this parameter to collect all the libraries with only the directory path. This choice helps the user to insert only a path instead all the libraries manually. As the other parameters, the separator is the space character and the path could be absolute or relative to the launching directory.
This parameter could be not instanced if the project doesn’t require a library.

This parameter refers to the project’s encoding. The possible values are described in the JRE documentation. The default of this parameter is the encoding “UTF-8” that is the most used encoding.

This parameter refers to the .properties file. This file must contain the references to the Java libraries.
It allows the user to insert the libraries path only a time in this file, and the user must specify only the desired Java Version. There are three possibilities:

• User doesn’t specify a Java Version: this parameter is not useful and the parser will take the running boot class path;
• User specifies a Java Version, but not a config path: the CLI will search the file in the home directory;
• User specifies a Java Version and a config Path: the CLI will search the file in the given path.

This parameter could be an absolute path or a relative path to the launched directory, as the other path parameters.

It is the compliance version. It refers to the desired Java Version. It accepts all the Java Version String that the user has defined in the .properties file.
The analysis needs the parameters -JV and the .properties file if a cross-compilation analysis is requested. With these parameters, the factory can autonomously take the Java Boot Class Path, and adds the boot libraries to the class path.

The parser will start the parsing with the chosen parameters.

DFMC4J is interested in some parameters that should be decided by the user. The user must be allowed to decide some options for DFMC4J computation.

It is the name of the analysis. It is an identification string in DFMC4J and it is used to give a name to the analysis. It has not particular requirements: you can decide the name you want with all the alphanumeric characters. Parameter’s default is the name of the first source directory.

A user could be interested in deciding the number of threads that will run to compute the analysis. This parameter could be used when the user is interested in some analysis on DFMC4J.
This parameter isn’t required, and it takes the number of processors available to the Java Virtual Machine as default value. The default thread number is often the best choice. This parameter can be set for particular needs, for example to avoid machine overload giving only a processor for the computation.

The analysis must be saved once it has finished. The user must be allowed to decide where to store the analysis and the output type. I have studied three types of output thinking about what the user wants from DFMC4J. In particular, there are two macro-types of outputs: the first is to support the serialization, the second is a dataset format that is widely used in statistic analysis.

This parameter refers to the desired output’s reference. This reference is a particular string which represents where to store the file. The reference can be various and it depends on the output type. For instance, the three types of output implemented at this moment are referenced by the path and the file’s name. But some output type structures could need other ways to select a reference different from the path (e.g. to store the analysis in a remote Data Base). The three output type paths could be absolute or relative to the launching directory, as all the path parameters.
The default of this parameter is the first source path with the name of the project. For example, if the first source path is C:\example the absolute path of the output will be C:\example\example.OutputType. This choice allows a user to not specify this parameter, but it is fine only when the output type requires a path.

The output is divided in three types:

• JavaScript Object Notation(JSON): specifying “JSON” value;
• eXtensible Markup Language(XML): specifying “XML” value;
• SQLite: specifying “SQLite” or “SQL” value.

When a user needs to serialize the analysis, he could use the JSON or the XML outputs. The SQLite output is tabular format. This type of output is typically used for statistical analysis. I explain how the three types of output in are composed.

In this section, some examples of the manual input-type are shown. This is currently the only type of input available, but the tool will manage other input methods (e.g. Maven project). All the input types will define which parsing parameters the tool will use for the analysis, while the DFMC4J and output parameters keep the same behaviour. In fact, DFMC4J has its parameters and the output has its types, so the only parameters that could be managed in various ways are the parsing ones. All the following examples are written with a Windows syntax.

The manual input-type allows many types of setting using the default parameters. The next instruction shows how to launch a simple analysis.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
            -source myProject\mySources
        

The path is relative to the launching directory C:\user, and it is equivalent to give the absolute path C:\user\myProject\mySources. This is a simple analysis with no libraries, default encoding, default boot class path, and default values for DFMC4J. The output file’s extension will be SQLite, and its absolute path will be C:\user\myProject\mySources\mySources.SQLite. In the next example, two source paths are inserted in the command.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
            -source myProject\mySources 
                    C:\user\myProject\mySources2
        

Libraries must be inserted if the project requires them. Let us assume that the libraries are stored in the directory C:\user\libraries. The user will include the libraries path, as shown in the following.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources
           -lib myProject\libraries
        

The parameter -encoding allows to select the project’s encoding. If the project is not written in UTF-8, the chosen encoding must be specified. For example, the encoding is set to KOI8-R in the following command.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources
           -lib myProject\libraries
           -encoding KOI8-R
        

You must create the file .properties if you want a different Java Version for the analysis. You must also specify which Java Version you want with the -JV parameter.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources
           -lib myProject\libraries
           -JV 1.5
        

The CLI will search the configuration file in the home directory if you don’t specify a different path. -config parameter allows to select the path of the configuration file, and it could be absolute or relative to the launching directory as all the path parameters.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources
           -lib myProject\libraries
           -JV 1.5
           -config myProject\

DFMC4J is interested in two parameters: the name of the analysis and the number of the running threads. These parameters take some default. For example, the threads’ number is set to four if Java Virtual Machine has got four available processors and the CLI will call the analysis with the name of the first source path.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources

The analysis will be called “mySources” in the previous example. In the following example, the DFMC4J parameters are set to give one thread and to give the name “myAnalysis” to the analysis.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources
           -analysis myAnalysis
           -threads-number 1

Output parameters are two: -output and -output-type. The first parameter is the reference to the storing position. It depends on the output type and on how this format stores the information. For example, the output reference is an absolute path or a relative path to the launching directory in the three currently supported types, but it will be a Data Base reference string in the case of a particular Data Base storage. The first example uses the default of the CLI.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources

The output type will be SQLite and its path will be
C:\user\myProject\mySources\mySources.SQLite. The output parameters are specified in the next example.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources
           -output-type JSON
           -output myProject\myOutput\myResult.JSON

The output type is JSON and the result will be stored in
C:\user\myProject\myOutput\myResult.JSON. The following example shows how to use all the parameters. The Parameters may be in any order, so it does not matter the order of the parameters.

C:\user> java -jar JCodeOdor-Launcher-1.0-standalone.jar
           -source myProject\mySources 
                   C:\user\myProject\mySources2
           -lib myProject\libraries
           -encoding KOI8-R
           -JV 1.5
           -config myProject\
           -analysis myAnalysis
           -threads-number 1
           -output-type JSON
           -output myProject\myOutput\myResult.JSON

The output format follows a model inspired by the model of DFMC4J. It is based on the Project elements hierarchy:

1. Project: it is the main element where all the project’s components are contained. This concept does not exist in Java, but subsists in the IDEs such as Eclipse or Maven. A Java project represents a view of a project resources in terms of packages, types and methods;
2. Package: it is defined as a container of types. Package has often an architectural logic. Oracle’s Java Tutorial describes it as: “A package is a grouping of related types providing access protection and name space management.”
3. Type: it refers to classes, interfaces, enumerations and annotation types. It is often composed of fields and methods;
4. Method: it is a number of instructions grouped together to perform a specific task.

The CLI computes the metrics from DFMC4J and the smells from JCodeOdor. JCodeOdor gives to the smell an harmfulness index, making the code smells similar to a metric. In fact, smells have a name and a quantitative information in JCodeOdor, and this allows managing smells and metrics as similar elements.

JSON and XML are standards for the serialization of information, often exchanged through the internet. Serialization allows the possibility to send and receive objects over the web’s protocols. The tool uses a simple library to support these outputs. The library does not require particular settings: it just needs the output path and the root class.
The root class is defined as the principal class where the elements hierarchy starts. The analysis is referred to a Java Project, which is conformed to a project elements hierarchy. Each element has a number of metrics, while only the Types and the Methods have smells. The figure shows the class diagram of the model, and it meets the Java Project model.

The output file will result as the project’s hierarchy, with all its informations, included the packages, the Types in the packages and the methods in the Types.

SQLite²⁾ is a software library which implements a Structured Query Language(SQL) database, conformed to the Atomicity, Consistency, Isolation, and Durability(ACID) transaction properties. It allows to store the Data Base in a single file and to query it. SQLite has been chosen for its simplicity and to perform some analysis on a relational database. This output format is very similar to a dataset format which is common in statistical analysis, so it will be familiar and simple to use in a statistical analysis context.

A good design for the Entity Relationship(E/R) diagram is required to allow simple queries. The figure in the end of the section shows the designed E/R. It contains two main entities with some specializations:

• Measure: it refers to a quantitative information for a project’s element. It could be a smell or a metric;
• Measurable: it refers to a project’s element. It could be a Project, a Package, a Type or a Method (See beginning of ).

The relationships have the following meaning:

• Measurable has-a Measure: it means that a Measurable object contains a certain quantity of Measure;
• Measurable parent Measurable: it refers to the project’s hierarchy. For instance, the parent of a package is the project, or a parent of a type is the package which contains it.

The entity “Parameter” is associated to the method’s signature. A method is not unique only for its name and the containing Type. Let us take a class which contains two methods called aMethod. Java allows this if the two methods take several parameters. This feature is called method overload and allows a developer to create a class with a number of methods with the same name and different parameters. The entity “Parameter” allows a user to take all the corresponding parameters, and it also gives the Type’s reference if the Type is in the project. The externalType attribute will be instanced if the type isn’t in the project or in the schema and it is the name of the type(e.g. the primitive type int will be stored as int). The “position” attribute is the position of the parameter in the signature.

I have incorporated the is-a relationship during the logical design. This choice simplifies the query construction because the schema has less tables, but the various types of specialization must be recognizable. So, the tables Measurable and Measures will have a parameter for their type:

• Measurable type could be project, package, type or method;
• Measures type could be smell or metric.

So, the Data Base will have three tables:

• Measurable(:int, type:string, name:string, parent:int REFERENCES Measurable(id))
• Measures(:int, type:string, key:string, value:string, measurable:int REFERENCES Measurable(id))
• Parameters(type:int REFERENCES Measurable(id), method:int REFERENCES Measurable(id), externalType:string, position:int)

shows a view of the schema whose table correlates the method’s parameter with the corresponding project’s type.

CREATE VIEW MethodsAndTypes AS
    SELECT Parameters.type,
    Parameters.method,
    Parameters.externalType,
    Types.parent AS package, 
    Types.name AS type,
    Methods.name AS method, 
    %position%
    FROM Parameters LEFT JOIN Measurable AS Types
        ON Types.id = Parameters.type
    LEFT JOIN Measurable AS Methods
        ON Methods.id = method