Configure Payara Server with Dotted Names

Experienced users of Payara Server will already be familiar with some common asadmin commands, such as start-domain, create-cluster, and change-admin-password, which are the recommended way to manage the configuration of a Payara Server domain.

Unfortunately, there is not a specific asadmin command for every configurable attribute in Payara Server. This is where dotted names, and the get, set, and list commands come in. 

Every attribute that can be defined in the domain.xml also has a corresponding "dotted name" attribute, which can be viewed and configured with the commands mentioned above - get, set, and list. This provides a safer method of configuring a domain over manually editing the domain.xml thanks to the validation it provides.

Configuring domains using asadmin commands is always preferred due to the ability to include the commands in a script and to avoid common typo errors. 

To begin using dotted names for configuration, some explanation is needed. 

What are Dotted Names?

Dotted names in Payara Server refer to the attributes of a domain, taking a form commonly seen in properties files. A dotted name is used to identify specific elements in the Payara Server, such as configurable or monitorable objects, with the period (.) acting as a delimiter between parts of the name. The dotted names form a tree structure of attributes, where each dot acts as a node, providing an easy to understand means of viewing and configuring the values of each attribute.

For example, in the default domain template there is an HTTP listener named http-listener-1.  This listener has two attributes: name and security-enabled, determining the name of the listener and whether or not it has security (HTTPS) enabled. These attributes would respectively be represented in dotted name format by:

configs.config.server-config.network-config.protocols.protocol.http-listener-1.name
configs.config.server-config.network-config.protocols.protocol.http-listener-1.security-enabled

Note: In some cases you might also see default-config instead of server-config. The server-config is used by the default server instance, while default-config can act as a template or shared base. Be sure you're targeting the correct one for your changes.

It’s sometimes easier to envision the dotted names as the tree structure they actually represent. For the example given above, it would look like this:

configs
 └── config
      └── server-config
           └── network-config
                └── protocols
                     └── protocol
                          └── http-listener-1
                               ├── name
                               └── security-enabled

If any part of a dotted name itself includes a period (.), that period must be escaped with a backslash (\.) so it is not treated as a delimiter.

The Get Command

This commands retrieves the current value of attributes by looking up its dotted name. This command accepts wildcards, so it can be used to get the values of multiple attributes at once or, if the precise list of options for a component is not known, a wildcard can be used to return a long list of options

As an example, to get the values of the http-listener-1 attributes (see the diagram above), you can run:

asadmin> get configs.config.server-config.network-config.protocols.protocol.http-listener-1

The output of this command looks like this:

configs.config.default-config.network-config.protocols.protocol.http-listener-1.name=http-listener-1
configs.config.default-config.network-config.protocols.protocol.http-listener-1.security-enabled=false

Using get '*' returns all attributes at the top level of the configuration hierarchy. To get deeper attributes, use patterns like get server.*.* or get configs.config.server-config.*

asadmin> get *

Characters that have special meaning to the shell or command interpreter, such as * (asterisk), should be quoted or escaped as appropriate to the shell, for example, by enclosing the argument in quotes. In multimode, quotes are needed only for arguments that include spaces, quotes, or backslash.

The List Command

This command serves the same function as the ls command from the Linux/PowerShell terminal, listing the tree nodes (or directories) that have attributes or further child nodes (subdirectories). Differing from the get command, this command is more suitable for navigating the tree since it returns the names of nodes, allowing for more easy navigation of the dotted name tree.

For example, to list the children of the http-listener-1 HTTP listener:

asadmin> list configs.config.server-config.network-config.protocols.protocol.http-listener-1

This returns:

configs.config.server-config.network-config.protocols.protocol.http-listener-1
configs.config.server-config.network-config.protocols.protocol.http-listener-1.http
configs.config.server-config.network-config.protocols.protocol.http-listener-1.ssl

This indicates that this listener has two child nodes, http and ssl, as well as its own attributes (signified by the command returning itself as a result). This can then be followed up for further navigation of the tree by running the list command in one of the child nodes shown, or using the get command to list the values of the attributes of the http-listener-1 node.

Like the get command, list also accepts wildcards, making searching and navigation easier.

Without a wildcard, list returns only the immediate children of the specified node. With a wildcard, it traverses the hierarchy.

The Set Command

As indicated by the name, this is the command that sets the value of an attribute. Once the dotted name of an attribute is known, this command can be used to set the attribute's value, provided your supplied value passes basic validation checks.

For example, to enable security on the http-listener-1 HTTP listener, you would run this:

asadmin> set configs.config.server-config.network-config.protocols.protocol.http-listener-1.security-enabled=true 

This property is a boolean, so the value entered here would have to be either true or false, or the validation check would reject it.

Final Notes

Using dotted names with asadmin gives you deep, scriptable control over your Payara Server's configuration and monitoring setup. It also offers validation and structure, reducing risk when compared to direct domain.xml edits.

Attributes from the monitoring hierarchy are read-only and reflect runtime metrics. Use the --monitor=true option with get or list to access these, for example:

asadmin> get --monitor=true server.jvm.memory.usedheapsize-count