Skip to content

_reference.adoc

Latest commit

 

History

History
433 lines (335 loc) · 13.4 KB

_reference.adoc

File metadata and controls

433 lines (335 loc) · 13.4 KB

Reference

Project Types

This section describes the various projects types. The described directory layout is the default structure as assumed by the plugin.

Policy Project

Policy project contain shared and reusable policies. No sever settings are included in the project. Policy projects may depend on other policy projects or external libraries (JARs).

Directory Layout

[folder] project-home
  [file] pom.xml (1)
  [folder] src
    [folder] main (2)
      [folder] axwgw
        [folder] policies (3)
          [file] config.xml
          [file] ...
        [folder] resources
          [folder] staticFiles (4)
    [folder] test (5)
      [folder] policies (6)
        [file] config.xml
        [file] ...

  1. Maven Project Object Model, which describes your project and the dependencies

  2. Main sources of your project

  3. Policies as to be opened by PolicyStudio

  4. Folder for static files (e.g. HTML, text, JavaScript, …​)

  5. Test sources for your project

  6. Server project for testing your project

Archive Content

The outcome of the policy project is the policy archive artifact. It contains the policies of the project (as edited in PolicyStudio) and the static files.

[folder] policy-archive.axpar (1)
  [folder] policies (2)
    [file] config.xml
    [file] ...
  [folder] staticFiles (3)

  1. Generated policy archive.

  2. Policies of the project (copied from src/main/axwgw/policies).

  3. Static files belonging to the project (copied from src/main/resources/staticFiles). The static files are optional.

Server Project

Server projects represent gateway instances. They contain policies and server settings. Server projects may depend on other policy projects or external libraries (JARs). Server projects are environment independent.

Directory Layout

[folder] project-home
  [file] pom.xml (1)
  [folder] src
    [folder] main (2)
      [folder] axwgw
        [folder] policies (3)
          [file] config.xml
          [file] ...
        [folder] resources
          [folder] staticFiles (4)

  1. Maven Project Object Model, which describes your project and the dependencies

  2. Main sources of your project

  3. Policies, including server setting, as to be opened by PolicyStudio

  4. Folder for static files (e.g. HTML, text, JavaScript, …​)

Archive Content

The outcome of a server project is a server archive artifact. The server archive contains everything required for a deployment of a gateway instance, except the environment dependent configuration.

[folder] server-archive.axsar (1)
  [folder] lib (2)
  [folder] staticFiles (3)
  [file] gateway.pol (4)
  [file] gateway.env (5)
  [file] gateway.info.json (6)
  [file] readme-server-archive.txt (7)

  1. Generated server archive.

  2. Folder containing dependent JARs.

  3. Static files belonging to the gateway instance. The files are copied from the staticFiles folders of all dependent policy archives.

  4. Packed .pol archive containing the server configuration and polices (including policies of all dependent policy archives)

  5. .env file containing all environment specific information. The environment is not configured and should be treated as environment independent.

  6. JSON document describing the content of the archive (e.g. version and dependencies)

  7. Generated readme file describing the content of the archive (e.g. version of dependent policy archives)

gateway.info.json File

The artifact information file describes the content of the server archive as a JSON document. It contains information about the deployment archive itself the dependencies.

{
  "id" : "com.example:hello-world-gw:axway-server-archive:0.1.0-SNAPSHOT",
  "name" : "Hello World Server",
  "description" : "My first \"Hello World\" server project.",
  "buildTime" : "2019-12-17T17:25:40",
  "artifact" : {
    "groupID" : "com.example",
    "artifactID" : "hello-world-gw",
    "version" : "0.1.0-SNAPSHOT"
  },
  "dependencies" : [ "com.example:hello-world:axway-policy-archive:0.1.0-SNAPSHOT" ]
}

Deployment Project

Deployment projects are used to configure API gateways for specific environments or groups based on an environment independent server project. A deployment project depends on exactly one server project.

Directory Layout

[folder] project-home
  [file code] pom.xml (1)
  [folder] src
    [folder] main (2)
      [folder] axwgw
        [file] gateway.config.json (3)

  1. Maven Project Object Model, which describes your project and the dependencies

  2. Main sources of your project

  3. Configuration file as to be used by the configuration tool.

Archive Content

The outcome of a deployment project is a environment specific deployment archive. It contains a fully configured API gateway instance including required static files and depending JARs.

[folder] deploy-archive.axdar (1)
  [folder] lib (2)
  [folder] staticFiles (3)
  [file] gateway.fed (4)
  [file] gateway.info.json (5)
  [file] readme-deployment-archive.txt (6)
  [file] readme-server-archive.txt (7)

  1. Generated server archive.

  2. Folder containing dependent JARs.

  3. Static files belonging to the gateway instance. The files are copied from the staticFiles folders of all dependent policy archives.

  4. Configured .fed file. It is environment specific and contains all configured certificates and environmentalized fields.

  5. JSON document describing the content of the archive (e.g. version and dependencies)

  6. Generated readme file describing the content of the archive (e.g. version of dependent server archive).

  7. Generated readme file describing the content of the archive (e.g. version of dependent policy archives). Copied from server archive.

gateway.info.json File

The artifact information file describes the content of the deployment archive as a JSON document. It contains information about the deployment archive itself and about the based server archive.

{
  "id" : "com.example:hello-world-dev:axway-deployment-archive:0.1.0-SNAPSHOT",
  "name" : "Hello World (DEV)",
  "description" : null,
  "buildTime" : "2019-12-17T17:25:40",
  "artifact" : {
    "groupID" : "com.example",
    "artifactID" : "hello-world-dev",
    "version" : "0.1.0-SNAPSHOT"
  },
  "dependencies" : [ "com.example:hello-world-gw:axway-server-archive:0.1.0-SNAPSHOT" ],
  "serverArchive" : {
    "id" : "com.example:hello-world-gw:axway-server-archive:0.1.0-SNAPSHOT",
    "name" : "Hello World Server",
    "description" : "My first \"Hello World\" server project.",
    "buildTime" : "2019-12-17T17:25:40",
    "artifact" : {
      "groupID" : "com.example",
      "artifactID" : "hello-world-gw",
      "version" : "0.1.0-SNAPSHOT"
    },
    "dependencies" : [ "com.example:hello-world:axway-policy-archive:0.1.0-SNAPSHOT" ]
  }
}

Build Properties

The plugin can be configured by various properties. For most properties a default value exists, so the configuration effort is reduced to a minimum.

Table 1. Properties
Property Description

axway.home

Home directory of the installed Axway API Gateway suite. This property has to be defined before using the plugin.

Default: none

axway.home.apigw

Home directory of the installed API Gateway.

Default: ${axway.home}/apigateway

axway.home.policystudio

Home directory of installed PolicyStudio.

Default: ${axway.home}/policystudio

axway.project.version

Version name of the project.

The version name is used for setting the version attribute of the policy properties within .pol or .fed packages.

Default: ${project.version}

axway.dir.source

Directory of gateway or configuration file source code used by the plugin. ${basedir}/src/main/axwgw

axway.dir.resources

Directory of resources.

Default: ${basedir}/src/main/resources

axway.dir.sharedProjects

Directory to extracted dependent policy projects.

Default: ${project.build.directory}/sharedProjects

axway.dir.testServer

Source directory for the test API Gateway (only for policy projects).

Default: ${basedir}/src/test/policies

axway.policystudio.data

Data directory for project specific PolicyStudio data.

Default: ${basedir}/.studio/data

axway.policystudio.config

Directory for project specific PolicyStudio configuration.

Default: ${basedir}/.studio/conf

axway.dir.archive.build

Directory for building project archives.

Default: ${project.build.directory}/axway-archive

axway.template.gateway.fed

Template for the server project.

Default: ${axway.home}/apigateway/system/conf/templates/BlankConfiguration-VordelGateway.fed

axway.template.policies.fed

Template for the policy project.

Default: ${axway.home}/apigateway/system/conf/templates/BlankNoSettingsConfiguration-VordelGateway.fed

axway.config.envs

Path to configuration file for environmentalized fields (required for deployment or deployment projects).

Default: ${axway.dir.source}/gateway.config.json (only for deployment projects)

axway.config.certs

Path to configuration file for certificates (required for deployment or deployment projects).

Default: none

axway.config.certs.basedir

Base directory for certificate files.

Default: none

axway.config.props

Path to configuration file for properties (required for deployment or deployment projects).

Default: none

axway.config.props.files

Comma separated path to configuration files for properties.

Default: none

axway.tools.cfg.verbose

Set to true to enable verbose mode for internal configuration tool.

Default: false

axway.tools.cfg.cert.expirationDays

Minimum number of days before certificates expires.

The build fails if at least one configured certificate expires within the next given days. Use -1 to disable the check.

Default: 10

axway.tools.cfg.cert.updateConfigured

Set to true to enable writing the info section of "update" certificates in the configuration file.

Since version v0.7.0 the info section of "update" certificates are not written any more. This property can be used to enable the previous behavior.

Default: false

axway.passphrase.pol

Passphrase for reading or generating .pol and .env packages.

Default: no passphrase

axway.passphrase.fed

Passphrase for reading or writing .fed packages.

Default: no passphrase

axway.passphrase.deploy

Passphrase for gateway deployment.

Default: no passphrase

axway.anm.host

Host of Admin Node Manager (required for deployment only)

Default: none

axway.anm.port

Port of Admin Node Manager (required for deployment only)

Default: 8090

axway.anm.user

Admin user for Admin Node Manager (required for deployment only)

Default: admin

axway.anm.password

Password for Admin Node Manager (required for deployment only)

Default: none

axway.deploy.group

Group the projects have to be deployed to (required for deployment only)

Default: none

axway.skipPackaging

Set to true to skip package goal in case of the target artifact already exists.

Default: false

📎
 It is not checked if the source files are newer than the target artifact.

axway.config.secrets.file

Path to file storing secrets.

axway.config.secrets.key

Path to key file to decrypt/encrypt values of secrets file.

Plugin Configuration

The plugin can also be configured in the pom.xml via the <configuration> element of the plugin.

pom.xml
<!- ... ->
<plugin>
  <groupId>com.axway.maven.plugins</groupId>
  <artifactId>apigw-maven-plugin</artifactId>
  <version>{mvn-plugin-ver}</version>
  <extensions>true</extensions>
  <configuration>
    <configConfigFile>${basedir}/src/main/axwgw/gateway.config.json</configConfigFile> <!--(1)-->

    <configCertsFile>${basedir}/src/main/axwgw/gateway.certs.json</configCertsFile> <!--(2)-->

    <configPropertyFile>${basedir}/gateway.prop.json</configPropertyFile> <!--(3)-->

    <configPropertyFiles> <!--(4)-->
      <configPropertyFile>${basedir}/prop-a.json</configPropertyFile>
      <configPropertyFile>${basedir}/prop-b.json</configPropertyFile>
    </configPropertFiles>

    <configCertsBaseDir>${basedir}/src/main/axwgw/certs</configCertsBaseDir> <!--(5)-->
    <configCertsBaseDirs>
      <configCertsBaseDir>${basedir}/src/main/axwgw/certs/common</configCertsBaseDir> <!--(6)-->
      <configCertsBaseDir>${basedir}/src/main/axwgw/certs/ca</configCertsBaseDir>
    </configCertsBaseDirs>
    <configSecretsFile>${basedir}/src/main/axwgw/gateway.crypt.json</configSecretsFile> <!--(7)-->
    <configSecretsKey>${user.home}/secrets.key</configSecretsKey> <!--(8)-->
  </configuration>
</plugin>
<!- ... ->

  1. Location of the configuration file for environmentalized fields.

  2. Location of the configuration file for certificates.

  3. Location of a configuration file for properties.

  4. Location of a list of configuration files for properties.

  5. Base directory for certificate files.

  6. Additional base directories for certificate files supported.

  7. Path to secrets file.

  8. Key file to decrypt/encrypt values of secrets file.