Payara Community Documentation

Download Enterprise Documentation

Payara Platform
Edit this Page

Payara Micro Maven Plugin

Payara Micro has a Maven plugin which can start and stop Payara Micro and create an Uber JAR bundle of the application and Payara Micro.

The plugin requires JDK 8 or higher and the latest version is currently 1.4.0

Configurable Goals

bundle

Aim: This goal bundles the attached project’s artifact into an Uber JAR with the specified configurations. By default, this goal is attached to the install phase. Usage: mvn payara-micro:bundle

Example:

<plugin>
    <groupId>fish.payara.maven.plugins</groupId>
    <artifactId>payara-micro-maven-plugin</artifactId>
    <version>${payara.micro.maven.plugin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>bundle</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <startClass>my.custom.start.class.Main</startClass>
        <deployArtifacts>
            <artifactItem>
                <groupId>org.mycompany</groupId>
                <artifactId>my-project</artifactId>
                <version>1.0</version>
                <type>ear</type>
            </artifactItem>
        </deployArtifacts>
        <customJars>
            <artifactItem>
                <groupId>org.primefaces</groupId>
                <artifactId>primefaces</artifactId>
                <version>6.0</version>
            </artifactItem>
        </customJars>
    </configuration>
</plugin>
Configuration tags

|=== | |Element | |System Property | |Environment Variable | |Default | |Notes |

|autoDeployArtifact | |payara.auto.deploy.artifact | |PAYARA_AUTO_DEPLOY_ARTIFACT | |true | |If the extension of the produced artifact is WAR, it will be copied automatically to the MICRO-INF/deploy directory when this property is set to true. |

|autoDeployContextRoot | |payara.auto.deploy.context.root | |PAYARA_AUTO_DEPLOY_CONTEXT_ROOT | |none | |Sets context root of the deployed artifact if autoDeployArtifact is true. autoDeployContextRoot has the higher precedence compared to the autoDeployEmptyContextRoot. |

|autoDeployEmptyContextRoot | |payara.auto.deploy.empty.context.root | |PAYARA_AUTO_DEPLOY_EMPTY_CONTEXT_ROOT | |true | |Sets context root of the deployed artifact to / if autoDeployArtifact is true. If set to false, context root is derived from project.build.finalName. If autoDeployContextRoot is specified, autoDeployEmptyContextRoot will be ignored. |

|startClass | |payara.start.class | |PAYARA_START_CLASS | |(optional): | |Replaces the Start-Class definition that resides in the MANIFEST.MF file with the provided class. |

|appendSystemProperties | |payara.append.system.properties | |PAYARA_APPEND_SYSTEM_PROPERTIES | |true | |Appends all system properties defined into the payara-boot.properties file. |

|payaraMicroVersion | |payara.micro.version | |PAYARA_MICRO_VERSION | |main-7 | |By default, bundle mojo fetches Payara Micro with version main-7. Note: payaraVersion is deprecated and has been replaced by payaraMicroVersion to stay in sync with the Payara Server Maven Plugin. |

|deployArtifacts | | | |None | |Can contain a list of artifactItems, which defines the dependencies with their GAVs to be copied under MICRO-INF/deploy folder. |

|customJars | | | |None | |Can contain a list of artifactItems, which defines the dependencies with their GAVs to be copied under MICRO-INF/lib folder. |

|uberJarClassifier | |payara.uber.jar.classifier | |PAYARA_UBER_JAR_CLASSIFIER | |microbundle | |Specifies the maven artifact classifier to use for the generated uber-jar. | |=== |

The bundle goal always searches for domain configuration files in src/main/resources to copy in to the MICRO-INF/domain directory of the Uber jar. The files which are currently included are:

  • domain.xml

  • hazelcast-config.xml

  • keystore.jks

  • login.conf

  • logging.properties

  • metrics.xml

Additionally, boot command scripts will be included if they exist in src/main/resources and transferred to the MICRO-INF directory of the Uber jar artifact.

pre-boot-commands.txt

Provides a file of asadmin commands to run before booting the server.

post-boot-commands.txt

Provides a file of asadmin commands to run after booting the server.

post-deploy-commands.txt

Provides a file of asadmin commands to run after all deployments have completed.

start

Aim: This goal starts Payara Micro with the specified configuration. Usage: mvn payara-micro:start

Example:

<plugin>
    <groupId>fish.payara.maven.plugins</groupId>
    <artifactId>payara-micro-maven-plugin</artifactId>
    <version>${payara.micro.maven.plugin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <useUberJar>true</useUberJar>
        <payaraMicroAbsolutePath>/path/to/payara-micro.jar</payaraMicroAbsolutePath>
        <payaraVersion>{page-version}</payaraVersion>
        <artifactItem>
            <groupId>fish.payara.extras</groupId>
            <artifactId>payara-micro</artifactId>
            <version>{page-version}</version>
        </artifactItem>
        <daemon>true</daemon>
        <javaPath>/path/to/Java/Executable</javaPath>
        <deployWar>true</deployWar>
        <contextRoot>myApp</contextRoot>
        <javaCommandLineOptions>
            <option>
                <value>-Xdebug</value>
            </option>
            <option>
                <key>-Xrunjdwp:transport</key>
                <value>dt_socket,server=y,suspend=y,address=5005</value>
            </option>
        </javaCommandLineOptions>
        <commandLineOptions>
            <option>
                <key>--domainconfig</key>
                <value>/path/to/domain.xml</value>
            </option>
            <option>
                <key>--autoBindHttp</key>
                <value>true</value>
            </option>
        </commandLineOptions>
    </configuration>
</plugin>
If you want to execute the payara-micro plugin along with maven-toolchains-plugin, you need to execute the plugin as: mvn toolchains:toolchain payara-micro:start. See Using Toolchains for more information.
Configuration tags

|=== | |Element | |System Property | |Environment Variable | |Default | |Notes |

|useUberJar | |payara.use.uber.jar | |PAYARA_USE_UBER_JAR | |false | |Use the created uber-jar that resides in the target folder. The name of the JAR artifact will be resolved automatically by evaluating its final name, artifact ID and version. This configuration element has the higher precedence compared to payaraMicroAbsolutePath, payaraVersion and artifactItem. |

|uberJarClassifier | |payara.uber.jar.classifier | |PAYARA_UBER_JAR_CLASSIFIER | |microbundle | |Specifies the maven artifact classifier to use for the Uber JAR. |

|payaraMicroPath | |payara.micro.path | |PAYARA_MICRO_PATH | |none | |Absolute path to the Payara Micro executable. Note: Parameter payaraMicroAbsolutePath is deprecated and has been replaced by payaraMicroPath to stay in sync with the Payara Server Maven Plugin. |

|payaraMicroVersion | |payara.micro.version | |PAYARA_MICRO_VERSION | |main-7 | |By default, bundle mojo fetches Payara Micro with version main-7. Note: payaraVersion is deprecated and has been replaced by payaraMicroVersion to stay in sync with the Payara Server Maven Plugin. |

|artifactItem | | | |none | |Defines payara-micro artifact with its coordinates. Specified artifact should be available in local maven repository. |

|daemon | |payara.daemon | |PAYARA_DAEMON | |false | |Starts Payara Micro in separate JVM process and continues with the maven build. |

|immediateExit | |payara.immediate.exit | |PAYARA_IMMEDIATE_EXIT | |false | |If Payara Micro is executed in daemon mode, the executor thread will wait for the ready message before shutting down its process. By setting immediateExit to true you can skip this and instantly interrupt the executor thread. |

|javaHome | |payara.java.home | |PAYARA_JAVA_HOME | |java | |Absolute path to the java executable. This has higher priority to the java executable identified via the Maven toolchain. Note: Parameter javaPath is deprecated and has been replaced by javaHome to stay in sync with the Payara Server Maven Plugin. |

|deployWar | |payara.deploy.war | |PAYARA_DEPLOY_WAR | |false | |If the attached project is of type WAR, it will automatically be deployed if deployWar is set to true. |

|contextRoot | |payara.context.root | |PAYARA_CONTEXT_ROOT | |none | |Defines the context root of an application. |

|javaCommandLineOptions | | | |none | |Defines a list of command line options that will be passed to java executable. Command line options can either be defined as key-value pairs or just as list of values. key-value pairs will be formatted as key=value. |

|commandLineOptions | | | |none | |Defines a list of command line options that will be passed onto payara-micro. |

|hotDeploy | |payara.hot.deploy | |PAYARA_HOT_DEPLOY | |false | |Enables the Hot Deploy mode. |

|autoDeploy | |payara.auto.deploy | |PAYARA_AUTO_DEPLOY | |false | |Enables automatic compilation and deployment upon saving files. |

|liveReload | |payara.live.reload | |PAYARA_LIVE_RELOAD | |false | |Triggers a browser refresh for an up-to-date view after each redeployment. |

|browser | |payara.browser | |PAYARA_BROWSER | |none | |Specifies the browser for live reload. Adapted based on the system if not specified. |

|keepState | |payara.keep.state | |PAYARA_KEEP_STATE | |false | |Persists session state across multiple redeployments. |

|trimLog | |payara.trim.log | |PAYARA_TRIM_LOG | |false | |Refactors log format for improved readability. | |=== |

stop

Aim: This goal stops Payara Micro with the specified configuration. By default, this goal tries to find the currently executing Payara Micro instance by checking the running JAR.

If an artifactItem is defined, it will take precedence for identifying currently running instances. If processId is defined, this takes the highest precedence and the given processId will immediately kill the executing Payara Micro instance.

Usage: mvn payara-micro:stop

Example:

<plugin>
    <groupId>fish.payara.maven.plugins</groupId>
    <artifactId>payara-micro-maven-plugin</artifactId>
    <version>${payara.micro.maven.plugin.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <processId>32333</processId>
        <artifactItem>
            <groupId>fish.payara.extras</groupId>
            <artifactId>payara-micro</artifactId>
            <version>{page-version}</version>
        </artifactItem>
    </configuration>
</plugin>
If you want to execute the payara-micro plugin along with maven-toolchains-plugin, you need to execute the plugin as: mvn toolchains:toolchain payara-micro:start. See Using Toolchains for more information.
Configuration tags

|==== | |Element | |System Property | |Environment Variable | |Default | |Notes |

|processId | |payara.process.id | |PAYARA_PROCESS_ID | |none | |Process id of the running Payara Micro instance. |

|artifactItem | | | |none | |Defines payara-micro artifact with its coordinates. This information is used to identify the process id of the running Payara Micro instance. |

|useUberJar | |payara.use.uber.jar | |PAYARA_USE_UBER_JAR | |false | |Use the name of the created uber-jar that resides in target folder to identify the process id of the running Payara Micro instance. |

|uberJarClassifier | |payara.uber.jar.classifier | |PAYARA_UBER_JAR_CLASSIFIER | |microbundle | |Specifies the maven artifact classifier of the generated uber-jar to identify the process id of the running Payara Micro instance. |

|maxStopTimeoutMillis | |payara.max.stop.timeout.millis | |PAYARA_MAX_STOP_TIMEOUT_MILLIS | |5000 | |Defines the maximum timeout in milliseconds to wait for the process of Payara Micro instance to stop. | |==== |

reload

Aim: This goal reloads the Payara Micro application with the specified configuration. By default, this goal performs the vanilla deployment of the application without restarting the Payara Micro instance.

If hotDeploy is set to true then the Hot Deploy functionality will be enabled.

Usage: mvn payara-micro:reload

This goal is specifically designed for integration with the IDEs and Editors. Payara Micro instance allows IDEs to deploy the application in Hot Deploy mode by reusing the existing application instance and updating its classloader and internal components relative to the modified source.
This can lead to significant savings of time when an application is redeployed and boost developer productivity even more.
Configuration tags

|=== | |Element | |System Property | |Environment Variable | |Default | |Notes |

|hotDeploy | |payara.hot.deploy | |PAYARA_HOT_DEPLOY | |false | |Enables the Hot Deploy mode. |

|sourcesChanged | |payara.sources.changed | |PAYARA_SOURCES_CHANGED | |none | |Defines a list (comma separated) of the absolute paths to the source file which need to be reloaded via the Hot Deploy feature. |

|metadataChanged | |payara.metadata.changed | |PAYARA_METADATA_CHANGED | |false | |If set to true, reloads deployment descriptors metadata in Hot Deploy mode |

|keepState | |payara.keep.state | |PAYARA_KEEP_STATE | |false | |Persists session state across multiple re-deployments. | |=== |

dev

Aim: The dev goal is designed to streamline development by enabling deployWar, exploded, autoDeploy, liveReload, keepState, and trimLog to true, which facilitating auto compilation and deployment on saving files resulting in rapid compilation, and deployment for an efficient development workflow.

Usage:

mvn payara-micro:dev

The dev goal is an extended goal of start and is pre-configured for developing web applications in development mode which is equivalent to starting the Payara Micro instance using the following command:

mvn payara-micro:start -DautoDeploy=true -DliveReload=true -DdeployWar=true -Dexploded=true -DkeepState -DtrimLog=true

Features in Dev Mode:

  1. Auto Deploy: The AutoDeploy feature enables automatic compilation and deployment of the application upon saving files within the project structure. Enabled by setting autoDeploy=true.

    The AutoDeploy feature relies on Java’s WatchService to monitor changes in source directories, enabling continuous build and reload using Maven’s Invoker. It dynamically modifies Maven goals based on file modifications, supports asynchronous execution for concurrent build tasks, and includes specifics for tracking changes in source, resources, and test directories.

    The AutoDeploy feature has a limitation and is not supported for pom.xml, pre-boot-commands.txt, post-boot-commands.txt, or post-deploy-commands.txt.

  2. Restart on modifying boot command scripts: The restart functionality in dev mode enables a seamless instance restart upon modifications to the boot command scripts pre-boot-commands.txt, post-boot-commands.txt, or post-deploy-commands.txt, offering a quick server restart option for improved development efficiency.

    Modifying the pom.xml is not supported in this context, as limitations may arise when restarting with a modified pom.xml, potentially conflicting with previously passed properties via the command line.

  3. Live Reload: The LiveReload feature automatically refreshes the browser upon redeployment.

    • liveReload Property: Enables or disables automatic browser refresh on redeployment. The liveReload property is set to true by default in the dev goal and false in the start goal.

    • browser Property: The browser property offers seamless configuration. If not specified, the system prioritizes Chrome and Firefox, gracefully falling back to Edge for Windows, Safari for macOS, or Firefox for other platforms. This improvement simplifies setup - no need to worry about specifying a browser; it adapts based on your system.

    • Cached Last Accessed URL: The last accessed Payara Micro URL is stored in the payara-maven-config.properties file within the system’s temporary directory. This ensures accessibility across application restarts, eliminating the need for users to manually navigate to the last accessed URL. This streamlined approach enhances the overall user experience by maintaining continuity and reducing manual intervention after each restart.

  4. Persistent Session State: The keepState property allows for the persistence of session state across multiple re-deployments during the development process. Enabled by default in the dev goal and disabled in the start goal.

  5. Readable Logging: The trimLog property refactors the log format for improved readability. Enabled by default in the dev goal and disabled in the start goal.

All listed features are enabled by default in the dev mode.

Using Toolchains

The Maven Toolchains provide a way for plugins to discover what JDK (or other tools) are to be used during the build and Payara Micro Maven Plugin also supports using toolchains with its configuration.

In order to use the toolchains with either payara-micro:start or payara-micro:stop, first toolchains plugin should be defined as:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-toolchains-plugin</artifactId>
    <version>1.1</version>
    <executions>
        <execution>
            <goals>
                <goal>toolchain</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <toolchains>
            <jdk>
                <version>1.8</version>
                <vendor>oracle</vendor>
            </jdk>
        </toolchains>
    </configuration>
</plugin>

toolchains.xml is the file for configuring each toolchain, and it should reside under the .m2 folder. A sample would be as:

<?xml version="1.0" encoding="UTF8"?>
<toolchains>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.7</version>
            <vendor>oracle</vendor>
        </provides>
        <configuration>
            <jdkHome>/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home</jdkHome>
        </configuration>
    </toolchain>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.8</version>
            <vendor>oracle</vendor>
        </provides>
        <configuration>
            <jdkHome>/Library/Java/JavaVirtualMachines/jdk1.8.0_131.jdk/Contents/Home</jdkHome>
        </configuration>
    </toolchain>
</toolchains>

The version and the vendor defined in the plugins section should match one of the entries defined in the toolchains.xml file. After configuring the toolchain, the plugin can be executed with start and stop goals as:

mvn toolchains:toolchain payara-micro:start
mvn toolchains:toolchain payara-micro:stop