Working with GlassFish & Payara Server Dotted Names

Many of you will know of some of the common asadmin commands, such as start-domain, create-cluster, and change-admin-password, some of which I covered in a previous blog written for GlassFish (which still holds true for Payara Server).

Unfortunately, there is not a specific asadmin command for every configurable attribute in GlassFish or 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 get, set, and list commands. 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 also preferred due to the ability to include the commands in a script.

I’ve found that the get, set, and list commands are often ignored from online tutorials, and are rarely mentioned besides that. So in this blog, I’ll give a quick overview of the commands, and how you can use them to configure a domain. First though, a quick description of dotted names.

Dotted Names

Dotted names in Payara Server and GlassFish refer to the attributes of a domain, taking a form commonly seen in properties files. The dotted names form a tree structure of attributes, with each dot acting as a node. For those of a certain mindset, this provides an easy to understand means of viewing and configuring the values of each attribute.

As an 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 it has security (HTTPS) enabled or not. These attributes would respectively be represented in dotted name format by:

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

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:

The Get Command

This commands retrieves the dotted name and current value of an attribute, particularly useful if you’re not a maverick - configuring attributes blindly. Helpfully, this command accepts wildcards, so you can use it to get the values of multiple attributes at once.

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

asadmin get configs.config.default-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

Alternatively, if you’re having trouble finding an attribute, you can simply list every single attribute and their values by using an asterisk as a wildcard:

asadmin get "*"

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 as it returns the names of nodes, allowing you to more easily navigate the dotted name tree.

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

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

This returns:

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

This lets us know 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). We can then follow this up and navigate further into the tree by running list in one of the child nodes, or using the get command to list the attributes and their values of the http-listener-1 node.

As a bonus, this command also accepts wildcards, making searching and navigation easier.

The Set Command

As you can probably gather from the name, this is the command that sets the value of an attribute. Once you know the dotted name of the attribute that you intend to alter, you can use this command to set its value, provided your supplied value passes any validation checks.

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

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

The value entered here would have to be either true or false, else the validation check would reject it. This is something that raises configuring the domain in this way above altering the domain.xml; it helps to reduce user error.

Wrapping Up

While most of us use, and will continue to use, the bespoke asadmin commands to do our domain configuration (myself included!), it’s always good to let people know that they aren’t all encompassing and that there is a backup to fall back on before we resort to hacking around in the domain.xml.