Payara Server Documentation Fork

Table
of Contents
General Info
Introduction 1.1
General Info 1.2
Getting Started 1.3
Build Instructions 1.4
Release Notes 1.5
Payara Server 4.1.1.163 Release Notes 1.5.1
Technical Documentation
Core Documentation 2.1
JACC 2.1.1
Extended Documentation 2.2
Application Deployment 2.2.1
Deployment Descriptor Files 2.2.1.1
Elements of the Decriptor Files 2.2.1.2
Advanced JDBC 2.2.2
Log JDBC Calls 2.2.2.1
Slow SQL Logger 2.2.2.2
SQL Trace Listeners 2.2.2.3
JBatch 2.2.3
JCache 2.2.4
Hazelcast 2.2.5
Health Check Service 2.2.6
Asadmin Commands 2.2.6.1
Configuration 2.2.6.2
Notification Service 2.2.7
Request Tracing Service 2.2.8
1
Asadmin Recorder Service 2.2.9
JMX Monitoring Service 2.2.10
Phone Home 2.2.11
System Properties 2.2.12
Classloading 2.2.13
Production Ready Domain 2.2.14
User Guides 2.3
Payara Server Domain Backup 2.3.1
Restore a Payara Server Domain 2.3.2
Upgrade Payara Server 2.3.3
Payara Micro Documentation 2.4
Starting an Instance 2.4.1
Deploying Applications 2.4.2
From the Command Line 2.4.2.1
Programmatically 2.4.2.2
During Bootstrap 2.4.2.2.1
To a Bootstrapped Instance 2.4.2.2.2
Using an asadmin Command 2.4.2.2.3
From a Maven Repository 2.4.2.2.4
Configuring an Instance 2.4.3
From the Command Line 2.4.3.1
Programmatically 2.4.3.2
Packaging as an Uber Jar 2.4.3.3
Via System Properties 2.4.3.4
Alternate Keystores for SSL 2.4.3.5
Stopping an Instance 2.4.4
Automatic Clustering 2.4.5
Maven Support 2.4.6
HTTP(S) Auto-Binding 2.4.7
2
Running asadmin Commands 2.4.8
Running Callable Objects 2.4.9
Logging to a file 2.4.10
Remote CDI Events 2.4.11
Payara Micro Appendices 2.4.12
Command Line Options 2.4.12.1
Payara Micro API 2.4.12.2
Configuration Methods 2.4.12.2.1
Operation Methods 2.4.12.2.2
Javadoc 2.4.12.2.3
Appendices
History of Release Notes 3.1
Payara Server 4.1.1.161.1 Release Notes 3.1.3
Payara Server 4.1.153 Release Notes 3.1.6
3
Introduction
Payara Server began life in 2014, derived from GlassFish 4.1. Since then, Payara Server
has been refined with bug fixes, enhanced with new features, and has grown a strong
community following. The documentation here will be updated with all the significant
changes made with each new release.
Payara Server Documentation
The documentation of Payara Server edition. Consists of basic information, features

shared with GlassFish 4, and additional features
User Guides
Useful guides and tutorials
Payara Micro Documentation
The documentation of Payara Micro edition
Payara Server is released on a quarterly cadence and versioned with the year and quarter
number to reflect that:
2016 Q3 - Payara Server 4.1.163


4
Introduction
5
General Info
Welcome to the Payara wiki General

Information Page!
This page provides some general information about the Payara Project.
Release Strategy
Payara has a release every quarter. Each release incorporates fixes and enhancements
from the Payara team, GlassFish upstream, and the community.
Naming Strategy
The payara naming strategy works off of the pre-existing GlassFish Strategy. The Payara
naming strategy is to append the year and quarter as the final dot version of the release. For
example, for the Payara release built on GlassFish 4.1, released in quarter 3 of 2015, the
version number would be payara-4.1.153.
In the case of updates, we will simply attach an additional point number to the end of the
version number described above. For example, if a patch is released for Payara 4.1.152, the
version number would be 4.1.152.1. This will be in addition to any extra point releases that
Oracle do for GlassFish, so it's possible for a version number to be something like
4.1.1.152.1!
Releases will also have a name attached to the release. For example, the name attached to
Payara 4.1.152 is #badassfish.
6
General Info
Work Strategy
From Payara 4.1.152 onwards, we will be implementing a strategy concerning pulling in
changes from the GlassFish upstream, and to making changes late into a release's
development time.
Change Freeze
Two to three weeks before a release, we will implement a change freeze. This means that
no new features or changes will go into the coming release of Payara. The remaining two to
three weeks will be used for finding any bugs brought on by changes and fixes implemented
for the coming release. If any bugs are found, these will be corrected before the release; if
we can't fix it before the release date, we will simply revert the change that caused the bug
(pending a review).
GlassFish Upstream Cherry-Pick

We aim to do three cherry picks from the GlassFish upstream for each release: just after a
release; at the beginning of the penultimate month of the release; and again at the beginning
of the final month of the release (before the change freeze). This to allow us time to find and
fix any errors that may be brought in from the GlassFish upstream.
If a bug fix is committed to the GlassFish upstream during our change freeze, we will
consider pulling in that solitary commit before the release.
GitHub
The Payara project is hosted on GitHub, allowing us to make use of the various tools GitHub
has integrated for managing projects. GitHub also makes allowing the community access to
view and edit the source code very easy and public.
How to Contribute
We make use of the Fork and Pull model (see here: https://help.github.com/articles/using-
pull-requests/). This means that if you want to make any changes, you'll need to fork the
Payara project and make your changes in your own repository. You will then need to create
a pull request back into the Payara project's master branch to merge your changes into the
main project.
7
General Info
Before we merge your pull request though, you must read and sign the Individual Contributor
License Agreement (CLA) before sending it to us at the address specified on the document,
or as an email attachment to info@payara.co.
Once we've received the CLA and checked it for any mistakes, we'll allow any pull requests
you've made to start being merged.
In most cases, pull requests will not be merged immediately. This is to allow the Payara
team, and other members of the community, to review and dliberate over any of the changes
made; we will typically wait 2-3 days before merging any pull requests.
Issue Tracking
We make use of GitHub's integrated issue tracker to allow the community to create
enhancement and bug fix requests. The only requirements to create a bug fix or
enhancement request is a GitHub account, and a reproducible bug or idea for an
enhancement; you do not need to sign the CLA to create an enhancement or bug fix
request.
Someone on the Payara team, or someone from the community, will then investigate and
converse with you about the enhancement request or bug.
We also attach labels and milestones to issues to help both us, and the community, search
through and track issues.
Documentation
We make use of GitHub's in-built wiki to store and host our technical documentation about
Payara, as well as general information (such as this document) about the Payara project.
For technical documentation, we only store documentation that we have written, which
typically pertains to new or modified features and commands made by us or the community;
we do not host GlassFish documentation, nor will we rewrite it for unmodified modules.
8
Getting Started
Contents
1. Overview
2. Downloading Payara Server
3. Starting Payara Server
4. Accessing the Administration Console
5. Deploying an Application
5.1 Deploying using Asadmin
5.2 Deploying using Administration console
1. Overview
This page covers how to download Payara Server, start Payara Server, access the
Administration Console, deploy an application and how to access the deployed application.
2. Downloading Payara Server

Payara Server can be downloaded from (http://www.payara.fish/downloads). Download to a
directory of your choosing and then unzip. On Linux based systems you can use the
following command:
3. Starting Payara Server

To start Payara Server, execute the following command:
$ Payara_installed_directory/bin/asadmin start-domain
This will start domain1, which is the default domain included with Payara Server. If you
wanted to start a different domain, the domain name would need to be specified. An
example can be seen below:
$ asadmin start-domain your_domain_name
4. Accessing the Administration Console
9
Getting Started
Once the server is up and running, type this URL http://localhost:4848 in your browser to
access the Administration Console. This is the default URL for accessing the Administration
Console.
5. Deploying an Application
In order for a web application to run, it must be first deployed on an application server such
as Payara Server.
5.1 Deploying using Asadmin

To deploy a WAR file, you need to use the deploy option , followed by the path to the
application to deploy. See below for an example of deploying a WAR file:
$ Payara_installed_directory/bin/asadmin deploy your_application.war
5.2 Deploying using Administration console

Access the Administration Console by navigating to http://localhost:4848 (make sure a
domain is running beforehand)
Click on Applications under the heading Common Tasks pane on the left side of the
page.
Any deployed applications are listed here. Since there are none right now, click on
Deploy.
The current display should be the Deploy Applications or Modules page. Select
Packaged File to be uploaded to the Server and click browse. Navigate to where your
application is located, select the file and click Open. You should be returned to the same
page with some settings listed.
Change any settings if needed otherwise accept the default settings and click ok to be
returned to the applications page. Your application should now be listed.
Finally, under the action tab click launch. The default URL for application is
http://localhost:8080/ your_application .
10
Build Instructions
Welcome to the Payara wiki Build Instructions

Page!
This page provides instructions on how to build the Payara source code.
Prerequisites
To build and run Payara, your environment must be set up with the following:
Oracle JDK 7 Update 65 or later, or Oracle JDK 8 Update 20 or later.

Maven 3.0.3 or above
Git
A JAVA_HOME environment variable pointing to the JDK install location (e.g.
/home/user/jdk11.8.0_45/)
A PATH environment variable that has a pointer to the Java binaries (JAVA_HOME/bin)
You can also optionally add the Maven bin folder to the PATH environment variable as well,
and the documentation will assume that you have done so.
Configuring Maven
If using JDK 7, you will need to increase the heap size and PermGen size to prevent the
build process from running out of memory.
Create a MAVEN_OPTS environment variable and set it as:
11
Build Instructions
-Xmx1024m -XX:MaxPermSize=512m
If using JDK 8, PermGen has been replaced by Metaspace, which can increse its maximum
size on its own, so you only need to increase the heap size:
-Xmx1024m
Getting the Source Code

To download the Payara source code, open a terminal or Git Bash window, navigate to the
directory you would like the source code to be downloaded to, and run git clone
https://github.com/payara/Payara.git .
This will download the Payara source code, and initialise git, in a directory called Payara.
Building Payara
With your Git Bash or terminal window, navigate into the downloaded Payara directory, and
run:
mvn clean install
This will build Payara and run the integrated GlassFish unit tests. To save a bit of time, you
can skip these tests by appending the skipTests flag to the install command like so:
mvn clean install -DskipTests
Building Payara Micro

To save some time on the main build Payara Micro is not automatically built from the top
level maven project. To build Payara Micro you must previously build the full Payara as
described above. Once that has been built
cd appserver/extras/embedded/payara-micro
mvn clean install -DskipTests
After the build has completed the Payara Micro jar is in the target directory.
12
Build Instructions
13
Release Notes
Release notes
Detailed information about features and fixes in every release.
All Release Notes

2016
2016 Q3 - Payara Server 4.1.1.163

2016 Q2 - Payara Server 4.1.1.162
2016 Q1 - Payara Server 4.1.1.161.1
2016 Q1 - Payara Server 4.1.1.161
2015
2015 Q4 - Payara Server 4.1.1.154

2015 Q2 - Payara Server 4.1.152.1
2014
14
Payara Server 4.1.1.163 Release Notes
Release Highlights
The 163 release of Payara will feature a couple of new tech previews. These are new
features added to Payara which we do not recommend are used on production systems.
Request Tracing is a new service that will allow Payara to track and log information about
the requests it handles. Payara now offers a JMX Monitoring Service. Once configured,
Payara Server will monitor and log the values of attributes that have been listed for
monitoring.
Updated Modules
ibm.jbatch.container.version 1.0.1.payara-p2
Hazelcast 3.6.4
Grizzly 2.3.25
mimepull 1.9.6
javax.batch-api.version 1.0.1
jbatch.container.version 1.0.1
jbatch.spi.version 1.0.1
Weld 2.3.5.Final
Tyrus 1.13
New Features
This section details the newly developed additions to Payara Server.
PAYARA-168 - Integrate HealthCheck notifications with the Notification Service

PAYARA-612 - Create a general notification service
856/PAYARA-186 - Hazelcast Based EJB Persistent Timer Store for Payara Micro
857/PAYARA-592 - Monitoring for Concurrent Resources
939/PAYARA_174 - Initial Tech Preview implementation of Request Tracing
975/PAYARA-811 - Monitor agent to write JMX metrics to file periodically
977/PAYARA-180 - CDI Interceptor api that can be used to wrap any CDI call to be
traced by Request Tracing
Enhancements
15
This section details the issues marked as enhancements that have been implemented for
this release.
PAYARA-177 - Trace EJB Method Calls

PAYARA-183 - asadmin commands to configure and control request tracing
PAYARA-697 - Create Notification Service Log Notifier
PAYARA-757 - Request tracing of outbound WebService calls
PAYARA-758 - Request tracing of outbound REST calls
754/PAYARA-755 - Request tracing support for WebSockets
787/PAYARA-729 - Send Payara access logs to stdout/stderr
820/PAYARA-740 - Add a --version option to Payara Micro
836/PAYARA-746 - Add validation to prevent you entering a negative value for
fish.payara.jts.RecoveryResynchTimeout property
851/PAYARA-754 - Add extra output location validation for the Asadmin Recorder
service
855/PAYARA-827 - JTA Transaction Timer Thread should be named
859/PAYARA-791 - server.log file empty for Payara micro
862/PAYARA-823 - DataSource is silently defaulted to jdbc/__default on any lookup
failure
865/PAYARA-683 - When EAR is deployed, it is not possible to see details of EJB
modules in admin console
891/PAYARA-184 - Admin Console Integration for configuration of request tracing
894/PAYARA-848 - Admin Console Integration for configuration of Notification Service
897/PAYARA-169 - Admin Console integration to display Notifications on server tab
903/PAYARA-628 - Move Hazelcast and JBatch configuration into the tree view rather
than its current location on the tab view. Only members should be on the tab view.
905/PAYARA-796 - Add license key field for Payara Scales
913/PAYARA-845 - Add option to disable the Server Header
915/PAYARA-832 - Create new version identifier for Payara Blue
916/PAYARA-847 - Change the thread-pool for the Admin HTTP listener in a cluster
environment
924/PAYARA-859 - Request for finer-grained slow sql logger with miliseconds
934/PAYARA-839 - Disabled apps have no contextRoot param after restart
943/PAYARA-909 - healthcheck commands do not accept configurations as a target
947/PAYARA-927 - Merge two Request Tracing Service configuration page into one
950/PAYARA-928 - Merge two Notification Service configuration page into one
957/PAYARA-926 - Request Tracing for EJB Timers
968/PAYARA-851 - Access logging command line option for Payara Micro
970/PAYARA-731 - Shrink the Payara Micro Jar
974/PAYARA-836 - Allow user to use their own logging.properties file for Payara Micro
975/PAYARA-771 - Create asadmin commands for the monitoring logger
16
943/PAYARA-909 - healthcheck commands do not accept configurations as a target
Fixed Issues
This section details the issues marked as bugs that have been fixed for this release.
Payara Fixes
This section details the fixes implemented by the Payara team or community.
244/PAYARA-470 - JTS recovery hangs for the full length of the recovery timeout and
then succeeds
PAYARA-580 -Investigate Closed Entity Factory possible bug
PAYARA-682 - Properties substitustion does not work when EJB module with
application-scoped datasource is deployed
794/PAYARA-776 - Windows service is named "domain1 GlassFish Server"
798/PAYARA-775 - Unwrapping principal interferes with JASPIC's register session
799/PAYARA-710 - Fix CVE-2012-2098
807/PAYARA-643 - The JMS Availability tab contains a deep link to Oracle docs
808/PAYARA-594 - Spurious AllPermission warning
812/PAYARA-382 - Fix GitHub issue 384 spurious SEVERE log message when
deploying WebService
816/PAYARA-742 - Eclipselink generates broken SQL for Informix
822/PAYARA-355 - thousands of ClassNotFound warnings while deploying an EAR with
many WAR's
825/PAYARA-800 - Payara Micro Maven Deployer gives a FileNotFoundException
828/PAYARA-794 - NPE in LazyBootPersistenceManager if configured JNDI name does
not point to a valid datasource
829/PAYARA-803 - No LoginModules configured for jdcbRealm on Payara Micro
831/PAYARA-802 - Payara Domain is missing -Djavax.xml.accessExternalSchema=all
834/PAYARA-799 - The exception: "java.lang.IllegalArgumentException: PWC2788:
setAttribute: Non-serializable attribute" will occur when a web-fragment.xml with is
found
835/PAYARA-724 - The admin console does not render escape characters on the log
levels page
837/PAYARA-639 - Weld NPE when invalidating sessions
845/PAYARA-664 - NullPointerException during WebDirContext.lookupFromJars
probably caused by race conditions
847/PAYARA-734 - Admin console should spit out a warning if JMS destination name
contains a forward slash
17
852/PAYARA-795 - Payara Blue on IBM JDK invalid JVM options

854/PAYARA-826 - ClassNotFoundException with JSR107 annotations on stateless
session bean
867/PAYARA-821 - JoinFetch annotation in EclipseLink ignores default
889/PAYARA-808 - j-interop-repackaged.jar is missing in Payara Server 162
893/PAYARA-853 - thread pool statistics counters not correct
899/PAYARA-852 - New admin console design doesn't display on Chinese, Japanese
and korean
908/PAYARA-863 - Payara no longer starts in windows
920/PAYARA-900 - NPE in Payara Micro when --noCluster
922/PAYARA-889 - Hazelcast not booting when started from the Configurations.
925/PAYARA-903 - Error message for config validator gives incorrect property
926/PAYARA-810 - Group principal not evaluated in WS-Security context
933/PAYARA-911 - asadmin requesttracing-configure command not working when
threshold values not explicitly specified
935/PAYARA-904 - asadmin fails on add-resources when creating a jdbc pool with
connection validation
948/PAYARA-908 - asadmin healthcheck-configure-service failing on remote standalone
instance without optional parameters
952/PAYARA-869 - Batch job xml file in META-INF/batch-jobs folder is not closed after
executing batchlet
953/PAYARA-901 - Fix CVE-2016-3092
958/PAYARA-893 - Payara Micro and embedded contains different classes for jboss
logging than Payara Server
964/PAYARA-870 - Notification Service isn't dynamic
967/PAYARA-945 - Race condition on restart command
973/PAYARA-841 - Malformed SQL Query caused by EclipseLink @JoinFetch with
Table per class inheritance and secondary tables
988/PAYARA-960 - RequestTraceTest fails on Windows
990/PAYARA-961 - Set-monitoring-configuration delete property not working if property
is last item in list
991/PAYARA-962 - Get-monitoring-configuration using --pretty output by default
993/PAYARA-965 - Notification or RequestTracing Service does not seem to be
dynamic
997/PAYARA-951 - Admin Console does not prevent you setting the Request Tracing
Threshold to less than 0
1002/PAYARA-968 - Notification starting incorrectly from the Configurations.
1003/PAYARA-967 - Request tracing starting incorrectly from the Configurations.
1007/PAYARA -970 - Validation on Request Tracing service "thresholdUnit" value.
1008/PAYARA-816 - Fix JAXWS Tests in Payara Blue
18
1011/PAYARA-953 - Fix CVE-2016-3607

1012/PAYARA-986 - Add -configuration suffix to the set commands of both request
tracing and notification service.
Upstream Fixes
There have been no upstream fixes brought in for this release.
Known Issues
Known issues can be seen on our GitHub issues page here:
https://github.com/payara/Payara/issues
19
Core Documentation
Core Documentation
Documentation of core features, shared with GlassFish Server 4 Open Source Edition.
References
GlassFish Server 4 Open Source Edition documentation
20
JACC
Core Documentation
JACC stands for Java Authentication Contract for Containers. It's defined in JSR 115 and all
Java EE complaint servers are mandated to provide a default JACC Policy.
How to install a custom JACC provider

Having coded a JACC provider, the first thing to register it is to make the classes available
for the server. For that purpose, you need to put the implementation JAR, with all its
dependencies, under [payara_home]/lib . So for example, if Payara Server is installed under
/opt/payara , your JAR should reside under /opt/payara/lib . That way it will be part of
Payara's global classpath on boot.
The next thing to do is to tell Payara you want to use that specific JACC provider. For that
purpose, you have to execute the following commands in the asadmin CLI: create-jacc-
provider --
policyConfigurationFactoryProvider=com.example.CustomPolicyConfigurationFactory --
policyProvider=com.example.CustomPolicy --target=server-config custom-provider set
configs.config.server-config.security-service.jacc=custom-provider
create-jacc-provider --policyConfigurationFactoryProvider=com.example.CustomPolicyConf
igurationFactory --policyProvider=com.example.CustomPolicy --target=server-config cust
om-provider
set configs.config.server-config.security-service.jacc=custom-provider
These will result in the following domain.xml snippet to be added:
<security-service jacc="custom-provider">
<jacc-provider policy-provider="com.example.CustomPolicy" name="custom-provider" p
olicy-configuration-factory-provider="com.example.CustomPolicyConfigurationFactory"></
jacc-provider>

</security-service>
As you can derive from the XML excerpt, more JACC providers can be defined (by default,
simple and default are already defined), but only one will be used at runtime, specified
by the jacc attribute on the security-service element.
21
JACC
22
Extended Documentation
Extended Documentation
Documentation of all the features added on top of GlassFish Server 4 Open Source Edition.
23
Application Deployment
Application Deployment
You can deploy the applications to Payara Server in the same way as to GlassFish Server
4.1 Open Source Edition. Payara Server does not modify this process, it only adds some
improvements, so it is safe to refer to the GlassFish Server Application Deployment guide in
GlassFish Server 4 Open Source Edition documentation
This section describes additional improvements added by Payara Server.
24
Deployment Descriptor Files
Payara Server Deployment Descriptor

Files
Payara Server supports additional configuration in some GlassFish Server descriptor files.
The additional supported elements are listed here.
glassfish-application.xml
glassfish-application
classloading-delegate
enable-implicit-cdi
25
Elements of the Decriptor Files
Elements of the Deployment Decriptor

Files
classloading-delegate
With this option, the libraries included in the EAR assembly will override libraries included in
Payara Server distribution. For more information about how Payara Server loads the
required classes and libraries, see the Classloading section.
enable-implicit-cdi
Configure whether the implicit CDI scanning, as defined by CDI 1.1, is in place for all
modules inside the EAR assembly. The default value is true . If implicit CDI scanning
causes problems for an EAR assembly, the value false will disable implicit CDI scanning
for all CDI modules inside the EAR assembly. This value can be forcibly overridden during
deployment, either by an argument to asadmin deploy command, or by a checkbox in the
web admin console.
26
Advanced JDBC
Advanced JDBC Configuration and

Diagnostics.
Payara Server and Micro 161 (4.1.1.161) onwards
Payara Server 161 (4.1.1.161) and Payara Micro 161 introduce new capabilites for
advanced JDBC connection pool configuration and diagnostics.
Many performance problems in Enterprise Applications can be traced to slow database

access or database connectivity problems. To help prevent and diagnose database access
problems we have introduced a number of powerful new features.
Slow SQL Logging

Connection pools can be configured to log a warning whenever a database query exceeds a
defined threshold. This enables your operations team to rapidly diagnose performance
problems and identify poorly performing SQL.
See Slow-SQL-Logger for detailed information.
Full JDBC Tracing

Connection pools can be configured to log all JDBC calls made to the connection pool
including the SQL and execution times of the call. This is especially useful in development to
understand the SQL generated via frameworks like JPA and see what the performance
characteristics look like. As the tracing is done at the connection pool level all direct SQL or
other data access technologies are captured.
See Log-JDBC-Calls for detailed information.
SQL Trace Listeners

It is also possible to use the Payara Server apis used to implement both the Payara Server
Slow SQL Logging and JDBC tracing capabilities to create custom diagnostic and tracing
functionality via SQL Trace Listeners.
See SQL Trace Listeners for detailed Information.
27
Advanced JDBC
Advanced Connection pool Configuration

Properties
All connection pool properties available on the administration console for Payara Server
global datasources can now be configured on application scoped datasources deployed via
deployment descriptors or annotations.
See Advanced Connection Pool Properties for detailed information.
Payara Micro Support

All these powerful capabilities available on Payara Server can also be used in Payara Micro
to create robust enterprise ready microservices.
28
Log JDBC Calls
JDBC Call Logging (SQL Tracing)

From Payara 161 (4.1.1.162) tracing of all SQL calls through a Payara Server connection
pool is possible, with the time taken to execute the call also recorded. SQL Tracing is ideal
fo debugging those hard to pin down performance issues during the development phase and
as all SQL is visible SQL tracing is also a great way to see the SQL generated out of your
JPA code. With "Log JDBC Calls" configured on the connection call each call into the
Connection pool is timed and logged to the server log at FINE level. A typical log message
with Log JDBC Enabled is shown below;
[#|2016-02-04T18:51:01.467+0000|FINE|Payara 4.1|javax.enterprise.resource.sqltrace.com
.sun.gjc.util|_ThreadID=35;_ThreadName=http-listener-1(5);_TimeMillis=1454611861467;_L
evelValue=500;ClassName=com.sun.gjc.util.SQLTraceLogger;MethodName=sqlTrace;|
PoolName=DerbyPool | ExecutionTime=1ms | ClassName=org.apache.derby.client.net.NetCo
nnection40 | MethodName=prepareStatement | arg[0]=SELECT ID, AGE, BIO, BIRTHDATE, BIRT
HDAY, DATEFORMAT, DATEOFBIRTH, DATEOFHIRE, EMAIL, HIREDATE, HIREDAY, MEMBERAGE, NAME,
TODAYSDATE FROM MEMBERENTITY WHERE (NAME = ?) | arg[1]=1003 | arg[2]=1007 | |#]
PoolName=DerbyPool | ExecutionTime=0ms | ClassName=com.sun.gjc.spi.jdbc40.PreparedSt
atementWrapper40 | MethodName=setString | arg[0]=1 | arg[1]=test | |#]
atementWrapper40 | MethodName=executeQuery | |#]
atementWrapper40 | MethodName=close | |#]
You can see in the log messages that the prepareStatement, setString, executeQuery and
close methods are all logged along with their execution times and their parameters. This
gives exceptional debugging capabilites for tracking down database connection related
issues.
WARNING: This is a feature best used for development due to the volume of trace that is
produced.
29
Log JDBC Calls
Enabling JDBC Call Logging

Administration Console
SQL Tracing caan be enabled through the Payara Server administration console. Navigate
to the advanced tabl of your connection pool. Using the left hand tree view selecte JDBC-
>JDBC Connection pools->Your Connection pool. then select the Advanced Tab in the main
window of the administration console. Then select the checkbox next to Log JDBC Calls to
enable logging of all SQL call.
asadmin command line interface

The Log JDBC Calls setting for a connection pool can also be configured via asadmin using
the set command to set the fish.payara.log-jdbc-calls property of your connection pool to
true. For example the command enables JDBC call logging.
asadmin set domain.resources.jdbc-connection-pool.__TimerPool.log-jdbc-calls=true
Deployment
In Java EE 7 a JDBC datasource can be deployed by adding annotations to a JavaEE
component. The Log JDBC Calls setting can be configured via these annotations. Using
annotations is the best way to enable SQL Tracing through logging of the JDBC calls.
@DataSourceDefinition(
name = "java:app/MyApp/MyDS",
className = "org.h2.jdbcx.JdbcDataSource",
url = "jdbc:h2:mem:test",
properties = {"fish.payara.log-jdbc-calls=true"})
or the Datasource definition can be added to a deployment descriptor of an application for

example in the web.xml
30
Log JDBC Calls
<data-source>
<name>java:global/ExampleDataSource</name>
<class-name>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</class-name>
<server-name>localhost</server-name>
<port-number>3306</port-number>
<database-name>mysql</database-name>
<user>test</user>
<password>test</password>

<property>
<name>fish.payara.log-jdbc-calls</name>
<value>true</value>
</property>
</data-source>

Payara Micro also supports SQL Tracing which brings powerful operational diagnostics to
your micro-services platform. To enable SQL Tracing of JDBC calls your datasource must be
deployed using the annotations described above.
31
Slow SQL Logger
Slow SQL Logger

Many performance problems in Enterprise Applications can be traced to slow database

access. Payara Server 161 (4.1.1.162) includes capabilities to detect and log slow SQL
queries executed via a Connection pool. The Slow SQL logger monitors all queries executed
on the connection pool and if they exceed a configurable execution time in seconds a
warning message is logged into the server log. The warning message (see below) logs the
SQL query and the stack trace to the code executing the query. This enables rapid diagnosis
pinpointing the exact lines of code to investigate.
Configuring the Slow SQL Logger

There are a number of ways to configure the slow SQL threshold time on a connection pool.
To configure slow SQL logging on a connection pool via the administration console, navigate
to the Connection Pool's Advanced Properties tab. Then specify the Slow Query Log
Threshold time in seconds or use a decimal value to signify milliseconds. The value (-1)
disables slow SQL logging feature.
32
Slow SQL Logger
asadmin
The Slow Query log Threshold Time for a connection pool can also be configured via
asadmin using the set command to set the slow-query-threshold-in-seconds property of your
connection pool. For example the command below sets the threshold on the __TimerPool to
50 seconds.
asadmin set domain.resources.jdbc-connection-pool.__TimerPool.slow-query-threshold-in-

seconds=50
You can also set the threshold time to milliseconds simply by passing a decimal value.
Below is a example of setting the threshold on the __TimerPool to 200 millseconds.
asadmin set domain.resources.jdbc-connection-pool.__TimerPool.slow-query-threshold-in-

seconds=0.2
Deployment
component. The Slow Query Threshold time can be configured via these annotations. Using
annotations is the best way to configure the Slow SQL Query logger on Payara Micro.
properties = {"fish.payara.slow-query-threshold-in-seconds=5"})

33
Slow SQL Logger
<data-source>
<user>test</user>
<property>
<name>fish.payara.slow-query-threshold-in-seconds</name>
<value>5</value>
</property>
</data-source>
Example trace
Below is an example WARNING for a slow query from the Server Log.
[#|2016-02-01T22:39:29.289+0000|WARNING|Payara 4.1|javax.enterprise.resource.sqltrace.
com.sun.gjc.util|_ThreadID=61;_ThreadName=http-listener-1(2);_TimeMillis=1454366369289
;_LevelValue=900;|
SQL Query Exceeded Threshold Time: 5000(ms): Time Taken: 10000(ms)
Query was SELECT ID, AGE, BIO, BIRTHDATE, BIRTHDAY, DATEFORMAT, DATEOFBIRTH, DATEOFHIR
E, EMAIL, HIREDATE, HIREDAY, MEMBERAGE, NAME, TODAYSDATE FROM MEMBERENTITY WHERE (NAME
= ?);
java.lang.Exception: Stack Trace shows code path to SQL

at fish.payara.jdbc.SlowSQLLogger.sqlTrace(SlowSQLLogger.java:123)
at com.sun.gjc.util.SQLTraceDelegator.sqlTrace(SQLTraceDelegator.java:122)
at com.sun.gjc.spi.jdbc40.ProfiledConnectionWrapper40$1.invoke(ProfiledConnectionW
rapper40.java:448)
at com.sun.proxy.$Proxy265.executeQuery(Unknown Source)
at org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor.executeSelect(
DatabaseAccessor.java:1009)
at org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor.basicExecuteCa
ll(DatabaseAccessor.java:644)
at org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor.executeCall(Da
tabaseAccessor.java:560)
at org.eclipse.persistence.internal.sessions.AbstractSession.basicExecuteCall(Abst
ractSession.java:2055)
at org.eclipse.persistence.sessions.server.ServerSession.executeCall(ServerSession
.java:570)
at org.eclipse.persistence.internal.queries.DatasourceCallQueryMechanism.executeCa
ll(DatasourceCallQueryMechanism.java:242)
at org.eclipse.persistence.internal.queries.DatasourceCallQueryMechanism.executeCa
ll(DatasourceCallQueryMechanism.java:228)
at org.eclipse.persistence.internal.queries.DatasourceCallQueryMechanism.executeSe
lectCall(DatasourceCallQueryMechanism.java:299)
at org.eclipse.persistence.internal.queries.DatasourceCallQueryMechanism.selectAll
34
Slow SQL Logger
Rows(DatasourceCallQueryMechanism.java:694)
at org.eclipse.persistence.internal.queries.ExpressionQueryMechanism.selectAllRows
FromTable(ExpressionQueryMechanism.java:2740)
at org.eclipse.persistence.internal.queries.ExpressionQueryMechanism.selectAllRows
(ExpressionQueryMechanism.java:2693)
at org.eclipse.persistence.queries.ReadAllQuery.executeObjectLevelReadQuery(ReadAl
lQuery.java:559)
at org.eclipse.persistence.queries.ObjectLevelReadQuery.executeDatabaseQuery(Objec
tLevelReadQuery.java:1175)
at org.eclipse.persistence.queries.DatabaseQuery.execute(DatabaseQuery.java:904)
at org.eclipse.persistence.queries.ObjectLevelReadQuery.execute(ObjectLevelReadQue
ry.java:1134)
at org.eclipse.persistence.queries.ReadAllQuery.execute(ReadAllQuery.java:460)
at org.eclipse.persistence.queries.ObjectLevelReadQuery.executeInUnitOfWork(Object
LevelReadQuery.java:1222)
at org.eclipse.persistence.internal.sessions.UnitOfWorkImpl.internalExecuteQuery(U
nitOfWorkImpl.java:2896)
at org.eclipse.persistence.internal.sessions.AbstractSession.executeQuery(Abstract
Session.java:1857)
Session.java:1839)
Session.java:1804)
at org.eclipse.persistence.internal.jpa.QueryImpl.executeReadQuery(QueryImpl.java:
258)
at org.eclipse.persistence.internal.jpa.QueryImpl.getResultList(QueryImpl.java:473
)
at fish.payara.team.info.controllers.MemberSessionBean.getTeamMemberByName(MemberS
essionBean.java:35)

Payara Micro also supports Slow SQL logging which brings powerful operational diagnostics
to your micro-services platform. To enable Slow SQL logging your datasource must be
deployed using the annotations described above.
35
SQL Trace Listeners
SQL Trace Listeners

Payara Server 161 (4.1.1.162) provides support for custom SQL Trace Listeners. A SQL
Trace Listener is registered against a datasource and is called after each method call on the
Payara Server connection pool. SQL Trace Listeners enable a developer to track all calls to
the database and can be used to develop custom Auditing, Error handling or monitoring.
SQL Trace Listeners can be enabled globally on a datasource if you class is on the server
classpath or can be enabled on an application specific datasource deployed within a WAR or
EAR deployment, in which case the class only needs to be on the classpath of your
application i.e. contained within your WAR or EAR.
SQL Trace listener Interface

The SQL Trace Listener is implemented as shown below;
public interface SQLTraceListener {

/**
* Notify listeners with SQL trace information.
* @param record SQLTraceRecord that has information related
* to the SQL operation
*/
public void sqlTrace(SQLTraceRecord record);
To write a listener you just need to implement the interface and override the sqlTrace
method. The SQLTraceRecord contains information about the call to the JDBC driver. Each
of the properties below has a getter on the SQLTraceRecord class;
36
SQL Trace Listeners
/**
* Thread ID from which SQL statement originated.
*/
private long threadID;
/**
* Thread Name from which SQL statement originated.
*/
private String threadName;
/**
* Pool Name in which the SQL statement is executed.
*/
private String poolName;
/**
* Type of SQL query. Could be PreparedStatement, CallableStatement or
* other object types.
*/
private String className;
/**
* Method that executed the query.
*/
private String methodName;
/**
* Time of execution of query.
*/
private long timeStamp;
/**
* Parameters of the method that executed the SQL query. Includes information
* like SQL query, arguments and so on.
*/
private Object[] params;
Example SQL Trace Listener

The Log JDBC Calls functionality of Payara Server is implemented as a SQL Trace Listener.
The code of the sqltrace method is;
37
SQL Trace Listeners
public class SQLTraceLogger implements SQLTraceListener {
private static Logger _logger = initLogger();
private static Logger initLogger() {

_logger = LogDomains.getLogger(SQLTraceLogger.class, LogDomains.SQL_TRACE_LOGG
ER);
return _logger;
}
public SQLTraceLogger() {
public void sqlTrace(SQLTraceRecord record) {

_logger.log(Level.FINE, record.toString());
}
Configuring SQL Trace Listeners

SQL Trace Listners can be enabled on a connection pool through the Payara Server
administration console. Navigate to the advanced tab of your connection pool. Using the left
hand tree view select JDBC->JDBC Connection pools->Your Connection pool. then select
the Advanced Tab in the main window of the administration console. Then add the fully
qualified class name of your SQL Trace Listener implementation class in the SQL Trace
Listeners text field. NOTE the
implementation class must be on the classpath of Payara Server to be configured from the
administration console.
asadmin command line interface

The Adding a SQL Trace Listener to a connection pool is also possible via asadmin using
the set command to set the fish.payara.lsql-trace-listeners property of your connection pool
to the fully qualified classname of your listener implementation. For example the command
below adds a custom listener to the __TimerPool.
asadmin set domain.resources.jdbc-connection-pool.__TimerPool.sql-trace-listeners=fish

.payara.examples.payaramicro.datasource.example.CustomSQLTracer
38
SQL Trace Listeners
Deployment
component. SQL Trace Listener classes can be configured via these annotations. .
properties = {"fish.payara.sql-trace-listeners=fish.payara.examples.payaramicro.da
tasource.example.CustomSQLTracer"})

<data-source>
<user>test</user>
<property>
<name>fish.payara.sql-trace-listeners</name>
<value>fish.payara.examples.payaramicro.datasource.example.CustomSQLTracer</v
alue>
</property>
</data-source>

Payara Micro also supports SQL Trace Listners which brings powerful operational
diagnostics to your micro-services platform. To add a SQL Trace Listener to your
datasource, deploy the datasource using the annotations or deployment descriptor
described above.
39
JBatch
Contents
1. Overview
2. Documentation Conventions
3. Defining a Schema name
3.1 Defining a Schema name through the Admin Console
3.2 Defining a Schema name using Asadmin
3.3 Defining a Schema name in the domain.xml file
3.4 Specifying a Blank Schema Name
4. Setting a Table Prefix and/or Suffix
4.1 Setting a Table Prefix and/or Suffix through the Admin Console
4.2 Setting a Table Prefix and/or Suffix using Asadmin
4.3 Setting a Table Prefix and/or Suffix in the domain.xml file
5. Using MySQL, PostgreSQL, Oracle, or DB2 with JBatch
5.1 Usage Restrictions
5.2 MySQL
6. Altered Asadmin Commands
6.1 set-batch-runtime-configuration
1. Overview
This page shall cover how to use the additional JBatch functionality in Payara 4.1.1.162.
${Product-Root} - This is the root of the Payara server directory, referring to where you have
Payara installed.
${Domain} - This refers to the name of your Payara domain.
3. Defining a Schema name

Included in this release of Payara is the ability to define the name of the database schema
that will hold the batch tables. This can be set via the Admin Console, in the domain.xml file,
or using Asadmin commands.
40
JBatch
3.1 Defining a Schema name through the

Admin Console
Click on the instance or cluster to move to its configuration page.
Select the Batch tab, and from there click on the Configuration sub-tab.
Enter your desired value in the Database Schema Name field.
Save your changes
3.2 Defining a Schema name using Asadmin

This is set using the set-batch-runtime-configuration command.
The command requires you to specify the Executor or Datasource lookup name, which you
can do with the -x or -d options respectively.
The command defaults to targeting the Admin Server instance (server), to target a different
instance or cluster, use the --target option.
To specify the schema name, use the --schemaName option, or its shortcut -n.
An example can be seen below:
asadmin set-batch-runtime-configuration -d jdbc/__default --target cluster1 -n test
This command expects the Admin Server to be listening on port 4848. If it is not, use the -p
option to specify the port, for example:
asadmin -p 5048 set-batch-runtime-configuration -d jdbc/__default --target cluster1 -n
test
3.3 Defining a Schema name in the domain.xml

file
Open up the domain.xml file of the domain in question to edit.
It can be found under ${Product_Root}/glassfish/domains/${Domain}/config/
Find the \ tag under the appropriate \ tag (e.g. \ for the Admin Server), and enter the
schema name like so:
<batch-runtime-configuration schema-name="testSchemaName"></batch-runtime-
configuration>
Note - If you're editing the domain.xml of a domain that has not been started at
least once, the batch-runtime-configuration tag will not exist and you will have to
add it in yourself
3.4 Specifying a Blank Schema Name
41
JBatch
If you specify a blank schema name, then the schema name will depend on the type of
database being used. MySQL will use test, whereas Derby, Oracle, DB2 and PostgreSQL
will use the username of the JDBC connection pool resource associated with the JDBC
resource to which JBatch is configured to use. Take note that this only applies if you
explicitly specify the schema name as blank; the schema name will still default to APP if not
overwritten.
4. Setting a Table Prefix and/or Suffix

This release of Payara allows you to set the prefix and/or the suffix of the batch table name.
This can be set via the Admin Console, in the domain.xml file, or using Asadmin commands.
Note - the table prefix and suffix settings may be ignored by non-RDBMS based datastores.
4.1 Setting a Table Prefix and/or Suffix through

the Admin Console
Select the Batch tab, and the Configuration sub-tab should load.
Enter your desired values in the Table Prefix and Table Suffix fields.
Save your changes
4.2 Setting a Table Prefix and/or Suffix using

Asadmin
This is set using the set-batch-runtime-configuration command.
The command requires you to specify the Executor or Datasource lookup name, which you
can do with the -x or -d options respectively.
The command defaults to targeting the Admin Server instance (server), to target a different
instance or cluster, use the --target option.
TO specify the prefix, use the --tablePrefix option.
TO specify the table suffic, use the --tableSuffix option. An example can be seen below:
asadmin set-batch-runtime-configuration -d jdbc/__default --target cluster1 --tablePrefix

PRE --tableSuffix SFX
This command expects the Admin Server to be listening on port 4848. If it is not, use the -p
option to specify the port, for example:
asadmin -p 5048 set-batch-runtime-configuration -d jdbc/__default --target cluster1 --
tablePrefix PRE --tableSuffix SFX
42
JBatch
4.3 Setting a Table Prefix and/or Suffix in the

domain.xml file
Open up the domain.xml file of the domain in question to edit.
It can be found under ${Product_Root}/glassfish/domains/${Domain}/config/
Find the \ tag under the appropriate \ tag (e.g. \ for the Admin Server), and enter the
table prefix and/or suffix like so:
<batch-runtime-configuration table-prefix="PRE" table-suffix="SFX"></batch-runtime-
configuration>
least once, the batch-runtime-configuration tag will not exist and you will have to
add it in yourself
5. Using MySQL, PostgreSQL, Oracle, or

DB2 with JBatch
You configure JBatch to use each of these in the same way that you would configure it to
use Derby.
In the Admin Console:
Create a Connection Pool:

Navigate to Resources > JDBC > JDBC Connection Pools and click on New...
Give it a name in the Pool Name field, select the resource type from the Resource
Type drop-down, and choose the Database Driver Vendor as either DB2, MySql,
Oracle, or Postgresql from the Database Driver Vendor menu.
Set any further configuration options on the next page.
Click Finish
Create a JDBC Resource:
Navigate to Resources > JDBC > JDBC Resources and click on New...
Give it a name in the JNDI Name field, and select the datasource you just created
from the Pool Name drop-down.
Add any additional properties and select the targets for it to be enabled on.
Click OK.
Navigate to the Batch configuration page of the instance or cluster:
Select the Batch tab, and the Configuration sub-tab should load.
Select the new datasource from the Data Source Lookup Name drop-down menu.
Save the changes.
43
JBatch
5.1 Usage Restrictions

JBatch will not create internally more than one set of Jbatch tables per schema. So in your
schema if there exists a set of JBatch tables with prefixes and suffixes in the table names
and then specify in the Glassfish JBatch configuration for the same schema above that you
wish to use JBatch tables under a different name (for example no table prefix and suffix)
then during the Jbatch initialisation phase, JBatch will attempt to create these tables since
they do not exist. However since the table constraint names already exist for the existing
JBatch tables in the same schema, table creation will fail. One can of course run a sql script
to create the relevant JBatch schema objects under different names.
5.2 MySQL
For MySQL database use, it is recommended the following additional property be set:
Name Value Description

Action for DATETIME values that are
zeroDateTimeBehavior convertToNull composed entirely of zeros (used by
MySQL to represent invalid dates)
6. Altered Asadmin Commands
6.1 set-batch-runtime-configuration
Sets the batch runtime configuration settings. This command requires the admin server to be
running.
44
JBatch
Option Shortcut Description Default Mandatory
The instance
or cluster to
set the
--target server No
JBatch
configuration
of.
Sets the
name of the
Yes, or specify
--datasourcelookupname -d datasource
executorServiceLookupName
to lookup
and use.
Sets the
name of the
-- executor Yes, or specify
-x
executorservicelookupname service to datasourceLookupName
lookup and
use.
Sets the
name of the
database
--schemaName -n APP No
schema that
holds the
batch tables.
Sets the
prefix to
--tablePrefix apply to the No
batch table
name.
Sets the
suffix to
--tableSuffix apply to the No
batch table
name.
45
JCache
Contents
1. Overview
3. Using JCache in your Applications
3.1 Accessing the JSR107 Caching Provider and Cache Manager
3.1.1 Using Injection
3.2 Creating a Cache using Injection
3.2.1 Creating a custom Cache using Injection
3.3 Using JCache Annotations
4. Appendices
4.1 NamedCache Annotation
1. Overview
This page covers how to use the JCache functionality in Payara 4.1.1.162.
JSR107 (JCache) is implemented in Payara by Hazelcast.
Any paths listed throughout the documentation will use the Unix/Linux file path structure
(forward slashes).
3. Using JCache in your Applications

The following section will detail how to access and use JCache in your code.
3.1 Accessing the JSR107 Caching Provider

and Cache Manager
To create a Cache, you will need a CachingProvider and CacheManager. The embedded
Hazelcast member in Payara has a CachingProvider and CacheManager registered to JNDI,
so you do not have to create your own. To access them, import the following classes and
initialise two variables like so:
46
JCache
import javax.cache.spi.CachingProvider;
import javax.cache.CacheManager;
...
Context ctx = new InitialContext();
CachingProvider provider = (CachingProvider) ctx.lookup("payara/CachingProvider");
CacheManager manager = (CacheManager) ctx.lookup("payara/CacheManager");
3.1.1 Using Injection

You can also use injection to access and use the CachingProvider and CacheManager
embedded in Payara. Inject them into your application like so (note, your war or jar must be
an implicit or explicit bean archive i.e. contains a CDI Bean with a bean defining annotation,
an EJB Session Bean or a beans.xml file):
import javax.cache.CacheManager;
import javax.cache.spi.CachingProvider;
import javax.inject.Inject;
...
@Inject
CacheManager manager;
@Inject
CachingProvider provider;
3.2 Creating a Cache using Injection

You can create a cache using either the getCache method of a CacheManager, or using
injection. Creating the cache with injection uses the Caching Provider and Cache Manager
described above.
Creating a cache with injection can be done like so:
import javax.cache.Cache;
...
@Inject
Cache cache;
The name of this cache will be the canonical name of the class it is created in. Caches
created in this way will also have JMX statistics and management enabled.
3.2.1 Creating a custom Cache using Injection
47
JCache
You can determine the name and other attributes of a cache created through injection using
the @NamedCache annotation.
You can specify the desired custom values as a comma separated list of parameters of the
NamedCache annotation when creating a cache.
For example, to inject a cache with a custom name and with JMX management enabled:
import fish.payara.cdi.jsr107.impl.NamedCache;
import javax.cache.Cache;
...
@NamedCache(cacheName = "custom", managementEnabled = true)
@Inject
Cache cache;
The full array of parameters can be seen in the NamedCache section of the appendices.
3.3 Using JCache Annotations

Payara has the necessary interceptors implemented for allowing the full set of JCache
annotations to be used.
The JCache annotations are as follows:
@CachePut - Puts the specified key and value in the cache.

@CacheRemove - Removes the specified key and value from the cache.
@CacheResult - Retrieves the value associated with the specified key.
@CacheRemoveAll - Removes all keys and values from the cache.
@CacheDefaults - Allows the configuration of defaults for CacheResult, CachePut,
CacheRemove, and CacheRemoveAll at the class level.
@CacheKey - Marks a method parameter as the key of a cache.
@CacheValue - Marks a method parameter as the value of a cache key.
4. Appendices
4.1 NamedCache Annotation
48
JCache
Configuration Option Description Default Value
The canonical name

of the class
String cacheName Sets the name of the cache.
receiving the
injected cache.
Class keyClass Sets the class of the cache keys. Object.class
Class valueClass Sets the class of the cache values. Object.class
boolean
statisticsEnabled Enables or disables JMX statistics. false
boolean Enables or disables JMX

managementEnabled false
management.
Enables or disables cache read

through. If set to true, a
boolean readThrough false
CacheLoader factory class must
be specified.
Enables or disables cache write
through. If set to true, a
boolean writeThrough false
CacheWriter factory class must be
specified.
Class Sets the CacheLoader factory If not specified, this
cacheLoaderFactoryClass class to be attached to the cache. option is not used.
Class Sets the CacheWriter factory class If not specified, this
cacheWriterFactoryClass to be attached to the cache. option is not used.
Class Sets the ExpiryPolicy factory class If not specified, this
expiryPolicyFactoryClass to be attached to the cache. option is not used.
49
Hazelcast
Contents
1. Overview
3. Enabling Hazelcast
3.1 Enabling Hazelcast through the Admin Console
3.2 Enabling Hazelcast using Asadmin
3.3 Enabling Hazelcast in the domain.xml file
4. Configuring Hazelcast
4.1 Configuring Hazelcast with the Admin Console
4.2 Configuring Hazelcast using Asadmin
4.3 Configuring Hazelcast in the domain.xml file
5. Using Hazelcast in your applications
5.1 Accessing the JNDI registered Hazelcast Instance
6. Using Hazelcast for Web and EJB container Persistence
6.1 Setting Hazelcast as the Persistence Provider through the Admin Console
6.1.1 For the Web Container
6.1.2 For the EJB Container
6.2 Setting Hazelcast as the Persistence Provider using Asadmin
6.3 Setting Hazelcast as the Persistence Provider in the domain.xml file
7. Asadmin Commands
7.1 set-hazelcast-configuration
7.2 get-hazelcast-configuration
7.3 list-hazelcast-members
7.4 restart-hazelcast
1. Overview
This page covers how to use the Hazelcast functionality in Payara 4.1.1.162.
Hazelcast is an In-Memory Data Grid, providing Web and EJB session persistence, and
implementing JSR107 (JCache) in Payara Server.
50
Hazelcast
Payara installed.
${Target} - This refers to the name of an instance or cluster.
... - Denotes a skipping of unrelated code that would be present in the actual file or
program.
${Cluster-Config} - This refers to the name of a cluster configuration.
3. Enabling Hazelcast
In the default domain configuration of Payara, Hazelcast is not enabled. It can be enabled
either through the Admin Console, using a command line asadmin command, or through
editing the domain.xml file.
3.1 Enabling Hazelcast through the Admin

Console
From the Admin Console home:
Click on the cluster, standalone instance, or Admin Server instance (server) to load the
General Information page of the cluster or instance.
Click on the Hazelcast tab to see the Hazelcast Configuration page.
Check the Enabled box, and save your changes
3.2 Enabling Hazelcast using Asadmin

The set-hazelcast-configuration asadmin command requires you to specify whether or not
Hazelcast is enabled each time you run it. This command is also used to configure
Hazelcast, which will be covered here. The command requires the Admin Server to be
running, and will expect it to be listening on port 4848 unless specified differently with the --
port asadmin utility option.
asadmin set-hazelcast-configuration --enabled=true
If no target is specified, the command will enable Hazelcast on the Admin Server instance.
To enable Hazelcast on another instance or cluster, use the --target option like so:
51
Hazelcast
asadmin set-hazelcast-configuration --enabled=true --target=${Target}
The dynamic option of the asadmin command defaults to false, so to enable Hazelcast
without requiring a restart of the target instance/cluster, use --dynamic=true:
asadmin set-hazelcast-configuration --enabled=true --dynamic=true
3.3 Enabling Hazelcast in the domain.xml file

Open up the domain.xml file in your text editor of choice, it can be found under
${Product_Root}/glassfish/domains/${Domain}/config/
Find the \ tag under the appropriate \ tag (e.g. \ for the Admin Server), and add
enabled="true" to it, like so:
<hazelcast-runtime-configuration enabled="true"/>
least once, this tag will not exist and you will have to add it in yourself
4. Configuring Hazelcast
Payara Server supports configuring Hazelcast through the Admin Console or domain.xml
file, or by using a Hazelcast configuration file. Using a Hazelcast configuration file will cause
the settings in the Admin Console and domain.xml file to be ignored, with any parameters
not specified in the configuration file reverting to the Hazelcast defaults, even if they are
specified in the Admin Console or domain.xml (Note - the Hazelcast defaults are not
necessarily the same as the Payara Hazelcast defaults).
4.1 Configuring Hazelcast with the Admin

Console
Navigate to the Hazelcast configuration page as detailed in Enabling Hazelcast through the
Admin Console:
Click on the cluster, standalone instance, or Admin Server instance (server) to load the
General Information page of the cluster or instance.
Click on the Hazelcast tab to see the Hazelcast Configuration page.
From here, the following configuration options are available to you (excluding the
Enabled property detailed above):
52
Hazelcast
Property Description
Determines if the Hazelcast member embedded in Payara will be

Dynamic
restarted to apply any changes made
Specifies the Hazelcast configuration file to use. The path specified is
relative to the domain config directory. If you are using a custom
Override
GlassFish server configuration for a cluster or standalone instance e.g.
Configuration
cluster-config then the hazelcast configuration file should be placed in
File
the directory with the same name e.g. $domain_root/config/cluster-
config. This will ensure it is replicated to the node during startup.
Determines the port to start Hazelcast on. If this port is in use,
Start Port
Hazelcast will increment this port until it finds one it can use.
Multicast
The multicast port for communications in the Hazelcast cluster.
Port
Multicast
The multicast group for communications in the Hazelcast cluster.
Group
JNDI Name The JNDI name to bind the Hazelcast instance to.
Enter your required values, and click Save. Restarting the domain or instance/cluster is not
necessary for any changes made to take effect.
4.2 Configuring Hazelcast using Asadmin

As noted in the Enabling Hazelcast using Asadmin section, the set-hazelcast_configuration
asadmin command is used to both enable/disable Hazelcast, and to configure it. You can
pass the --help option to the command to see usage instructions in your terminal. The
available configuration options can be found here.
The following example demonstrates setting all of the options on a cluster called cluster1:
asadmin set-hazelcast-configuration --enabled=true --target=cluster1 --dynamic=true -f
hazelcast-config.xml --startport=5902 -g 224.2.2.3 --multicastport=6666 -j
payara/Hazelcast
4.3 Configuring Hazelcast in the domain.xml

file
Find the \ tag under the appropriate \ tag (e.g. \ for the Admin Server), and add one or
more of the following properties to it as required:
53
Hazelcast
Admin
Property Console Description
Equivalent
hazelcast- Override Specifies the Hazelcast configuration file to use. The

configuration- Configuration path specified must be relative to the domain config
file File directory.
Determines the port to start Hazelcast on. If this port
start-port Start Port it in use, Hazelcast will increment this port until it
finds one it can use.
multicast- Multicast The multicast group for communications in the
group Group Hazelcast cluster.
Multicast The multicast port for group communications in the
multicast-port
Port Hazelcast cluster.
jndi-name JNDI Name The JNDI name to bind the Hazelcast instance to.
See here for an example configuration demonstrating each property:
<config name="server-config">
...
<hazelcast-runtime-configuration enabled="true" hazelcast-configuration-file="haze
lcast-configuration.xml" start-port="5666" multicast-group"224.2.2.4" jndi-name="payar
a/Hazelcast1 multicast-port="54328"></hazelcast-runtime-configuration>
...
</config>
5. Using Hazelcast in your Applications

The following sections will detail how to use the Hazelcast embedded in Payara within your
code.
5.1 Accessing the JNDI registered Hazelcast

instance
By default, the JNDI name of the hazelcast instance is payara/Hazelcast, though this can be
altered as detailed in section 4.
You will need to import the following packages into your Java class:
54
Hazelcast
import com.hazelcast.core.HazelcastInstance;
import javax.naming.Context;
import javax.naming.InitialContext;
To import the Hazelcast package, you will need to set the Payara Hazelcast package as a
dependency in the project pom.xml file (for Maven projects), or for you to set the Hazelcast
JAR as a project dependency (if using a non-Maven based project). To add the Payara
Hazelcast package as a dependency in a pom, enter the following in the dependencies
section of your pom:
<dependency>
<groupId>fish.payara.appserver</groupId>
<artifactId>payara-jsr107</artifactId>
<version>4.1</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
The Hazelcast JAR (for non-Maven projects), can either be downloaded from the Hazelcast
website, or you can make use of the JAR packaged with Payara. The JAR packaged with
Payara can be found at ${Product-Root}/glassfish/modules/hazelcast.jar.
The following will initialise a HazelcastInstance variable with the instance embedded in
Payara:
Context ctx = new InitialContext();

HazelcastInstance instance = (HazelcastInstace) ctx.lookup("payara/Hazelcast");
You will have to wrap this in a try-catch clause, or throw the Naming Exception that this
could generate.
6. Using Hazelcast for the Web and EJB

Container Persistence
You can use Hazelcast as the persistence provider for the Web and EJB Container in a
cluster. Hazelcast must be enabled for this to work, which is detailed in section 3 (Note, even
if Hazelcast is not enabled, you will still be able to select Hazelcast as the persistence
provider; the persistence will fail in these circumstances).
55
Hazelcast
6.1 Setting Hazelcast as the Persistence

provider through the Admin Console
In the left hand panel, under Configurations, expand the configuration of the cluster you wish
to set Hazelcast as the persistence provider for, and click on Availability Service.

To set Hazelcast as the persistence provider of the Web Container:
Navigate to the Web Container Availability tab

Expand the Persistence Type drop-down menu, and select hazelcast
Save your changes

To set Hazelcast as the persistence provider of the EJB Container:
Navigate to the EJB Container Availability tab

Expand the HA Persistence Type drop-down menu, and select hazelcast
Save your changes

provider using Asadmin
To configure the persistence provider with asadmin, you have to use the set command.

To set Hazelcast as the persistence provider of the Web Container, run: asadmin set
${Cluster-Config}.availability-service.web-container-availability.persistence-
type=hazelcast

To set Hazelcast as the persistence provider of the EJB Container, run: asadmin set
${Cluster-Config}.availability-service.ejb-container-availability.sfsb-ha-persistence-
type=hazelcast
56
Hazelcast

provider in the domain.xml file
Configuring the persistence provider via the domain.xml file requires editing the availability-
service settings of a cluster configuration.

To set Hazelcast as the persistence provider of the web container, edit domain.xml as
follows:
<config name="${Cluster-Config}">
...
<availability-service>
...
<web-container-availability persistence-type="hazelcast"></web-container-avail
ability>
...
</availability-service>
...
</config>

To set Hazelcast as the persistence provider of the web container, edit domain.xml as
follows:
<config name="${Cluster-Config}">
...
<availability-service>
...
<ejb-container-availability sfsb-ha-persistence-type="hazelcast"></ejb-contain
er-availability>
...
</availability-service>
...
</config>
7. Asadmin Commands
7.1 set-hazelcast-configuration
57
Hazelcast
Enables/Disables and configures the embedded Hazelcast member. This command requires
the Admin Server to be running.
Option Shortcut Description

Determines whether or not the embedded
--enabled false
Hazelcast member is enabled or disabled.
--target The instance or cluster to configure. server

Enable or disable dynamic stopping and
--dynamic starting of the embedded Hazelcast false
member.
The Hazelcast configuration file to use. The
path is relative to domain config directory
(${Product-
Root}/glassfish/domains/${Domain}/config/).
-- hazelcast-
-f Using this option to point to a valid
hazelcastconfigurationfile config.xml
Hazelcast configuration file will cause all
other options set to be ignored. Any options
not specified in the Hazelcast configuration
file will revert to the Hazelcast defaults.
The port to run Hazelcast on. If this port is
--startport busy, the port specified will be incremented 5900
until a valid port is found.
The multicast group for communications in
--multicastgroup -g 224.2.2.3
the Hazelcast instance.
The multicast port for communications in
--multicastport 54327
the Hazelcast instance.
The JNDI name to bind the Hazelcast
--jndiname -j payara/Haze
instance to.
Example:
asadmin set-hazelcast-configuration --enabled=true --target=cluster1 --dynamic=true -f
hazelcast-config.xml --startport=5902 -g 224.2.2.3 --multicastport=6666 -j
payara/Hazelcast
7.2 get-hazelcast-configuration
Gets the configuration settings of the embedded Hazelcast member. This command requires
the Admin Server to be running.
The instance or cluster to get the

--target server No
Hazelcast configuration of.
58
Hazelcast
Example:
asadmin get-hazelcast-configuration --target=server
7.3 list-hazelcast-members
Lists the active Hazelcast instances and their clustering. This command requires the Admin
Server to be running.

--target server No
Example:
asadmin list-hazelcast-members --target=server
7.4 restart-hazelcast
Restarts the Hazelcast instances attached to a server or cluster. This command requires the
Admin Server to be running.

--target server No
Example:
asadmin restart-hazelcast --target=server
59
Health Check Service

Since version 4.1.1.161, Payara Server includes the Health Check Service. When enabled,
Payara Server periodically checks:
Host CPU Usage

Host Memory Usage
Payara Servers JVM Garbage Collections
Payara Servers JVM Heap Usage
CPU Usage of individual threads
Detects stuck threads
If there is a problem with any of these metrics and they exceed a configurable threshold then
a GOOD , WARNING or CRITICAL event message is logged to the server log file. This allows
operations teams to rapidly detect problems or work out what happened after these
problems have occurred. Such events will be presented in a similar manner to this:
[2016-05-24T03:52:28.690+0000] [Payara 4.1] [INFO] [fish.payara.nucleus.healthcheck.He

althCheckService] [tid: _ThreadID=72 _ThreadName=healthcheck-service-3 [timeMillis: 14
64061948690] [levelValue: 800] [[
CPUC:Health Check Result:[[status=WARNING, message='CPU%: 75.6, Time CPU used: 267 mil
liseconds'']']]]
[2016-05-24T21:11:36.579+0000] [Payara 4.1] [SEVERE] [fish.payara.nucleus.healthcheck.

HealthCheckService] [tid: _ThreadID=71 _ThreadName=healthcheck-service-3] [timeMillis:
1464124296579] [levelValue: 1000] [[
HOGT:Health Check Result:[[status=CRITICAL, message='Thread with <id-name>: 145-testin
g-thread-1 is a hogging thread for the last 59 seconds 999 milliseconds'']']]]
Asadmin Commands
Configuration
60
Asadmin Commands
Healthcheck Service
Command Reference
healthcheck-configure
Usage: asadmin> healthcheck-configure --enabled=true|false --dynamic=true|false
Aim: Enables or disables the health check service. The command updates the domain.xml
with the provided configuration but does not apply changes directly to the working service by
default.
Command Options:
Option Type Description Default Mandatory
-- The instance or cluster that will
target String server no
enable or disable its service
-- Whether to apply the changes

dynamic Boolean false no
directly to the server without a reboot
-- Whether to enable or disable the
enabled Boolean N/A yes
service
Example:
To enable the Healthcheck service such that it will only activate from the next time the server
is restarted, the following command would be used:
asadmin> healthcheck-configure \
--enabled=true \
--dynamic=false
healthcheck-list-services
Usage: asadmin> healthcheck-list-services
Aim: Lists the names of all metric services that can be configured for monitoring.
Command Options
61
Asadmin Commands
There are no options for this command.
Example
Running the command will show output similar to the example below:
Available Health Check Services:
healthcheck-cpool
healthcheck-cpu
healthcheck-gc
healthcheck-heap
healthcheck-threads
healthcheck-machinemem
healthcheck-configure-service
Usage: asadmin> healthcheck-configure-service --serviceName=<service.name> --name=<name>

--enabled=true|false --dynamic=true|false --time=<integer.value> --
unit=MICROSECONDS|MILLISECONDS|SECONDS|MINUTES|HOURS|DAYS
Aim: Enables or disables the monitoring of an specific metric. If enabling the service for an
specific metric, the command also configures the frequency of monitoring for that metric.
Command updates the domain.xml with provided configurations but does not apply changes
directly to the working service by default. dynamic attribute should be set to true in order to
apply the changes directly.
Command Options
62
Asadmin Commands
The instance or cluster that will

--target String enable or disable its metric server no
configuration
Whether to apply the changes
--dynamic Boolean directly to the server without a false no
reboot
Whether to enable or disable
--enabled Boolean - yes
the metric monitoring
The metric service name. Must
--
serviceName String correspond to one of the - yes
values listed before
A user determined name for
easy identification. This name One of:
CONP
is used in the service output, CPUC
--name String so any useful name can be GBGC no
chosen, though it should be HEAP
HOGT
unique among the services you MEMM
have configured.
The amount of time units that
--time Integer the service will use to 5 no
periodically monitor the metric
The time unit to set the
frequency of the metric
--unit TimeUnit monitoring. Must correspond to MINUTES no
a valid
java.util.concurrent.TimeUnit
If this command gets executed before running the healthcheck-configure command, the
command will succeed and the configuration will be saved, but the healthcheck service will
not be enabled.
Example
A very basic command to simply enable the GC checker and activate it without needing a
restart would be as follows:
asadmin> healthcheck-configure-service --enabled=true --serviceName=healthcheck-gc --n

ame=MYAPP-GC --dynamic=true
healthcheck-configure-service-threshold
63
Asadmin Commands
Usage: asadmin> healthcheck-configure-service-threshold --serviceName=<service.name> --

dynamic=true|false --thresholdCritical=90 --thresholdWarning=50 --thresholdGood=0
Aim: Configures CRITICAL , WARNING and GOOD threshold values for a service specified
with its name. Command updates the domain.xml with provided configurations but does not
apply changes directly to the working service by default. The dynamic attribute should be
set to true in order to apply the changes directly.
This command only configures thresholds for the following metrics:
CPU Usage
JVM Heap Space
Host Memory
JDBC Connection Pools
Command Options
The instance or cluster that

--target String server no
will be configured
Whether to apply the
--dynamic Boolean changes directly to the false no
server without a reboot
The metric service name.
--serviceName String Must correspond to one of - yes
the values listed before
The threshold value that
this metric must surpass to
-- log a CRITICAL event. A
thresholdCritical Integer 90 no
value between WARNING
VALUE and 100 must be
used
-- log a WARNING event. A
thresholdWarning Integer 50 no
value between GOOD
VALUE and CRITICAL
VALUE must be used

--thresholdGood Integer log a GOOD event. A value 0 no
between 0 and WARNING
VALUE must be used
64
Asadmin Commands
In order to execute this command for an specific metric, the healthcheck-configure-service

command needs to be executed first.
Important!
There is no asadmin command to configure the threshold values for the Hogging Threads
or Garbage Collection metrics. In the case of Hogging Threads metrics, check the
domain.xml configuration section on how to adjust its parameters.
In the case of the Garbage Collection metric, there is no configuration available for this
metric; since the service calculates and prints out how many times garbage collections were
executed within the time elapsed since the last check. The service will determine the
severity of the messages based on how much the CPU time is being taken by the GC when
measuring.
Example
Monitoring the health of JDBC connection pools is a common need. In that scenario, it is
very unlikely that on-the-fly configuration changes would be made, so a very high CRITICAL
threshold can be set. Likewise, a nonzero GOOD threshold is needed because an empty or
unused connection pool may not be healthy either. (The actual GOOD threshold would need
to be arrived at following testing).
The following command would apply these settings to the connection pool checker:
asadmin> healthcheck-configure-service-threshold \
--serviceName=healthcheck-cpool \
--dynamic=true \
--thresholdCritical=95 \
--thresholdWarning=70 \
--thresholdGood=30
get-healthcheck-configuration
Usage: asadmin> get-healthcheck-configuration

Aim: Lists the current configuration for the health check service and for the configured
metrics in a tabular format.
Command Options
65
Asadmin Commands
Example
A sample output is as follows:
Health Check Service Configuration is enabled?: true
Below are the list of configuration details of each checker listed by its name.
Name Enabled Time Unit

GC false 10 SECONDS
Name Enabled Time Unit Threshold Percentage Retry Count

HT true 10 SECONDS 95 3
Name Enabled Time Unit Critical Threshold Warning Threshold Goo

d Threshold
CONP true 5 MINUTES 70 40 20
CPU false 10 SECONDS 40 20 2
HP false 8 SECONDS - - -
MM false 7 SECONDS - - -
66
Configuration

Configuration
The Health Check service configuration is stored in the domain.xml . An example can be
seen below:
<health-check-service-configuration enabled="true">
<garbage-collector-checker unit="SECONDS" name="GC" time="5" enabled="true"></garb
age-collector-checker>
<cpu-usage-checker unit="SECONDS" name="CPU" time="5" enabled="true">
<property name="threshold-critical" value="90"></property>
<property name="threshold-warning" value="70"></property>
<property name="threshold-good" value="0"></property>
</cpu-usage-checker>
<machine-memory-usage-checker enabled="true" unit="SECONDS" name="MMEM" time="5">
</machine-memory-usage-checker>
<heap-memory-usage-checker unit="SECONDS" name="HEAP" time="5" enabled="true">
</heap-memory-usage-checker>
</health-check-service-configuration>
The main configuration tag is the <health-check-service-configuration> which can be found

directly under the parent config tag, <config name="server-config"> for example. It has only
one attribute named enabled , which can be set to either true or false to turn the entire
Healthcheck service on or off.
The List of Available Checkers

<health-check-service-configuration> can contain a variety of checkers, each of which do
specific monitoring on the listed metrics:
67
Configuration
Attribute Description
<cpu-usage- Calculates the CPU usage and prints out the percentage along with the
checker> usage time.
<garbage-
collector-
Calculates and prints out how many times GC is executed with its
checker> elapsed time.
<machine-
memory-usage-
Calculates the machine memory usage and prints out the percentage
checker> along with the total and used physical memory size.
<heap-
memory-usage-
Calculates the heap memory usage and prints out the percentage
checker> along with initial and committed heap sizes.
<hogging-
threads- Identifies the threads that are hogging the CPU.
checker>
<connection- Calculates the ratio of free/used connections available for all JDBC
pool- connections pool an prints the percentage of used connections for
checker>
each active pool.
They all have the following base attributes, that need to be specified:
Attribute Description
enabled Enables or disables the specified checker.
name Name of the checker that will be printed in the log messages for tracing.
unit
The time unit value, which could either be: NANOSECONDS , MICROSECONDS ,
MILLISECONDS , SECONDS , HOURS , DAYS .
time
The time interval value (as an integer) specified in given unit to execute the
checker for the metric.
Threshold configurations
Just like with the healthcheck-configure-service-threshold asadmin command, there are
threshold configurations for the following checkers:
<cpu-usage-checker>
<machine-memory-usage-checker>
<heap-memory-usage-checker>
<connection-pool-checker>
The threshold configurations are specified for 3 different levels: CRITICAL , WARNING and
GOOD . By default their values are 80 , 50 and 0 respectively. A sample configuration for
the cpu-usage-checker is given as follows:
68
Configuration
<cpu-usage-checker enabled="true" unit="SECONDS" name="CPU" time="3">

</cpu-usage-checker>
Keep in mind that all threshold values must be provided, otherwise the configuration will not
work appropriately and will cause a startup error.
Checkers with Customized Configuration

<garbage-collector-checker>
There are no configurable options to set for the Garbage Collection checker. The checker is
either on or off.
<hogging-threads-checker>
The Hogging Threads checker offers the following 2 properties for configuration:
threshold-percentage : Defines the minimum percentage needed to count the thread is
hogged CPU-wise. The percentage is calculated with the ratio of elapsed CPU time to
checker execution interval. It default value is 95.
retry-count : Represents the count value that should be reached by the hogged thread
in order to give health check messages to the user. Its default value is 3.
A sample of this configuration could be:
<health-check-service-configuration enabled="true">
<hogging-threads-checker unit="MINUTES" time="1" enabled="true" threshold-percen
tage="65" retry-count="10"></hogging-threads-checker>
</health-check-service-configuration>
69
Notification Service
Payara Server version 4.1.1.163 introduced a general Notification service in order to log
events which come from other services, such as the Health Check service or the Request
Tracing service
The Notification service provide disseminating of notification events through various

channels that are being created by Request Tracing Services and/or Health Check Services.
As of 4.1.1.163, the Notification service integrates with log notification mechanism which can
be seen in the domain.xml :
<notification-service-configuration enabled="true">
<log-notifier-configuration enabled="true" />
</notification-service-configuration>
The main configuration tag notification-service-configuration which has only one

attribute named enabled , which can be set to either true or false . and this enables or
disables the whole notification distributing.
The <log-notifier-configuration> tag registers a log notifier to the pub-sub model of

notification service where it subscribes to each log notification event that would get
published either by health check services or request tracing services.
The Notification service can be configured through the admin console:
70
In 4.1.1.163, the only available notifier is the service-log notifier, so configuration options
are limited.
Asadmin Commands
71
Asadmin Commands
Command Reference
notification-configure
Usage: asadmin> notification-configure --enabled=true --dynamic=true
Aim: Enables or disables the service.
Command Options:

--
enabled=true Boolean Enables or disables the service False No
When set to true, applies the

--
dynamic=true Boolean changes without a restart. False No
Otherwise a restart is required.
The argument --dynamic=true is necessary to turn on the service for a running server,
otherwise the change would only be applied after a server restart.
Example:
asadmin> notification-configure \
--enabled=true \
--dynamic=true
notifier-list-services
Usage: asadmin> notifier-list-services
Aim: Lists available notifiers to use with the service. These can then be configured
individually or referenced by other service commands, for example the requesttracing-
configure-notifier command.
Command Options
There are no options for this command
72
Asadmin Commands
Example
In order to configure the notifier for request tracing, for example, the asadmin command to
list available notifiers should be run first:
> asadmin notifier-list-services
which will give the following output:
Available Notifier Services:

service-log
Command notifier-list-services executed successfully.
By providing a notifier service with its name, its possible to assign it to another service, like
the Request Tracing service. The command named requesttracing-configure-notifier
adds a logger notifier to request tracing by enabling it as follows:
asadmin> requesttracing-configure-notifier
--notifierName="service-log" \
--notifierEnabled=true \
--dynamic=true
notification-configure-notifier
Usage: asadmin> notification-configure-notifier --notifierName=${name} --

notifierEnabled=true --dynamic=true
Aim: Enables or disables an individual notifier for the notification service to use.
Command Options:
-- The name of the notifier

notifierName=${name} String - Yes
to configure
-- Enables or disables the

notifierEnabled=true Boolean False No
service
When set to true,
applies the changes
--dynamic=true Boolean without a restart. False No
Otherwise a restart is
required.
73
Asadmin Commands
Example:
asadmin> notification-configure-notifier \
--notifierName=service-log \
--dynamic=true
get-notification-configuration
Usage: asadmin> get-notification-configuration
Aim: This command can be used to list the details of the Notification Service.
Command Options:
Example:
asadmin> get-notification-configuration
will give output similar to the following:
Enabled Notifier Enabled Notifier Name

false false service-log
Command get-notification-configuration executed successfully.
set-notification-configuration
Usage: asadmin> set-notification-configuration --enabled=true --dynamic=true --

notifierName="service-log" --notifierEnabled=true --notifierDynamic=true
Aim: This command can be used to set all configuration of the Notification Service at once.
It effectively wraps notification-configure and notification-configure-notifier in one
command.
Command Options:
74
Asadmin Commands
Enables or disables
--enabled=true Boolean False No
the service
When set to true,
applies the changes
--dynamic=true Boolean without a restart. False No
required.
The name of the service-
--notifierName String log Yes
notifier to use
Enables or disables
--notifierEnabled Boolean false Yes
notifications
When set to true,
applies the changes
--
notifierDynamic=true Boolean without a restart. false No
required.
Example:
asadmin> set-requesttracing-configuration
--enabled=true \
--dynamic=true
--notifierDynamic=true
75
Request Tracing Service
Request Tracing Service

WARNING: This is a tech preview only and unsupported for production in 4.1.1.163
The Request Tracing Service provides tracing facilities for Servlet request events. The
service logs each request in detail; capturing EJB method calls and web service invocations.
The service can be configured to inform the user of a threshold breach during request
execution.
By logging requests that exceed the specified threshold, it helps users to detect long running
requests and give insight to recover from the bottlenecks that arise within the application.
Asadmin Commands
Configuration
76
Asadmin Commands
Request Tracing
Command Reference
requesttracing-configure
Usage: asadmin> requesttracing-configure --enabled=true --thresholdValue=10 --

thresholdUnit="SECONDS" --dynamic=true
Aim: Enables or disables the service and provides ways to configure threshold time by
specifying a value and a unit.
Command Options:
Enables or
--enabled=true Boolean disables the false Yes
service
Sets the number of
time units which
--thresholdValue=10 Integer 30 No
trigger the tracing
of a request
Sets the time unit
--
thresholdUnit="SECONDS" TimeUnit to use for the SECONDS No
threshold
When set to true,

applies the
changes without a
--dynamic=true Boolean false No
restart. Otherwise
a restart is
required.
The argument --dynamic=true is necessary to turn on the service for a running server,
otherwise the change would only be applied after a server restart.
Example:
77
Asadmin Commands
asadmin> requesttracing-configure \
--enabled=true \
--thresholdValue=10 \
--thresholdUnit="SECONDS" \
--dynamic=true
requesttracing-configure-notifier
Usage: asadmin> requesttracing-configure-notifier --notifierName="service-log" --

notifierEnabled=true --dynamic=true
Aim: Controls which notifier to use and enables or disables notifications.
Command Options:

The name of the notifier to service-
use
-- Enables or disables
notifierEnabled Boolean false Yes
notifications
When set to true, applies
the changes without a
restart. Otherwise a restart
is required.
Example:
In order to configure the notifier for request tracing, the asadmin command to list available
notifiers should be run first:
asadmin> notifier-list-services
which will give output similar to the following:
Available Notifier Services:

service-log
Command notifier-list-services executed successfully.
78
Asadmin Commands
By providing a notifier service with its name, its possible to assign it to the Request Tracing
service. The command named requesttracing-configure-notifier adds a logger notifier to
request tracing by enabling it as seen follows.
asadmin> requesttracing-configure-notifier
--dynamic=true
get-requesttracing-configuration
Usage: asadmin> get-requesttracing-configuration
Aim: This command can be used to list the details of the Request Tracing Service.
Command Options:
Example:
asadmin> get-requesttracing-configuration
will give output similar to the following:
Enabled ThresholdUnit ThresholdValue Notifier Name Notifier Enabled

true SECONDS 10 service-log true
Command get-requesttracing-configuration executed successfully.
set-requesttracing-configuration
Usage: asadmin> set-requesttracing-configuration
Aim: This command can be used to set all configuration of the Request Tracing Service at
once. It effectively wraps requesttracing-configure and requesttracing-configure-notifier
in one command.
Command Options:
79
Asadmin Commands
Enables or
--enabled=true Boolean disables the false Yes
service
Sets the number of
time units which
--thresholdValue=10 Integer 30 No
trigger the tracing
of a request
Sets the time unit
--
thresholdUnit="SECONDS" TimeUnit to use for the SECONDS No
threshold
When set to true,
applies the
changes without a
restart. Otherwise
a restart is
required.
The name of the service-
notifier to use
Enables or
--notifierEnabled Boolean disables false Yes
notifications
When set to true,
applies the
changes without a
--notifierDynamic=true Boolean false No
restart. Otherwise
a restart is
required.
Example:
asadmin> set-requesttracing-configuration
--enabled=true \
--thresholdValue=10 \
--thresholdUnit="SECONDS" \
--dynamic=true
--notifierDynamic=true
80
Configuration
Request Tracing
Configuration
The request tracing service configuration is stored in the domain.xml file. As with any aspect
of Payara Server configuration, we do not recommend modifying the domain.xml due to the
likelihood of typos causing problems.
<request-tracing-service-configuration
threshold-value="30"
threshold-unit="SECONDS"
enabled="true">
<log-notifier enabled="true"></log-notifier>
</request-tracing-service-configuration>
As shown above, there are three main attributes which can be configured, in addition to a
notifier:
threshold-value
This defines the number of units beyond which a request will be traced.
threshold-unit
This defines the time duration per unit. The accepted options are any valid
java.util.concurrent.TimeUnit values. By default the threshold value is 3 MINUTES.
In the snippet given above, its set to 30 SECONDS.
enabled
Whether or not the service is turned on
There is an additional configuration option which can be seen in the admin console, or
specified as an argument to the asadmin command called dynamic . Setting this to true will
activate the change without a server restart.
81
Configuration
Not included in the admin console for 4.1.1.163 is an option to set the notifier type. This is
intentional for this tech-preview release, since the general notifier service is released with
only one available notifier. When further notifiers are added, the option to specify the type of
notifier will be added.
See Also
82
Asadmin Recorder Service
Contents
1. Overview
3. Starting and Stopping the Asadmin Recorder
4. Configuring the Asadmin Recorder
5. Running the Generated Scripts
6. Appendices
6.1 Asadmin Commands
1. Overview
This page will cover how to use the Asadmin Recorder feature of Payara Server.
This feature allows you to record the actions you take in the admin console as asadmin
commands, aiding with automating or reproducing your setup across multiple Payara Server
installations.
References to the domain directory refers to the directory where the Payara Server
domain is located.
3. Starting and Stopping the Asadmin

Recorder
From the admin console, you should be able to see a button labelled Enable Asadmin
Recorder or Disable Asadmin Recorder, depending on whether or not the asadmin recorder
feature is enabled or not. Clicking this button will enable or disable the asadmin recorder
feature respectively.
Once enabled, actions in the admin console that have a corresponding asadmin command
will be recorded to a file. By default, this file is located in the domain directory, and is called
asadmin-commands.txt.
83
Once enabled or disabled, the asadmin recorder will remain enabled/disabled until
specifically enabled or disabled again through clicking this button or using the appropriate
asadmin command - the asadmin recorder will remain enabled or disabled across server
restarts.
You can also enable or disable the asadmin recorder on its configuration page (detailed in
section 4.), or by using the following asadmin commands:
enable-asadmin-recorder - Enables the asadmin recorder.
disable-asadmin-recorder - Disables the asadmin recorder.
set-asadmin-recorder-configuration --enabled true - Alternative way of enabling the
asadmin recorder.
set-asadmin-recorder-configuration --enabled false - Alternative way of disabling the
asadmin recorder.
4. Configuring the Asadmin Recorder

To configure the asadmin recorder, navigate to the following page in the admin console:
server > Asadmin Recorder You will be presented with a series of configuration options:
Enabled - Sets whether the asadmin recorder service should be enabled or disabled.
Filter Commands - Sets whether or not to exclude the asadmin commands and regular
expressions listed in the Filtered Commands setting from being recorded.
Output Location - The absolute file path for the asadmin commands to be written to.
This defaults to a file called asadmin-commands.txt in the domain directory.
Filtered Commands - A comma separated list of asadmin commands and regular
expressions to be excluded from being recorded if the Filter Commands option is
enabled.
The default regular expressions and asadmin commands set in the Filtered Commands
option are a selection of commands and regular expressions that are typically not needed for
any automation purposes, yet are still sometimes called by commands and through
navigation of the admin console. If you remove any of these commands from the filtered
commands list, or choose not to filter any commands at all, the asadmin commands script is
liable to get filled up with these commands. Due to this, it is advised that you only add to this
list, only removing the defaults if you really need to.
Be sure to click on the Save button to have any changes you make take effect.
In addition to using the admin console, you can configure the asadmin recorder service
using the set-asadmin-recorder-configuration command. The command takes the following
parameters:
84
--enabled - Enables or Disables the Asadmin Recorder service.
--outputLocation - Specifies the absolute file path of where the recorded asadmin
commands will be written to.

--filterCommands - Specifies whether or not the commands specified with the --
filteredcommands option should be excluded from being recorded or not.

--filteredCommands - A comma separated list of asadmin commands and regular
expressions to exclude from being recorded.
As an example, the following will enable the asadmin recorder, set the output location to
/home/user/asadmin-commands.txt, and prevent the start-instance command from being
recorded (in addition to the defaults):
asadmin set-asadmin-recorder-configuration --enabled true --outputLocation /home/user/

asadmin-commands.txt --filterCommands true --filteredCommands "version,_(.*),list(.*),
get(.*),uptime,enable-asadmin-recorder,disable-asadmin-recorder,set-asadmin-recorder-c
onfiguration,asadmin-recorder-enabled,start-instance"
5. Running the Generated Scripts

Documentation on running asadmin scripts can be found in the core documentation, under
the Run a Set of asadmin Subcommands From a File section.
6. Appendices
6.1 Asadmin Commands
85
Command Description Options
get- Returns the current

asadmin- configuration of the
None
recorder- Asadmin Recorder
configuration service.
--enabled - Enables or Disables the
Asadmin Recorder service.
--outputLocation - Specifies the absolute file
path of where the recorded asadmin
set- commands will be written to.
Configures the
asadmin- --filterCommands - Specifies whether or not
Asadmin Recorder
recorder- the commands specified with the --
service.
configuration filteredcommands option should be excluded
from being recorded or not.
--filteredCommands - A comma separated list
of asadmin commands and regular
expressions to exclude from being recorded.
Enables the Asadmin
enable- Recorder service with
asadmin- it's current None
recorder configuration
settings.
disable-
Disables the Asadmin
asadmin- None
Recorder service.
recorder
Returns whether or
asadmin-
not the Asadmin
recorder- None
Recorder service is
enabled
enabled.
86
JMX Monitoring Service
JMX Monitoring Service

Payara Server 4.1.1.163 onwards
With the release of Payara Server 163, Payara offers a JMX Monitoring Service. Once
configured, Payara Server will monitor and log the values of attributes that have been listed
for monitoring. The metrics are logged together in a single log message as a series of key-
value pairs prefixed by the string PAYARA-MONITORING: .
Payara uses the AMX API for working with JMX MBeans. AMX is not fully exposed by
default and as such needs to be loaded to access most JMX MBean objects. The JMX
Monitoring Service can be used without AMX but there is a limit to what can be monitored
without it.
87
Configuration
Configuring the JMX Monitoring Service

There are two possible ways to configure the JMX Monitoring Service:
1. Using the set-monitoring-configuration asadmin command

2. Editing the domain.xml file
Examples on how to use the service to monitor the HeapMemoryUsage attribute using both
methods are shown below, but it is first worth noting the default configuration values for the
service:
enabled: false , valid type: Boolean

amx: false , valid type: Boolean , optional
logfrequency: 15 , valid type: Long , optional
logfrequencyunit: SECONDS , valid type: TimeUnit , optional
Monitoring attributes are added to the service as properties of the configuration and contain
the following values:
name: the MBean attribute name

value: the MBean domain name
description: displayed in the get-monitoring-configuration asadmin command, optional
1. Using the asadmin command

Adding the monitoring attribute
To add HeapMemoryUsage to the list of MBean attributes to monitor using the service the
following command can be used:
asadmin> set-monitoring-configuration --addproperty 'name=HeapMemoryUsage value=java.l

ang:type=Memory' --enabled false
Breaking this command down, two options have been used:
--addproperty
--enabled
88
Configuration
Passing --addproperty to set-monitoring-configuration provides a way to add a new

MBean attribute to monitor using the service. The option takes in a string of space-delimited
key-value pairs corresponding to the values listed earlier. The name and value fields are
required, but description is not. Providing name=HeapMemoryUsage denotes that the name of
the MBean attribute to log is HeapMemoryUsage , while value=java.lang:type=Memory denotes
the ObjectName of the MBean to look for the attribute on is java.lang:type=Memory .
The second option passed, --enabled , is the only required option for the asadmin
command. The only valid values to give this option are true or false . Passing false to
the option will disable the logging service on next startup if it is currently enabled, but will
otherwise do nothing. Under this scenario the monitoring service has not been configured
yet so false was passed to the option.
Dealing with composite MBean attributes

The MBean attribute added, HeapMemoryUsage , is a composite attribute. It has metrics for
commited , init , max and used . The monitoring service will by default monitor each
metric and log it as {$metric}{$attribute_name}:{$attribute_value} .
If this is not the desired result, it is possible to monitor a single metric for a composite
MBean attribute. To monitor a single metric for the attribute the value of name passed to the
--addproperty option should be modified like so:
name=HeapMemoryUsage.metric
So to log only the used heap memory the asadmin command would be:
asadmin> set-monitoring-configuration --addproperty 'name=HeapMemoryUsage.used value=j

ava.lang:type=Memory' --enabled false
Setting logging frequency

There are two configuration attributes related to the frequency at which log messages are
written, logfrequency and logfrequencyunit . The first of the two is a numerical value for
the rate, while the second value is the unit for the rate. The default configuration is set to
have a message logged every 15 seconds.
If the value of logfrequencyunit is the default of SECONDS then to have the monitoring
service log messages every one minute execute the command:
asadmin> set-monitoring-configuration --logfrequency 60 --enabled false
89
Configuration
Enabling the monitoring service

After configuring the monitoring service, there are two options to enable it. The service can
either be enabled for next startup or the service can be dynamically enabled on a running
instance of Payara (provided a non-empty configuration existed at server startup). To enable
the service dynamically on the default running instance of Payara the command to run is:
asadmin> set-monitoring-configuration --dynamic true --enabled true
To enable the service for next startup the --dynamic option would need to be dropped from
the command.
2. Editing the domain.xml file

To configure the monitoring service through editing the domain.xml file it's useful to know
about the structure of the monitoring service's tag.
<monitoring-service-configuration enabled="true" logfrequency="60">

<property name="Attribute1" value="MBean1"></property>
<property name="Attribute2" value="MBean2"></property>
</monitoring-service-configuration>
The <monitoring-service-configuration> tag houses the configuration values in its

attributes. Omitted values take the respective default value. If the configuration is edited
while the server is running the service must be restarted for the configuration changes to
updates.
If the service has not yet run on the instance then the configuration tag will not have been
created. To manually create it the tag needs to be added to the domain.xml in the relevant
config section.
<configs>
<config name="server-config">
...
<monitoring-service-configuration>
...
</config>
</configs>
Adding the monitoring attribute
90
Configuration
MBean attributes to monitor are added to the configuration section as <property> tags.
Each property tag can take values for name , value and description . To add an MBean
attribute to monitor a <property> tag should be added as shown:
<property name="HeapMemoryUsage" value="java.lang:type=Memory"></property>
Here all of the necessary attributes have been given to the tag, name and value . The
value given to name should be the name of the MBean attribute to monitor, while the value
given to value should be the ObjectName of the MBean to look for the MBean attribute on.
Here the MBean attribute added is HeapMemoryUsage which resides in the MBean with the
ObjectName of java.lang:type=Memory .
Dealing with composite MBean attributes

The MBean attribute added, HeapMemoryUsage , is a composite attribute. It has metrics for
commited , init , max and used . The monitoring service will by default monitor each
metric and log it as {$metric}{$attribute_name}:{$attribute_value} .
If this is not the desired result, it is possible to monitor a single metric for a composite
MBean attribute. To monitor a single metric for the attribute the attribute of name for the
property should be changed to:
name="HeapMemoryUsage.metric"
So to log only the used heap memory the configuration would looked like this:
<property name="HeapMemoryUsage.used" value="java.lang:type=Memory"></property>
Setting logging frequency

There are two configuration attributes related to the frequency at which log messages are
written, logfrequency and logfrequencyunit . The first of the two is a numerical value for
the rate, while the second value is the unit for the rate. The default configuration is set to
have a message logged every 15 seconds.
To have the monitoring service log messages every one minute change the tag as shown:
91
Configuration
<monitoring-service-configuration logfrequency="60">
Enabling the monitoring service

Now that the service is configured, it can be enabled simply by adding enabled="true" to
the tag.
<monitoring-service-configuration enabled="true" logfrequency="60">

Saving the domain.xml will result in the monitoring service enabled on next startup to log
heap memory usage every minute. To activate on a running instance of Payara the asadmin
command should be used to enable the service, with the --dynamic option as shown above.
92
Asadmin Commands
Using the asadmin commands

The JMX Monitoring Service provides two asadmin commands: set-monitoring-

configuration and get-monitoring-configuration . This page documents the options
available to the commands and how they should be used.
set-monitoring-configuration
Usage: asadmin> set-monitoring-configuration --dynamic true|false --enabled true|false --

amx true|false --logfrequency <long.value> --logfrequencyunit
MICROSECONDS|MILLISECONDS|SECONDS|MINUTES|HOURS|DAYS --addproperty 'name=AttributeName
value=MBeanObjectName description=Option_Description' --delproperty AttributeName
Aim: Sets the monitoring service configuration and can dynamically reload the configuration.
93
Asadmin Commands
The instance or cluster to

--target String get the monitoring service server no
configuration of
Whether or not to
dynamically reload the
configuration. This requires
a non-empty configuration
--dynamic Boolean to have existed at server false no
startup and can be
achieved by setting any
option or property to have a
value
The enabled state of the
--enabled Boolean N/A yes
service
Whether or not to boot AMX
--amx Boolean N/A no
on startup
The numerical value for the
--logfrequency Long rate at which messages are N/A no
logged
-- The unit for of rate at which
logfrequencyunit TimeUnit N/A no
messages are logged
MBean attribute to monitor.
Takes a string of the format
'name=AttributeName
value=MBeanObjectName
--addproperty String description="Description"' , N/A no
where name and value are
required and the string
must be enclosed in ' '
MBean attribute to stop

monitoring. Takes a name
--delproperty String value of and removes the N/A no
property corresponding to
it.
get-monitoring-configuration
Usage: asadmin> get-monitoring-configuration --pretty false|true
Aim: Retrieves the monitoring service configuration and outputs it.
94
Asadmin Commands
-- The instance or cluster to get the

target String server no
monitoring service configuration of
-- Displays Boolean configuration
pretty Boolean N/A no
options as a tick or cross
95
Phone Home
1. Overview
3. What information is sent?
4. Phone Home Source Code
5. Disabling Phone Home
5.1 Disable Phone Home by removing the service file
5.2 Disable Phone Home using Asadmin
5.3 Disable Phone Home in the domain.xml file
6. Phone Home URL
1. Overview
Starting with release 4.1.1.162, phone home data is used to learn about the usage of Payara
Server.
This is part of work towards an automated Payara Server update facility.
Domains call our phone home server when they are started and then once again each day.
Payara installed.
program.
3. What information is sent?

The following information is sent in each phone home call:
Payara Server version

Java Virtual Machine version
Domain uptime
Number of nodes in the domain
Number of instances in the domain
4. Phone Home Source Code

96
Phone Home
The phone home code is Open Source and available to view here.
5. Disabling Phone Home

By default, Phone Home activity is enabled.
It may be disabled by any of the following methods:
Removing the service file

Through a command line asadmin command
Editing the domain.xml file
5.1 Disable Phone Home by removing the

service file
Navigate to the ${Product-Root}/glassfish/modules directory.
Delete phonehome-bootstrap.jar.
5.2 Disable Phone Home using Asadmin

The command requires the Admin Server to be running, and will expect it to be listening on
port 4848 unless specified differently with the --port asadmin utility option.
asadmin disable-phone-home
This command will also update the domain.xml with the change described below.
5.3 Disable Phone Home in the domain.xml

file
Find the <config name="server-config"> tag
Add the tag <phone-home-runtime-configuration enabled="false"/>
6. Phone Home URL

97
Phone Home
Phone Home messages are sent to:
http://www.payara.fish/phonehome
98
Asadmin Commands
The Phone Home Services offer three admin commands to enable/disable activity and to list
the current setting.
enable-phone-home
Usage: ./asadmin enable-phone-home
Aim: Enables the Phone Home service. Command updates the domain.xml.
disable-phone-home
Usage: ./asadmin disable-phone-home
Aim: Disables the Phone Home service. Command updates the domain.xml and disables
the running service
list-phone-home
Usage: ./asadmin list-phone-home
Aim: Lists the current status of the Phone Home service as Enabled or Disabled
99
System Properties
Contents
1. Overview
3. System Properties
1. Overview
This page details the new system properties added to Payara Server.
Payara installed.
3. System Properties
100
System Properties
Value Accepted
Option Description Default
Type Values
Sets the TLS

version to be
used by the
asadmin client.
This is TLSv1,
fish.payara.clientHttpsProtocol String separate from TLSv1.1, TLSv1.2
the TLS TLSv1.2
version set for
HTTPS
communication
on a listener.
When set to
false, libraries
from
applications,
and
fish.payara.classloading.delegate Boolean ${Domain}/lib true, false true
will override
the library in
${Product-
Root}/modules
directory
101
Classloading
Contents
1. Overview
3. Default Class and Library Loading
3.1 Possible issues with default behavior
4. Solutions to the Class Loading issue
4.1 Globally override Payara-included libraries
4.2 WAR Files
4.3 EAR Files
4.4 Payara domain
5. Conclusion and Recommendations
1. Overview
This page covers how to use the Enhanced Class and Library Loading functionality in
Payara 4.1.1.162.
Payara installed.
program.
3. Default Class and Library Loading

Payara server comes included with many Java libraries and packages, for example Google
Guava, Jackson, Logback and others. By default, due to the way Java Class Loading works,
if a class is found in one of Payara-included libraries, it will be the one used in your
application, even if you include a different version of the same library in your application
package.
102
Classloading
3.1 Possible issues with default behavior

In some cases, application developer will want to include a different version of the libraries
that are already included in Payara. A common case is a later version of Guava or Jackson.
Another case is to include older versions of these packages for compatibility. Unfortunately,
due to the default class loading behavior, this will not be possible, and Payara-included
libraries will take precedence.
4 Solutions to the Class Loading issue
4.1 Globally override Payara-included

libraries
You can set the system property fish.payara.classloading.delegate to false . This way,
any library that is included by the application developer will override the one that's included
in Payara. Class Loading is accomplished in the following order:
Libraries From WAR files - WEB-INF/lib - Optional, controlled by the <class-loader>

directive in web.xml
Libraries From EAR files - usually /lib
Libraries from the Domain - ${Domain}/lib
And finally, libraries from Payara itself - ${Product-Root}/modules
This is a Payara-specific feature
4.2 WAR Files

For WAR files, you can include <class-loader delegate="false"/> in your WEB-
INF/glassfish-web.xml . With this option, your WEB-INF/lib/xxx.jar libraries will take
precedence over Payara-included libraries. This option is also provided by GlassFish Server
4 Open Source Edition.
4.3 EAR Files
103
Classloading
For EAR files, you can include <classloading-delegate>false</classloading-delegate> in

your META-INF/glassfish-application.xml file. With this option, your EAR-included libraries
will override Payara-included libraries.
4.4 Payara domain

The only way to enable libraries in the ${Domain}/lib to override Payara-included libraries (
${Product-Root}/modules ) is to set the system property fish.payara.classloading.delegate
to false as described above.
5. Conclusion and Recommendations

We recommend that you set the system property fish.payara.classloading.delegate to
false as this behavior is the desired behavior for most cases. The reason this is not the
default out-of-the-box is because Payara wants to keep drop-in replacement compatibility

with GlassFish.
104
Production Ready Domain
Contents
1. Overview
This page details the new production ready domain available in Payara Server 4.1.1.162.
(forward slashes).
JVM Options are listed in the key=value notation (when applicable).
3. Production Ready Domain

With Payara Server 4.1.1.162, there is a new domain called payaradomain in the
${PAYARA_HOME}/glassfish/domains/ folder of that is fine-tuned to be used in production
environments.
The following changes are made for this domain configuration:
3.1. JVM Options

The following JVM options are fine tuned:
-XX:MaxPermSize=512m (previously 192m)

-Xmx1024m (previously 512m)
-server (previously client)
-Djdk.tls.rejectClientInitiatedRenegotiation=true
The following JVM options were removed (OSGi Felix parameters):
-Dosgi.shell.telnet.port=6666
-Dosgi.shell.telnet.maxconn=1
-Dosgi.shell.telnet.ip=127.0.0.1
-Dgosh.args=--nointeractive
-Dfelix.fileinstall.poll=5000
105
Production Ready Domain
-Dfelix.fileinstall.log.level=2
-Dfelix.fileinstall.bundles.new.start=true
-Dfelix.fileinstall.bundles.startTransient=true
-Dfelix.fileinstall.disableConfigSave=false
-Dcom.ctc.wstx.returnNullForDefaultNamespace=true
-
Dorg.glassfish.additionalOSGiBundlesToStart=org.apache.felix.shell,org.apache.felix.go
go.runtime,org.apache.felix.gogo.shell,org.apache.felix.gogo.command,org.apache.felix
.shell.remote,org.apache.felix.fileinstall
3.2. HTTP Connection Pool

The maximum size for the thread pool http-thread-pool has been increased from 5 to 50.
106
User Guides
User Guides
These pages are intended to answer common questions and provide more practical
documentation on how to work with Payara Server and Payara Micro
For regular updates on Payara Server and Payara Micro, including announcements of new
features, subscribe to the official Payara Blog
107
Payara Server Domain Backup

Oracle GlassFish 3 had a built-in automatic backup facility using the asadmin command
create-backup-config . This allowed you to specify a schedule for when to backup, where to
place the backed up file, and how many backups to keep.
This is no longer present in GlassFish or Payara Server, since it was a commercial feature
that was never open-sourced, but its effects can be reproduced without much effort using
the backup-domain command and some scheduling software (crontab, for example)
Since the domain directory is where all of the user configuration of Payara Server is kept, we
can consider this to be separate to the installation files that Payara Server uses to run the
app server itself. We can backup the domain using the asadmin backup-domain command as
follows:
asadmin backup-domain --backupDir /path/to/backup/directory myDomain
The effect of this command is to create a full backup of the domain directory. To complete
the command, however, the domain must be stopped. This will mean that any application
deployed to the DAS is unavailable while the backup takes place.
The job of running this backup command on a given schedule and managing the resulting
backed up files needs to be done by a script external to Payara Server.
See Also
Restore a Payara Server Domain
Upgrade Payara Server
108

To restore from a backup the asadmin restore-domain command is used:
asadmin restore-domain --filename ${name} --backupdir /path/to/backup/directory myDoma

in
This command will restore just the domain named in the command. Since instances are
stored separately to each domain (and may be on remote hosts), the command will have
no effect on instances.
Restoring an Instance
Since all data in an instance directory is kept in sync with the DAS, there is no added data
(besides logs, caches and some MQ data when a file-based store is used) and an instance
can be completely restored simply by making sure there is an empty directory with the name
of the instance inside a node folder of the correct name. For example:
payara41/nodes/localhost-localdomain/myInstance
Running the start-local-instance command with a full sync, as discussed earlier, will
restore the instance completely:
asadmin start-local-instance --sync=full myInstance
Considerations for OpenMQ

If OpenMQ (Payara Servers JMS broker) is being used, the default configuration is to use
EMBEDDED mode, meaning that Payara Server will fully manage the JMS broker within the
same JVM as the server instance and a file-based store is used for persistent messages.
The alternative option of LOCAL allows for the use of an enhanced broker cluster, whereby
the JMS broker instances are started as separate JVMs and use a database connection for
storage. Assuming the database is highly available, this completely avoids any danger when
needing to --sync=full the instance.
See Also
109
110

There are two valid methods of fully upgrading to a new release of Payara Server. Either of
the following two methods would work in most circumstances:
Backing up and restoring the existing configuration to a new installation

Maintaining completely separate domain and node directories and pointing the new
version to the existing directories
Method 1: Backup and Restore

There are detailed instructions on backup and restore already in my recent blog post, so I
wont go over all the details of it here.
In summary, the method would involve the following steps:
Stop the running domain

The asadmin backup-domain subcommand will only work if the domain is not
running so, if this method is chosen for a production system, there would need to
be an arranged period of downtime
Run asadmin backup-domain from the existing Payara Server installation
Once the domain has been backed up, restore the domain to the newly downloaded
Payara Server installation by running asadmin restore-domain from the bin directory of
the new Payara Server installation
After following those steps, you should be left with a similar directory structure to the
following:
/opt/payara/161/payara41/glassfish/domains/myDomain
/opt/payara/162/payara41/glassfish/domains/myDomain
/opt/payara/backups/myDomain/myDomain_2016_05_27_v00001.zip
Its important to note that this only backs up the domain directory and its contents. Any
instances you have in node directories will need to regenerated by using the --sync=full
option of the start-local-instance subcommand:
asadmin start-local-instance --sync=full myInstance
111
This will recreate the instance from scratch. Be aware, though, that this will not recreate
things stored in the instance directory which are outside of the configuration like JMS
filestores. If there is any JMS persistence which does not use a database, these must be
handled manually. See Restore a Payara Domain for more detail.
Method 2: Move the domain directory and node directories

An alternative to backing up and restoring the domain, then recreating the instances, would
be to create the domain and node directories in a location separate to the installation. For
example, if I downloaded Payara 154, created my domain, then wanted to use Payara 162, I
would use the following process:
/opt/payara/payara-4.1.154/payara41 bin/asadmin create-domain --domaindir /tmp myTem

pDomain
/opt/payara/payara-4.1.154/payara41 cd ../../payara-4.1.162/payara41
/opt/payara/payara-4.1.162/payara41 bin/asadmin start-domain --domaindir /tmp myTemp
Domain
This will use the 154 installation to create a new domain, and then run it with the 162
installation.
You can do the same thing with nodes too:
/opt/payara/payara-4.1.154/payara41 bin/asadmin create-node --nodedir /tmp myLocalNo

de
In this way, the user configuration is always kept separate to the installation, and rollback is
as simple as using the previous installation directory.
If you are using Payara Server on Linux, you could take advantage of symbolic links to make
life easier. When your domain directory is in a non-standard location, it means that you need
to specify its location with each start/stop/restart command. If you were to create a symbolic
link to the domain directory inside the default domains directory, then all of your existing
scripts will carry on as normal.
You could even extend this further to create a symbolic link to whichever Payara Server
installation was currently used in production, for example:
/opt/payara/live/payara41/....
This means that any rollback is as simple as stopping the server, updating a symbolic link
and starting it again.
112
Without the use of symbolic links, things get a bit more manual (though still quite
straightforward). The asadmin start-domain subcommand has a --domaindir option which
allows you to specify the location of a domain directory. So you could have a directory
structure like this:
/opt/payara/154/payara41/....
/opt/payara/domains/myDomain
/opt/payara/nodes/myLocalNode
Then you could start your domain with whatever version of Payara you wanted:
/opt/payara/154/payara41/bin/asadmin start-domain --domaindir /opt/payara/domains myDo

main
...or:
/opt/payara/162/payara41/bin/asadmin start-domain --domaindir /opt/payara/domains myDo

main
Note: the --domaindir option specifies the parent directory for your domain...so where
you would store all of your domains. There is then a space and then the name of the
domain you want to start - domain1 is still the default
You can start nodes in the same way:
/opt/payara/162/payara41/bin/asadmin start-local-instance --nodedir /opt/payara/nodes

myLocalNode
See Also
113

This page shall cover how to use Payara Micro.
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.
Documentation Conventions
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.
(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.
114
Starting an Instance
This section details the very basics of starting an instance.
Starting an Instance from the Command Line

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.
Starting an Instance Programmatically

You need to import two classes from the fish.payara.micro package (contained in the Payara
Micro JAR, see section Maven Support 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:
public class EmbeddedPayara

{
public static void main(String[] args) throws BootstrapException
{
PayaraMicro.bootstrap();
}
}
115
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
Programmatically 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:

{
{
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.PayaraMicroRuntime;

{
{
PayaraMicroRuntime instance = PayaraMicro.bootStrap();
}
}
116
Deploying Applications
Deploying Applications
This section details how to deploy applications.
117
From the Command Line
Deploying Applications From the

Command Line
Deploying an Application
As noted in section Starting an Instance, 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_ ...
Deploying an application package

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
Deploying an Exploded War

An exploded war can be deployed to a Payara Micro instance just be specifying the path to
the exploded war root directory on the --deploy command line or via the api. The exploded
war can be redeployed by creating a file .reload in the root directory of the explded war and
updating its timestamp for example using touch .reload in LINUX.
Deploying Multiple Applications

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:
118
java -jar payara-micro.jar --deploy /home/user/example.war --deploy /home/user/test.wa

r
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
Deploying Applications from a Maven

repository
You can deploy an application directly from a Maven repository using the --deployFromGAV
option. This option accepts a comma separated string denoting a maven artefact's groupId,
artifactId, and version attributes.
java -jar payara-micro.jar --deployFromGAV "fish.payara.examples,test,1.0-SNAPSHOT"
This option can be used multiple times, and in conjunction with the standard --deploy
options.
By default, Payara Micro will only search for artefacts in the Maven Central repository. If you
wish to search additional repositories, you can add them to the list of repositories to search
with the --additionalRepository option:
java -jar payara-micro.jar --deployFromGAV "fish.payara.examples,test,1.0-SNAPSHOT" --

additionalRepository https://maven.java.net/content/repositories/promoted/
To search through multiple additional repositories, you can simply call the option multiple
times:
java -jar payara-micro.jar --deployFromGAV "fish.payara.examples,test,1.0-SNAPSHOT" --

additionalRepository https://maven.java.net/content/repositories/promoted/ --additiona
lRepository https://raw.github.com/payara/Payara_PatchedProjects/master/
119
Programmatically
Deploying Applications Programmatically

This section details deploying applications from within the code.
120
Programmatically
Programmatically during Bootstrap
There are two methods you can use to deploy an application during the bootstrapping
process:
addDeployment(String pathToWar)
addDeploymentFile(File file)
The first, addDeployment(String pathToWar) , accepts a String that points to the path of the file
to be deployed. For example:

{
{
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 java.io.File;

{
{
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:
121
Programmatically

{
{
PayaraMicro micro = PayaraMicro.getInstance();
micro.addDeployment("/home/user/example.war");
micro.bootStrap();
}
}
Deploying Multiple Applications

Programmatically during Bootstrap
Similar to when deploying multiple applications from the command line, you must call the
addDeployment or addDeploymentFile method for each application you wish to deploy.
For example, to deploy three applications:

{
{
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 the section Deploying From the Command Line):
setDeploymentDir(File deploymentRoot) method
For example:
122
Programmatically

{
{
File deployments = new File("/home/user/deployments/");
micro.setDeploymentDir(deployments);
micro.bootStrap();
}
}
123
Programmatically
Programmatically to a Bootstrapped
Instance
There are three methods available for deploying an application to a bootstrapped instance:
deploy(File war)
deploy(String name, InputStream is)
deploy(String name, String contextRoot, InputStream is)
deploy(File war)
The first method works in the same way as the addDeploymentFile method described in the
section Deploying Programmatically during Bootstrap.

{
{
File war = new File("/home/user/deployments/");
PayaraMicroRuntime instance = PayaraMicro.bootstrap();
instance.deploy(war);
}
}
deploy(String name, InputStream is)

This method allows you to deploy WARs from an InputStream:
124
Programmatically
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.logging.Level;
import java.util.logging.Logger;

{
{
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, e
x);
}
}
}
deploy(String name, String contextRoot,

InputStream is)
This method works in the same way as the previous method, but allows you to specify the
context root of the application. The following example would deploy the test application to a
context root of /app:
125
Programmatically
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.logging.Level;
import java.util.logging.Logger;

{
{
try (InputStream is = new FileInputStream("/home/user/test.war"))

{
instance.deploy("test", "app", is);
}
catch (IOException ex)

{
Logger.getLogger(EmbeddedPayara.class.getName()).log(Level.SEVERE, null, e
x);
}
}
}
126
Programmatically
Deploying Applications Using an asadmin

Command
Deploying on a Local Instance

As an alternative to using the deploy 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:
127
Programmatically
import fish.payara.micro.services.data.InstanceDescriptor;
import java.util.ArrayList;
import java.util.Collection;

{
{
PayaraMicroRuntime runtime = PayaraMicro.getInstance().setHttpAutoBind(true).b
ootstrap();
// 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");
}
}
Deploying an Application to Multiple

Bootstrapped Instances
You can use the run method to run the deploy asadmin command on multiple 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:
128
Programmatically

{
{
PayaraMicroRuntime runtime = PayaraMicro.getInstance().setHttpAutoBind(true).b
ootstrap();
// Run the deploy asadmin command on all instances in the runtime's cluster
runtime.run("deploy", "/home/user/test.war");
}
}
See the example for deploying on local instance on using the run method on a subset of
instances in a cluster.
129
Programmatically
Programmatically from a Maven
Repository
Deploying an Artefact Using Maven

Coordinates
To deploy an application programmatically directly from a Maven repository, you will need to
add a Maven GAV coordinate. This can be done using addDeployFromGAV() method. This
method accepts a comma separated string denoting a maven artefact's groupId, artifactId,
and version attributes.

{
{
PayaraMicro.getInstance().addDeployFromGAV("fish.payara.testing,clusterjsp,1.1"
).bootStrap();
}
}
Specifying Additional Maven Repositories

By default, Payara Micro will only search for artefacts in the Maven Central repository. If you
wish to search additional repositories, you can add them to the list of repositories to search
with the addRepoUrl() method:
130
Programmatically

{
{
PayaraMicro.getInstance().addRepoUrl("https://raw.github.com/Pandrex247/Payara_
PatchedProjects/Payara-Maven-Deployer");
PayaraMicro.getInstance().addDeployFromGAV("fish.payara.testing,clusterjsp,1.1"
).bootStrap();
}
}
To search through multiple additional repositories, you can simply call the addRepoUrl
method, using commas to separate URLs:

{
{
micro.addRepoUrl("https://raw.github.com/Pandrex247/Payara_PatchedProjects/Paya
ra-Maven-Deployer", "https://maven.java.net/content/repositories/promoted/");
micro.addDeployFromGAV("fish.payara.testing,clusterjsp,1.1");
micro.bootStrap();
}
}
Deploying Multiple Applications from a Maven

Repository
Similar to when deploying multiples applications from the command line, you must call the
addDeployFromGAV method for each application you wish to deploy directly from a Maven
repository.
For example, to deploy two applications:
131
Programmatically

{
{
micro.bootStrap();
}
}
132
Configuring an Instance
Configuring an Instance
This section details how to configure a Payara Micro instance.
133
Configuring an Instance from the

Command Line
As described in Deploying From the Command Line, 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
Read configuration from a file

With --domainConfig option, it is possible to define multiple options in a configuration file.
This option would override the default Payra Micro configuration completely. The provided
file must conform to the same structure as the domain.xml file in a Payara Server domain.
The --rootDir option sets the root configuration directory and saves the configuration
across restarts. If empty, this directory will be filled by the default confguration, including the
domain.xml file.
Precedence
If specifying multiple options at once, the following precedence is followed:
rootDir < domainConfig < autoBindHttp | autoBindSsl < port | sslPort
In human language:
The domain.xml in the directory specified by the rootDir option (if one exists) is
overriden by the domain.xml specified with the domainConfig option
The Http and Https port numbers specified in either of these domain.xml files are
134
overidden to be the default values of 8080 and 8081 when the autoBindHttp or
autoBindSsl options are enabled respectively.
These default port values are then overriden in turn by the port numbers specified with
the port or sslPort options.
135
Programmatically
Configuring an Instance Programmatically

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 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:

{
{
PayaraMicro.getInstance().setHttpPort(2468).setClusterStartPort(5902).bootStra
p();
}
}
For the example of the same, but done across multiple lines, see here:

{
{
micro.setHttpPort(2468);
micro.setClusterStartPort(5902);
micro.bootStrap();
}
}
136
Programmatically
It is also possible to configure an instance programmatically by specifying a domain.xml file

that is packaged within your application by passing a resource string to the
setApplicationDomainXML method. The path in the string will be resolved using the
getResource method of the Thread context class loader.

{
{
PayaraMicro.getInstance().setApplicationDomainXML("config/domain.xml").bootStr
ap();
}
}
137
Packaging as an Uber Jar
Packaging a Configured Instance as an

Uber Jar
Sometimes it is preferable to package the application, configuration and dependencies into a
single executable jar. To do this with Payara Micro use the --outputUberJar command line
option for example;
java -jar payara-micro.jar --deploy test.war --outputUberJar test.jar
this will package up the payara-micro.jar and the war file into a single jar. this jar will then be
able to be run with;
java -jar test.jar
Any additional command line options you specify when creating an uber jar are recorded
and retained when you run the uber jar with no parameters. For example
java -jar payara-micro.jar --deploy test.war --port 9080 --lite --clusterName test-clu
ster --clusterPassword test-password --outputUberJar test2.jar
All the command line option for port etc. will be retained when the uber jar is ran with no
parameters.
138
Via System Properties
Configuring Payara Micro via System

Properties
Payara Micro can also be configured via System properties. These can either be set on the
command line or passed into Payara Micro using the --systemProperties command line
option which will load the properties from the specified file.
Payara micro supports the following system properties.
System Property Equivalent Command Line Flag

payaramicro.domainConfig --domainConfig
payaramicro.hzConfigFile --hzConfigFile
payaramicro.autoBindHttp --autoBindHttp
payaramicro.autoBindRange --autoBindrange
payaramicro.autoBindSsl --autoBindSsl
payaramicro.enableHealthCheck --enableHealthCheck
payaramicro.port --port
payaramicro.mcAddress --mcAddress
payaramicro.mcPort --mcPort
payaramicro.clusterName --clusterName
payaramicro.clusterPassword --clusterPassword
payaramicro.lite --lite
payaramicro.maxHttpThreads --maxHttpThreads
payaramicro.minHttpThreads --minHttpThreads
payaramicro.noCluster --noCluster
payaramicro.disablePhoneHome --disablePhoneHome
payaramicro.rootDir --rootDir
payaramicro.name --name
payaramicro.logToFile --logToFile
139
Alternate Keystores for SSL
Configuring Alternate Keystores for SSL

Payara Micro comes with keystores embedded within the jar file. These can be overridden
using the standard Java SSL system properties. javax.net.ssl.trustStore etc.
140
Stopping an Instance
This section describes how to shut down a Payara Micro instance.
6.1 Stopping an Instance from the Command

Line
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.
6.2 Stopping an Instance Programmatically

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:

{
{
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:
141

{
{
instance.shutdown();
}
}
142
Automatic Clustering
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. You can also
use --clusterName and --clusterPassword to segregate clusters.
Lite Cluster Members

If you specify on the command line or through the API that a Payara Micro instance is a lite
instance. Then the Payara Micro instance will join the cluster but will not store any clustered
data, for example web session data or JCache data. This is very useful for a number of
scenarios;
You can create a cluster topology whereby a web application is hosted in a number of
payara micro instances and the garbage collection ergonomics for these instances are tuned
for throughput, in addition a number of payara micro instances are also in the cluster with no
143
applications deployed and these instances are tuned for long lived web session data. In this
case the web application instances could be designated as lite cluster members to ensure
no web session data is stored within their JVMs.
Lite members can also be used purely if you want a clustered payara micro instance to join
the same cluster and receive CDI events or clustered events but without storing any data.
Preventing Cluster Cross Talk

By default Payara Micro clusters automatically discover other cluster members via multicast.
This can lead to the situation whereby different development environments being used by
different teams cluster together as they are using the same multicast address and multicast
port. This can lead to confusing errors. To prevent cluster cross-talk ensure that the
multicast-address and muticast-port are set to different values on each unique cluster. In the
case where this is not possible payara micro provides the capability to set a cluster name
and a cluster password both through the command line or through the api. If all the multicast
settings are similar, instances will only cluster together if all the instances have the same
cluster name and cluster password.
Clustering with Payara Server

Payara Micro can cluster with Payara Server and share web session and JCache data. To
cluster with Payara Server just start up a Payara Micro instance with the same multicast
address, multicast port, cluster name and cluster password as configured in your Payara
Server.
144
Maven Support
Maven Support
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.1.162</version>
</dependency>
145
HTTP(S) Auto-Binding
HTTP and HTTPS Auto-Binding

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 --a
utoBindRange 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.
146
Running asadmin Commands
Running asadmin Commands on

Bootstrapped Instances
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 command 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
method getClusteredPayaras() provided by PayaraMicroRuntime to retrieve the list of all
instances in the cluster and filter the list afterwards.
Examples on using the first and second methods can be seen in section Deploying
Applications Using an asadmin Command. 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.
147
Running Callable Objects
Running Callable Objects on Bootstrapped

Instances
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:
run(Callable<T> callable) runs the specified Callable on all instances in a runtime's
cluster
run(Collection<InstanceDescriptor> members, Callable<T> callable) runs the Callable
on a subset of the instances in a runtime's cluster
Both methods return a Map with a key/value type of <InstanceDescriptor, Future<T>> ,

where the type variable T is Serializable.
148
Logging to a file
Logging to a file
This section describes how to print all the Payara Micro log messages into a file.
Logging to a file from the Command Line

To print all of the Payara Micro log messages into a file from the command line, you will
need to use the --logToFile option, followed by either a path to where you want to put the
log file or by giving the name of a file you want to print the logs into. If a file name is not
given, a default file called payara-server.log is generated.
java -jar payara-micro.jar --logToFile /home/user/PayaraMicro.log
Logging to a file Programmatically

To print all the Payara Micro log messages into a file programmatically, you will need to use
setUserLogFile(String filePath) method.

{
{
PayaraMicro.getInstance().setUserLogFile("/home/user/PayaraMicro.log").bootSt
rap();
}
}
149
Remote CDI Events
Firing and Listening for remote CDI Events

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.
150
Payara Micro Appendices
Payara Micro Appendices
151
Command Line Options
Payara Micro Command Line Options

Configuration
Description Default Value
Option
--noCluster Disables clustering for this instance. false
Sets the HTTP port that the instance
--port 8080
will bind to.
If not set, has no

Sets the HTTPs port that the instance
--sslPort value and HTTPS is
will bind to.
disabled.
Sets the cluster multicast group for the
--mcAddress 224.2.2.4
instance.
--mcPort Sets the cluster multicast port. 2904
--startPort Sets the cluster start port number. 5900
--clusterName Sets the cluster group name
--
clusterPassword Sets the cluster group password
Generated
--name Sets the instance name. Universally Unique
Identifier.
If not set, has no
Sets the root configuration directory
value and defaults
--rootDir and saves the configuration across
to the temp
restarts.
directory.
If not set, has no

Sets a directory which will be scanned
--deploymentDir value and is not
for WAR files for auto-deployment.
used.
If not set, has no
--deploy Specifies a WAR file to deploy. value and is not
used.
If not set, the

domain.xml
Overrides the server configuration with
--domainConfig contained in the
an alternative domain.xml file.
Payara Micro JAR is
used.
-- Sets the minimum number of threads
minHttpThreads 10
in the HTTP thread pool.
-- Sets the maximum number of threads

maxHttpThreads 10
in the HTTP thread pool.
152
Command Line Options
Sets the Hazelcast configuration file to if not set, the in-built

--hzConfigFile use for overriding the in-built Hazelcast Hazelcast
cluster configuration. configuration file is
used.
--autoBindHttp Enables auto-binding for the HTTP port false
Enables auto-binding for the HTTPS
--autoBindSsl false
port
Sets the range for HTTP and HTTPS

--autoBindRange 5
port auto-binding.
sets the micro container to lite mode
--lite
which means it clusters with other
Payara Micro instances but does not
store clustered data
packages up an uber jar at the
--outputUberJar specified path based on the command
line arguments and exits
--
systemProperties Reads system properties from a file
--logo
Reveals the #BadAssFish or a custom
logo on boot
-- Disables Phone Home activities for this If not set, Phone

disablePhoneHome instance Home is active
--help
Displays the configuration options and If not set, this option
then exits. is not used.
153
Payara Micro API
Payara Micro API

This section contains documentation on the Payara Micro API.
154
Payara Micro API
Configuration Methods
This section details the PayaraMicro.class configuration methods that are used during the
bootstrap process.
Configuration
Description Get Method Set Method
Operand
Gets or sets the

domain.xml
PayaraMicro
Alternate used to override File
setAlternateDomainXML(File
Domain XML the default getAlternateDomainXML()
alternateDomainXML)
server
configuration.
Gets or sets the

Cluster PayaraMicro
cluster multicast String
Multicast getClusterMulticastGroup()
setClusterMulticastGroup(String
group for the hzMulticastGroup)
Group
instance.
Gets or sets the

PayaraMicro setClusterPort(int
Cluster Port multicast cluster int getClusterPort()
hzPort)
port.
Gets or sets the

start port
number for the PayaraMicro
Cluster Start
Payara Micro int getClusterStartPort() setClusterStartPort(int
Port hzStartPort)
instance to listen
on for cluster
communications.
Gets or sets the

directory to be PayaraMicro
Deployment
scanned for File getDeploymentDir() setDeploymentDir(File
Directory deploymentRoot)
archives to
deploy.
155
Payara Micro API
Gets or sets the

HTTP port for PayaraMicro setHttpPort(int
HTTP Port int getHttpPort()
httpPort)
the instance to
bind to.
Gets or sets the PayaraMicro

Instance
name of the String getInstanceName() setInstanceName(String
Name instanceName)
instance.
Gets or sets the

maximum
PayaraMicro
Maximum number of int getMaxHttpThreads() setMaxHttpThreads(int
HTTP Threads threads in the maxHttpThreads)
HTTP thread
pool.
Gets or sets the

minimum
PayaraMicro
Minimum number of int getMinHttpThreads() setMinHttpThreads(int
HTTP Threads threads in the minHttpThreads)
HTTP thread
pool.
Gets or sets the

root PayaraMicro setRootDir(File
Root Directory File getRootDir()
rootDir)
configuartion
directory.
Gets or sets the

HTTPS port for
the instance to
bind to. A PayaraMicro setSslPort(int
HTTPS Port int getSslPort()
sslPort)
HTTPS port is
not bound
unless this value
is manually set.
Gets or sets
whether
clustering is PayaraMicro
No Clustering enabled or boolean isNoCluster() setNoCluster(boolean
noCluster)
156
Payara Micro API
disabled for an
instance.
Enables or
Disables auto- PayaraMicro
HTTP Auto-
binding of the boolean getHttpAutoBind() setHttpAutoBind(boolean
Binding httpAutoBind)
HTTP port for an
instance.
Enables or
Disables auto- PayaraMicro
HTTPS Auto-
binding of the boolean getSslAutoBind() setSslAutoBind(boolean
Binding sslAutoBind)
HTTPS port for
an instance.
Sets the range

PayaraMicro
Auto-Bind for HTTP and int getAutoBindRange() setAutoBindRange(int
Range HTTPS port autoBindRange)
auto-binding.
157
Payara Micro API
Operation Methods
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.
The list of methods in the API:
Deployment Methods
Setup and Shutdown Methods
CDI Methods
Run Methods
Get Methods
Deployment Methods
Deployment methods are used for the deployment of applications to Payara Micro instances.
PayaraMicro.class Methods
Command
Method Description Line
Equivalent
PayaraMicro Adds the file found at the location of the

addDeployment(String pathToWar parameter to the list of files to be --deploy
pathToWar)
deployed upon starting the instance.
PayaraMicro Adds the file associated with the file

addDeploymentFile(File parameter to the list of files to be deployed --deploy
file)
upon starting the instance.
PayaraMicroRuntime.class Methods
158
Payara Micro API
Method Description
boolean deploy(String name, Deploys an application from an InputStream

InputStream is) with the name specified.
boolean deploy(String name, String Deploys an application from an InputStream,
contextRoot, InputStream is) with the specified name and context root.
boolean deploy(File war)

Deploys the application located at the war
parameter path.
boolean undeploy(String name) Un-deploys the specified application.
Setup and Shutdown Methods

These methods are required for setting up Payara Micro instances.
PayaraMicro.class Methods
Method Description
PayaraMicroRuntime
bootStrap() throws
Checks the supplied configuration parameters and starts a
BootstrapException Payara Micro instance.
PayaraMicro Obtains the static singleton instance of the Payara Micro server.
getInstance() If one does not exist, one will be created and returned.
PayaraMicro Obtains the static singleton instance of the Payara Micro server.
getInstance(boolean If one does not exist and create is set to true, one will be
create)
created and returned, otherwise returns null.
void shutdown()
throws Stops and shuts down the Payara Micro instance.
BootstrapException
PayaraMicroRuntime.class Methods
Method Description
void shutdown() throws Stops and shuts down the Payara Micro
BootstrapException instance.
CDI Methods
These methods are used for firing CDI Events across running instances.
159
Payara Micro API
Method Description
void addCDIEventListener(CDIEventListener listener) Adds a CDI Event Listener.
void removeCDIEventListener(CDIEventListener Removes a CDI Event
listener) Listener.
void addClusterListener(PayaraClusterListener
listener) Adds a Cluster Listener.
void removeClusterListener(PayaraClusterListener
listener) Removes a Cluster Listener.
void publishCDIEvent(PayaraClusteredCDIEvent event) Publishes a CDI Event.
Run Methods
These methods are used for running asadmin commands or Callable objects on
bootstrapped instances.
Method Description
Map<InstanceDescriptor, Runs an asadmin command

Future<ClusterCommandResult>> run (String command, on all members of a Payara
String... args )
Micro Cluster.
Map<InstanceDescriptor, Runs an asadmin command
Future<ClusterCommandResult>> run
(Collection<InstanceDescriptor> members, String on specified members of a
command, String... args ) Payara Micro Cluster.
Runs a Callable object on all
<T extends Serializable> Map<InstanceDescriptor,
Future<T>> run (Callable<T> callable) members of a Payara Micro
Cluster.
<T extends Serializable> Map<InstanceDescriptor, Runs a Callable object on

Future<T>> run (Collection<InstanceDescriptor> specified members of a
members, Callable<T> callable)
Payara Micro Cluster.
Get Methods
These methods are 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.
160
Payara Micro API
Method Description
Collection<InstanceDescriptor> Returns a collection of instance descriptors for all the

getClusteredPayaras() Payara Micros instances in a cluster.
Collection<String>
getDeployedApplicationNames() Returns the names of the deployed applications.
String getInstanceName() Returns the instance name.

InstanceDescriptor Returns the instance descriptor of the instance the
getLocalDescriptor() method is run on.
161
Payara Micro API
Javadoc
The Javadoc for the most recent version of the Payara Micro API can be found here:
http://payara.github.io/Payara/nucleus_API/payara-modules/payara-micro/target/apidocs/
162
History of Release Notes
Appendix: History of release notes

Detailed information about features and fixes in every release.
163
Release Highlights
Our highlights for the 162 release are our new asadmin command recorder, Payara Server's
new ability to create uber jars and a new EAR scoped class loader.
The asadmin recorder feature will allow you view the commands you have run from the
admin console. These can be used to investigate what the console is really doing or used in
automation scripts.
Payara Micro now has --outputUberJar option that allows you to create easily distributed
uber-jars from your war files.
EAR Scoped classloader that loads classes from within the EAR providing the ability to
override server classes.
Payara Server and Payara Micro can now cluster together enabling new cluster topologies
for cloud based and/or containerised deployments!
New Features
This section details the newly developed additions to Payara Server.
636/PAYARA-603 - Payara Micro Enhancements

669/PAYARA-626 - added support for Hazelcast Lite Members
687/PAYARA-249 - Payara Micro Maven Deployer
697/PAYARA-163 - connection pool checker impl
724/PAYARA-201 - Initial working Asadmin Recorder with Admin Console integration
777/PAYARA-629 - Disable CDI for an entire deployment in deployment descriptor
627 - Invocation Webservice deployed from directory
784/PAYARA-685 - Phone Home Service Creation
Updated Modules
This section details the modules that have been updated since the last release (4.1.1.161.1).
Guava 18.0
Weld 2.3.2.Final
Tyrus 1.12
hk2 2.4.0
164
Mojarra 2.2.13
Grizzly 2.3.24
Hazelcast 3.6.2
Enhancements
this release.
602/PAYARA-639 - Unique IDs are kept based on the name of the EJB
677/PAYARA-593 - Cleanup on Admin Console
691/PAYARA-610 - integrated healthcheck with payara micro
694/PAYARA-263 - Autobinding port precedence warnings
711/PAYARA-576 - Integrate upstream pull request for the 4.1.162 release
712/PAYARA-675 - Payara Micro can deploy exploded archive
718/PAYARA-745 - Fix isSupportClientInfo in ConnectionHolder40 for old drivers
720/PAYARA-676 - Restart cluster asadmin command
728/PAYARA-679 - Uber Jar command line option
733/PAYARA-743 - Prevent duplicate server respawn when run under supervision
738/PAYARA-692 - Remove dependency on Hazelcast
739/PAYARA-687 - Implement Hazelcast Cluster Group
745/PAYARA-720 - plugin versions upgraded for to be compatible with maven upgrade
750/PAYARA-688 - Add ability to pass a system properties file to Payara Micro
776/PAYARA-707 - edit of message for tls
749/PAYARA-686 - Clean up the help message by indicating whether a command line
flag has a parameter or not
772/PAYARA-728 - Implement new index page
774/PAYARA-672 - add PostgreSQL ejbtimer table creation sql
785/PAYARA-390 - allow monitoring of asynchronous methods
786/PAYARA-677 - Add support for overriding app server libraries using
ScopedEARClassloader on domain level
Fixed Issues
Payara Fixes
165
617/PAYARA-657 - GLASSFISH-21486: EntityManager should not be detached in

extended Persistence context
637/PAYARA-599 - Remove Boot time OSGI warnings
640/PAYARA-658 - GLASSFISH-20818: Pass passwords from passwordfile to
commands
649/PAYARA-624 - mixed cluster session replication
656/PAYARA-594 - Spurious AllPermission warning
658/PAYARA-542 - Cannot enable secure ciphers for admin listener
659/PAYARA-588 - Excessive logging from the ASURL classloader
667 - #505 is not fixed when TxType is REQUIRES_NEW
672/PAYARA-631 - rollbacked pax-logging and patched the webservices-osgi again
673 - Problems on deployment of OSGi hybrid bundles
678/PAYARA-663 - Cannot find resource bundle
com.sun.logging.enterprise.resource.corba
681/PAYARA-659 - Fix failing transaction recovery when OSGi applications are present
682/PAYARA-671 Always perform clean up on application on DAS upon undeployment
683/PAYARA-660 - Resolve com.sun.aas.instanceName in JVM arguments
686/PAYARA-578 - Payara Blue should use Metro AIX bundle
695/PAYARA-637 - Only-1-Health-Check-Service-is-run-if-no-name-is-specified
698/PAYARA-661 - empty value for sql-trace-listeners in a connection-pool fails
validation
699/PAYARA-665/PAYARA-535 - force JarFileFactory to close all cached Jar
Files/Undeploy App leaves stale NFS handle behind
702/PAYARA-670 - Payara not showing modules for versioned application
704/PAYARA-541/PAYARA-663 - Fix resource bundle issues
709/PAYARA-606 explicitly set TCCL before attempting Batch repository purge on
undeployment
716/PAYARA-744 - Fixed logging dependencies of several modules
717 - isSupportClientInfo in ConnectionHolder40 is not implemented correctly
726/PAYARA-681 - changed gosh command in XML files
727/PAYARA-684 - enabled initializing FacesInitializer while using useBundledJsf param
729/PAYARA-693 - Payara micro: setting SSL trustStore / keyStore manually
734/PAYARA-696 - added default name to connection pool checker
735/PAYARA-494 - Help button displays wrong page and pop-up page is fixed
740/PAYARA-652 - ensure rootDir option does not override domainCofig option
743/PAYARA-636 - setting values for the checker services dynamically is now working
correctly
752/PAYARA-662 - Set TLSv1.2 as default for the asadmin client
757/PAYARA-601 - changed warning note in asenv.conf/asenv.bat
761/PAYARA-727 - Fixed GLASSFISH-21536 possible NPE in SQLTraceRecord
166
763/PAYARA-674 - The "Restart Required" screen does not have the warning about
restarting when Payara is a service
762/PAYARA-717 - invokeMethod now depends on getDeclaredMethod as recursive
instead of getMethod
766/PAYARA-708 - Admin-console-still-shows-Grizzly-Snoop-option-despite-the-feature-
being-removed
783/PAYARA-738 - references to weld osgi bundle.jar should be fixed
Known Issues
167
Payara Server 4.1.1.161.1 Release Notes
Updated Modules
This section details the modules that have been updated since the last release (4.1.1.161).
Metro 2.3.2-b608.payara-p3 (Removed Pax-Logging)
Fixed Issues
Payara Fixes
637/PAYARA-599 Cannot start bundle ../core.jar because it is not contained in the list
of installed bundles
649/PAYARA-624 Mixed Payara Micro and Payara Server cluster causes session loss
656/PAYARA-594 Spurious AllPermission warning
658/PAYARA-542 Cannot enable secure ciphers for admin-listener
659/PAYARA-588 Excessive logging from the ASURL Classloader
667/PAYARA-640 Payara does not rollback when TxType is REQUIRES_NEW
672/PAYARA-631 Problems with Pax-Logging
673/PAYARA-642 Fix Classloader issue when bootstrapping the ORB for OSGi bundle
deployments
Known Issues
168
Release Highlights
The most eye catching feature in this release is a new look for the Admin Console; weve
given the Admin Console another go over from our initial attempt, rebranding it to look more
distinctly Payara!
The more exciting highlight of this release is the Healthcheck Service. In its initial release,
this service allows you to monitor CPU usage, the number of times Garbage Collection has
occurred, the machine memory usage, the heap memory usage, and any hogging threads.
Documentation for it can be found here), and documentation for the asadmin commands can
be found here).
Updated Modules
Jersey 2.22.1
EclipseLink 2.6.2 (Patched to payara-p1)
GlassFish Corba 4.0.1 (Patched to payara-p3)
Woodstock 4.0.2.10 (Patched to payara-p2)
Metro 2.3.2-b608 (Patched to payara-p2)
MQ 5.1.1-b02 (Patched to payara-p1)
Apache commons-fileupload 1.3.1
Enhancements
this release.
511 Add support for Informix for persisted ejb timers

512 Update usages of EclipseLink
551/PAYARA-527 - Speed up Payara Micro boot times
566/PAYARA-540 - Removed cause of spurious warning RAR875
570/PAYARA-491 - Redesign of the admin console
572/PAYARA-408 - Option to turn on orb keepalive
576/PAYARA-549 - Currently only deployment artifacts ending in .war are deployed
583/PAYARA-458 Many threadpools have bad names
169
586/PAYARA-554 SQL tracing and slow SQL logging

588 Payara Micro cant be stopped and restarted in the same process
593/PAYARA-359 - JBatch supports SQL server
605/PAYARA-518 Disable SSL3 on Sec-Admin-listener
613/PAYARA-558 Editing the front page
619/PAYARA-488 Restart behaviour when running windows service
Fixed Issues
Payara Fixes
195/PAYARA-222 Jbatch and Postgresql db as job repository fails

229/PAYARA-548 - Fix CDI and SAM
468/PAYARA-323 Admingui crashes after timeout
481/PAYARA-477 Behaviour of Logging for @Transactional CDI methods
491/PAYARA-346 WELD warnings during deployment
492/PAYARA-511 Redploying war/ear on cluster fails
494/PAYARA-376 Instance server.log written to despite change of log file
name/location
497/PAYARA-490 admin GUI interface refresh issue
500/PAYARA-406 Wrong thread name in server.log
502 - Message catalog key not transformed: using.default.ds
505/PAYARA-510 Payara does NOT rollback when RuntimeException occurs in CDI
@Transactional method using JDBC
510/PAYARA-547 - @DataSourceDefinition defined data source can't be used in
persistence.xml
525/PAYARA-449 Sporadic attempted duplicate class definition for name in Payara
4.1.153
534/PAYARA-446 Multiple cookies cannot be added using Headers.putAll()
535/PAYARA-526 - Problems with jndi lookup
536/PAYARA-551 - Websocket @OnOpen sometimes isn't called
539/PAYARA-556 - ACC needs 3 seconds for initialContext.lookup("myHome")
540/PAYARA-520 Fix Batch: SQL string is not Query
545/PAYARA-492 Fix WSIT enabled WS services
549/PAYARA-480 - Warnings when connecting via JMX
555/PAYARA-529 - Problem with mcAddress on payara micro
170
556/PAYARA-496 - ensure the truststore is only written to when we have read/write

permissions
560/PAYARA-533 - Upgrade Commons File Upload
561/PAYARA-486 - Fixed wrong session count after failover
564/PAYARA-538 - Upstream commit breaks redeploy of CargoTracker
567/PAYARA-371 - Spurious warning when changing open mq admin/guest password
578/PAYARA-346 - added javax.ejb as an imported package to the weld integration
bundle
589/PAYARA-557 - Incorrect Server Version and Vendor provided in JMX Bean
596/PAYARA-568 - Payara Blue uses incorrect key algorithm
603/PAYARA-560 Not all batch objects use prefix/suffix
615/PAYARA-495 - Fix FileNotFoundException "noop=true"
618 Deployment of EJB_Timer_App when app has orm.xml
627 Webservice deployed from directory archive on windows fails
632/PAYARA-602 - Update woodstock version to fix exploit
Known Issues
171
Release Highlights
This release brings us back in line with GlassFish 4.1.1, with the benefit of all our additional
fixes and enhancements from our previous releases, as well as a few more. Of particular
interest in this release:
Up to date with GlassFish 4.1.1.

Removal of the dependency on .NET Framework 3.5, allowing Payara to be used with
.NET Framework 4.
The payaradomain domain will now use an embedded Derby database for its default
datasources (domain1 is unchanged to retain drop-in replacement viability).
You can now set DISABLED as a JMS Broker type, allowing you to disable the
OpenMQ Broker.
Setting size-based log rotation to 0 will now turn it off.
In line with our naming strategy, our version number has also been extended for this release
to reflect the fact that we are up to date with GlassFish 4.1.1.
Updated Modules
This section details the modules that have been updated since the last release (4.1.153).
Mojarra 2.2.12
Webservices 2.3.2-b608
JAXB 2.2.12-b141219.1637
JAXB-API 2.2.13-b141020.1521
Weld 2.2.16.Final
Tyrus 1.11
JBatch 1.0.1-b09
Grizzly 2.3.23
HK2 2.4.0-b32
Jersey 2.22
Hazelcast 3.5.2
Enhancements
172
this release.
414/PAYARA-389 - Disable size based log rotation when set to zero

421/PAYARA-447 Add some simple asadmin commands
425 - Make Instance Descriptor null safe when zero applications deployed
429/PAYARA-387 - Make the default DerbyPool use Derby Embedded
439/PAYARA-427 - Allow DISABLED as a JMS Broker type.
440 - Allow MDB to specify the resource adapter to use in the Activation Config
457/PAYARA-409 Remove Update Center
463/PAYARA-369 - Payara product names are not correct in the console. Should be
Payara Server
467/PAYARA-457 - classloader work
475/PAYARA-347 - Converter autoApply does not work for primitive types
479/PAYARA-453 - Windows service wrapper depends on .NET Framework 3.5
Fixed Issues
Payara Fixes
270 - Support rolling updates

300 - Bean identifier index inconsistency after Hot re-deployment from NetBeans
327 - Tyrus send partial message more than buffer size will cause exception in catalina
OutputBuffer
350 - Using AJP when downloading of large streaming data results in the errors
"OutOfMemoryError: Java heap space" and "503 Service Temporarily Unavailable"
371 - Creating an HTTP listener with security enabled using web admin console doesn't
work
377 - JAX-RS integration with EJB Technology doesn't work
385/PAYARA-444/GLASSFISH-21371 - Alternate descriptors not persisted in remote
deployments
395 - IllegalArgumentException when starting a payara micro on Windows via cli with --
rootDir or --domainConfig
409/PAYARA-266 - Unable to add or remove java debug option using asadmin
410/PAYARA-349 - Batch configuration requires data source on DAS
411/PAYARA-372 - JMS broker issues when broker port is already in use
173
412/PAYARA-373 - REST interface to create auth-realm fails

415/PAYARA-405 It is possible to set invalid ejb container thread pool settings
418/PAYARA-415 - Can not inject PayaraMicroRuntime CDI bean when deploying a war
on the PayaraMicro command line
420 - Changed the way to load payara-bootstrap.properties.
423 - Payara Micro name not passed through to the instance descriptor
427/PAYARA-322 - enable-secure-admin-principal adds principal multiple times
433/PAYARA-452 - Clustered / Versioned applications cannot be enabled on individual
cluster instances
458/PAYARA-466 - File deleted after successfuly deployed with web gui local file dialog
460/PAYARA-459 - ${com.sun.aas.hostName} not resolved correctly in JVM options
465/PAYARA-448 - Could not load class javax.rmi.CORBA.EnumDesc
472/PAYARA-454 - NPE thrown by JMS Ping if no Default JMS Host is configured on
the DAS
485/PAYARA-388 - Server log displays webappClassLoader severe warnings on
shutdown
PAYARA-370 - Fixes confusing typo in the admin console
GLASSFISH-21007 - HTTP Upgrade handler init called twice when access log is turned
on
Upstream Fixes
This section details the fixes brought in from the GlassFish upstream.
GLASSFISH-21009 - The behavior of --timeout-seconds is not in line with the document

GLASSFISH-21172 - javax.transaction.RollbackException from @Transactional bean
has no cause set
GLASSFISH-21381 - war with web service not deploying correctly
GLASSFISH-21391 - Disable SSLv3 by default in config module
GLASSFISH-21426 - Application deployment fails when DataSourceDefinition
annotation is used within an EJB inside a war.
fix enforcer version of the javadoc-jdk8+ profile activation
fixed redundant null check caught by findbugs for an earlier commit
In case of JDK 9, java.logging loading sun.util.logging.resources.logging resource
bundle and java.logging module is used as the cache key with null class loader.So we
are adding a null check
As per servlet spec 3.1, when Request.setCharacterEncoding(String enc) is called, the
call should be a no-op if request input parameters have already been read or if
getReader() has been called. However, at present, check is there only in case of use of
reader and no check if parameter has been read by a different method call (e.g by
calling getParameter()). This seems to be a regression introduced during Grizzly 2.0
174
integration in revision 46674. Changes have been made to check if parameters have
been processed/read too. character encoding will not be set if either parameters have
been reader or reader is being used.
EjbDescriptor abstract class implements JndiNameEnvironment and
WritableJndiNameEnvironment. For some of these methods, though there is a generic
implementation (For example via CommonResourceDescriptor), these methods still
needs to be implemented in a specific way within EjbDescriptor abstract class to get the
expected behavior whenever these methods are invoked in EjbDescriptor's context. To
ensure the same, a new unit test is being introduced within source workspace, namely
EjbDescriptorInheritedMethodImplementationTest,which basically ensures following two
things: All methods defined in JndiNameEnvironment and
WritableJndiNameEnvironment have a direct implementation within EjbDescriptor
abstract class and all these methods are marked final in EjbDescriptor to ensure that
sub-classes of EjbDescriptor don't override these methods accidentally, possibly
causing unexpected behavior.
fix web container issue filed in Grizzly
Known Issues
175
Payara Server 4.1.153 Release Notes
Release Highlights
This release has several notable features:
The Payara Micro API has been improved, now granting control over running instances
and the ability to run asadmin commands.
There is now an auto-binding feature for the HTTP and HTTPS ports of Payara Micro
instances. This feature allows Payara Micro instances to automatically find a free port if
the default or specified HTTP or HTTPS ports are already bound to.
This release also introduces the Payara-Blue series of distributions, built using the IBM
JDK for AIX systems.
See the What's new in Payara 4.1.153 blog for descriptions of these features.
Updated Modules
Mojarra 2.2.11
Javax XML Registry API 1.0.7
Weld 2.2.13.Final
JBatch Container 1.0.1-b08
JBatch SPI 1.0.1-b08
Grizzly 2.3.21
Jersey 2.19
Jackson 2.5.1
Mail 1.5.4
Hazelcast 3.5
Enhancements
This section details the GitHub issues marked as enhancements that have been
implemented for this release.
61 - Docker support?
175 - Add extra usage instructions for set-batch-runtime-configuration Asadmin
command
188 - CDI container should be able to inject Cache
176
297 - Make Payara Micro Failfast

314 - Extend Payara Micro api to enable deployment from an InputStream
321 - Support all attribute names in set-log-attributes
325 - Jcache enhancements
332 - Review file handling for Master Password
333 - file permissions should be set on master-password file using NIO2 file attribute api
rather than chmod-via-ProcessBuilder
334 - file permissions should be set on glassfish client password file using NIO2 file
attribute api rather than chmod-via-ProcessBuilder
339 - Upgrade to Hazelcast 3.5 for JCache fix
347 - Payara micro enhancements
349 - Don't make me think about payaradomain vs. domain1 (have asadmin start-
domain "just work")
359 - Automatically increment busy payara micro http and https ports
361 - Update Japanese translation
Fixed Issues
This section details the GitHub issues marked as bugs that have been fixed for this release.
204 - JBatch fails to execute job on @Startup

276 - lib/ext does not exist in domains created by 4.1.152 resulting in failure during add-
library
288 - payara embedded/micro artifacts unresolvable in maven central repo
291 - Fix of domainConfig argument, the index specified error.
293 - Fix Payara Micro Warnings on boot
329 - Add support for access-logging of session attributes
330 - glassfish-ha module uses incorrect groupId for ha-hazelcast-store dependency
Upstream Fixes
This section details the fixes brought in from the GlassFish upstream.
Fix for GLASSFISH-20856

fix for bug GLASSFISH-20864
Glassfish part of the fix of the https://java.net/jira/browse/GRIZZLY-1786
GLASSFISH-21131 fix
fix aggregated test report for newer hudson versions
177
Changed fix for GF 20680326

fix broken images links, and allow jdk8 to be used to have the {@docRoot}
FindBug fix
fix for bug-20864
fix for GLASSFISH-21261
fiix for bug-20931
Fix for GLASSFISH-21343 - GlassFish fails to start on MacOSX 10.10.3
Fix for findbug GF_UNCONDITIONAL_DEBUG_LOGGING error in In
stalledLibrariesResolver.java
Fix for findbug DLS_DEAD_LOCAL_STORE error in WebContainer.java
fix no args usage of gfbuild.sh
Fix for GLASSFISH-20842 - X-Forwarded-Proto not honored by glassfish 4.0
Commit for Bug GLASSFISH-21028:Deployment from Web Console: temporary files are
not deleted
178
Fixed Issues
272 - Cannot log in to Admin Console of Domain created from payara-domain.jar

Template
275 - Bug on click Enable Secure Admin button
179
Release Highlights
The payara-embedded-nucleus distribution has been replaced by the Payara Micro
distribution. This is a light-weight distribution that has Hazelcast integrated to allow for
automatic web session clustering and JCache distribution.
We have also added a separate Payara domain template, which has a few optimisations:
Increased PermGen Size of 512m (previously 192m)

Increased Xmx value of 1024m (previously 512m)
Removed Felix OSGI parameters
Increased HTTP thread pool size of 50 (previously 5)
Changed the JVM option client to server (this has been done for both domain
templates)
Added the JVM option to reject client initiated TLS renegotiation
Updated Modules
This section details the modules that have been updated since the last release (4.1.151).
Hazelcast 3.4.2
EclipseLink 2.6 (Payara Patched)
Weld 2.10.SP1
GlassFish-CORBA 4.0.1-p1 (Payara Patched)
Grizzly 2.3.19
HK2 2.4.0-b12
HK2 Plugin 2.4.0-12
Jersey 2.17
JMS API 2.0.1
Mojarra 2.2.10
Webservices 2.3.1-b419 (downgrade)
JAXB API 2.2.12-b140109.1041 (downgrade)
JAXB 2.2.10-b140802.1033 (downgrade)
MQ 5.1.1-b02
Tyrus 1.10
Shoal 1.7.0-M1 (Payara Patched)
180
Enhancements
implemented for this release.
72 Create fix for GLASSFISH-21236 (JDK 9 Support)

154 - Payara #154 - Removed the Classloader hack for older Hazelcast versions
166 Upgrade EclipseLink to the latest
168 Update the default-web.xml to to set xpoweredBy init param to false for
JspServlet
186 Within Netbeans, I no longer can create a glassfish server entry with payara-
4.1.155
190 - Adds cluster back into payara-minimal
193 - Add hazelcast dependency to payara-web-embedded pom
206 - Review table names for Jbatch
208 Get Web Session Clustering on Payara Embedded
217 Upgrade Mojorra to 2.2.10
230 Add Serialization of values in JSR107 CDI
234 Upgrade Weld to 2.2.10.Final or newer
259 - Ensure key system properties are set by Payara Micro
Fixed Issues
138 Verify Symbolic link checking in Payara

139 Fix exception handling code in com.sun.enterprise.util.io.FileUtils.java
191 Payara Embedded Web Profile does not contain Hazelcast
192 Prevent null pointer exception when GMS is not enabled
197 Slow startup/hang when application uses Eclipselink and genericra
207 Fix checking to verify table existence in specified schema in DB2 persistence
manager
209 - CDI Injection in Entity Listener results in null reference
218 - EJB webservice with wssecurity policy gets NoClassDefFoundError:
org/apache/commons/logging/LogFactory
216 com.sun.gjc.spi.jdbc40.ProfiledConnectionWrapper40 changes Exception thrown
by wrapped jdbc Connection (fix inside)
228 Investigate GLASSFISH-20670 JSF Performance
239 - java.lang.ClassNotFoundException:
181
javax.xml.parsers.ParserConfigurationException not found by

org.eclipse.persistence.moxy
244 Transaction is aborted after 2 minutes
251 - Performance regression in corba serialization in migration glassfish 4.0 -> payara-
4.1.151
262 - Incorporate fix for GLASSFISH-21343
269 Nightly build 2015-04-28 does not allow creating jdbc connection pool resources
through web interface
182
Release Highlights
JBatch has been upgraded to version 1.0.1-b04 and now recognises MySQL, Postgresql,
Oracle, and DB2 as persistence managers. Hazelcast 3.4 has also been implemented as a
clustered web session store and provider of JSR107.
We are also now providing distributions of the Multi-Language (ml) releases, which contain
the l10n packages from GlassFish.
Note We lack translations for the additions we have made, such as the Hazelcast
configuration page in the Admin Console. We would prefer to not accept internet translations
as they are typically inaccurate.
Updated Modules
This section details the modules that have been upgraded since the last release (4.1.144).
Jersey 2.15
Tyrus 1.9
JSTL-Impl 1.2.4
Mojarra 2.2.9
Weld 2.2.7
Javax Batch API 1.0.1-b01
JBatch Container 1.0.1-b04
JBatch SPI 1.0.1-b04
Grizzly 2.3.18
HK2 2.4.0-b08
HK2 Plugin 2.4.0-b08
Jackson 2.5.0
Jettison 1.3.7
Shoal 1.6.22
Metro 2.3.2-b608
JAXB-API 2.2.13-b141020.1521
JAXB 2.2.12-b141219.1637
New Module
183
Hazelcast 3.4
Enhancements
implemented for this release. You can view the issues in detail by following the provided
links.
25 Disable SSLv3 in default domain template

28 Integrate Hazelcast as JSR107 provider
29 Integrate Hazelcast as a clustered web session store
80 Integrate MySQL persistence manager into JBatch
81 Integrate Oracle persistence manager into JBatch
82 Integrate PostgreSQL persistence manager into JBatch
83 Integrate DB2 persistence manager into JBatch
86 Integrate different persistence managers into GF-batch-connector
111 Allow Blank Schema for JBatch
149 Update underlying specification implementations Fixed Issues This section details
the GitHub issues marked as bugs that have been fixed for this release. You can view
the issues in detail by following the provided links.
45 Glassfish 21148 - fixed bug in SSO clustered session management
46 Glassfish 21219
47 GLASSFISH-21146 Fixed NPE in log
53 Merge Patched Grizzly jar into build
68 Merge Fix for GLASSFISH-21251
70 Merge Fix for GLASSFISH-21007
76 Upgrade Weld to 2.2.4.Final or newer
79 Merge fix for GLASSFISH-21261
84 Fix XForwarded-Proto GLASSFISH-20842
85 - Create Fix for https://java.net/jira/browse/GLASSFISH-21249
101 Force early creation of static transaction manager to fix GLASSFISH-21175
114 Fix GLASSFISH-21265
122 JDBC Monitoring MBeans not working in JConsole
127 Further MBeans are broken GLASSFISH-21276
131 Java EE 7 Sample Chunk CSV Database Test Fails
184
185
Feature Improvements
Payara 4.1.144 ships with support for setting the schema in JBatch for Derby (GlassFish-
21041). This can be found in the Admin Console under server > Batch > Configuration
Tyrus has also been updated to version 1.8.3.
Bug Fixes
Payara 4.1.144 was built upon GlassFish 4.1, so contains all of the bug fixes and
improvements to be found there. The release notes for GlassFish 4.1 can be found here.
In addition to the fixes incorporated into GlassFish 4.1, Payara 4.1.144 also has the
following additional bug fixes:
GlassFish-21242 - Glassfish throws NPE with System.out.println(null)

GlassFish-21018 - set-batch-runtime-configuration change not reflected in admin gui
GlassFish-21138 - After editing Availability service in configurations domain.xml
corrupted
GlassFish-20610 - Fix spurious log messages on boot of AMX
GlassFish-21239 - Monitoring is not displayed in the console if the administrator
password is not blank
GlassFish-20718 - Write to System Log option do not send log on localhost udp port
514
GlassFish-21175 - Glassfish Hang when Timer application configured with XA
Datasource
GlassFish-21098 - GlassFish 4.x can't be built using jdk8
GlassFish-21159 - X-PoweredBy sent even when disabled in the console
GlassFish-20895 - @ForeignKey creates wrong ALTER TABLE statement
186

Payara Server Documentation Fork

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Payara Server Documentation Fork

Загружено:

Авторское право:

Доступные форматы

Table

Payara Server Documentation

The documentation of Payara Server edition. Consists of basic information, features

Useful guides and tutorials

Payara Micro Documentation

The documentation of Payara Micro edition

2016 Q3 - Payara Server 4.1.163

2015 Q4 - Payara Server 4.1.154

2014 Q4 - Payara Server 4.1.144

Welcome to the Payara wiki General

GlassFish Upstream Cherry-Pick

2. Downloading Payara Server

3. Starting Payara Server

4. Accessing the Administration Console

5.1 Deploying using Asadmin

5.2 Deploying using Administration console

Welcome to the Payara wiki Build Instructions

Oracle JDK 7 Update 65 or later, or Oracle JDK 8 Update 20 or later.

Create a MAVEN_OPTS environment variable and set it as:

Getting the Source Code

mvn clean install

mvn clean install -DskipTests

Building Payara Micro

All Release Notes

2016 Q3 - Payara Server 4.1.1.163

2015 Q4 - Payara Server 4.1.1.154

2014 Q4 - Payara Server 4.1.144

PAYARA-168 - Integrate HealthCheck notifications with the Notification Service

PAYARA-177 - Trace EJB Method Calls

943/PAYARA-909 - healthcheck commands do not accept configurations as a target

852/PAYARA-795 - Payara Blue on IBM JDK invalid JVM options

1011/PAYARA-953 - Fix CVE-2016-3607

How to install a custom JACC provider

Payara's global classpath on boot.

These will result in the following domain.xml snippet to be added:

by the jacc attribute on the security-service element.

This section describes additional improvements added by Payara Server.

Payara Server Deployment Descriptor

Elements of the Deployment Decriptor

Advanced JDBC Configuration and

Many performance problems in Enterprise Applications can be traced to slow database

Slow SQL Logging

See Slow-SQL-Logger for detailed information.

Full JDBC Tracing

See Log-JDBC-Calls for detailed information.

SQL Trace Listeners

See SQL Trace Listeners for detailed Information.

Advanced Connection pool Configuration

See Advanced Connection Pool Properties for detailed information.

Payara Micro Support

JDBC Call Logging (SQL Tracing)

Enabling JDBC Call Logging

asadmin command line interface

asadmin set domain.resources.jdbc-connection-pool.__TimerPool.log-jdbc-calls=true

or the Datasource definition can be added to a deployment descriptor of an application for

Payara Micro Support

Slow SQL Logger

Many performance problems in Enterprise Applications can be traced to slow database

Configuring the Slow SQL Logger

asadmin set domain.resources.jdbc-connection-pool.__TimerPool.slow-query-threshold-in-

asadmin set domain.resources.jdbc-connection-pool.__TimerPool.slow-query-threshold-in-

or the Datasource definition can be added to a deployment descriptor of an application for

java.lang.Exception: Stack Trace shows code path to SQL