• 1. Overview
• 2. Documentation Conventions
• 3. Starting an Instance
  • 3.1 Starting an Instance from the Command Line
  • 3.2 Starting an Instance Programmatically
• 4. Deploying an Application
  • 4.1 Deploying an Application from the Command Line
    • 4.1.1 Deploying Multiple Applications from the Command Line
  • 4.2 Deploying an Application Programmatically
    • 4.2.1 Deploying Multiple Applications Programmatically
• 5. Configuring an Instance
  • 5.1 Configuring an Instance from the Command Line
  • 5.2 Configuring an Instance Programmatically
• 6. Stopping an Instance
  • 6.1 Stopping an Instance from the Command Line
  • 6.2 Stopping an Instance Programmatically
• 7. Payara Micro Automatic Clustering
• 8. Appendices
  • 8.1 Payara Micro Command Line Options
  • 8.2 Payara Micro API
    • 8.2.1 Configuration Methods
    • 8.2.2 Operation Methods
      • 8.2.2.1 Deployment Methods
      • 8.2.2.2 Setup and Shutdown Methods

This page shall cover how to use Payara Micro 4.1.152.

Payara Micro is an embedded release of Payara built from the Payara Embedded Web release. It allows you to deploy and run WAR files from the command line with a single command, and also features automatic, dynamic clustering with Hazelcast.

Any commands listed will be written assuming they are being run from the same directory as the Payara Micro JAR file.

Any commands listed will also be written assuming that the system environment variables have been set up to have Java on the system Path.

Any paths listed throughout the documentation will use the Unix/Linux file path structure (forward slashes).

This section details the very basics of starting an instance.

To start an instance of Payara Micro from the command line, you simply run the JAR:

java -jar payara-micro.jar

This single command is all you need to run Payara Micro instances; additional configuration options are all a part of this command.

You need to import two classes from the fish.payara.micro package (contained in the Payara Micro JAR):

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

You can then start an instance by calling the getInstance() and bootstrap() methods from the PayaraMicro class. This initialisation will throw a BootstrapException exception, so you will need to surround it with a try-catch, or have the parent method throw the exception.

A simple example is as follows:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{ 
    public static void main(String[] args) throws BootstrapException
    {   
        PayaraMicro.getInstance().bootStrap();
    }    
}

This section details how to deploy an application.

As noted in section 3.1, all Payara Micro actions are run for the Payara Micro JAR, all in one command; it is not possible to start an instance with one command, and deploy an application to it with another.

The general structure of starting, configuring, and deploying an application to an instance is as follows:

java -jar payara-micro.jar _--option1_ _--option2_ ...

To deploy a WAR file to an instance, you need to use the --deploy option, followed by the path to the application to deploy. See below for an example of starting a Payara Micro instance and deploying a WAR file:

java -jar payara-micro.jar --deploy /home/user/example.war

If you want to deploy multiple applications to an instance with the ``--deploy` option, you must use it once for each application to be deployed; it does not accept multiple paths.

For example, to deploy two applications:

java -jar payara-micro.jar --deploy /home/user/example.war --deploy /home/user/test.war

Alternatively, you can use the --deploymentDir option. This option specifies a directory to scan for deployable archives, allowing you to store all of the applications you wish to be deployed in a directory, and have them be deployed automatically upon instance startup.

java -jar payara-micro.jar --deploymentDir /home/user/deployments

There are two methods you can use to deploy an application: addDeployment(String pathToWar), and addDeploymentFile(File file).

The first, addDeployment(String pathToWar), accepts a String that points to the path of the file to be deployed. For example:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro.getInstance().addDeployment(/home/user/example.war).bootStrap();
    }
}

The second method, addDeploymentFile(File file), functions in the same way as the addDeployment(String pathToWar) method, but takes a File object as its parameter instead:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;
import java.io.File;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        File file = new File("/home/user/example.war");
        PayaraMicro.getInstance().addDeploymentFile(file).bootStrap();
    }
}

Unlike when controlling Payara Micro from the command line, you can split the instance initialisation and configuration across multiple lines methods. For example, to deploy an application on one line, and start the instance on another:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.addDeployment("/home/user/example.war");
        micro.bootStrap();
    }
}

You cannot, however, configure an instance any further once it has been started (with the bootstrap() method).

Similar to when deploying multiple applications from the command line, you must use call the addDeployment or addDeploymentFile method for each application you wish to deploy.

For example, to deploy three applications:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        
        micro.addDeployment("/home/user/example.war");
        micro.addDeployment("/home/user/test.war");
        micro.addDeployment("/home/user/three.war");
        
        micro.bootStrap();
    }
}

Alternatively, you can use the programmatic equivalent of the --deploymentDir command line option (described in section 4.1.1): the setDeploymentDir(File deploymentRoot) method:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;
import java.io.File;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        File deployments = new File("/home/user/deployments/");
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.setDeploymentDir(deployments);
        micro.bootStrap();
    }
}

This section details how to configure a Payara Micro instance.

As described in section 4.1, the starting and configuration of an instance has to be done in its entirety on one line.

The options available can be seen by running the JAR with the --help option, or by consulting the Payara Micro Command Line Options section in the Appendices.

The general structure of starting, configuring, and deploying an application to an instance is as follows:

java -jar payara-micro.jar _--option1_ _--option2_ ...

As an example, see below for starting an instance with a non-default HTTP port:

java -jar payara-micro.jar --port 2468

There are various methods available for configuring a Payara Micro instance programmatically.

The configuration methods available to you should be detected by your IDE, allowing you to view them using the auto-complete feature common to most popular IDEs. Alternatively, you can consult the Payara Micro Configuration Methods section in the Appendices.

As noted before, in the Deploying an Application Programmatically section, you can either call the desired configuration commands on one line during instance initialisation, or on separate lines after creating a PayaraMicro variable.

As also noted in the same section: you cannot configure an instance any further once it has been bootstrapped.

As an example of configuring an instance to use a different HTTP and Cluster start port on one line, see here:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro.getInstance().setHttpPort(2468).setClusterStartPort(5902).bootStrap();
    }
}

For the example of the same, but done across multiple lines, see here:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.setHttpPort(2468);
        micro.setClusterStartPort(5902);
        micro.bootStrap();
    }
}

This section describes how to shut down a Payara Micro instance.

There is no specific option for shutting down a Payara Micro instance. The only way to shut down an instance from the command line is to find the process ID of the Payara Micro instance, and send a kill signal to it.

To shut down a Payara Micro instance programmatically, you will need to use the shutdown() method of the PayaraMicro class.

You must call this method specifically on the instance of Payara Micro that you want to shut down, so will realistically only be used on a PayaraMicro instance variable:

import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicro;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicro micro = PayaraMicro.getInstance();
        micro.bootStrap();
        
        micro.shutdown();
    }
}

This section details how the Payara Micro automatic clustering works.

The integration of Hazelcast into Payara Micro allows instances to automatically, and dynamically, cluster together. When two instances are pointed at the same multicast address and port, they will automatically cluster together.

You can see evidence of the automatic clustering by simply starting two instances (with different HTTP port configurations), and you should see the following in the log output:

Members [2] {
        Member [192.168.174.130]:5900 this
        Member [192.168.174.130]:5901

The --startPort option is used to determine which port the Payara Micro instance will first try to bind to, if the port is already bound to (say, by another Payara Micro instance), then the Payara Micro instance will simply increment the startPort value and try again until it finds a port it can bind to.

For example, if there are already two Payara Micro instances running, which have bound ports 5900 and 5901, then a third instance started with a startPort value of 5900 will first try to bind to 5900, then to 5901, then finally settle on 5902.

If you wish to have multiple clusters, then you can make use of the --mcAddress and ``mcPort` options to define a different multicast address and port; assign a different address and port to each set of instances you wish to operate in a separate cluster and they will automatically make their own cluster on the new multicast address and port.

This section contains documentation on the Payara Micro API.

This section details the instance configuration methods of the Payara Micro API.

This section details the other methods of the Payara Micro API that operate Payara Micro instances.

This section details the methods used for the deployment of applications to Payara Micro instances.

This section details the methods required for setting up Payara Micro instances.

Method | Description void bootStrap() throws BootstrapException | Checks the supplied configuration parameters and starts a Payara Micro instance. PayaraMicro getInstance() | Obtains the static singleton instance of the Payara Micro server. If one does not exist, one will be created and returned. PayaraMicro getInstance(boolean create) | Obtains the static singleton instance of the Payara Micro server. If one does not exist and create is set to true, one will be created and returned, otherwise returns null. void shutdown() throws BootstrapException | Stops and shuts down the Payara Micro instance.