Sun GlassFish Enterprise Server v3 Administration Guide

Chapter 2 General Administration

This chapter provides instructions for performing general administration tasks in the Sun GlassFish^TM Enterprise Server v3 environment by using the asadmin command-line utility.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

Using the `asadmin` Utility

Use the asadmin utility to perform administrative tasks for Sun GlassFish Enterprise Server from the command line or from a script. You can use this utility instead of the Administration Console interface.

The following topics are addressed here:

Path to the `asadmin` Utility

The asadmin utility is located in the as-install/bin directory. To run the asadmin utility without specifying the path, ensure that this directory is in your path.

`asadmin` Utility Syntax

The syntax for running the asadmin utility is as follows:

asadmin [asadmin-util-options] [subcommand [subcommand-options] [operands]]

The replaceable items in this syntax are described in the subsections that follow. For full details of this syntax, see the asadmin(1M) help page.

Subcommands of the `asadmin` Utility

The subcommand identifies the operation or task that you are performing. Subcommands are case-sensitive. Each subcommand is either a local subcommand or a remote subcommand.

A local subcommand can be run without a running domain administration server (DAS). However, to run the subcommand and have access to the installation directory and the domain directory, the user must be logged in to the machine that hosts the domain.
A remote subcommand is always run by connecting to a DAS and running the subcommand there. A running DAS is required.

For a list of the subcommands for this release of Enterprise Server, see Section 1 of Sun GlassFish Enterprise Server v3 Reference Manual.

`asadmin` Utility Options and Subcommand Options

Options control the behavior of the asadmin utility and its subcommands. Options are case-sensitive.

The asadmin utility has the following types of options:

asadmin utility options. These options control the behavior of the asadmin utility, not the subcommand. The asadmin utility options may precede or follow the subcommand, but asadmin utility options after the subcommand are deprecated. All asadmin utility options must either precede or follow the subcommand. If asadmin utility options are specified both before and after the subcommand, an error occurs. For a description of the asadmin utility options, see the asadmin(1M) help page.
Subcommand Options. These options control the behavior of the subcommand, not the asadmin utility. Subcommand options must follow the subcommand. For a description of a subcommand’s options, see the entry for the subcommand in Sun GlassFish Enterprise Server v3 Reference Manual.

Note –
Not all subcommand options are supported for this release of Enterprise Server. If you specify an unsupported option, a syntax error does not occur. Instead, the command runs successfully and the unsupported option is silently ignored.

A subcommand option may have the same name as an asadmin utility option, but the effects of the two options are different.

Options have a long form and a short form.

The short form of an option has a single dash (-) followed by a single character.
The long form of an option has two dashes (--) followed by an option word.

For example, the short form and the long form of the option for specifying terse output are as follows:

Short form: -t
Long form: --terse

Most options require argument values, except Boolean options, which toggle to enable or disable a feature.

Operands of `asadmin` Utility Subcommands

Operands specify the items on which the subcommand is to act. Operands must follow the argument values of subcommand options, and are set off by a space, a tab, or double dashes (--). The asadmin utility treats anything that follows the subcommand options and their values as an operand.

To Run an `asadmin` Utility Subcommand in Single Mode

In single mode, you must type a separate asadmin command for each subcommand that you want to use. After the subcommand has run, you are returned to the operating system's command shell. Any asadmin utility options must be specified in each separate asadmin command that you run. If you require the same asadmin utility options for multiple subcommands, use the asadmin utility in multimode. For more information, see To Start a Multimode Session.

In the operating system's command shell, run the asadmin utility, specifying the subcommand.

If necessary, also specify any required asadmin utility options, subcommand options, and operands.

Example 2–1 Running an `asadmin` Utility Subcommand in Single Mode

This example runs the list-applications(1) subcommand in single mode. In this example, the default values for all options are used.

The example shows that the application hello is deployed on the local host.

asadmin list-applications
hello <web>
Command list-applications executed successfully.

Example 2–2 Specifying an `asadmin` Utility Option With a Subcommand in Single Mode

This example specifies the --host asadmin utility option with the list-applications subcommand in single mode. In this example, the DAS is running on the host srvr1.example.com.

The example shows that the applications basic-ezcomp, scrumtoys, ejb31-war, and automatic-timer-ejb are deployed on the host srvr1.example.com.

asadmin --host srvr1.example.com list-applications
basic-ezcomp <web>
scrumtoys <web>
ejb31-war <ejb, web>
automatic-timer-ejb <ejb>
Command list-applications executed successfully.

Example 2–3 Specifying an `asadmin` Utility Option and a Subcommand Option in Single Mode

This example specifies the --host asadmin utility option and the --type subcommand option with the list-applications subcommand in single mode. In this example, the DAS is running on the host srvr1.example.com and applications of type web are to be listed.

asadmin --host srvr1.example.com list-applications --type web
basic-ezcomp <web>
scrumtoys <web>
ejb31-war <ejb, web>
Command list-applications executed successfully.

To Display Help Information for the `asadmin` Utility or a Subcommand

Enterprise Server provides help information about the syntax, purpose, and options of the asadmin utility and its subcommands. This help information is written in the style of UNIX® platform man pages. This help information is also available in Sun GlassFish Enterprise Server v3 Reference Manual.

If you are displaying help information for a remote subcommand, ensure that the server is running.

Remote subcommands require a running server.

Specify the subcommand of interest as the operand of the help subcommand.

If you run the help subcommand without an operand, help information for the asadmin utility is displayed.

Example 2–4 Displaying Help Information for the `asadmin` Utility

This example displays the help information for the asadmin utility.

asadmin help

Example 2–5 Displaying Help Information for an `asadmin` Utility Subcommand

This example displays the help information for the create-jdbc-resource subcommand.

asadmin help create-jdbc-resource

To Start a Multimode Session

The asadmin utility can be used in multiple command mode, or multimode. In multimode, you run the asadmin utility once to start a multimode session. During the session, the asadmin utility continues to accept subcommands until you end the session and return to the operating system's command shell. Any asadmin utility options that you set for your multimode session are used for all subsequent subcommands in the session.

Note –

Starting a multimode session does not require a running DAS.

Do one of the following:
- Run the asadmin utility without a subcommand.
- Use the multimode(1) subcommand.
If necessary, also specify any asadmin utility options that will apply throughout the multimode session.

In a multimode session, the asadmin> prompt is displayed on the command line. You can now type asadmin subcommands at this prompt to administer Enterprise Server.

Example 2–6 Starting a Multimode Session With `asadmin` Utility Options

This example starts a multimode session in which the asadmin utility options --user and --passwordfile are set for the session.

asadmin --user admin1 --passwordfile pwd.txt multimode

Example 2–7 Starting a Multimode Session by Using the `multimode` Subcommand

This example uses the multimode subcommand to start a multimode session in which the default asadmin utility options are used.

asadmin multimode

The asadmin> prompt is displayed on the command line.

Example 2–8 Running a Subcommand in a Multimode Session

This example starts a multimode session and runs the list-domains subcommand in the session.

asadmin
Enter commands one per "line", ^D to quit
asadmin> list-domains
Name: domain1 Status: Running
Command list-domains executed successfully.
asadmin>

Starting a Multimode Session From Within an Existing Multimode Session

You can start a multimode session from within an existing session by running the multimode subcommand from within the existing session. After you end the second multimode session, you return to your original multimode session.

To End a Multimode Session

At the asadmin> prompt, type one of the following commands or key combinations:
- exit
- quit
- UNIX and Linux systems: Ctrl-D
- Windows systems: Ctrl-Z
You are returned to the operating system's command shell and the asadmin> prompt is no longer displayed. If the asadmin> prompt is still displayed, you might have opened a multimode session within a multimode session. In this situation, repeat this procedure to end the remaining multimode session.

To Run a Set of `asadmin` Subcommands From a File

Running a set of asadmin subcommands from a file enables you to automate repetitive tasks.

Create a plain text file that contains the sequence of subcommands that you want to run.

Run the multimode(1) subcommand, specifying the file that you created.

If necessary, also specify any asadmin utility options that are required to enable subcommands in the file to run.

Example 2–9 Running a Set of `asadmin` Subcommands From a File

This example contains the following:

A listing of a file that is named commands_file.txt, which contains a sequence of asadmin subcommands
The command to run the subcommands in the file commands_file.txt

The commands_file.txt file contains the asadmin utility subcommands to perform the following sequence of operations:

Creating the domain customdomain
Starting the domain customdomain
Listing all available subcommands
Stopping the domain customdomain
Deleting the domain customdomain

The content of the commands_file.txt file is as follows:

create-domain --portbase 9000 customdomain
start-domain customdomain
list-commands
stop-domain customdomain
delete-domain customdomain

This example runs the sequence of subcommands in the commands_file.txt file. Because the --portbase option is specified for the create-domain subcommand in the file, the --port asadmin utility option must also be set.

asadmin --port 9048 multimode --file commands_file.txt

Administering System Properties

Shared server instances will often need to override attributes defined in their referenced configuration. Any configuration attribute can be overridden through a system property of the corresponding name.

The following topics are addressed here:

To Create System Properties

Use the create-system-properties subcommand in remote mode to create or update one or more system properties of the domain or configuration. Any configuration attribute can be overwritten through a system property of the corresponding name.

Ensure that the server is running.

Remote subcommands require a running server.

Create system properties by using the create-system-properties(1) subcommand.

Information about properties for the subcommand is included in this help page.

Example 2–10 Creating a System Property

This example creates a system property associated with http-listener-port=1088 on localhost.

asadmin> create-system-properties http-listener-port=1088
Command create-system-properties executed successfully.

To List System Properties

Use the list-system-properties subcommand in remote mode to list the system properties that apply to a domain or configuration.

Ensure that the server is running.

Remote subcommands require a running server.

List system properties by using the list-system-properties(1) subcommand.

The existing system properties are displayed, including predefined properties such as HTTP_LISTENER_PORT and HTTP_SSL_LISTENER_PORT.

Example 2–11 Listing System Properties

This example lists the system properties on host localhost.

asadmin> list-system-properties
http-listener-port=1088
Command list-system-properties executed successfully.

To Delete a System Property

Use the delete-system-property subcommand in remote mode to delete system properties.

Ensure that the server is running.

Remote subcommands require a running server.

List the existing system properties by using the list-system-properties(1) subcommand.

Delete the system property by using the delete-system-property(1) subcommand.

If necessary, notify users that the system property has been deleted.

Example 2–12 Deleting a System Property

This example deletes a system property named http-listener-port from localhost.

asadmin> delete-system-property http-listener-port
Command delete-system-property executed successfully.

Administering Resources

This section contains instructions for integrating resources into the Enterprise Server environment. Information about administering specific resources, such as JDBC, is contained in other chapters.

The following topics are addressed here:

To Add Resources From an XML File

To Add Resources From an XML File

Use the add-resources subcommand in remote mode to create the resources named in the specified XML file. The following resources are supported: JDBC connection pool and resource, JMS, JNDI, and JavaMail resources, custom resource, connector resource and work security map, admin object, and resource adapter configuration.

The XML file must reside in the as-install/domains/domain1/config directory. If you specify a relative path or simply provide the name of the XML file, this subcommand will prepend as-install/domains/domain1/config to this operand.

Ensure that the server is running.

Remote subcommands require a running server.

Add resources from an XML file by using the add-resources(1) subcommand.

Information about properties for the subcommand is included in this help page.

Restart Enterprise Server.

See To Restart a Domain.

Example 2–13 Adding Resources

This example creates resources using the contents of the resource.xml file on localhost.

asadmin> add-resources c:\tmp\resource.xml
Command : JDBC resource jdbc1 created successfully.
Command : JDBC connection pool poolA created successfully.
Command add-resources executed successfully.

Listing Various System Elements

To Display the Enterprise Server Version

Use the version subcommand in remote mode to display information about the Enterprise Server version for a particular server. If the subcommand cannot communicate with the server by using the specified login (user/password) and target (host/port) information, then the local version is displayed along with a warning message.

Ensure that the server is running.

Remote subcommands require a running server.

Display the version by using the version(1) subcommand.

Example 2–14 Displaying Version Information

This example displays the version of Enterprise Server on the local host.

asadmin> version
Version = GlassFish v3
Command version executed successfully.

To List Applications

Use the list-applications subcommand in remote mode to list the deployed Java^TM applications. If the --type option is not specified, all applications are listed.

Ensure that the server is running.

Remote subcommands require a running server.

List applications by using the list-applications(1) subcommand.

Example 2–15 Listing Applications

This example lists the web applications on localhost.

asadmin> list-applications --type web
hellojsp <web>
Command list-applications executed successfully.

To List Containers

Use the list-containers subcommand in remote mode to list application containers.

Ensure that the server is running.

Remote subcommands require a running server.

List containers by using the list-containers(1) subcommand.

Example 2–16 Listing Containers

This example lists the containers on localhost.

asadmin> list-containers
List all known application containers
Container : grizzly
Container : ejb
Container : webservices
Container : ear
Container : appclient
Container : connector
Container : jpa
Container : web
Container : jruby
Container : security
Container : webbeans
Command list-containers executed successfully.

To List Modules

Use the list-modules subcommand in remote mode to list the modules that are accessible to the Enterprise Server module subsystem. The status of each module is included. Possible statuses include NEW and READY.

Ensure that the server is running.

Remote subcommands require a running server.

List modules by using the list-modules(1) subcommand.

Example 2–17 Listing Modules

This example lists the accessible modules.

asadmin> list-modules

Information similar to the following is displayed (partial output):

List Of Modules
Module : org.glassfish.web.jstl-connector:10.0.0.b28
    properties=(visibility=public,State=READY,Sticky=true)
    Module Characteristics : List of Jars implementing the module
        Jar : file:/C:/Preview/v3_Preview_release/distributions/web/target/glass
fish/modules/web/jstl-connector.jar
    Module Characteristics : List of imported modules
    Module Characteristics : Provides to following services
Module : org.glassfish.admingui.console-common:10.0.0.b28
    properties=(visibility=public,State=NEW,Sticky=true)
Module : org.glassfish.admin.launcher:10.0.0.b28
    properties=(visibility=public,State=NEW,Sticky=true)
Module : org.glassfish.external.commons-codec-repackaged:10.0.0.b28
    properties=(visibility=public,State=NEW,Sticky=true)
Module : com.sun.enterprise.tiger-types-osgi:0.3.32.Preview-b28
    properties=(visibility=public,State=READY,Sticky=true)
    Module Characteristics : List of imported modules
    Module Characteristics : Provides to following services
    Module Characteristics : List of Jars implementing the module
        Jar : file:/C:/Preview/v3_Preview_release/distributions/web/target/glass
fish/modules/tiger-types-osgi.jar.
...
Command list-modules executed successfully.

To List Subcommands

Use the list-commands subcommand in remote mode to list the deployed asadmin subcommands. You can specify that only remote subcommands or only local subcommands are listed. By default, this subcommand displays a list of local subcommands followed by a list of remote subcommands.

Ensure that the server is running.

Remote subcommands require a running server.

List subcommands by using the list-commands(1) subcommand.

Example 2–18 Listing Subcommands

This example lists only local subcommands.

asadmin> list-commands --localonly
create-domain
delete-domain
list-commands
list-domains
login
monitor
start-database
start-domain
stop-domain
stop-database
version
Command list-commands executed successfully.

To List Timers

The timer service is a persistent and transactional notification service that is provided by the enterprise bean container and is used to schedule notifications or events used by enterprise beans. All enterprise beans except stateful session beans can receive notifications from the timer service. Persistent timers set by the service are not destroyed when the server is shut down or restarted.

Use the list-timers subcommand in remote mode to list the persistent timers owned by a specific server instance. You can use this information to decide whether to do a timer migration, or to verify that a migration has been completed successfully.

Ensure that the server is running.

Remote subcommands require a running server.

List timers by using thelist-timers(1) subcommand.

Example 2–19 Listing Timers

This example lists the timers in a particular standalone server instance. There is one currently active timer set.

asadmin> list-timers server
1
The list-timers command was executed successfully.

To Show Component Status

Use the show-component-status subcommand in remote mode to get the status (either enabled or disabled) of the specified deployed component.

Ensure that the server is running.

Remote subcommands require a running server.

Show component status by using the show-component-status(1) subcommand.

Example 2–20 Showing Status of a Component

This example shows the status of the MEjbApp component.

asadmin> show-component-status MEjbApp
Status of MEjbApp is enabled
Command show-component-status executed successfully.

Using REST Interfaces to Administer Enterprise Server

Enterprise Server provides representational state transfer (REST) interfaces to enable you to access monitoring and configuration data for Enterprise Server, including data that is provided by newly installed add-on components.

You can access the Enterprise Server REST interfaces through client applications such as:

Web browsers
cURL
GNU Wget

You can also use the Enterprise Server REST interfaces in REST client applications that are developed in languages such as:

JavaScript
Ruby
Perl
Java
JavaFX

The implementation of the Enterprise Server REST interfaces is based on project Jersey. Project Jersey is the reference implementation of Java ^TM Specification Request (JSR) 311: JAX-RS: The Java API for RESTful Web Services. Information about JSR 311 is also available from the JSR 311 project home page.

The following topics are addressed here:

Using REST URLs to Administer Enterprise Server

Each node in the configuration and monitoring object trees is represented as a REST resource that is accessible through an HTTP uniform resource locator (URL). Access to REST resources for Enterprise Server monitoring and configuration data requires a running DAS.

The formats of the URLs to resources that represent nodes in the configuration and monitoring object trees are as follows:

Configuration: http://host:port/management/domain/path
Monitoring: http://host:port/monitoring/domain/path

The replaceable items in these URLs are as follows:

host

The host where the DAS is running.

port

The HTTP port or HTTPS port for administration.

path

The path to the node. The path is the dotted name of the node in which each dot (.) is replaced with a slash (/). For more information, see the following documentation:

If the URL to a REST resource for Enterprise Server monitoring or configuration data is opened in a web browser, the browser displays a web page that contains the following information about the resource:

A list of the attributes of the resource and their values. If the resource represents a node in the configuration tree, these attributes are presented in an HTML form that you can use to update the resource. Attributes of a resource for a node in the monitoring tree are read only.
A list of hypertext links to the children of the resource. This list of links enables you to traverse the tree that contains the resource and to discover the all resources in the tree.

The following figure shows the web page for the REST resource for managing a domain.

Figure 2–1 Web Page for the REST Resource for Managing a Domain

Screen capture showing the web page for the REST resource
for managing a domain.

Using REST Resource Methods to Administer Enterprise Server

The Enterprise 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.

Table 2–1 REST Resource Methods for Administering Monitoring and Configuration Data


Task	REST Method
Determine the methods and method parameters that a node in the tree supports	`OPTIONS` or `GET`
Retrieve data for a node in the tree	`GET`
Add a node to the tree	`POST`
Update a node in the tree	`POST`
Delete a node from the tree	`DELETE`

Note –

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.

Ensure that the server is running.

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

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.

Ensure that the server is running.

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

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

Ensure that the server is running.

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

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.

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

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.

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"
    }
  }
}

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.

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

Ensure that the server is running.

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

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.

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

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.

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"}
      }
    }
  }
}

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.

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

Ensure that the server is running.

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

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.

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.

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"}
      }
    }
  }
}

This step deletes the jdbc-myjdbcresource resource.

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

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"
  ]

Child Resources for Non-CRUD Operations

The Enterprise Server REST interfaces also support operations other than create, read, update, and delete (CRUD) operations, for example:

State management
Queries
Application deployment

These operations are supported through child resources of the resource on which the operation is performed. The child resources do not represent nodes in the configuration object tree.

For example, the resource for managing a domain provides child resources for non-CRUD operations as shown in the following table.

Table 2–2 Child Resources for Non-CRUD Operations on a Domain


Resource	Action
`host-port`	Displays the host on which the DAS is running and the port on which the DAS listens for HTTP requests.
`restart`	Stops and then restarts the DAS of the domain.
`rotate-log`	Rotates the server log file by renaming the file with a timestamp name in the format `server.log_date-and-time`, and creating an empty log file.
`stop`	Stops the DAS of the domain.
`uptime`	Displays the length of time that the DAS has been running since it was last restarted.
`version`	Displays version information for Enterprise Server.

Securing Enterprise Server REST Interfaces

The Enterprise Server REST interfaces support basic authentication over a secure connection. When security is enabled, you must specify https as the protocol in the URLs to REST resources and provide a username and password.

Securing Enterprise Server REST Interfaces involves the following sequence of tasks:

Adding an admin-realm user to the asadmin user group
Enabling Secure Sockets Layer (SSL)

For information about how to perform these tasks from the command line, see the following documentation:

For information about how to perform these tasks by using the Administration Console, see the following topics in the Administration Console online help:

To Add a User to the Admin Realm
To Edit SSL Settings for a Protocol

Formats for Resource Representation

The Enterprise Server REST interfaces represent resources in the following formats:

JSON
XML
HTML

How to specify the resource representation depends on how you are accessing the Enterprise Server REST interfaces. For example, if you are using the cURL utility, specify the resource representation through the -H option as follows:

For JSON, specify -H "Accept: application/json".
For XML, specify -H "Accept: application/xml".
For HTML, omit the -H option.

JSON Resource Representation

The general format for the JSON representation of a resource is as follows:

{
    "resource":{attributes},

    "Methods": {
        method-list
    }

    "Child Resources":[urls]
}

The replaceable items in this format are as follows:

resource: The name of the resource.
attributes: Zero or more name-value pairs separated by a comma (,). Each name-value pair is specified as "name":value.
method-list: One or more metadata sets separated by a comma (,) that represent the methods that the resource supports. For the format of each metadata set, see JSON Representation of a Method in a Method List.
urls: Zero or more URLs to child resources separated by a comma (,).

JSON Representation of a Method in a Method List

The JSON representation of a method in a method list is as follows:

Method":{
    "Name":"method-name",

    "Message Parameters":{
        message-parameter-list
    }

    "Query Parameters":{
        queryparameter- list
    }
}

The replaceable items in this format are as follows:

method-name: The name of the method, which is GET, POST, or DELETE.
message-parameter-list: Zero or more metadata sets separated by a comma (,) that represent the message parameters that are allowed for the method. For the format of each metadata set, see JSON Representation of a Message Parameter or a Query Parameter.
query-parameter-list: Zero or more metadata sets separated by a comma (,) that represent the query parameters that are allowed for the method. For the format of each metadata set, see JSON Representation of a Message Parameter or a Query Parameter.

JSON Representation of a Message Parameter or a Query Parameter

The JSON representation of a message parameter or a query parameter is as follows:

"parameter-name":{attribute-list}

The replaceable items in this format are as follows:

parameter-name

The name of the parameter.

attribute-list

A comma-separated list of name-value pairs of attributes for the parameter. Each pair is in the following format:

"name":"value"

Possible attributes are as follows:

Default Value

The default value of the parameter.

Acceptable Values

The set or range of acceptable values for the parameter.

Type

The data type of the parameter, which is one of the following types:

boolean
int
string

Optional

Indicates whether the parameter is optional. If true, the parameter is optional. If false, the parameter is required.

Key

Indicates whether the parameter is key. If true, the parameter is key. If false, the parameter is not key.

Example JSON Resource Representation

This example shows the JSON representation of the resource for managing a domain. In this example, the DAS is running on the local host and the HTTP port for administration is 4848. The URL to the resource in this example is http://localhost:4848/management/domain.

Line breaks are added to enhance readability.

{

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

  "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"
  ]

}

XML Resource Representation

The general format for the XML representation of a resource is as follows:

<resource attributes>

    <Methods>
        method-list
    </Methods>
children
</type>

The replaceable items in this format are as follows:

resource: The name of the resource.
attributes: Zero or more name-value pairs separated by a space. Each name-value pair is specified as name="value".
method-list: One or more XML elements that represent the methods that the resource supports. For the format of each element, see XML Representation of a Resource Method.
children: Zero or more XML elements that specify the URLs of child resources. Each element is specified as <child-resource>url</child-resource>, where child-resource is the name of the child resource and url is the URL to the child resource.

XML Representation of a Resource Method

The XML representation of a method in a method list is as follows:

<Method name="method-name">
    <Message-Parameters>
        message-parameter-list
    </Message-Parameters>
    <Query-Parameters>
        query-parameter-list
    </Query-Parameters>
</Method>

The replaceable items in this format are as follows:

method-name: The name of the method, which is GET, POST, or DELETE.
message-parameter-list: Zero or more XML elements separated by a line feed that represent the message parameters that are allowed for the method. For the format of each element, see XML Representation of a Message Parameter or a Query Parameter.
query-parameter-list: Zero or more XML elements separated by a line feed that represent the query parameters that are allowed for the method. For the format of each element, see XML Representation of a Message Parameter or a Query Parameter.

XML Representation of a Message Parameter or a Query Parameter

The XML representation of a message parameter or a query parameter is as follows:

<parameter-name attribute-list/>

The replaceable items in this format are as follows:

parameter-name

The name of the parameter.

attribute-list

A space-separated list of name-value pairs of attributes for the parameter. Each pair is in the following format:

name="value"

Possible attributes are as follows:

Default Value

The default value of the parameter.

Acceptable Values

The set or range of acceptable values for the parameter.

Type

The data type of the parameter, which is one of the following types:

boolean
int
string

Optional

Indicates whether the parameter is optional. If true, the parameter is optional. If false, the parameter is required.

Key

Indicates whether the parameter is key. If true, the parameter is key. If false, the parameter is not key.

Example XML Resource Representation

This example shows the XML representation of the resource for managing a domain. In this example, the DAS is running on the local host and the HTTP port for administration is 4848. The URL to the resource in this example is http://localhost:4848/management/domain.

Line breaks are added to enhance readability.

<Domain log-root="${com.sun.aas.instanceRoot}/logs" 
application-root="${com.sun.aas.instanceRoot}/applications" locale="" version="73">

  <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"/>
      </Message-Parameters>
    </Method>
    <Method name="GET">
    </Method>
  </Methods>

  <Child-Resources>
    <Child-Resource>http://localhost:4848/management/domain/configs</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/resources</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/servers</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/property</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/applications</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/system-applications</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/stop</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/restart</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/uptime</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/version</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/rotate-log</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/host-port</Child-Resource>
  </Child-Resources>

</Domain>

HTML Resource Representation

The format for the HTML representation of a resource is a web page that provides the following information about the resource:

A list of the attributes of the resource and their values.
A list of the methods and method parameters that the resource supports. Each method and its parameters are presented as a field of the appropriate type in an HTML form.
A list of hypertext links to the children of the resource.

For a sample web page, see Figure 2–1. In this example, the DAS is running on the local host and the HTTP port for administration is 4848. The URL to the resource in this example is http://localhost:4848/management/domain.

Chapter 2 General Administration

Using the asadmin Utility

Path to the asadmin Utility

asadmin Utility Syntax

Subcommands of the asadmin Utility

asadmin Utility Options and Subcommand Options

Operands of asadmin Utility Subcommands

To Run an asadmin Utility Subcommand in Single Mode

Example 2–1 Running an asadmin Utility Subcommand in Single Mode

Example 2–2 Specifying an asadmin Utility Option With a Subcommand in Single Mode

Example 2–3 Specifying an asadmin Utility Option and a Subcommand Option in Single Mode

To Display Help Information for the asadmin Utility or a Subcommand

Example 2–4 Displaying Help Information for the asadmin Utility

Example 2–5 Displaying Help Information for an asadmin Utility Subcommand

See Also

To Start a Multimode Session

Example 2–6 Starting a Multimode Session With asadmin Utility Options

Example 2–7 Starting a Multimode Session by Using the multimode Subcommand

Example 2–8 Running a Subcommand in a Multimode Session

Starting a Multimode Session From Within an Existing Multimode Session

See Also

To End a Multimode Session

To Run a Set of asadmin Subcommands From a File

Example 2–9 Running a Set of asadmin Subcommands From a File

See Also

Administering System Properties

To Create System Properties

Example 2–10 Creating a System Property

See Also

To List System Properties

Example 2–11 Listing System Properties

See Also

To Delete a System Property

Example 2–12 Deleting a System Property

See Also

Administering Resources

To Add Resources From an XML File

Example 2–13 Adding Resources

See Also

Listing Various System Elements

To Display the Enterprise Server Version

Example 2–14 Displaying Version Information

See Also

To List Applications

Example 2–15 Listing Applications

See Also

To List Containers

Example 2–16 Listing Containers

See Also

To List Modules

Example 2–17 Listing Modules

See Also

To List Subcommands

Example 2–18 Listing Subcommands

See Also

To List Timers

Example 2–19 Listing Timers

To Show Component Status

Example 2–20 Showing Status of a Component

Using REST Interfaces to Administer Enterprise Server

Using REST URLs to Administer Enterprise Server

Figure 2–1 Web Page for the REST Resource for Managing a Domain

Using REST Resource Methods to Administer Enterprise Server

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

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

To Retrieve Data for a Node in the Tree

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

To Add a Node to the Tree

Example 2–23 Adding a Node to the Tree

To Update a Node in the Tree

Example 2–24 Updating a Node in the Tree

To Delete a Node From the Tree

Example 2–25 Deleting a Node From the Tree

Child Resources for Non-CRUD Operations

Securing Enterprise Server REST Interfaces

Formats for Resource Representation

JSON Resource Representation

JSON Representation of a Method in a Method List

JSON Representation of a Message Parameter or a Query Parameter

Example JSON Resource Representation

Using the `asadmin` Utility

Path to the `asadmin` Utility

`asadmin` Utility Syntax

Subcommands of the `asadmin` Utility

`asadmin` Utility Options and Subcommand Options

Operands of `asadmin` Utility Subcommands

To Run an `asadmin` Utility Subcommand in Single Mode

Example 2–1 Running an `asadmin` Utility Subcommand in Single Mode

Example 2–2 Specifying an `asadmin` Utility Option With a Subcommand in Single Mode

Example 2–3 Specifying an `asadmin` Utility Option and a Subcommand Option in Single Mode

To Display Help Information for the `asadmin` Utility or a Subcommand

Example 2–4 Displaying Help Information for the `asadmin` Utility

Example 2–5 Displaying Help Information for an `asadmin` Utility Subcommand

Example 2–6 Starting a Multimode Session With `asadmin` Utility Options

Example 2–7 Starting a Multimode Session by Using the `multimode` Subcommand

To Run a Set of `asadmin` Subcommands From a File

Example 2–9 Running a Set of `asadmin` Subcommands From a File