Using REST Resource Methods to Administer GlassFish Server

The GlassFish Server REST interfaces support methods for accessing nodes in the monitoring and configuration object trees.

The following table shows the REST methods for administering monitoring and configuration data and the tasks that you can perform with each method. These methods are HTTP 1.1 primitives. For the detailed specification of these primitives, see Hypertext Transfer Protocol -- HTTP/1.1.

The GET method can be used instead of the OPTIONS method to determine the methods and method parameters that a node in the tree supports. The GET method also provides additional information about the node. For details, see To Retrieve Data for a Node in the Tree.

To Determine the Methods and Method Parameters That a Node in the Tree Supports

The methods and method parameters that a node in the tree supports depend on the REST resource that represents the node:

• REST resources for monitoring support only the GET method.

• All REST resources for configuration support the GET method and the OPTIONS method. However, only some REST resources for configuration also support the POST method and the DELETE method.

Before performing any operations on a node in the tree, determine the methods and method parameters that the node supports.

You can specify the format in which this information is presented. For more information, see Formats for Resource Representation.

1. Ensure that the server is running.

   Operations on REST resources for GlassFish Server data require a running server.

2. Use the appropriate method on the REST resource that represents the node.

   • If the node is in the monitoring object tree, use the GET method.

   • If the node is in the configuration object tree, use the OPTIONS method or the GET method.

   The GET method and the OPTIONS method return the list of methods that the resource supports. For each method, the list of acceptable message parameters or the list of acceptable query parameters are returned.

Example 2–21 Determining the Methods and Method Parameters That a Node in the Tree Supports

This example uses the cURL utility to determine the methods and method parameters that the resource for the domain supports. The example uses the following options of the cURL utility:

• -X to specify that the OPTIONS method is used

• -H to specify that the resource is represented in JavaScript Object Notation (JSON)

In this example, the DAS is running on the local host and the HTTP port for administration is 4848. In addition to the OPTIONS method, the resource supports the POST method and the GET method.

curl -X OPTIONS -H "Accept: application/json" http://localhost:4848/management/domain
{"Domain":
  {
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "log-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "application-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "locale":{"Key":"false", "Type":"string", "Optional":"true"},
        "version":{"Key":"false", "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    }
  }
}

To Retrieve Data for a Node in the Tree

Retrieving data for a node in the tree obtains the following information about the REST resource that represents the node:

• A list of the REST methods that the resource supports

• A list of the attributes of the resource and their values

• A list of URLs to the children of the resource

You can specify the format in which this information is presented. For more information, see Formats for Resource Representation.

1. Ensure that the server is running.

   Operations on REST resources for GlassFish Server data require a running server.

2. Use the GET method on the REST resource that represents the node.

Example 2–22 Retrieving Data for a Node in the Tree

This example uses the cURL utility to retrieve data for the resource for a domain. The example uses the following options of the cURL utility:

• -X to specify that the GET method is used

• -H to specify that the resource is represented in JavaScript Object Notation (JSON)

In this example, the DAS is running on the local host and the HTTP port for administration is 4848.

Line breaks are added to enhance readability.

curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain
{

  "Domain":{"log-root":"${com.sun.aas.instanceRoot}/logs", 
"application-root":"${com.sun.aas.instanceRoot}/applications", 
"locale":"", "version":"74.1"},

  "Methods":{
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "log-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "application-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "locale":{"Key":"false", "Type":"string", "Optional":"true"},
        "version":{"Key":"false", "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    }
  },

  "Child Resources":[
    "http://localhost:4848/management/domain/configs",
    "http://localhost:4848/management/domain/resources",
    "http://localhost:4848/management/domain/servers",
    "http://localhost:4848/management/domain/property",
    "http://localhost:4848/management/domain/applications",
    "http://localhost:4848/management/domain/system-applications",
    "http://localhost:4848/management/domain/stop",
    "http://localhost:4848/management/domain/restart",
    "http://localhost:4848/management/domain/uptime",
    "http://localhost:4848/management/domain/version",
    "http://localhost:4848/management/domain/rotate-log",
    "http://localhost:4848/management/domain/host-port"
  ]

To Add a Node to the Tree

1. Ensure that the server is running.

   Operations on REST resources for GlassFish Server data require a running server.

2. Determine the acceptable message parameters for the POST method of the resource that represents the parent of the node.

   For information about how to perform this step, see To Determine the Methods and Method Parameters That a Node in the Tree Supports.

3. Use the POST method on the REST resource that represents the parent of the node that you are adding.

4. Confirm that the node has been added.

   Perform this step on the resource that represents the node that you have just added, not the parent. For information about how to perform this step, see To Retrieve Data for a Node in the Tree.

Example 2–23 Adding a Node to the Tree

This example uses the cURL utility to add a JDBC resource node to the tree by creating a REST resource to represent the JDBC resource.

In this example, the DAS is running on the local host and the HTTP port for administration is 4848.

Line breaks are added to enhance readability.

1. This step determines the acceptable message parameters for the POST method of the resource jdbc-resource.

   curl -X OPTIONS -H "Accept: application/json" http://localhost:4848/management/domain/resources/jdbc-resource {"JdbcResource": { "Method":{ "Name":"POST", "Message Parameters":{ "id":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"false"}, "enabled":{"Acceptable Values":"", "Default Value":"true", "Type":"boolean", "Optional":"true"}, "description":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"}, "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"}, "property":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"}, "connectionpoolid":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"false"} } }, "Method":{ "Name":"GET" } } }

2. This step adds a resource as a child of the jdbc-resource resource. The -d option of the cURL utility sets the required message parameters as follows:

   • id is set to jdbc/myjdbcresource.

   • connectionpoolid is set to DerbyPool.

   curl -X POST -d "id=jdbc/myjdbcresource&connectionpoolid=DerbyPool" http://localhost:4848/management/domain/resources/jdbc-resource "http://localhost:4848/management/domain/resources/jdbc-resource/ jdbc/myjdbcresource" created successfully.

3. This step confirms that the node has been added by retrieving data for the REST resource that represents the node.

   curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource { "JdbcMyjdbcresource":{"enabled":"true", "pool-name":"DerbyPool", "description":"", "jndi-name":"jdbc/myjdbcresource", "object-type":"user"}, "Methods":{ "Method":{ "Name":"POST", "Message Parameters":{ "enabled":{"Key":"false", "Default Value":"true", "Type":"boolean", "Optional":"true"}, "pool-name":{"Key":"false", "Type":"string", "Optional":"true"}, "description":{"Key":"false", "Type":"string", "Optional":"true"}, "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"}, "object-type":{"Key":"false", "Default Value":"user", "Type":"string", "Optional":"true"} } }, "Method":{ "Name":"GET" }, "Method":{ "Name":"DELETE", "Message Parameters":{ "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"} } } } }

To Update a Node in the Tree

1. Ensure that the server is running.

   Operations on REST resources for GlassFish Server data require a running server.

2. Determine the acceptable message parameters for the POST method of the resource that represents the node.

   For information about how to perform this step, see To Determine the Methods and Method Parameters That a Node in the Tree Supports.

3. Use the POST method on the REST resource that represents the node that you are updating.

4. Confirm that the node has been updated.

   For information about how to perform this step, see To Retrieve Data for a Node in the Tree.

Example 2–24 Updating a Node in the Tree

This example uses the cURL utility to update a JDBC resource in the tree by modifying the REST resource that represents the JDBC resource.

In this example, the DAS is running on the local host and the HTTP port for administration is 4848.

Line breaks are added to enhance readability.

1. This step determines the acceptable message parameters for the POST method of the resource jdbc-myjdbcresource.

   curl -X OPTIONS -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource {"JdbcMyjdbcresource": { "Method":{ "Name":"POST", "Message Parameters":{ "enabled":{"Key":"false", "Default Value":"true", "Type":"boolean", "Optional":"true"}, "pool-name":{"Key":"false", "Type":"string", "Optional":"true"}, "description":{"Key":"false", "Type":"string", "Optional":"true"}, "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"}, "object-type":{"Key":"false", "Default Value":"user", "Type":"string", "Optional":"true"} } }, "Method":{ "Name":"GET" }, "Method":{ "Name":"DELETE", "Message Parameters":{ "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"} } } } }

2. This step updates the REST resource jdbc-myjdbcresource to disable the JDBC resource that jdbc-myjdbcresource represents. The -d option of the cURL utility sets the enabled message parameter to disabled.

   curl -X POST -d "enabled=false" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource "http://localhost:4848/management/domain/resources/jdbc-resource/ jdbc-myjdbcresource" updated successfully.

3. This step confirms that the node has been updated by retrieving data for the REST resource that represents the node.

   curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource { "JdbcMyjdbcresource":{"enabled":"false", "pool-name":"DerbyPool", "description":"", "jndi-name":"jdbc/myjdbcresource", "object-type":"user"}, "Methods":{ "Method":{ "Name":"POST", "Message Parameters":{ "enabled":{"Key":"false", "Default Value":"true", "Type":"boolean", "Optional":"true"}, "pool-name":{"Key":"false", "Type":"string", "Optional":"true"}, "description":{"Key":"false", "Type":"string", "Optional":"true"}, "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"}, "object-type":{"Key":"false", "Default Value":"user", "Type":"string", "Optional":"true"} } }, "Method":{ "Name":"GET" }, "Method":{ "Name":"DELETE", "Message Parameters":{ "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"} } } } }

To Delete a Node From the Tree

1. Ensure that the server is running.

   Operations on REST resources for GlassFish Server data require a running server.

2. Confirm that the node can be deleted.

   For information about how to perform this step, see To Determine the Methods and Method Parameters That a Node in the Tree Supports.

3. Confirm that the node has been deleted.

   Perform this step on the resource that represents the parent of the node that you have just deleted. For information about how to perform this step, see To Retrieve Data for a Node in the Tree.

Example 2–25 Deleting a Node From the Tree

This example uses the cURL utility to delete a JDBC resource from the tree by deleting the REST resource that represents the JDBC resource.

In this example, the DAS is running on the local host and the HTTP port for administration is 4848.

Line breaks are added to enhance readability.

1. This step confirms that the node can be deleted by retrieving the REST methods that the resource jdbc-myjdbcresource supports.

   curl -X OPTIONS -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource {"JdbcMyjdbcresource": { "Method":{ "Name":"POST", "Message Parameters":{ "enabled":{"Key":"false", "Default Value":"true", "Type":"boolean", "Optional":"true"}, "pool-name":{"Key":"false", "Type":"string", "Optional":"true"}, "description":{"Key":"false", "Type":"string", "Optional":"true"}, "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"}, "object-type":{"Key":"false", "Default Value":"user", "Type":"string", "Optional":"true"} } }, "Method":{ "Name":"GET" }, "Method":{ "Name":"DELETE", "Message Parameters":{ "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"} } } } }

2. This step deletes the jdbc-myjdbcresource resource.

   curl -X DELETE http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource

3. This step confirms that the node has been deleted by retrieving data for the REST resource that represents the parent of the node.

   curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/jdbc-resource/ { "JdbcResource":{}, "Methods":{ "Method":{ "Name":"POST", "Message Parameters":{ "id":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"false"}, "enabled":{"Acceptable Values":"", "Default Value":"true", "Type":"boolean", "Optional":"true"}, "description":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"}, "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"}, "property":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"true"}, "connectionpoolid":{"Acceptable Values":"", "Default Value":"", "Type":"string", "Optional":"false"} } }, "Method":{ "Name":"GET" } }, "Child Resources":[ "http://localhost:4848/management/domain/resources/jdbc-resource/ jdbc-__TimerPool", "http://localhost:4848/management/domain/resources/jdbc-resource/ jdbc-__default" ]