Adapters as Apache Maven projects

When you use Maven projects to create, deploy, test, and configure adapters, you benefit from Maven's simple project setup, efficient dependency management, and supported IDEs, such as IntelliJ and Eclipse.

Maven repositories

Up-to-date Maven artifacts that support MobileFirst adapters are available at The Central Repository under the GroupId com.ibm.mfp. When you build a Maven project, Maven checks your pom.xml file to identify which dependency to download.

If your organization does not permit online access to The Central Maven Repository, your administrator must set up a local repository to hold and share MobileFirst artifacts. For more information, see Setting up an internal Maven repository for offline development.

Java adapter Maven projects

When you create a new Java™ adapter, a Maven project with the following structure is produced:

Figure 1. Java adapter Maven project
This figure shows the structure of a regular Java adapter.
  • pom.xml: The Maven Project Object Model (POM) file is in the root folder. It contains references to the adapter-maven-api, adapter-maven-plugin, and mfp-security-checks-base adapter artifacts that were developed by MobileFirst. For more details, see Maven adapter artifacts.
  • adapter.xml: The adapter-descriptor file is under src/main/adapter-resources. For more details, see The Java adapter-descriptor file.
  • <package>: Java package that contains the JAX-RS application and all the source files that it needs. They are located under src/main/java/. For more details, see Implementing the JAX-RS service of the adapter.

JavaScript adapter Maven projects

When you create a new JavaScript adapter, a Maven project with the following structure is produced:

Figure 2. JavaScript adapter Maven project
This figure shows the structure of a regular JavaScript adapter.
  • pom.xml: The Maven Project Object Model (POM) file is in the root folder. It contains references to the adapter-maven-api, adapter-maven-plugin, and mfp-security-checks-base adapter artifacts that were developed by MobileFirst. For more details, see Maven adapter artifacts.
  • adapter.xml: The adapter-descriptor file is under src/main/adapter-resources. For more details, see The JavaScript adapter-descriptor file.
  • <adapter-name>-impl.js: Contains the JavaScript source files.

Maven adapter artifacts

MobileFirst adapters contain three main artifacts, which are referenced in the pom.xml file:

Maven adapter API

adapter-maven-api contains the MobileFirst code and third-party dependencies that the adapter needs to compile properly.

Maven adapter plug-in

adapter-maven-plugin is a Maven plugin that is used to build the adapter and deploy it. It is also used to pull and push adapter configuration. The plug-in is defined in the pom.xml as follows:

<plugin>
    <groupId>com.ibm.mfp</groupId>
    <artifactId>adapter-maven-plugin</artifactId>
    <version>8.0.0</version>
    <extensions>true</extensions>
</plugin>
The plug-in has four goals: build, deploy, configpull, and configpush:
  • The build goal creates the adapter file by zipping the relevant files from the project and adding the dependencies to the adapter file. The goal creates the adapter file in the target directory with the name <adapter-name>.adapter. The build goal runs automatically as part of the packaging phase of the Maven lifecycle.

  • The deploy goal deploys the adapter file to the server. To use this goal, ensure that the following values in your pom.xml file are correct.

    <properties>
        <!-- MobileFirst adapter deployment properties -->
        <mfpfUrl>http://localhost:9080/mfpadmin</mfpfUrl>
        <mfpfUser>admin</mfpfUser>
        <mfpfPassword>admin</mfpfPassword>
        <mfpfRuntime>mfp</mfpfRuntime>
    </properties>

    The parameter mfpfUrl is the URL to the server where the adapter is deployed. If you are using HTTPS as the protocol, the connection to the server is encrypted. The parameters mfpfUser and mfpfPassword are the user name and password of the administration service. The parameter mfpfRuntime defines the target runtime to deploy to.

    Note: The adapter-maven-plugin deploy goal does not support server certificate checking or host name checking. Use it in development only. For production purposes, use the Ant deployer instead. For more information, see Administering MobileFirst applications through Ant.

    For more information about deploying adapters with Maven, see Deploying JavaScript adapters and Deploying Java adapters.

  • The configpull goal pulls the configuration for an adapter from the MobileFirst Server and writes it to the file specified for the mfpfConfigFile parameter. For more information about configuring adapters in MobileFirst Server, see Configuring adapters. To run this goal, do either of the following:
    • Set the mfpfConfigFile parameter in the pom.xml file to point to an output file name.
    • Pass an output file name by using the DmfpfConfigFile option in a command. For example:
      mvn adapter:configpull [-DmfpfConfigFile =<path to file>]
    The result is a JSON object.
  • The configpush goal pushes the adapter configuration from the file name defined for the mfpfConfigFile parameter to the MobileFirst Server. For more information about configuring adapters in MobileFirst Server, see Configuring adapters. To run this goal, do either of the following:
    • Set the mfpfConfigFile parameter in the pom.xml file to point to an output file name.
    • Pass an output file name by using the DmfpfConfigFile option in a command. For example:
      mvn adapter:configpush [-DmfpfConfigFile=<path to file>]
    The result is a JSON object.
Custom security base classes
The mfp-security-checks-base dependency provides base classes that enable you to implement custom security checks in adapters. If your adapter does not use custom security checks, you can delete or comment out this dependency:
<dependency>
    <groupId>com.ibm.mfp</groupId>
    <artifactId>mfp-security-checks-base</artifactId>
    <version>8.0.0</version>
</dependency>

For more information about implementing custom security, see Security-checks implementation.

Third-party Maven dependencies

Use Maven's dependency mechanism to package any artifact into your adapter. For information on limitations in using dependencies, see Adapters and third-party dependencies.
Note:
  • If the artifact is not a Maven artifact, you can add it as a dependency by using the systemPath element. For more information, see Introduction to the Dependency Mechanism.
  • If you wish to use the dependency without packaging it in the adapter, use the provided scope.