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.
# 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.
com.devonfw.tools.solicitor.lifecycle.SolicitorLifecycleListener
Spring beans implementing this interface will be called at certain points in the Solicitor processing lifecycle. See the Javadoc for details. Implementations should preferably use com.devonfw.tools.solicitor.lifecycle.AbstractSolicitorLifecycleListener as base class which contains NOOP functionality for all methods which might be overridden as required.