Sun GlassFish Enterprise Server v2.1.1 Developer's Guide

The sun-appserv-instance Task

Starts, stops, restarts, creates, or removes one or more application server instances.


Note –

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.


Subelements of sun-appserv-instance

The following table describes subelements for the sun-appserv-instance task. These are objects upon which this task acts.

Table 3–5 The sun-appserv-instance Subelements

Element 

Description 

The server Subelement

An Enterprise Server instance 

Attributes of sun-appserv-instance

The following table describes attributes for the sun-appserv-instance task.

Table 3–6 The sun-appserv-instance Attributes

Attribute 

Default 

Description 

action

none 

The control command for the target application server. Valid values are start, stop, create, and delete. A restart sends the stop command followed by the start command. The restart command is not supported on Windows.

debug

false

(optional) Deprecated. If action is set to start, specifies whether the server starts in debug mode. This attribute is ignored for other values of action. If true, the instance generates additional debugging output throughout its lifetime. This attribute is inherited by nested server elements.

nodeagent

none 

(required if action is create, otherwise ignored) The name of the node agent on which the instance is being created.

cluster

none 

(optional, applicable only if action is create) The clustered instance to be created. The server’s configuration is inherited from the named cluster.

The config and cluster attributes are mutually exclusive. If both are omitted, a stand-alone server instance is created.

config

none 

(optional, applicable only if action is create) The configuration for the new stand-alone instance.

The configuration must exist and must not be default-config (the cluster configuration template) or an already referenced stand-alone configuration (including the administration server configuration server-config).

The config and cluster attributes are mutually exclusive. If both are omitted, a stand-alone server instance is created.

property

none 

(optional, applicable only if action is create) Defines system properties for the server instance. These properties override port settings in the server instance’s configuration. The following properties are defined: http-listener-1-port, http-listener-2-port, orb-listener-1-port, SSL-port, SSL_MUTUALAUTH-port, JMX_SYSTEM_CONNECTOR_port.

System properties can be changed after instance creation using the system property commands. For details, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.

user

admin

(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements.

host

localhost

(optional) Target server. If it is a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.

port

4848

(optional) The administration port on the target server. This attribute is inherited by nested server elements.

instance

name of default instance 

(optional) Target application server instance. This attribute is inherited by nested server elements.

asinstalldir

see description 

(optional) The installation directory for the local Enterprise Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

Examples of sun-appserv-instance

This example starts the local Enterprise Server instance:

<sun-appserv-instance action="start" passwordfile="${passwordfile}"
 instance="${default-instance-name}"/>

Here is an equivalent script showing all the implied attributes:

<sun-appserv-instance
 action="start"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 instance="${default-instance-name}"
 asinstalldir="${asinstalldir}" />

Multiple servers can be controlled using a single command. In this example, two servers are restarted, and in this case each server uses a different password:

<sun-appserv-instance action="restart"
	 instance="${default-instance-name}"/>
<server host="greg.sun.com" passwordfile="${password.greg}"/>
 <server host="joe.sun.com" passwordfile="${password.joe}"/>
</sun-appserv-instance>

This example creates a new Enterprise Server instance:

<sun-appserv-instance
 action="create" instanceport="8080"
 passwordfile="${passwordfile}"
 instance="development" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-instance
 action="create"
 instanceport="8080"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 instance="development"
 asinstalldir="${asinstalldir}" />

Instances can be created on multiple servers using a single command. This example creates a new instance named qa on two different servers. In this case, both servers use the same password.

<sun-appserv-instance
	 action="create"
	 instanceport="8080"
	 instance="qa"
	 passwordfile="${passwordfile}>
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
</sun-appserv-instance>

These instances can also be removed from their respective servers:

<sun-appserv-instance
	 action="delete"
	 instance="qa"
	 passwordfile="${passwordfile}>
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
</sun-appserv-instance>

Different instance names and instance ports can also be specified using attributes of the server subelement:

<sun-appserv-instance action="create" passwordfile="${passwordfile}>
 <server host="greg.sun.com" instanceport="8080" instance="qa"/>
 <server host="joe.sun.com" instanceport="9090"
	 instance="integration-test"/>
</sun-appserv-instance>