Usage

Brief examples on how to use this plugin.

Installing the SAP Cloud Platform SDK for Neo environment

This plugin allows you to conveniently call the SAP Cloud Platform console client and most of its commands from Maven. To use the plugin, you require an installed SAP Cloud Platform SDK for Neo environment. While you can download and install it from the SAP Cloud Platform Tools page, we recommend that you use the install-sdk goal instead.

    <project>
        [...]
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.sap.cloud</groupId>
                        <artifactId>neo-java-web-maven-plugin</artifactId>
                        <version>1.151.13</version>
                        <executions>
                            <execution>
                                <!-- Choose a phase when to install the SDK -->
                                <phase>initialize</phase>
                                <goals>
                                    <!-- Call the SDK installation goal of this plugin -->
                                    <goal>install-sdk</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <!-- Location of the SAP Cloud Platform SDK for Neo environment -->
                            <sdkInstallPath>${project.build.directory}/sdk</sdkInstallPath>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        [...]
    </project>

Running SAP Cloud Platform Console Client Commands

If you are already used to the console client (neo commands) you might find it easier to use the run-console-command or run-console-commands goal, instead of the dedicated Maven goals.

    <project>
        [...]
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.sap.cloud</groupId>
                        <artifactId>neo-java-web-maven-plugin</artifactId>
                        <version>1.151.13</version>
                        <executions>
                            <execution>
                                <!-- Choose a phase when to run the command -->
                                <phase>package</phase>
                                <goals>
                                    <!-- Call the generic command runner goal of this plugin -->
                                    <goal>run-console-command</goal>
                                </goals>
                                <configuration>
                                    <!-- Call the command in the syntax you would normally use with the console client -->
                                    <consoleCommand>deploy -a ${sap.cloud.account} -b ${sap.cloud.application} -h ${sap.cloud.host} -u ${sap.cloud.username} -p ${sap.cloud.password} -source ${project.build.directory}/${project.artifactId}.war</consoleCommand>
                                </configuration>
                            </execution>
                        </executions>
                        <configuration>
                            <!-- Location of the SAP Cloud Platform SDK for Neo environment -->
                            <sdkInstallPath>${project.build.directory}/sdk</sdkInstallPath>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        [...]
    </project>

Note: The use of the parameter properties (for example, for the account) is optional, but it is generally good practice to use properties to inject this type of information dynamically.

Recommendation: The ultimately cleaner and more convenient way is to use the dedicated goals this plugin offers for most console client commands (see below).

Calling Dedicated Goals

Almost all console client commands have a corresponding Maven goal with the same name. Their arguments can be supplied as configuration parameters and have names similar to those in the console client, that is, the long form version of the argument name, converted into camel case, without dashes (normal practice for Maven plugins).

    <project>
        [...]
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.sap.cloud</groupId>
                        <artifactId>neo-java-web-maven-plugin</artifactId>
                        <version>1.151.13</version>
                        <executions>
                            <execution>
                                <!-- Choose a phase when to execute the goal -->
                                <phase>package</phase>
                                <goals>
                                    <!-- Call the dedicated deploy goal of this plugin -->
                                    <goal>deploy</goal>
                                </goals>
                                <configuration>
                                    <!-- Configuration for the above deploy goal -->
                                    <host>${sap.cloud.host}</host>
                                    <user>${sap.cloud.username}</user>
                                    <password>${sap.cloud.password}</password>
                                    <account>${sap.cloud.account}</account>
                                    <application>${sap.cloud.application}</application>
                                    <source>${project.build.directory}/${project.artifactId}.war</source>
                                </configuration>
                            </execution>
                        </executions>
                        <configuration>
                            <!-- Location of the SAP Cloud Platform SDK for Neo environment -->
                            <sdkInstallPath>${project.build.directory}/sdk</sdkInstallPath>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        [...]
    </project>

Note: Again as above, the use of the parameter properties (for example, for the account) is optional, but it is generally good practice to use properties to inject this type of information dynamically.

Avoiding Passwords in Clear-Text

Most goals access the SAP Cloud. For that you will have to supply your user name and password. Naturally, you would like to avoid doing this in clear-text. Therefore this plugin supports Maven Password Encryption.

First you will have to encrypt a so-called master password (for details please see here):

    mvn --encrypt-master-password <master-password>

Store your encrypted master password from above in the settings-security.xml file (usually to be placed under ~/.m2/settings-security.xml):

    <settingsSecurity>
        <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
    </settingsSecurity>

Next you will have to encrypt your SAP Cloud Platform password (for details please see here):

    mvn --encrypt-password <password>

Add a new server entry with your user name (your SAP Cloud Platform user name) and the encrypted server password from above to the settings.xml under an ID of your choice:

    <settings>
        [...]
        <servers>
            <server>
                <id>sap-hana-cloud-credentials</id>
                <username>p0123456789</username>
                <password>{IPbt04hIvvgHyp7LVASAmUewXuQFHa32ob5XResyc2s=}</password>
            </server>
        </servers>
        [...]
    </settings>

Now you can refer to this server entry via its ID and drop the user name and password from your plugin or goal configuration.

    <project>
        [...]
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.sap.cloud</groupId>
                        <artifactId>neo-java-web-maven-plugin</artifactId>
                        <version>1.151.13</version>
                        <configuration>
                            <!-- Server ID referring to settings server entry with user name and encrypted password -->
                            <!-- Clear-text user name and password are no longer necessary to be provided separately -->
                            <mavenSettingsServerId>sap-hana-cloud-credentials</mavenSettingsServerId>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        [...]
    </project>

Note: If you specify user and/or password properties as well, they will overwrite whatever you have defined in your server entry (more specific trumps more general properties).

Handling Goal Output

When you specify consoleOutputPropertyPrefix with a goal execution, the console client command output will be put into Maven properties for further processing, either as textual console client command output or as a structured result. You can then use this or other plugins (for example, maven-antrun-plugin) to process the Maven properties further. The names of the Maven properties will start with the prefix you specify with the above configuration. Run the goal once manually to see which Maven properties are effectively set. You can hide the output later with consoleOutputPropertyDump, for example, if you don't want the output to appear in the build log.

    <project>
        [...]
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.sap.cloud</groupId>
                        <artifactId>neo-java-web-maven-plugin</artifactId>
                        <version>1.151.13</version>
                        <executions>
                            <execution>
                                <id>open-db-tunnel</id>
                                <!-- Choose a phase when to execute the goal -->
                                <phase>pre-integration-test</phase>
                                <goals>
                                    <!-- Call the dedicated open-db-tunnel goal of this plugin -->
                                    <goal>open-db-tunnel</goal>
                                </goals>
                                <configuration>
                                    <!-- Configuration for the above open-db-tunnel goal -->
                                    <host>${sap.cloud.host}</host>
                                    <user>${sap.cloud.username}</user>
                                    <password>${sap.cloud.password}</password>
                                    <account>${sap.cloud.account}</account>
                                    <background>true</background>
                                    <id>schema</id>
                                    <consoleOutputPropertyPrefix>db-tunnel</consoleOutputPropertyPrefix>
                                </configuration>
                            </execution>
                            <execution>
                                <id>close-db-tunnel</id>
                                <!-- Choose a phase when to execute the goal -->
                                <phase>post-integration-test</phase>
                                <goals>
                                    <!-- Call the dedicated close-db-tunnel goal of this plugin -->
                                    <goal>close-db-tunnel</goal>
                                </goals>
                                <configuration>
                                    <!-- Configuration for the above close-db-tunnel goal -->
                                    <sessionId>${db-tunnel.result.sessionId}</sessionId>
                                </configuration>
                            </execution>
                        </executions>
                        <configuration>
                            <!-- Location of the SAP Cloud Platform SDK for Neo environment -->
                            <sdkInstallPath>${project.build.directory}/sdk</sdkInstallPath>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        [...]
    </project>

Note: Again as above, the use of the parameter properties (for example, for credentials) is optional, but it is generally good practice to use properties to inject this type of information dynamically.

The first execution above (the one using consoleOutputPropertyPrefix) will dump the following, which can then be processed as shown by the second execution (using $db-tunnel.result.sessionId):

    [INFO] Property db-tunnel.exitCode set to 0
    [INFO] Property db-tunnel.pid set to 1234@machine
    [INFO] Property db-tunnel.result.dbSchema set to NEO_0123456789012345678901234
    [INFO] Property db-tunnel.result.dbType set to HANA
    [INFO] Property db-tunnel.result.dbUser set to DEV_0123456789012345678901234
    [INFO] Property db-tunnel.result.dbUserPassword set to ***
    [INFO] Property db-tunnel.result.host set to localhost
    [INFO] Property db-tunnel.result.instanceNumber set to 00
    [INFO] Property db-tunnel.result.jdbcUrl set to jdbc:sap://localhost:12345/?currentschema=NEO_0123456789012345678901234
    [INFO] Property db-tunnel.result.port set to 12345
    [INFO] Property db-tunnel.result.sessionId set to 01234567-0123-0123-0123-0123456789ab

Tip: The pid is useful if you need to find the corresponding log in the SAP Cloud Platform SDK for Neo environment tools/log folder.

Configuring a Proxy

You can configure proxy parameters for all goals.

    <project>
        [...]
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.sap.cloud</groupId>
                        <artifactId>neo-java-web-maven-plugin</artifactId>
                        <version>1.151.13</version>
                        [...]
                        <configuration>
                            <!-- Configure proxy -->
                            <consoleHttpProxyHost>${proxy.host}</consoleHttpProxyHost>
                            <consoleHttpProxyPort>${proxy.port}</consoleHttpProxyPort>
                            <consoleHttpsProxyHost>${proxy.host}</consoleHttpsProxyHost>
                            <consoleHttpsProxyPort>${proxy.port}</consoleHttpsProxyPort>
                            [...]
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        [...]
    </project>

Note: Again as above, the use of the parameter properties (for example, for the proxy) is optional, but it is generally good practice to use properties to inject this type of information dynamically.

Getting Help on the Command Line

Help can be invoked in the normal manner for Maven plugins:

  mvn com.sap.cloud:neo-java-web-maven-plugin:1.151.13:help
  • Append -Dgoal=… to show help for only one specific goal or command, as opposed to all
  • Append -Ddetails=true to also list the parameters