Here you get a simple introduction on how to use the Maven Plugin for Axway API Gateway. It assumes that you are familiar with Apache Maven and that you are familiar with PolicyStudio and the API Gateway.
First you have to install the Maven plugin for Axway API Gateway. Clone the repository on your machine and install the plugin:
$ cd apigw-maven-plugin $ mvn clean install
The Axway API Gateway Maven plugin is now installed on your machine.
The plugin requires the installation of the Axway API Gateway Package and Deploy Tools.
The location of the software has to be specified by the property axway.home.
Due to the location is individual for each developer, configure the property in your ~/.m2/settings.xml file.
<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 https://maven.apache.org/xsd/settings-1.0.0.xsd"
>
<profiles>
<profile>
<id>axway</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<axway.home>C:/Axway-7.6.2</axway.home> <!--(1)-->
</properties>
</profile>
</profiles>
<activeProfiles>
<activeProfile>axway</activeProfile>
</activeProfiles>
</settings>-
Specify the location of your Axway installation here.
As a first step we will create a simple policy project. A policy project contains shared and reusable policies. No server setting are included in a policy project.
To create a policy project create new folder (e.g. pol-hello-world) and create a pom.xml file (see template below).
<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.example</groupId> <!--(1)-->
<artifactId>hello-world</artifactId> <!--(2)-->
<version>0.1.0-SNAPSHOT</version> <!--(3)-->
<packaging>axway-policy-archive</packaging> <!--(4)-->
<name>Hello World Policy</name>
<description>My first "Hello World" policy project.</description>
<build>
<plugins>
<plugin> <!--(5)-->
<groupId>com.axway.maven.plugins</groupId>
<artifactId>apigw-maven-plugin</artifactId>
<version>1.2.1</version>
<extensions>true</extensions>
</plugin>
</plugins>
</build>
</project>-
Define the group ID of your artifact.
-
Define the name of your artifact.
-
Define the version of your artifact.
-
The packing type
axway-policy-archivemarks it as a policy project. -
Use Maven Plugin for API Gateway for this project.
To initialize the project invoke the Maven goal apigw:init.
$ mvn apigw:init
|
Tip
|
All goals which are specific to the Maven Plugin for API Gateway have the prefix apigw:.
|
This will create a source folder with an empty policy project based on a factory template. For testing purpose it also creates an empty policy project with server configuration.
To edit the policies start PolicyStudio by calling the Maven goal apigw:policystudio.
$ mvn apigw:policystudio
|
Note
|
If PolicyStudio is started the first time in the project directory, it has to be initialized first. In this case you will be prompted to close PolicyStudio right after startup.
So, just close PolicyStudio and invoke the Maven goal |
This will open PolicyStudio. The recently used projects are automatically configured by the plugin. So you don’t have to search for your source code. Just select your policies or the Test Server project.
Open the "hello-world" project and create a simple policy (see screenshot).
Configure PolicyStudio to support environmentalization. For demonstration environmentalize the Attribute Value of the hello.name attribute.
Close your project.
For building an environment independent API Gateway instance create a separate folder (e.g. srv-hello-world) and create a server project pom.xml file (see template below).
<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.example</groupId>
<artifactId>hello-world-gw</artifactId>
<version>0.1.0-SNAPSHOT</version>
<packaging>axway-server-archive</packaging> <!--(1)-->
<name>Hello World Server</name>
<description>My first "Hello World" server project.</description>
<dependencies>
<dependency> <!--(2)-->
<groupId>com.example</groupId>
<artifactId>hello-world</artifactId>
<version>0.1.0-SNAPSHOT</version>
<type>axway-policy-archive</type>
</dependency>
</dependencies>
<build>
<plugins>
<plugin> <!--(3)-->
<groupId>com.axway.maven.plugins</groupId>
<artifactId>apigw-maven-plugin</artifactId>
<version>1.2.1</version>
<extensions>true</extensions>
</plugin>
</plugins>
</build>
</project>-
The packaging type
axway-server-archivemarks it as a server project. -
Include the dependency of your previously created policy archive.
-
Use Maven Plugin for API Gateway for this project.
As before, to initialize the project invoke the Maven goal apigw:init.
$ mvn apigw:init
This will create a source folder with an empty server project based on a factory template.
Same as before, to edit the policies start PolicyStudio by calling the Maven goal apigw:policystudio.
$ mvn apigw:policystudio
|
Note
|
For the first start of PolicyStudio in this project you have to close PolicyStudio after startup and invoke the goal again. |
The dependent policy archive will automatically downloaded from the Maven repository and will be extracted in a temporary folder. The recently used project is automatically configured by the plugin.
Open your project. PolicyStudio will automatically ask you to enable environmentalization and team development.
As you can see the dependent hello-world project was automatically configured by the plugin.
Develop a very simple policy to call the previously created Hello World Message policy.
And configure the according listeners.
Close your project and close PolicyStudio.
For building an environment specific API Gateway instance create a separate folder (e.g. dpl-hello-world) and create a deployment project pom.xml file (see template below).
<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.example</groupId>
<artifactId>hello-world-dev</artifactId> <!--(1)-->
<version>0.1.0-SNAPSHOT</version>
<packaging>axway-deployment-archive</packaging> <!--(2)-->
<name>Hello World (DEV)</name>
<properties>
<!--(3)-->
<!--
<axway.config.certs>${basedir}/src/main/axwgw/gateway-cert.json</axway.config.certs>
<axway.config.props>${basedir}/src/main/axwgw/gateway-prop.json</axway.config.props
-->
</properties>
<dependencies>
<dependency> <!--(4)-->
<groupId>com.example</groupId>
<artifactId>hello-world-gw</artifactId>
<version>0.1.0-SNAPSHOT</version>
<type>axway-server-archive</type>
</dependency>
</dependencies>
<build>
<plugins>
<plugin> <!--(5)-->
<groupId>com.axway.maven.plugins</groupId>
<artifactId>apigw-maven-plugin</artifactId>
<version>1.2.1</version>
<extensions>true</extensions>
</plugin>
</plugins>
</build>
</project>-
Environment specific artifact, so the name should include the target environment.
-
The packaging type
axway-deployment-archivemarks it as a deployment project. -
Optionally specify additional configuration files.
-
Include the dependency of your previously created server archive.
-
Use Maven Plugin for API Gateway for this project.
To initialize the project invoke the Maven goal apigw:init.
$ mvn apigw:init
This will create a source folder with an empty configuration file.
{}Build the package.
$ mvn clean package
We use envionmentalized fields in our project. The plugin scans for environmentalized fields and set the values from the configuration. As we haven’t configured our project yet, the build will fail.
For convenience the plugin will automatically add new fields to the configuration file (see below).
{
"entities": {
"/[CircuitContainer]name=Hello World/[FilterCircuit]name=Hello World Message/[SetAttributeFilter]name=Set name": { (1)
"description": "",
"fields": {
"attributeValue#0": { (2)
"source": "value", (3)
"type": "string", (4)
"used": true, (5)
"value": null (6)
}
}
}
}
}-
Short handed key of the environmentalized entity.
-
Name and index of the environmentalized field.
-
Specifies that the field value is literally retrieved form "value".
-
Type of the field (just for documentation, don’t change it).
-
Indicates if the configured field is used. If false the field is no longer environmentalized or the entity is renamed or removed. The property is automatically maintained by the plugin.
-
Literal value of the field. null indicates an unconfigured field.
|
Tip
|
When the configuration file is written by the plugin, all JSON properties are sorted. This makes diff & merge easy. |
Now configure the field in the configuration file.
{
"attributeValue#0": {
"source": "value",
"type": "string",
"used": true,
"value": "Fred" (1)
}
}-
Your configured value.
And build your project again.
$ mvn clean package
Now the build succeeds and a deployment archive hello-world-dev-0.1.0-SNAPSHOT.axdar containing the .fed file is created.
For manual checks via ConfigurationStudio the content of the archive is located in the target/axway-archive folder.
The project can be deployed to a gateway via the plugin.
Just invoke the apigw:deploy goal within the deployment project and specify the target domain and group.
In the following example it is assumed that the Admin Node Manager is located at localhost:8090.
The user admin is allowed to deploy projects and has the password changeme.
The project shall be deployed to the group test.
$ mvn -Daxway.anm.host=localhost -Daxway.anm.port=8090 \ -Daxway.anm.user=admin -Daxway.anm.password=changeme \ -Daxway.deploy.group=test \ clean apigw:deploy
This project will create new Docker images and containers. The Docker image will be created with the fed file that was created when the package command was invoked.
Run this mvn plugin by invoking apigw:container. You must specify the following properties:
-
axway.deploy.group (mandatory)
-
axway.passphrase.deploy (optional)
-
axway.container.scripts (mandatory)
-
axway.remove.container (mandatory)
-
axway.container.name (optional)
-
axway.remove.image (optional)
-
axway.image.name (mandatory)
-
axway.image.tag (optional)
-
axway.parent.image.name (optional)
-
axway.parent.image.tag (optional)
-
axway.license (mandatory)
-
axway.merge.dir (optional)
-
axway.environment.variables
-
axway.links (optional)
-
axway.ports (optional)
-
axway.domain.cert (optional)
-
axway.domain.key (optional)
-
axway.domain.key.pass.file (optional)
-
axway.admin.node.manager.host (mandatory)
-
axway.metrics.db.url (optional)
-
axway.metrics.db.username (optional)
-
axway.metrics.db.password (optional)
When dealing with a domain cert and key there are 2 ways to handle this. First would be to generate your own cert, key and password file. These would then be needed to be passed in during the mvn call.
If no domain, key or password file is passed in maven will assume that it needs to use default cert and key. You will
need to create a cert\tmp\pass.txt file. In this file you just add changeme and save this file. Maven will assume
that is the location of the file.
In the following example, we will delete the existing container and image, then we will recreate everything using a default domain cert and key.
mvn clean apigw:container \
--define axway.deploy.group=emt-group \
--define axway.container.scripts=/mnt/c/Axway_7.6.2/Software/dockerscripts/emt-containers-1.0.0-9 \
--define axway.remove.container=true \
--define axway.container.name=apimgr \
--define axway.remove.image=true \
--define axway.image.name=apimgt \
--define axway.image.tag=7.6.2_3 \
--define axway.parent.image.name=apigw-base \
--define axway.parent.image.tag=7.6.2_3 \
--define axway.license=/mnt/c/Axway_7.6.2/Software/API_7.6_Docker_Temp.lic \
--define axway.merge.dir=/mnt/c/Axway_7.6.2/tmp/apigateway \
--define axway.environment.variables="METRICS_DB_URL;jdbc:mysql://mysql:3306/metrics\?useSSL=false,METRICS_DB_USERNAME;metrics,METRICS_DB_PASS;metrics,EMT_DEPLOYMENT_ENABLED;true,EMT_ANM_HOSTS;anm:8090,CASS_HOST;cassandra" \
--define axway.links="anm;anm,cassandra_2.2.12;cassandra,mysql_5.7;mysql" \
--define axway.ports="8075;8075,8065;8065,8080;8080" \
--define axway.admin.node.manager.host=anm:8090 \
--define axway.metrics.db.url=jdbc:mysql://mysql:3306/metrics\?useSSL=false \
--define axway.metrics.db.username=metrics \
--define axway.metrics.db.password=metrics