Appendix D: Extending Solicitor

Solicitor comes with a sample rule data set and sample reporting templates. In general it will be required to correct, supplement and extend this data sets and templates. This can be done straightforward by creating copies of the appropriate resources (rule data XLS/CSV and template files), adopting them and further on referencing those copies instead of the original resources from the project configuration file.

Even though this approach is possible it will result in hard to maintain configurations, especially in the case of multiple projects using Solicitor in parallel.

To support such scenarios Solicitor provides an easy extension mechanism which allows to package all those customized configurations into a single archive and reference it from the command line when starting Solicitor.

This facilitates configuration management, distribution and deployment of such extensions.

Format of the extension file

The extensions might be provided as JAR file or even as a simple ZIP file. There is only one mandatory file which contains (at least metadata) about the extension and which needs to be included in this archive in the root folder.

Listing 72. application-extension.properties
# Sample configuration file for a Solicitor Extension
#
# Version information of the extension
solicitor.extension-artifact = put-name-here
solicitor.extension-version = put-version-here
solicitor.extension-githash = put-buildnumber-here
solicitor.extension-builddate = put-builddate-here

# The Solicitor version range that the extension expects
solicitor.extension-expected-solicitor-version-range=put maven version range here

# Two optional text lines to be printed out when the extension is active
#solicitor.extension-message-1=
#solicitor.extension-message-2=

# source and target location of the optional extension user guide
#solicitor.extension-userguide-source=classpath:solicitor_extension_userguide.pdf
#solicitor.extension-userguide-target=target/solicitor_extension_userguide.pdf

# the URL of the base config file
# uncomment and change if you want to use some other defaults for configuration
# solicitor.base-config-url=classpath:com/devonfw/tools/solicitor/config/solicitor_base.cfg

#############################################################################
## You might override any other values from Solicitors application.properties
#############################################################################

This file is included via the standard Spring Boot profile mechanism. Besides containing naming and version info on the extension this file might override any property values defined within Solicitor.

Any other resources (like rule data or templates) which need to be part of the Extension can be included in the archive as well - either in the root directory or any subdirectories. If the extension is active those resources will be available on the classpath like any resources included in the Solicitor jar.

Overriding / redefining the default base configuration within the Extension enables to update all rule data and templates without the need to touch the projects configuration file.

Activating the Extension

The Extension will be activated by referencing it as follows when starting Solicitor:

java -Dloader.path=path/to/the/extension.zip -jar solicitor.jar <any other arguments>

Java Extensions

It is also possible to extend the functionality of Solicitor within an extension by implementing Spring Beans which implement certain interfaces. As the resources contained in the extension are included into Solicitors classpath those beans might be discovered through the Spring component scan mechanism and thus be activated.

The Spring components scanning mechanisms by default searches only in package com.devonfw.tools.solicitor (and subpackages). You either need to define the extension classes in these packages or create a specific configuration class in this package which has an appropriate @ComponentScan annotation which points to your packages.
Extending Solicitor via Java is an advanced topic. Only the Interfaces given below should be used. Even those should be regarded as unstable and might change without notice. For any details on the interfaces see the Solicitor source code and corresponding Javadoc.
Extension Interfaces
com.devonfw.tools.solicitor.componentinfo.ComponentInfoAdapter

A spring bean implementing this interface might provide ComponentInfo/LicenseInfo data for ApplicationComponents identified by their packageUrl. (The buildin implementation of this interface is reading such component info from scancode result files from the local file system, see Experimental Scancode Integration.) Alternative implementations might e.g. get this information from a corporate server or even a public service available on the internet.

Last updated 2022-11-30 15:22:16 UTC