Maven Integration
ApiOmat uses full Maven integration for native module lifecycle, which contains automatic tests, dependency management and the module deployment itself.
Every module contains a pom.xml skeleton with preconfigured lifecycles for your specific module. Starting with version 3.3, ant was completely replaced with our own maven plugin.
Module Deployment
Module deployment can be done directly using the plugin and providing some necessary config values:Bash
mvn clean package nm:upload -DcustomerPassword=doe -DcustomerName=john -Dhost=http://my.apiomat-instance.comMore about all possible goals and configurations can be found at the plugin documentation.
Actually, the only part which is modified in the pom.xml are the dependencies. Read more about that in the next paragraph.
For Git Modules
As there is no "upload" for git modules, you can adapt the lifecycle to your needs.
ApiOmat comments out the part which executes the Ant task in the initial pom.xml file for the module and adds another part that will request the "trigger pull from git" url when you run mvn install. If you change the branch or password at ApiOmat, the change won't currently be reflected in your pom.xml and you have to change it manually.
We also provide the Ant based way (as commented out code) in the pom.xml for Git based modules to let you choose which way to use, for example if you want to deploy the module as Ant based module on another server.
Dependency Management
One of the probably most useful features of Maven is its dependency management.
You can add the necessary dependencies to the pom.xml and Maven downloads them automatically from a remote repository, like Maven Central, adds them in your project and - in our case - also to the lib folder of your modules.
In the package phase Maven copies the dependent libraries to the lib folder of your module, as they're actually needed in the module before it gets uploaded to ApiOmat.
This excludes libraries with the scopes "test" and "system", as the former isn't necessary in your uploaded module and the latter should already be contained in your lib folder.
Maven does not create an uploadable artifact during the package phase. Maven will create a "slim jar" by default. If you have our nm-maven-plugin in your pom.xml and bound to the package phase, as described here, you'll also get the correct artifact during the package phase. In .that case, you'll have a moduleName-moduleVersion.jar (f.i. "JDBC-1.0.0.jar") and a moduleName-moduleVersion-NM.jar (f.i. "JDBC-1.0.0-NM.jar) after packaging contained in the target folder. The first artifact is the normal output of maven, which can be used f.i. as used module library and the second artifact (with the -NM suffix) is the real artifact you can use for upload.
Also note that it's necessary to upload the module with Maven if you added new dependencies to your pom.xml.
After up- and downloading the module (which the goal nm:update does automatically), your pom.xml will also have been updated.
ApiOmat processes the dependencies part in your pom.xml. It adds any libraries contained in your lib folder (and its subdirectories) to the dependencies section, each with system scope and path. The existing dependencies with system scope are removed and dependencies with any other, or unspecified scope left unchanged.
For modules created prior to 2.3.9, 2.4.9 or 2.5.2
Due to changed behavior in later versions of the maven-dependency-plugin, which copies the dependencies and libraries to the lib folder of your module, we encourage you to pin the version of the plugin to 2.1. Otherwise, libraries without version information in file name (such as used modules) will be copied to the lib folder by the plugin, using the default version "1.0.0" (e.g. JDBC.jar will be added again as JDBC-1.0.0.jar). This will lead to unforseen behavior, as ApiOmat may use the old and outdated files in the jar file with version in name. Please remove these duplicated libraries. ApiOmat versions after (including) 2.3.9, 2.4.9 and 2.5.2 will deliver a pom.xml file in the modules that have these plugin version pinned. The pom.xml file of existing modules won't be updated automatically and you'll have to do this manually.
After a while you may want to clean up your dependencies, as some of the libraries are contained twice in the modules pom.xml, due to the described behaviour. Once as unscoped "normal" Maven dependency, which you've added, and once as system scoped dependency with a path to the lib folder. This generally won't have an impact, but would be better for reasons of clarity to remove the unscoped dependency.
We're planning to provide a deeper integration of Maven in future versions, which will support the dependency resolution through remote Maven repositories, like Maven Central or even your own Maven repository.
For Git Modules
As mentioned before, there's currently no server-side dependency resolution, but you can locally add the necessary dependencies normally to your pom.xml file and run the mvn package task to copy the dependencies to the lib folder and push them to your Git repository.
Unit Tests
The delivered pom.xml is preconfigured so that the Maven Surefire Plugin (which runs the tests in the Maven lifecycle) searches for your simple unit tests in a folder named test in the root of your module directory. As these files are not contained in the source folder src, they also won't be uploaded (which will otherwise lead to compile errors). If you want to have integration test for your modules, please follow our Integration Test Structure Recommendation Guide.