Creating Java and JavaScript Adapters

Overview

An adapter can be created using either Maven commands or by using the PMF CLI (that is dependent on Maven being installed and configured). The Adapter code can then be edited and built using your IDE of choice, such as Eclipse or IntelliJ. This tutorial explains how to create, build and deploy Java or JavaScript adapters using Maven and the PMF CLI. To learn how to use the Eclipse or IntelliJ IDEs to create and build adapters, review the Developing Adapters in Eclipse tutorial.

Prerequisite: Make sure that you read the Adapters Overview first.

Install Maven
Creating Adapters Using PMF CLI
Install PMF CLI
Creating an Adapter
Creating Adapters Using Maven Archetype
File Structure
Build and Deploy Adapters
Dependencies
Grouping Adapters in a Single Maven Project
Downloading or Deploying Adapters Using PMF Operations Console
Working offline
Tutorials to follow next

Install Maven

In order to create an adapter, you first need to download and install Maven. Go to the Apache Maven website and follow the instructions how to download and install Maven.

Creating Adapters Using PMF CLI

Install PMF CLI

Follow the installation instructions in the Downloads page to Install PMF CLI.
Prerequisite: To create adapters using the Developer CLI, Maven must be installed.

Creating an Adapter

To create a Maven adapter project, use the pmfdev adapter create command. You can choose to run the command interactively or directly.

Interactive Mode

Open a Command-line window and run:
```
pmfdev adapter create
```
Enter an adapter name. For example:
```
? Enter Adapter Name: SampleAdapter
```

Select an adapter type using the arrows and the enter keys:

? Select Adapter Type:
   HTTP
   SQL
❯ Java

     * Select `HTTP` to create a JavaScript HTTP adapter
     * Select `SQL` to create a JavaScript SQL adapter  
     * Select `Java` to create a Java adapter

Enter an adapter package (this option is valid for Java adapters only). For example:
```
? Enter Package: com.mypackage
```
Enter a Group Id of the Maven project to be build. For example:
```
? Enter Group ID: com.mycompany
```

Direct Mode

Replace the placeholders with the actual values and run the command:

pmfdev adapter create <adapter_name> -t <adapter_type> -p <adapter_package_name> -g <maven_project_groupid>

Creating Adapters Using Maven Archetype “adapter-maven-archetype”

The “adapter-maven-archetype” is a PMF-provided archetype, that based on the Maven archetype toolkit, and is used by Maven in order to create the adapter Maven project.

To create a Maven adapter project, use the archetype:generate Maven command. Once the command is executed, Maven will download (or use the local repositories mentioned above) required files in order to generate the adapter Maven project.

You can choose to run the command interactively or directly.

Interactive Mode

From a Command-line window, navigate to a location of your choosing.
This is also where the Maven project will be generated.

Replace the DarchetypeArtifactId placeholder with the actual value and run:

mvn archetype:generate -DarchetypeGroupId=com.ibm.mfp -DarchetypeArtifactId=replace-with-the-adapter-type-artifact-ID

The Archetype Group Id and Archetype Version are required parameters to identify the archetype.
The Archetype Artifact Id is a required parameter to identify the adapter type:
- Use adapter-maven-archetype-java to create a Java adapter
- Use adapter-maven-archetype-http to create a JavaScript HTTP adapter
- Use adapter-maven-archetype-sql to create a JavaScript SQL adapter

Enter a Group Id of the Maven project to be build. For example:
```
Define value for property 'groupId': : com.mycompany
```
Enter an Artifact Id of the Maven project which will later be used also as the adapter name. For example:
```
Define value for property 'artifactId': : SampleAdapter
```
Enter a Maven project version (the default is 1.0-SNAPSHOT). For example:
```
Define value for property 'version':  1.0-SNAPSHOT: : 1.0
```

Enter an adapter package name (the default is the groupId). For example:

Define value for property 'package':  com.mycompany: : com.mypackage

Enter y to confirm:

Confirm properties configuration:
groupId: com.mycompany
artifactId: SampleAdapter
version: 1.0
package: com.mypackage
archetypeVersion: 9.0.0
Y: : y

Direct Mode

Replace the placeholders with the actual values and run the command:

mvn archetype:generate -DarchetypeGroupId=com.ibm.mfp -DarchetypeArtifactId=<adapter type artifact ID> -DgroupId=<maven_project_groupid> -DartifactId=<maven_project_artifactid>  -Dpackage=<adapter_package_name>

For more information about the archetype:generate command see the Maven documentation.

File Structure

After creating the adapter the result will be a Maven project containing a src folder and a pom.xml file:

mvn-adapter

Build and Deploy Adapters

Build

Using the PMF CLI - Run the adapter build command from the project’s root folder.
```
pmfdev adapter build
```
Using Maven - The adapter is built each time you run the install command to build the Maven project.
```
mvn install
```

Build All

If you have multiple adapters in a filesystem folder and you’d like to build all of them, use:

pmfdev adapter build all

The outcome is an .adapter archive file which can be found in the target folder of each adapter:

java-adapter-result

Deploy

The pom.xml file contains the following properties:
```
<properties>
 	
 	<mfpfUrl>http://localhost:9080/mfpadmin</mfpfUrl>
 	<mfpfUser>admin</mfpfUser>
 	<mfpfPassword>admin</mfpfPassword>
 	<mfpfRuntime>mfp</mfpfRuntime>
</properties>
```
- Replace localhost:9080 with your PMF IP address and port number.
- Optional. Replace the mfpfUser and mfpfPassword default values with your admin user name and password.
- Optional. Replace the mfpfRuntime default value with your runtime name.
Run the deploy command from the project’s root folder:
- Using the PMF CLI:
```
pmfdev adapter deploy -x
```
The -x option deploys the adapter to the PMF that is specified in adapter’s pom.xml file.
If the option is not used, the CLI will use the default server specified in the CLI settings.

For more CLI deployment options run the command: pmfdev help adapter deploy.

Using Maven:
```
mvn adapter:deploy
```

Deploy All

If you have multiple adapters in a filesystem folder and you’d like to deploy all of them, use:

pmfdev adapter deploy all

Tip: You can also build and deploy the adapter using a single command: mvn install adapter:deploy

Deploying to different runtimes

If you run multiple runtimes, see Registering applications and deploying adapters to different runtimes.

Dependencies

In order to use an external library in your adapter, follow one of the following suggested instructions:

Adding a local dependency

Add a lib folder under the root Maven project folder and put the external library in it.
Add the library path under the dependencies element in the Maven project’s pom.xml file.

For example:

<dependency>
<groupId>sample</groupId>
<artifactId>com.sample</artifactId>
<version>1.0</version>
<scope>system</scope>
<systemPath>${project.basedir}/lib/</systemPath>
</dependency>

Adding an external dependency

Search online repositories such as The Central Repository for the dependency.
Copy the POM dependency information and paste it under the dependencies element in the Maven project’s pom.xml file.

The following example uses the cloudant-client artifactId:

<dependency>
  <groupId>com.cloudant</groupId>
  <artifactId>cloudant-client</artifactId>
  <version>1.2.3</version>
</dependency>

For more information about dependencies see the Maven documentation.

Grouping Adapters in a Single Maven Project

If you have several adapters in your project you may want to arrange them under a single Maven project. Grouping adapters provides benefits such as build all, deploy all and sharing dependencies. You can also build all and deploy all adapters even if they are not grouped in a single Maven project using the pmfdev adapter build all and pmfdev adapter deploy all CLI commands.

To group adapters you need to:

Create a root folder and call it, for example, “GroupAdapters”.
Put the Maven adapter projects in it.

Create a pom.xml file:

<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>
 	<groupId>com.sample</groupId>
 	<artifactId>GroupAdapters</artifactId>
 	<version>1.0-SNAPSHOT</version>
 	<packaging>pom</packaging>

 	<modules>
             <module>Adapter1</module>
             <module>Adapter2</module>
 	</modules>

 	<properties>
 		<!-- parameters for deploy mfpf adapter -->
 		<mfpfUrl>http://localhost:9080/mfpadmin</mfpfUrl>
 		<mfpfUser>admin</mfpfUser>
 		<mfpfPassword>admin</mfpfPassword>
     <mfpfRuntime>mfp</mfpfRuntime>
 	</properties>

<build>
     <plugins>
         <plugin>
             <groupId>com.ibm.mfp</groupId>
             <artifactId>adapter-maven-plugin</artifactId>
             <extensions>true</extensions>
         </plugin>
     </plugins>
</build>

</project>

Define a groupId element of your choice
Add an artifactId element - the root folder’s name
Add a module element for each adapter
Add the build element
Optional. Replace localhost:9080 with your specific PMF IP address and port number.
Optional. Replace the mfpfUser and mfpfPassword default values with your admin user name and password.
Optional. Replace the mfpfRuntime default value with your runtime name.
To build or deploy all adapters, run the Maven commands from the root “GroupAdapters” project.

Downloading or Deploying Adapters Using PMF Operations Console

Open your browser of choice and load the PMF Operations Console using the address http://<IP>:<PORT>/mfpconsole/.
Click on the “New” button next to Adapters. You have two options to create an adapter:
- Using Maven or PMF CLI as previously explained above.
- Download a template adapter project (step 2).
Build the adapter Using Maven or PMF CLI.
Choose one of the following ways to upload the generated .adapter file which can be found in the target folder of the adapter project:
- Click on the Deploy Adapter button (step 5).
- Drag and drop the file into the “Create new” adapter screen.
After successfully deploying the adapter, the details page will be displayed containing the following tabs:
- Configurations - properties defined by the adapter XML file. Here you can change the configurations without having to deploy again.
- Resources - a list of the adapter resources.
- Configurations Files - adapter configuration data, to be used in DevOps environments.

Working offline

If you do not have online access to the Maven Central Repository, you can share PMF Maven artifacts in the internal repository of your organization.

Visit the Downloads page and download the Persistent Mobile Foundation Developer Kit Installer.
Start PMF and in a browser, load the PMF Operations Console from the following URL: http://<your-server-host:server-port>/mfpconsole.
Click Download Center. Under Tools → Adapter Archetypes, click Download. The mfp-maven-central-artifacts-adapter.zip archive is downloaded.
Add the adapter archetypes and security checks to the internal Maven repository by running the install.sh script for Linux and Mac.

The following JAR files are required by adapter-maven-api. Make sure they are located either in developers’ local .m2 folder, or in the Maven repository of your organization. You can download them from The Central Repository.
- javax.ws.rs:javax.ws.rs-api:2.0
- javax:javaee-web-api:6.0
- org.apache.httpcomponents:httpclient:4.3.4
- org.apache.httpcomponents:httpcore:4.3.2
- commons-logging:commons-logging:1.1.3
- javax.xml:jaxp-api:1.4.2
- org.mozilla:rhino:1.7.7
- io.swagger:swagger-annotations:1.5.6
- com.ibm.websphere.appserver.api:com.ibm.websphere.appserver.api.json:1.0
- javax.servlet:javax.servlet-api:3.0.1

Tutorials to follow next

▲

Last modified on

Creating Java and JavaScript Adapters

Overview

Jump to

Install Maven

Creating Adapters Using PMF CLI

Install PMF CLI

Creating an Adapter

Interactive Mode

Direct Mode

Creating Adapters Using Maven Archetype “adapter-maven-archetype”

Interactive Mode

Direct Mode

File Structure

Build and Deploy Adapters

Build

Build All

Deploy

Deploy All

Deploying to different runtimes

Dependencies

Adding a local dependency

Adding an external dependency

Grouping Adapters in a Single Maven Project

Downloading or Deploying Adapters Using PMF Operations Console

Working offline

Tutorials to follow next