Skip to main content

Using Data Resources to Provide Data

Data resources can add additional configuration to the expansion. The functionality of different data types will be explained below, but first we'll focus on how to add data resource files to the expansion-resource.

note

Due to standard behavior, some plurals are oddly constructed as singular + 's'.

Configuring Data Resources

Let's say we want to add some a new layerImplementation with some libraries. Files necessary will look like this:

src/
main/
resources/
data/
_data.xml
libraries.xml
layerImplementations.xml
pom.xml

The libraries.xml and layerImplementations.xml files contain the actual data, which will be explained below.

The _data.xml file defines which data resource files are present and, most importantly, how they should be read. The content of the file should look like this:

<dataResources>
<dataResource>
<path>data/libraries.xml</path>
<elementTypeCanonicalName>net.democritus.settings.Library</elementTypeCanonicalName>
</dataResource>
<dataResource>
<path>data/layerImplementations.xml</path>
<elementTypeCanonicalName>net.democritus.settings.LayerImplementation</elementTypeCanonicalName>
</dataResource>
</dataResources>

Each record contains 2 things:

  • The path of the resource relative to the root of the jar file, in normal circumstances this is the path within the resources directory.
  • The qualified java name of the element within the file. This will be used at expand time to load the correct Composite and CompositeFactory classes.

If everything went correctly, you should see the dataResources appear in the expansionResource.xml file:

<expansionResource name="org.example:example-expanders">
<version>1.0.0-SNAPSHOT</version>
<expanders/>
<features/>
<additionalExpansionSteps/>
<dataResources>
<dataResource>
<path>data/libraries.xml</path>
<elementTypeCanonicalName>net.democritus.settings.Library</elementTypeCanonicalName>
</dataResource>
<dataResource>
<path>data/layerImplementations.xml</path>
<elementTypeCanonicalName>net.democritus.settings.LayerImplementation</elementTypeCanonicalName>
</dataResource>
</dataResources>
<modelResources/>
<expansionResourceDependencys/>
</expansionResource>

To test if the data has been configured correctly, we can call the validate-data mojo:

  <plugin>
<groupId>net.democritus</groupId>
<artifactId>expanders-maven-plugin</artifactId>
<version>${expanders-maven-plugin.version}</version>
<executions>
...
<execution>
<id>validate</id>
<goals>
<goal>validate-data</goal>
</goals>
</execution>
</executions>
</plugin>

This will try to load the configuration during the maven verify phase to check if the data can be loaded correctly. It might be necessary to add a dependency on prime-data if the data references predefined data (such as standard layerTypes):

<dependency>
<artifactId>prime-data</artifactId>
<packaging>jar</packaging>
<version>2023.0.3</version>
</dependency>
data XML file name

The _data.xml file can be called anything as long as it ends with Data.xml or data.xml and has <dataResources> as root tag.

Data Resource Types

Concern

New concerns can be added as follows:

<concernTypes>
<concernType name="SEARCH ENGINE">
<description>Implements indexing of data and provides advanced search functionality</description>
</concernType>
</concernTypes>

Concern types are purely descriptive and don't add any functional differences.

Technology

By defining a new technology, we can use it in expanders to group all expanders of that specific technology.

E.g. the following

<technologys>
<technology name="APACHE SOLR">
<subdir>solr</subdir>
<concernType name="SEARCH ENGINE"/>
<description>https://lucene.apache.org/solr/</description>
</technology>
</technologys>

Both concernType and description are only there as information for the developers. Subdir will define the name of the sub-directory created for generated and external files for this technology.

LayerImplementation

A layerImplementation encapsulates the expanders, libraries and source-types that together implement a concern in a specific layer with a certain technology.

E.g. we can add a layerImplementation for Solr in the data layer:

<layerImplementations>
<layerImplementation name="Solr Search">
<technology name="APACHE SOLR"/>
<condition>component.getOption('solr.includeSearch').defined</condition>
<layerSources>
<layerSource name="sources">
<sourceType name="SRC"/>
</layerSource>
<layerSource name="resources">
<sourceType name="RESOURCE"/>
</layerSource>
</layerSources>
<layerDependencys>
<layerDependency>
<library name="solr-solrj"/>
</layerDependency>
</layerDependencys>
</layerImplementation>
</layerImplementations>
  • Condition describes when the layerImplementation should be added. This is decided on component level.
  • LayerSources defines which sourceTypes can be included for this technology. It will create a subdirectory for ext and gen in the corresponding layer. The name of the subdirectory is decided by the subdir defined in the technology.
  • LayerDependencies define which libraries should be added to the build. The names refer to instances of libraries, described below.

Library

Libraries can be defined to add them to layerImplementations in order to have them available at runtime or compile time.

<library name="solr-solrj">
<groupId>org.apache.solr</groupId>
<artifactId>solr-solrj</artifactId>
<version>8.4.1</version>
<technology name="APACHE SOLR"/>
<type>runtime</type>
<directory>shared/common/lib</directory>
</library>

Type can be declared as one of the 3 following types:

  • runtime: needed during runtime
  • compilation: only needed during compilation
  • test: only needed during test

Source types

Source types can be defined as follows:

<sourceTypes>
<sourceType name="CONFIGURATION">
<subdir>conf</subdir>
<description>Configuration files</description>
</sourceType>
</sourceTypes>

Subdir defines the directory of the sources.

Resources

In maven, all source types will be added as resources, except for SOURCE or JAVA, which are added as sources.