• 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 Applications
  • 4.1 Deploying an Application from the Command Line
    • 4.1.1 Deploying Multiple Applications from the Command Line
  • 4.2 Deploying Applications Programmatically
    • 4.2.1 Deploying an Application during Bootstrap
      • 4.2.1.1 Deploying Multiple Applications Programmatically during Bootstrap
    • 4.2.2 Deploying an Application Programmatically to Bootstrapped Instances
      • 4.2.2.1 Deploying an Application to Multiple Bootstrapped Instances 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. Payara Micro and Maven
• 9. Payara Micro HTTP and HTTPS Auto-Binding
• 10. Running Asadmin Commands on Bootstrapped Instances
• 11. Running Callable Objects on Bootstrapped Instances
• 12. Firing and Listening for CDI Events
• 13. Appendices
  • 13.1 Payara Micro Command Line Options
  • 13.2 Payara Micro API
    • 13.2.1 Configuration Methods
    • 13.2.2 Operation Methods
      • 13.2.2.1 Deployment Methods
        • 13.2.2.1.1 PayaraMicro.class Methods
        • 13.2.2.1.2 PayaraMicroRuntime.class Methods
      • 13.2.2.2 Setup and Shutdown Methods
        • 13.2.2.2.1 PayaraMicro.class Methods
        • 13.2.2.2.2 PayaraMicroRuntime.class Methods
      • 13.2.2.3 CDI Methods
      • 13.2.2.4 Run Methods
      • 13.2.2.5 Get Methods

This page shall cover how to use Payara Micro 4.1.152.1.

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).

The owning class of an API method will not be explicitly stated unless it is not clear if an instance has been started or not; methods that operate on Payara Micro instances before they have been bootstrapped (instances that have not yet been started) are contained in the PayaraMicro class, whereas methods that operate on bootstrapped instances (running instances) are contained within the PayaraMicroRuntime class.

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, see section 8 for instructions on importing this JAR with Maven):

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

You can then start an instance with default settings by calling the bootstrap() method 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.bootStrap();
    }    
}

To start an instance with non-default settings (configuration changes or deploying applications upon startup), you have to call the getInstance() method before using bootstrap(). More details on this can be found in the Configuring an Instance section. The use of the getInstance() method does not exclude you from using the default settings however; calling the bootstrap() method on its own (as shown in the example above) is functionally equivalent to calling the bootstrap() method directly after the getInstance() method, such as in the example below:

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

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

The bootStrap() method returns a PayaraMicroRuntime object instance, which is comes with various methods that afford you control over the instance and its cluster after you have bootstrapped it. To take advantage of this, you have to initialise a PayaraMicroRuntime object from the bootStrap method, like so:

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

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

This section details how to deploy applications.

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

This section details deploying applications from within your code.

There are two methods you can use to deploy an application during the bootstrapping process: 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();
    }
}

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();
    }
}

There are two methods available for deploying an application to a bootstrapped instance: deploy(File war) and deploy(String name, InputStream is).

The first works in the same way as the addDeploymentFile method described in section 4.2.1.

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

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        File war = new File("/home/user/deployments/");
        PayaraMicroRuntime instance = PayaraMicro.bootstrap();
        instance.deploy(war);
    }
}

The second method allows you to deplor WARs from an InputStream:

import fish.payara.micro.PayaraMicro;
import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicroRuntime;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.logging.Level;
import java.util.logging.Logger;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime instance = PayaraMicro.bootstrap();
        
        try (InputStream is = new FileInputStream("/home/user/test.war"))
        {        
            instance.deploy("test", is);
        }
        
        catch (IOException ex)
        {
            Logger.getLogger(EmbeddedPayara.class.getName()).log(Level.SEVERE, null, ex);
        }
    }
}

As an alternative to using the two methods above, you can use the run(Collection<InstanceDescriptor> members, String command, String... args ) method to run the deploy asadmin command. To deploy to a single instance, you must create a members Collection only containing a single instance.

As an example of deploying an application to only the local instance with the run command:

import fish.payara.micro.PayaraMicro;
import fish.payara.micro.BootstrapException;
import fish.payara.micro.PayaraMicroRuntime;
import fish.payara.micro.services.data.InstanceDescriptor;
import java.util.ArrayList;
import java.util.Collection;

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime runtime = PayaraMicro.getInstance().setHttpAutoBind(true).bootstrap();
        
        // Get a Collection with all running instances in the local runtime's cluster
        Collection<InstanceDescriptor> allInstances = runtime.getClusteredPayaras();       
        
        // Create a Collection to use as a subset
        Collection<InstanceDescriptor> subset = new ArrayList<>();
        
        // Loop through all instances
        for (InstanceDescriptor instance : allInstances)
        {
            // Only add the local instance
            if (instance == runtime.getLocalDescriptor())
            {
                subset.add(instance);
                break;
            }
        }

        // Run the deploy asadmin command on the subset Collection
        runtime.run(subset, "deploy", "/home/user/test.war");
    }
}

As noted to in the previous section, you can use the run method to run the deploy asadmin command on one or more clustered instances. There are two run methods available for running asadmin commands: one which runs an asadmin command on a subset of instances in a cluster, and another than runs an asadmin command on all instances in a cluster. More detail on these can be found in the Running Asadmin Commands on Bootstrapped Instances section.

As an example of deploying an application to all instances in a cluster:

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

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime runtime = PayaraMicro.getInstance().setHttpAutoBind(true).bootstrap();

        // Run the deploy asadmin command on all instances in the runtime's cluster
        runtime.run("deploy", "/home/user/test.war");
    }
}

See the previous section for an example on using the run method on a subset of instances in a cluster.

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. You can only configure an instance before it is bootstrapped however.

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 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 or PayaraMicroRuntime class.

The shutdown() method of the PayaraMicro class must be called 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();
    }
}

The shutdown() method of the PayaraMicroRuntime class is tied to an instance variable, so is used in much the same way:

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

public class EmbeddedPayara 
{
    public static void main(String[] args) throws BootstrapException 
    {
        PayaraMicroRuntime instance = PayaraMicro.bootstrap();

        instance.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.

Payara Micro has been uploaded to Maven central, allowing you to include it as a dependency in your POM. This allows you to easily add the required Payara Micro classes and methods to your application to use Payara Micro programmatically.

In your project's POM, include the following dependency:

<dependency>
    <groupId>fish.payara.extras</groupId>
    <artifactId>payara-micro</artifactId>
    <version>4.1.152.1</version>
</dependency>

Payara Micro supports an auto-binding feature for its HTTP and HTTPS port, allowing Payara Micro to dynamically find a free HTTP or HTTPS port as required during startup.

This feature is controlled through these three options:

• --autoBindHttp – Enables auto-bind functionality for the HTTP port
• --autoBindSsl – Enables auto-bind functionality for the HTTPS port
• --autoBindRange – Sets the range for the auto-bind feature

When auto-binding is enabled, Payara Micro will attempt to connect to the port specified with the --port or --sslPort option (or, if these options are not specified, to port 8080 and 8181 respectively), and if that port is busy, it will instead try to bind on the next port up, repeating this process until it finds a free port, or the --autoBindRange limiter is reached.

For example, if ports 8080, 8081, and 8181 were busy, and ports 8082 and 8182 were free, then starting Payara Micro with the following command would have the HTTP port bind to 8082 and the HTTPS port bind to 8182:

java -jar payara-micro.jar --autoBindHttp --sslPort 8181 --autoBindSsl

Whereas the following would fail to start in the same situation because --autoBindRange is not large enough (no free port within the range of 8080-8081):

java -jar payara-micro.jar --port 8080 --autoBindHttp --sslPort 8181 --autoBindSsl --autoBindRange 1

Be aware that the auto-bind feature does not currently read port values from domain.xml files; if the --port and --sslPort options are not used, then the --autoBindHttp and --autoBindSsl options will assume that the HTTP and HTTPS ports will be at the default values of 8080 and 8181 respectively.

There are two methods available for running asadmin commands, both named run.

The first, run(String command, String... args ), runs the specified asadmin command on all instances in a runtime's cluster. It returns a Map<InstanceDescriptor, Future<ClusterCommandResult>>, as detailed in the appendices.

The second, run(Collection<InstanceDescriptor> members, String command, String... args ), runs the specified asadmin commond on all instances contained in the Collection supplied. It returns a Map of the same type as the other run method. You can use the

Examples on using the first and second methods can be seen in sections 4.2.2 and [4.2.2.1](#4221-deploying-an-application-to multiple-bootstrapped-instances-programmatically) respectively. The first example shows one way in which you can construct a Collection containing a subset of the running instances in a cluster using the getClusteredPayara() method to get the InstanceDescriptor identifiers.

Like with running asadmin commands, there are two methods available for running Callable objects, both also named run.

The two methods also work in a similar way to the two asadmin run methods: the first, run(Callable<T> callable), runs the specified Callable on all instances in a runtime's cluster, and the second, run(Collection<InstanceDescriptor> members, Callable<T> callable), runs the Callable on a subset of the instances in a runtime's cluster. Both return a Map with a key/value type of <InstanceDescriptor, Future<T>>, where the type variable T is Serializable.

Payara Micro has the ability to listen for and fire CDI events across the cluster of a PayaraMicroRuntime instance.

You can view the methods associated with CDI Events in the appendices.

This section contains documentation on the Payara Micro API.

This section details the PayaraMicro.class configuration methods that are used during the bootstrap process.

This section details the other methods of the Payara Micro API that operate Payara Micro instances. PayaraMicro.class methods are used during the bootstrap process, whereas PayaraMicroRuntime.class methods are used on running instances.

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

Method | Description | Command Line Equivalent --- | --- | --- | --- PayaraMicro addDeployment(String pathToWar) | Adds the file found at the location of the pathToWar parameter to the list of files to be deployed upon starting the instance. | --deploy PayaraMicro addDeploymentFile(File file) | Adds the file associated with the file parameter to the list of files to be deployed upon starting the instance. | --deploy

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

This section details the methods used for firing CDI Events across running instances.

This section details the methods used for running asadmin commands or Callable objects on bootstrapped instances.

This section details the methods used for getting information on running Payara Micro instances. For information on the Get methods of an un-bootstrapped instance, see the Configuration Methods section.