Javapackages-validator

Javapackages-validator is a tool used to test RPM files. It executes checks implemented as Java classes over the set of provided RPM files.

Building

The project is built with Maven. JDK of version 22 is required. Simply run:

$ mvn install

Usage

The tool is executed from command line using java command with the proper class path. JVM of version 22 is required.

Main [optional flags] <main arguments>... [-f RPM files or directories to test]...

Note	Due to the usage of the Foreign Function & Memory API feature, JVM arguments must include: --enable-native-access ALL-UNNAMED.

Optional flags

-h, --help	Print help message.
-x, --debug	Display debug output.
-r, --color	Display colored output.

Options for specifying validators

-sp, --source-path	Additional .java source file or directory.
-d	Output directory for the compiled source files.
-cp, --class-path	Additional class path entry for the validators.

Main arguments

test name	The test name of the test that shall be executed.
validator factory	A fully-qualified-name of a ValidatorFactory to use for test discovery.

Options for specifying tested RPM files, can be specified multiple times

-f, --file

File path of an RPM file or a directory.

RPM files

The parameters specifying RPM files can either be RPM file paths or directories. In case of directories, the tool recursively searches for RPM files found inside.

Main arguments

There are two types of main arguments as was shown.

test name

The test name must start with a /. It can be immediately followed by space-separated square parentheses the contents of which will be passed as arguments to the validator. If no test name is provided, then all discovered tests are executed.

validator factory

The validator factory must be present on the class or source path. The validator provides a built-in class
org.fedoraproject.javapackages.validator.validators.DefaultValidatorFactory.

Validator arguments

The tool recursively finds all .java files present in the source path directory, compiles them and places the results under the path specified as the class path. Class path may already exist and contain .class files, this is useful to implement caching. The entries on this class path are used to add additional validator classes to the tool.

Compiler configuration

The directory pointed to by the --source-path can contain file javapackages-validator.properties, which is loaded as a standard Java properties file and is used to configure compilation. It can contain the following fields:

compiler.release

The value of this field is passed to Java compiler as --release argument. Defaults to 22 if not set.

dependencies

Specifies extra dependencies to add to class path, in addition to --class-path. Defaults to no extra dependencies. The format of the field is a space-separated list of coordinates of Maven artifacts, where each coordinate is in format of <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>. Only artifacts listed explicitly are added to class path — transitive dependencies are not resolved.

repositories

Specifies extra Maven repositories to use for dependency resolution, in addition to Maven Central repository. Defaults to no extra repositories — only Maven Central is used by default. The format of the field is a space-separated list of URLs of Maven repositories. Only URLs with protocol schemes http and https are supported.

Recompilation

If the directory pointed to by the --class-path parameter exists, then the tool searches for files inside and inspects their modification time. Recompilation is caused by any of these conditions:

• Class path directory is empty.

• Any regular file present on the class path is older than any file present on the source path

• Any directory on the class path has been modified after the latest modification time of any regular file present on the class path. (This can mean that some .class files were deleted from the class path.)

Recompilation causes the class path directory to be cleaned before the newly compiled classes are placed there.

Service file

The file META-INF/services/org.fedoraproject.javapackages.validator.spi.ValidatorFactory is a standard Java service file. It contains a line-separated list of validator factory class names which are available to be executed. This file will be copied from the source path to the class path and is expected to be present on the class path if source path is not specified.

The validator main arguments passed to javapackages-validator must exactly match one of the test names listed in either the service file or the service file on the built-in class path.

Example

$ Main /test-no-args -f file.rpm
$ Main package.name.CustomValidatorFactory /test-with-args [ arg1 arg2 'arg 3' ] -f file.rpm

tmt

The tool contains another main class MainTmt which is intended to be invoked from within tmt tests. When the validator is run from the tmt entry point, it requires the environment variables TMT_TEST_DATA and TMT_TREE to be defined.

Test execution from this entry point is configured using a configuration file named javapackages-validator.yaml. This file can be located either in the root, i.e. the value of the TMT_TREE variable or in the plans directory of the project.

Every validator has an associated test name. This is the result of the virtual getTestName function. This name must be in the format of tmt tests, i.e. starting with /. Test names are used for test selection, exclusion and to create report files.

Configuration

The following fields are allowed in the YAML configuration file.

Fields starting with /

The key is a tmt test name. The value of the field must be a list of strings. It will be passed as the arguments to the according validator.

exclude-tests-matching

The value of this field is a list of strings. The strings must be valid Java regular expressions. If any of these patterns matches the test name of a validator, it will be skipped.

Example of javapackages-validator.yaml configuration file

/java/bytecode_version: [":52"]
exclude-tests-matching:
  - "/java/.*"

Result

The tool generates both .log and .html reports with filenames matching the validator test names. These files are placed in the directory ${TMT_TEST_DATA}/results.

Custom validators

A custom validator must implement the org.fedoraproject.javapackages.validator.spi.Validator interface. The interface consists of the following methods.

String getTestName()

This is used to obtain the tmt test name as explained in the tmt section.

Result validate(Iterable<RpmPackage> rpms, List<String> args);

This is the main function of the validator. The validator is executed on a collection of RPM files and is given a list of arguments producing a Result.

Producing a result

A Result is effectively a collection of log entries and a final test result. There is a helper class ResultBuilder to ease producing results. User code is expected to call functions debug, skip, pass, info, warn, fail, error and produce the final result object using the build function. These functions internally produce LogEntry objects with the formatted message.

Log events

debug

This event serves to produce verbose internal information that is not visible by default and serves to ease debugging of the validators themselves.

The other log events correspond to the following result states.

Result states

Each Result has a single result state. The starting state is skip. The state is overriden by calling corresponding methods of the Validator class. The state listed lower in the following hierarchy overrides the previous states but not vice-versa.

Result states

skip	A check was expectedly skipped because the validator determined so. This can also mean that the property being tested was not present in the RPM under test.
pass	Validation was run successfully and all the checks that were executed passed.
info	The validator found a potential issue which does not affect validation results, but might be worth checking and fixing.
warn	The validator found an issue that might be a false-positive and therefore requires further human review.
fail	At least one check failed.
error	An error occured, for example invalid input or an unexpected state.

Invoking custom validators

If the user wants to run the tool with custom validators provided as .java or class files, they need to be present on the source path or the class path.

Examples of a custom factory and a custom service file follow.

Custom validator factory ValidatorFactoryCustom.java

package org.fedoraproject.javapackages.validator.validators.custom;

import java.util.List;

import org.fedoraproject.javapackages.validator.spi.Validator;
import org.fedoraproject.javapackages.validator.spi.ValidatorFactory;

public class ValidatorFactoryCustom implements ValidatorFactory {
    @Override
    public List<Validator> getValidators() {
        return List.of(new Validator[] {
                // ...
        });
    }
}

Custom validator service file org.fedoraproject.javapackages.validator.spi.ValidatorFactory

org.fedoraproject.javapackages.validator.validators.custom.ValidatorFactoryCustom