MapMaid - Documentation

MapMaid is a modern mapping framework in the scope of mapping data in Json, XML, or YAML format into DTOs composed and vice versa.

License

License

Categories

Categories

Ant Build Tools
GroupId

GroupId

de.quantummaid.mapmaid
ArtifactId

ArtifactId

documentation
Last Version

Last Version

0.9.44
Release Date

Release Date

Type

Type

jar
Description

Description

MapMaid - Documentation
MapMaid is a modern mapping framework in the scope of mapping data in Json, XML, or YAML format into DTOs composed and vice versa.
Project Organization

Project Organization

Richard Hauswald

Download documentation

How to add to project

<!-- https://jarcasting.com/artifacts/de.quantummaid.mapmaid/documentation/ -->
<dependency>
    <groupId>de.quantummaid.mapmaid</groupId>
    <artifactId>documentation</artifactId>
    <version>0.9.44</version>
</dependency>
// https://jarcasting.com/artifacts/de.quantummaid.mapmaid/documentation/
implementation 'de.quantummaid.mapmaid:documentation:0.9.44'
// https://jarcasting.com/artifacts/de.quantummaid.mapmaid/documentation/
implementation ("de.quantummaid.mapmaid:documentation:0.9.44")
'de.quantummaid.mapmaid:documentation:jar:0.9.44'
<dependency org="de.quantummaid.mapmaid" name="documentation" rev="0.9.44">
  <artifact name="documentation" type="jar" />
</dependency>
@Grapes(
@Grab(group='de.quantummaid.mapmaid', module='documentation', version='0.9.44')
)
libraryDependencies += "de.quantummaid.mapmaid" % "documentation" % "0.9.44"
[de.quantummaid.mapmaid/documentation "0.9.44"]

Dependencies

compile (3)

Group / Artifact Type Version
de.quantummaid.mapmaid.integrations : mapmaid-all jar 0.9.44
javax.validation : validation-api jar 2.0.1.Final
org.hamcrest : hamcrest-all jar 1.3

provided (1)

Group / Artifact Type Version
org.projectlombok : lombok jar 1.18.12

test (5)

Group / Artifact Type Version
org.junit.jupiter : junit-jupiter-api jar 5.6.2
org.junit.jupiter : junit-jupiter-engine jar 5.6.2
com.sun.mail : javax.mail jar 1.6.2
com.google.code.gson : gson jar 2.8.6
com.thoughtworks.xstream : xstream jar 1.4.12

Project Modules

There are no modules declared in this project.

Last Commit Maven Central Code Size License Slack Gitter Twitter

quantummaid-java-standards

Contains the Java quality standards for QuantumMaid projects.

Usage

Replace the top section of your pom.xml with the following:

<!--
  ~ Copyright (c) 2020 Richard Hauswald - https://quantummaid.de/.
  ~
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>de.quantummaid</groupId>
        <artifactId>quantummaid-opensource-parent</artifactId>
        <version>0.9.24</version>
    </parent>

Also make sure that the README.md of the project clearly recommends the usage of the pgpverify-maven-plugin by providing the link https://youtu.be/ES9hWkn_WBA?t=27m29s. It can be found under https://www.simplify4u.org/pgpverify-maven-plugin/ (usage instructions).

Checkstyle

Checkstyle is enabled after using this POM as parent in a Maven project. It is executed before tests are run.

Registering Checkstyle suppressions

Add the following to your pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
        ...
    <properties>
        ...
        <checkstyle.suppressions.location>
            ${project.basedir}/src/test/checkstyle/checkstyle-suppressions.xml
        </checkstyle.suppressions.location>
    </properties>
    ...
</project>

Create a suppression configuration file under /src/test/checkstyle/checkstyle-suppressions.xml with the contents of your choice based on the following example:

<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ Copyright (c) 2020 Richard Hauswald - https://quantummaid.de/.
  ~
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<!DOCTYPE suppressions PUBLIC
        "-//Puppy Crawl//DTD Suppressions 1.1//EN"
        "http://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
<suppressions>
    <suppress checks="VisibilityModifier" files=".*AggregatedValidationException.java" />
    <suppress checks="IllegalCatchCheck" files="NamedMethodSerializationCPMethod.java" />
    <suppress checks="IllegalCatchCheck" files="Deserializer.java" />
</suppressions>

The checkstyle step can be skipped for a run with -Dcheckstyle.skip.

IntelliJ IDEA integration

Install the CheckStyle-IDEA plugin. Afterwards, open Settings -> Other Settings -> Checkstyle and add a new Checkstyle configuration file, name it QuantumMaidOpenSource and use https://raw.githubusercontent.com/quantummaid/quantummaid-opensource-parent/master/checkstyle/checkstyle.xml as a URL location.

Spotbugs

Spotbugs is enabled after using this POM as parent in a Maven project. It is executed before tests are run.

Registering Spotbugs exclusions

Add the following to your pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
        ...
    <properties>
        ...
        <spotbugs.excludeFilterFile>
            ${project.basedir}/src/test/spotbugs/spotbugs-exclude.xml
        </spotbugs.excludeFilterFile>
    </properties>
    ...
</project>

Create a suppression configuration file under /src/test/spotbugs/spotbugs-exclude.xml with the contents of your choice based on the following example:

<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ Copyright (c) 2020 Richard Hauswald - https://quantummaid.de/.
  ~
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<FindBugsFilter
		xmlns="https://github.com/spotbugs/filter/3.0.0"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd">
    <Match>
         <Class name="de.quantummaid.someClass"/>
         <Method name="aSpecificMethod"/>
         <Bug pattern="RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE"/>
    </Match>
    
    <Match>
         <Class name="de.quantummaid.differentClass"/>
         <Bug category="PERFORMANCE"/>
    </Match>

</FindBugsFilter>

More information about exclusions can be found on the spotbugs website.

IntelliJ IDEA integration

Install the Findbugs-IDEA plugin.

Compiler

The compiler is configured for all child projects and should not be modified in any of the child projects of this POM. Following this recommendation provides child projects with the following benefits:

  • Encoding and Java version of the sources and compiled classes are managed
  • A configuration bug fix, that will prevent the maven-compiler-plugin from swallowing compilation errors and hence failing with 'unknown compilation error'
  • Building the child project in Intellij IDEA will be possible with warnings
  • Building the child project using maven will be possible with warnings, if built with -DskipTests=true
  • Testing the child project using maven will be possible with warnings, if built with -Dmaven.compiler.failOnWarning=false
  • Building/Testing the child project will fail, if the source code is causing compiler warnings
  • Releasing the child project will fail, if the source code is causing compiler warnings

Skipping tests

Just run the Maven command with -DskipTests=true.

Long running tests, that should be executed before every release, but not on every verify

Surefire will set a system property testMode to either NORMAL or RELEASE depending on the active profile.

In the test, an if statement can be used:

final Boolean runThisTest = Optional.ofNullable(System.getProperty("testMode")).map(s -> s.equals("RELEASE")).orElse(false);
if (runThisTest) {
    //test you long running stuff
} else {
    System.out.println("Skipping this test, since system property testMode is not set to RELEASE");
}

Releasing a version to Maven Central

The problem with releasing to Maven Central using a CI/CD pipeline is complicated, since both, the nexus staging account and the gpg key must be kept private. If an attacker gains access to one or both of these credentials users of our open source products are in grave danger (https://youtu.be/ES9hWkn_WBA?t=27m29s). A bitbucket pipeline can output secure environmental variables with some neat tricks. Since we would need to store both valuable credentials as such, that operation can only be done manually outside the GitHub cloud environment:

  • Ensure the gpg private key with the id 0xACB977BA5C6D5C6E installed in the gpg key store.
  • Ensure the maven settings.xml file contains the following section:
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
	...
	<servers>
		<server>
			<id>quantummaid.opensource.sonatype.staging</id>
			<username>the username of the sonatype nexus staging account</username>
			<password>{the encrypted password of the Sonatype nexus staging account created using mvn --encrypt-password}</password>
		</server>
	</servers>
	...
</settings>
  • Ensure the project version has been set to the appropriate value
  • Run the following command to test the project:
mvn clean verify
  • run the following command to release the project in case the tests passed:
mvn -DdeployToMavenCentral -DskipTests=true clean deploy

Excluding modules from being released to maven central

Sometimes a project needs a (test-)module that is not supposed to be released as an artifact to Maven Central. This is complicated because the nexus staging plugin will only deploy to staging if the last module of a multi modules build is actually one that is supposed to be released. Especially test modules tend to be the last ones built and are not to be deployed, so disabling the staging plugin in these modules will essentially end up in the whole project not being released to staging. In these cases two profiles will do the trick. One that is called development, which includes ALL the modules and is activated on the missing property named deployToMavenCentral. The other profile is called deployToMavenCentral, contains only the modules that are intended to be released to maven central and is activated on the presence of the property named deployToMavenCentral. Example:

<profiles>
    <profile>
        <id>development</id>
        <activation>
            <activeByDefault>false</activeByDefault>
            <property>
                <name>!deployToMavenCentral</name>
            </property>
        </activation>
        <modules>
            <module>core</module>
            <module>integrations</module>
            <module>tests</module>
        </modules>
    </profile>
    <profile>
        <id>deployToMavenCentral</id>
        <activation>
            <activeByDefault>false</activeByDefault>
            <property>
                <name>deployToMavenCentral</name>
            </property>
        </activation>
        <modules>
            <module>core</module>
            <module>integrations</module>
        </modules>
    </profile>
</profiles>

The reason for having a prepareForMavenCentral profile

The prepareForMavenCentral and deployToMavenCentral include the exact same configuration except a excluded modules. To apply all plugins, checks and verifications on all modules and not only the released ones, the prepareForMavenCentral profile is used.

Coverage reports in multi-module projects

Multi-module projects need to contain a special module coverage that directly depends on all modules for which coverage needs to be reported, i.e. all modules that contain code. A transitive dependency is not sufficient. The module needs to contain this plugin section:

   <build>
        <plugins>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.5</version>
                <executions>
                    <execution>
                        <id>report-aggregate2</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>report-aggregate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

All modules need to contain a property to point sonar to target/site/jacoco-aggregate/jacoco.xml in the coverage module. This has to be a relative path that needs to be tweaked to point to the coverage module, depending on the module it is declared in. Example:

    <properties>
        <sonar.coverage.jacoco.xmlReportPaths>../coverage/target/site/jacoco-aggregate/jacoco.xml</sonar.coverage.jacoco.xmlReportPaths>
    </properties>

Running sonar

The sonar plugin requires an access token to be set using the SONAR_TOKEN env variable.

Then the sonar plugin can be run with:

mvn verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -P sonar
de.quantummaid.mapmaid

QuantumMaid

The Java framework to export your domain logic without breaking clean architecture or introducing tedious configuration.

Versions

Version
0.9.44
0.9.43
0.9.42
0.9.41
0.9.40
0.9.39
0.9.38
0.9.37
0.9.36
0.9.35
0.9.34
0.9.33
0.9.32
0.9.31
0.9.28