Sun GlassFish Communications

Server 2.0 Quick Start Guide

Sun Microsystems, Inc.

4150 Network Circle
Santa Clara, CA 95054
U.S.A.

Part No: 821–0201

September 2009
Copyright 2009 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without
limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries.
U.S. Government Rights – Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions
of the FAR and its supplements.
This distribution may include materials developed by third parties.
Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other
countries, exclusively licensed through X/Open Company, Ltd.
Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coffee Cup logo, docs.sun.com, Java, and Solaris are trademarks or registered trademarks of Sun
Microsystems, Inc. or its subsidiaries in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of
SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.
The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts
of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to
the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license
agreements.
Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in
other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export
or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially
designated nationals lists is strictly prohibited.
DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO
THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Copyright 2009 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. Tous droits réservés.
Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier,
et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis
et dans d'autres pays.
Cette distribution peut comprendre des composants développés par des tierces personnes.
Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l'Université de Californie. UNIX est une marque déposée aux
Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd.
Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coffee Cup, docs.sun.com, Java et Solaris sont des marques de fabrique ou des marques déposées de
Sun Microsystems, Inc., ou ses filiales, aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou
des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture
développée par Sun Microsystems, Inc.
L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de
pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient
une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface
d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.
Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et
peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucléaires,
des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou
réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière
non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui
sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement designés, sont rigoureusement interdites.
LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES
SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE
IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON.

091026@22749
 Contents

Preface .....................................................................................................................................................5

1 Quick Start for Basic Features ............................................................................................................. 9

Getting Started ........................................................................................................................................9
▼ To Start the Domain on Solaris and Linux ................................................................................ 10
▼ To Start the Domain on Windows ............................................................................................. 10
▼ To Log On to the Admin Console .............................................................................................. 11
▼ To View the Domain Administration Server Log File ............................................................. 13
▼ To Start the Node Agent .............................................................................................................. 14
▼ To Add Cluster Support to a Domain ........................................................................................ 15
▼ To Start the Bundled Java DB Server ......................................................................................... 16
Administration Tools .......................................................................................................................... 16
Where to Go Next ................................................................................................................................ 18

2 Setting Up a Cluster ............................................................................................................................ 19

Setting Up a Cluster with Converged Load Balancer ...................................................................... 19
▼ To Set Up a Cluster with Converged Load Balancer ................................................................ 19
Creating a Cluster that Spans Multiple Machines ........................................................................... 22
▼ To Create a Cluster With Instances On Different Machines .................................................. 22
Viewing Ports for Clustered Server Instances .................................................................................. 26
▼ To View Ports for Clustered Server Instances .......................................................................... 26

3 Deploying an Application ..................................................................................................................27

Deploying a Sample SIP Module ....................................................................................................... 27
▼ To Deploy the CallSetup Application Using Admin Console ................................................ 27
Deploying a Sample Web Application .............................................................................................. 29
▼ To Deploy the Hello Application Using Autodeploy ............................................................... 29

3
Contents

▼ To Deploy the Hello Application Using Admin Console ........................................................ 30

Deploying the Sample Enterprise Application to a Cluster ............................................................ 31
▼ To Deploy the Sample Enterprise Application Using Admin Console ................................. 31
▼ To Verify Application Deployment ........................................................................................... 32

4 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Preface

This Quick Start Guide provides basic procedures to start the server, deploy an application, and
set up load balancing and failover.

This preface contains information about and conventions for the entire Sun GlassFishTM
Communications Server documentation set.

Sun GlassFish Communications Server Documentation Set

TABLE P–1 Books in the Communications Server Documentation Set

Book Title Description

Documentation Center Communications Server documentation topics organized by task and subject.

Release Notes Late-breaking information about the software and the documentation. Includes a
comprehensive, table-based summary of the supported hardware, operating system, JavaTM
Development Kit (JDKTM), and database drivers.

Quick Start Guide How to get started with the Communications Server product.

Installation Guide Installing the software and its components.

Application Deployment Guide Deployment of applications and application components to the Communications Server.
Includes information about deployment descriptors.

Developer’s Guide Creating and implementing Java Platform, Enterprise Edition (Java EE platform) applications
intended to run on the Communications Server that follow the open Java standards model for
Java EE components and APIs. Includes information about developer tools, security,
debugging, and creating lifecycle modules.

Java EE 5 Tutorial Using Java EE 5 platform technologies and APIs to develop Java EE applications.

Java WSIT Tutorial Developing web applications using the Web Service Interoperability Technologies (WSIT).
Describes how, when, and why to use the WSIT technologies and the features and options
that each technology supports.

Administration Guide System administration for the Communications Server, including configuration, monitoring,
security, resource management, and web services management.

5
Preface

TABLE P–1 Books in the Communications Server Documentation Set (Continued)

Book Title Description

High Availability Administration Setting up clusters, working with node agents, and using load balancers.
Guide

Administration Reference Editing the Communications Server configuration file, domain.xml.

Performance Tuning Guide Tuning the Communications Server to improve performance.

Reference Manual Utility commands available with the Communications Server; written in man page style.
Includes the asadmin command line interface.

Default Paths and File Names

The following table describes the default paths and file names that are used in this book.

TABLE P–2 Default Paths and File Names

Placeholder Description Default Value

as-install Represents the base installation directory for SolarisTM and Linux installations, non-root user:
Communications Server.
user’s-home-directory/SUNWappserver
Solaris and Linux installations, root user:
/opt/SUNWappserver
Windows, all installations:
SystemDrive:\Sun\AppServer

domain-root-dir Represents the directory containing all All installations:

domains.
as-install/domains/

domain-dir Represents the directory for a domain. domain-root-dir/domain-dir

In configuration files, you might see
domain-dir represented as follows:
${com.sun.aas.instanceRoot}

instance-dir Represents the directory for a server instance. domain-dir/instance-dir

samples-dir Represents the directory containing sample as-install/samples

applications.

docs-dir Represents the directory containing as-install/docs

documentation.

6 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Preface

Typographic Conventions
The following table describes the typographic changes that are used in this book.

TABLE P–3 Typographic Conventions

Typeface Meaning Example

AaBbCc123 The names of commands, files, and Edit your .login file.
directories, and onscreen computer
Use ls -a to list all files.
output
machine_name% you have mail.

AaBbCc123 What you type, contrasted with onscreen machine_name% su

computer output
Password:

AaBbCc123 A placeholder to be replaced with a real The command to remove a file is rm filename.
name or value

AaBbCc123 Book titles, new terms, and terms to be Read Chapter 6 in the User's Guide.
emphasized (note that some emphasized
A cache is a copy that is stored locally.
items appear bold online)
Do not save the file.

Symbol Conventions
The following table explains symbols that might be used in this book.

TABLE P–4 Symbol Conventions

Symbol Description Example Meaning

[] Contains optional arguments ls [-l] The -l option is not required.

and command options.

{|} Contains a set of choices for a -d {y|n} The -d option requires that you use
required command option. either the y argument or the n
argument.

${ } Indicates a variable ${com.sun.javaRoot} References the value of the

reference. com.sun.javaRoot variable.

- Joins simultaneous multiple Control-A Press the Control key while you press
keystrokes. the A key.

+ Joins consecutive multiple Ctrl+A+N Press the Control key, release it, and
keystrokes. then press the subsequent keys.

7
Preface

TABLE P–4 Symbol Conventions (Continued)

Symbol Description Example Meaning

→ Indicates menu item File → New → Templates From the File menu, choose New.
selection in a graphical user From the New submenu, choose
interface. Templates.

Documentation, Support, and Training

The Sun web site provides information about the following additional resources:
■ Documentation (http://www.sun.com/documentation/)
■ Support (http://www.sun.com/support/)
■ Training (http://www.sun.com/training/)

Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note – Sun is not responsible for the availability of third-party web sites mentioned in this
document. Sun does not endorse and is not responsible or liable for any content, advertising,
products, or other materials that are available on or through such sites or resources. Sun will not
be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by
or in connection with use of or reliance on any such content, goods, or services that are available
on or through such sites or resources.

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and
suggestions.

To share your comments, go to http://docs.sun.com and click Feedback. In the online form,
provide the document title and part number. The part number is a seven-digit or nine-digit
number that can be found on the title page of the book or at the top of the document.

8 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 1
C H A P T E R 1

Quick Start for Basic Features

Welcome to the Quick Start Guide. This guide provides a set of sample procedures that you can
use to get started with the Communications Server.

Before using the procedures in this document you must have already installed the GlassFish
Communications Server software.

This section contains the following topics:

■ “Getting Started” on page 9
■ “Administration Tools” on page 16
■ “Where to Go Next” on page 18

Getting Started
This topic provides instructions for the following basic tasks: starting the Domain
Administration Server (DAS), logging into the Admin Console, examining the log files, and
starting the node agent. The steps are presented in the order that you should complete them.
■ “To Start the Domain on Solaris and Linux” on page 10
■ “To Start the Domain on Windows” on page 10
■ “To Log On to the Admin Console” on page 11
■ “To View the Domain Administration Server Log File” on page 13
■ “To Start the Node Agent” on page 14
■ “To Add Cluster Support to a Domain” on page 15
■ “To Start the Bundled Java DB Server” on page 16

9
Getting Started

▼ To Start the Domain on Solaris and Linux

To start the Domain Administration Server, start the default domain, domain1.

1 Add the as-install/bin/ directory to the PATH environment variable.

2 Start the server by entering this command:

asadmin start-domain domain1
When you are prompted for the user, admin password, and the master password, enter your
user name and the passwords that you provided during installation. The default admin user
name is admin and the password is adminadmin. The default master password is changeit.
When the start up process is complete, the following message appears:
Domain domain1 started
Each domain has a corresponding profile: cluster or developer. domain1 is created with the
default profile, which is defined in the AS_ADMIN_PROFILE variable defined in the
asadminenv.conf file. For more information on profiles see the “Usage Profiles” in Sun
GlassFish Communications Server 2.0 Administration Guide. If domain1 was created with
developer profile, when you log in to the Admin Console, you cannot use features such as
clustering and node agents. To use clusters and server instances, use the create-domain
command to create a domain with cluster profile. For information on creating domains, type
asadmin create-domain --help or see create-domain(1).

▼ To Start the Domain on Windows

To start the Domain Administration Server, start the default domain, domain 1.

1 From the Explorer window or desktop, right click My Computer.

2 Choose Properties to display the System Properties dialog.

3 Click the Advanced tab.

4 Click Environment Variables.

5 In the User variables section:

■ If a PATH variable exists, verify that as-install\bin exists in the path:

as-install\bin;other_entries. If as-install\bin does not exist in the PATH variable, add it.

■ If a PATH variable is not present, click New. In Variable Name, type PATH. In Variable Value,
type the path to the server’s bin directory: as-install\bin. Click OK to commit the change.

10 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Getting Started

6 Add a new environment variable AS_ADMIN_USER and set it to the Administrative User Name
that you assigned during installation.

7 Click OK to commit the change and close the remaining open windows.

8 Start the Communications Server by clicking the Start Admin Server option within the Programs
menu.

9 When a command prompt window opens to prompt you for the user name and the admin
password, enter the passwords that you provided during installation.
When you are prompted for the user, admin password, and the master password, enter your
user name and the passwords that you provided during installation. The default admin user
name is admin and the password is adminadmin. The default master password is changeit.

Note – If you do not find the Start Admin Server option in your menu, open the Windows
Command Prompt and type the following command: asadmin start-domain domain1
When the startup process has completed, you see an additional message:
Domain domain1 started.
Press any key to continue ...
Each domain has a corresponding profile: cluster, or developer. domain1 is created with the
default profile, which is defined in the AS_ADMIN_PROFILE variable defined in the
asadminenv.conf file. For more information on profiles see the “Usage Profiles” in Sun
GlassFish Communications Server 2.0 Administration Guide. If domain1 was created with
developer profile, when you log in to the Admin Console, you cannot use features such as
clustering and node agents. To use clusters and server instances, use the create-domain
command to create a domain with cluster profile. For information on creating domains, type
asadmin create-domain --help or see create-domain(1).

10 Press a key to close the message window.

▼ To Log On to the Admin Console

The Admin Console is a browser interface that simplifies a variety of administration and
configuration tasks. It is commonly used to:
■ Deploy and undeploy applications
■ Enable, disable, and manage applications
■ Configure resources and other server settings
■ Select and view log files

For further information about using the Admin Console, consult the online help or the Sun
GlassFish Communications Server 2.0 Administration Guide.

Chapter 1 • Quick Start for Basic Features 11

Getting Started

1 Open a browser, and type this URL in your browser:

http:// hostname:4848
If the browser is on a different system than the server, replace the hostname variable with the
hostname or IP address of the system that the Domain Admin Server is running on.
4848 is the Admin Console’s default port number. If you changed the port number during the
installation or if you have created a domain with another port number, use that number instead.

Note – If a popup window appears with a message such as Website Certified by an Unknown
Authority, click OK.

This message appears because your browser does not recognize the self-signed certificate that
the Domain Administration Server uses to service the Admin Console over the secure
transmission protocol.

2 When the Log in window appears, enter the admin user name and password.

3 Click Login.

In the left pane, select what you want to manage from the tree provided. In the right pane,
various administrative tasks are listed under the Common Tasks heading.

12 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Getting Started

▼ To View the Domain Administration Server Log File

Communications Server instances and the Domain Administration Server produce annotated
logs on the file system. By default, all errors, warnings or useful informative messages are
logged.

1 From the Common Tasks list in the right pane, click Search Log Files to launch a new browser
window for Log Viewer.

2 In the Log Viewer window, select“server”from the Instance Name drop-down list and click
Search.
The Domain Administration Server’s recent log file entries are displayed.

Chapter 1 • Quick Start for Basic Features 13

Getting Started

3 Scan the messages and look for any WARNING or SEVERE messages indicating that problems were
encountered during server startup.
You can close Log Viewer at any time. After you create clusters and deploy applications,
examine log files if any of the operations failed. Use Log Viewer to view the log files of any
running Communications Server instance in the domain.

▼ To Start the Node Agent

A node agent is a lightweight process running on each machine that participates in an
administrative domain. The node agent is responsible for starting and stopping server instances
on the host. It also communicates with the Domain Administration Server to create new
instances.

Note – You can use node agents only on domains with the cluster profile . If you are running
only a developer domain, you need to create a domain with cluster profile before you can create
and use node agents. For information on creating domains, type asadmin create-domain
--help or see the create-domain(1) man page.

One node agent is needed on a machine for each administrative domain that the machine
belongs to. A default node agent called hostname may be created during installation. If not,
create a node agent, using the create-node-agent(1) command.

1 In a terminal window, type this command:

asadmin start-node-agent nodeagentname
Replace the variable nodeagentname with the name of the node agent that is created by default
by the installer. If your default domain on port 4848 (domain1) is not running on cluster profile ,
use the --port option to specify the port of the cluster domain.

2 When you are prompted, provide the master password.

The node agent starts and connects with the Domain Administration Server.

Note – Ensure that the Domain Administration Server is running before you start the node
agent. Check the server.log file of a cluster instance to identify problems related to starting
node agents or cluster instances.

If you have problems while starting a node agent or a cluster on Windows, see the Sun GlassFish
Communications Server 2.0 Release Notes for possible solutions to the problem.
After the node agent has been started once, you can view it in the Admin Console.

14 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Getting Started

Next Steps In this section you started the Domain Administration Server and confirmed that it is running.
You also logged in to the Admin Console and used the Log Viewer. You started the node agent.
You can stop the Quick Start trail here if you do not wish to continue, or you can go on to the
next section.

▼ To Add Cluster Support to a Domain

You can use the Admin Console add cluster support to a developer domain.

1 Log on to the Admin Console. For instructions, see “To Log On to the Admin Console”on page 11.

2 From the left pane, click Application Server.

3 Click the Add Cluster Support button in the General tab.

4 The Add Cluster Support page appears. Review the information on this page and click OK.

5 In the Restart Required Page, click the Stop Instance button to stop the domain.

6 Log in to the machine where the domain is installed and run the following command:
as-install/bin/asadmin list-domains. Verify that the domain was stopped.

7 Run the following command: as-install/bin/asadmin start-domain <domain-name>

The restarted domain supports clustering.

Chapter 1 • Quick Start for Basic Features 15

Administration Tools

More Information Troubleshooting

If the restarted domain does not show clustering capabilities, stop the domain, reboot the
machine on which the domain is installed, and restart the domain as shown in step 7.

▼ To Start the Bundled Java DB Server

The Communications Server includes a bundled Java DB server. To start it, use the following
procedure:

1 Make sure that you are logged in as the user that installed the database.

2 Run asadmin start-database.

For more information on the start-database command, see the start-database(1) man
page.

Administration Tools
To enable administrators to manage server instances and clusters running on multiple hosts,
Communications Server provides these tools:
■ The Admin Console, a browser-based graphical user interface (GUI). You can launch the
Admin console by opening http:// hostname:4848 in your browser.
■ Command-line tools, such as the asadmin utility. See Table 1–1 for the complete list of
command-line tools. The asadmin utility is at as-install/bin.
■ Programmatic Java Management Extensions (JMXTM) APIs

These tools connect to a server called the Domain Administration Server, a specially designated
instance that intermediates in all administrative tasks. The Domain Administration Server
(DAS) provides a single secure interface for validating and executing administrative commands
regardless of which interface is used.

A domain is a collection of configuration data, deployed applications, and machines with a

designated administrator. The domain definition describes and can control the operation of
several applications, stand-alone instances, and clusters, potentially spread over multiple
machines. When the DAS is installed, a default domain called domain1 is always installed. You
work with the default domain in this guide.

Communications Server offers a variety of command-line tools for performing administrative

functions, in addition to the Admin Console. To launch a tool, type the name of the tool in a
command window. Table 1–1 lists tools by name in the first column and describes them in the
second column.

16 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Administration Tools

TABLE 1–1 Command-Line Tools

Name of Tool Description

appclient Launches the Application Client Container and invokes the client
application packaged in the application Java archive (JAR) file.

asadmin Launches the Communications Server administration tool that provides a

set of subcommands for configuring the Communications Server software.

asant Launches the Jakarta Ant tool, so that you can automate repetitive
development and deployment tasks.

asapt Compiles Java sources with Java EE annotations. The tool automatically
invokes the wsimport command.

asupgrade Communications Server administration tool for upgrading the

Communications Server software.

capture-schema Extracts schema information from a database and produces a schema file
that the server can use for Container Managed Persistence (CMP).

jspc Compiles JSP pages.

package-appclient Packages the application client container libraries and JAR files.

schemagen Creates a schema file for each namespace referenced in your Java classes.

verifier Validates the Java EE deployment descriptors with the DTDs.

This tool also provides a graphical user interface. To see the GUI, specify the
-u option.
Some Windows systems launch a driver verifier utility with the same name.
To launch the Communications Server verifier, you must be in the
as-install/bin directory.

wscompile Takes the service definition interface and generates the client stubs or
server-side skeletons for JAX-RPC; or generates a Web Services Description
Language (WSDL) description for the provided interface.

wsdeploy Generates an implementation-specific, ready-to-deploy WAR file for web

services applications that use JAX-RPC.

wsgen Reads a web service endpoint class and generates all the required artifacts
for web service deployment and invocation.

wsimport Generates JAX-WS portable artifacts, such as service endpoint interfaces

(SEIs), services, exception classes mapped from the wsdl:fault and
soap:headerfault tags, asynchronous response beans derived from the
wsdl:message tag, and JAXB generated value types.

xjc Transforms, or binds, a source XML schema to a set of JAXB content classes
in the Java programming language.

Chapter 1 • Quick Start for Basic Features 17

Where to Go Next

Note –
■ To run these command-line tools on Windows, ensure that you have an environment
variable called PATH that points to the as-install/bin/ directory.
■ You can run the asadmin subcommands by prefixing asadmin with every sub command or
by entering the asadmin prompt (type asadmin and hit Return) in the as-install/bin/
directory.

Where to Go Next
The next steps of the Quick Start Guide are available in the following chapters.
■ Chapter 2, “Setting Up a Cluster”
Steps for creating a sample cluster. Skip to the next chapter if you are running a domain with
developer profile.
■ Chapter 3, “Deploying an Application”
Steps for deploying a sample web application. If you are using a domain with cluster
capabilities, you can perform the steps for deploying an enterprise application to a cluster.

Other resources for learning and using Communications Server are available. They include:
■ Product details at as-install/docs/about.html.
■ Sample applications at as-install/samples
■ Sample SIP applications at as-install/samples/sipservlet
■ Sun GlassFish Communications Server 2.0 Release Notes
■ Sun GlassFish Communications Server 2.0 Reference Manual (man pages)
■ Sun GlassFish Communications Server 2.0 Application Deployment Guide
■ The Java EE 5 Tutorial
■ Java BluePrints (http://java.sun.com/blueprints) guidelines for the Enterprise

18 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 2
C H A P T E R 2

Setting Up a Cluster

This chapter describes how to create and set up clusters. A cluster is a group of server instances
(typically on multiple hosts) that share the same configurations, resources, and applications. A
cluster facilitates load balancing across server instances and high availability through failover.
You can create clusters spanning multiple machines and manage them with the help of the node
agent process on each machine.

This chapter assumes that you are running a domain with cluster profile. This chapter has the
following sections:
■ “ Setting Up a Cluster with Converged Load Balancer ” on page 19
■ “Creating a Cluster that Spans Multiple Machines” on page 22
■ “Viewing Ports for Clustered Server Instances” on page 26

Setting Up a Cluster with Converged Load Balancer

This section explains how to create a cluster that contains two Communications Server
instances and describes how to use the converged load balancer, which is available
out-of-the-box with a Communications Server installation. This section assumes that you have
installed Communications Server with clustering.

▼ To Set Up a Cluster with Converged Load Balancer

This procedure creates the sample cluster one the same host on which the DAS is running.

Before You Begin It is assumed that you have already started the node agent. When you specify instances during
cluster creation, associate the instance with a running node agent for the machine on which you
want the instance to run. If the node agent is not running, the instance will not start. Node agent
and instance names must be unique across clusters that are created in a domain.

19
Setting Up a Cluster with Converged Load Balancer

1 Log in to the Administration Console at http:// hostname:portnumber if you have not already
done so.
Replace the hostname variable with the name of the system that the Domain Administration
Server is running on. Replace portnumber with the port number of the cluster domain, domain1.

2 On the left pane, click the Clusters tab.

3 Communications Server installation creates a default cluster called default-cluster, which is

associated with a default converged load balancer called cluster-lb. Click default-cluster.
The General Information for this cluster appears.

Note – In the General tab on the right hand pane, ensure that the Heartbeat Enabled checkbox is
selected. You need GMS service to be running to be able to use the converged load balancer.

4 On the right pane, click the Instances tab. Click the New button to create two entries to specify
two instances for the cluster.

5 Type instance1. In the Node Agent field, nodeagent1 is selected by default.

6 Type instance2. In the Node Agent field, nodeagent1 is selected by default. Click Save.
Instead of steps 4,5, and 6 you can use the following asadmin commands:
■ asadmin create-instance --user admin --passwordfile adminpassword.txt --host
hostname -port 4848 --cluster default-cluster --nodeagent nodeagent1
--systemproperties
"JMX_SYSTEM_CONNECTOR_PORT=8687:IIOP_LISTENER_PORT=3330:IIOP_SSL_LISTENER_PORT=4440:IIOP_SSL_
MUTUALAUTH_PORT=5550:HTTP_LISTENER_PORT=1110:HTTP_SSL_LISTENER_PORT=2220"
instance1
■ asadmin create-instance --user admin --passwordfile adminpassword.txt --host
hostname -port 4848 --cluster default-cluster --nodeagent nodeagent1
--systemproperties
"JMX_SYSTEM_CONNECTOR_PORT=8688:IIOP_LISTENER_PORT=3331:IIOP_SSL_LISTENER_PORT=4441:IIOP_SSL_
MUTUALAUTH_PORT=5551:HTTP_LISTENER_PORT=1111:HTTP_SSL_LISTENER_PORT=2221"
instance2

7 Click Save.

8 Run the following command to enable converged load balancing in default-cluster:

asadmin enable-converged-lb-server default-cluster

20 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Setting Up a Cluster with Converged Load Balancer

9 From the Converged Load Balancers node in the Admin Console, choose cluster-lb, and click
the Targets tab. Click the Edit Load Balancer Details link. In the Edit Load Balancer Details page,
click to enable the Automatically Apply Changes option and click Save. By default, this option is
disabled.
You can also use the asadmin set command to set this option to true. For more details, see
Chapter 2, “Configuring Converged Load Balancing,” in Sun GlassFish Communications
Server 2.0 High Availability Administration Guide.

10 To start the cluster,

■ Click the General tab and click the Start Cluster button.

■ Start the cluster and its instances by running the following command:
asadmin start-cluster --user admin --passwordfile adminpassword.txt --host
hostname --port 4848 default-cluster
The two instances are started by default when you start the cluster. default-cluster is
associated with a converged load balancer called cluster-lb, which is created by default by the
Communications Server installation. This figure shows default-cluster and two instances
running on this cluster.

Chapter 2 • Setting Up a Cluster 21

Creating a Cluster that Spans Multiple Machines

Creating a Cluster that Spans Multiple Machines

▼ To Create a Cluster With Instances On Different

Machines
The following procedure demonstrates how to create a cluster that has two instances, instance3
and instance4, each running on different machines. The two machines are called schumi and
sr115. schumi is the machine that is denoted as the administrative node and is called the
Domain Administration Server (DAS).

Before You Begin You must have already installed Communications Server on both machines.

1 Create and start a node agent (nodeagent2) on the DAS machine.

Use the following command: asadmin create-node-agent --user admin --host schumi
nodeagent2

2 Start the node agent on the DAS machine.

Use the following command: asadmin start-node-agent --user admin --host schumi
nodeagent2. For more information, see start-node-agent(1) command.

3 Create a start a node agent on another machine.

This example uses a second machine called sr115. On the second machine, at the invoke the
asadmin utility and use the following command: asadmin create-node-agent --user admin
--host schumi nodeagent3

Note – You need to provide the DAS machine name in the --host option.

4 Start the node agent on the second machine.

Use the following command: asadmin start-node-agent --user admin --host schumi
nodeagent3. For more information, see start-node-agent(1) command.

5 Log in to the Admin Console of the DAS machine at http:// das-machine-name:portnumber.

You can see that the two node agents are running if you click Node Agents on the left-hand tree
on the Admin Console.

6 On the left pane, click the Clusters tab and click New.

7 Specify a name for the cluster.

This example creates a cluster with the name, mycluster.

22 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Creating a Cluster that Spans Multiple Machines

8 In the Server Instances to be Created section, click New.

9 Type the instance name as instance3 and choose node agent, nodeagent3.
nodeagent3 was created on the machine called sr115 in step 2 of this procedure.

10 Type the instance name as instance4 and choose node agent, nodeagent2.
nodeagent2 was created on the DAS machine called schumi in step 1 of this procedure.

11 Click OK.
The cluster gets created.

12 To create and enable a converged load balancer for this cluster, use the following command:
asadmin create-converged-lb --user admin --passwordfile pass.txt --configfile
clb.xml --autocommit=true --lbenableallinstances=true --target mycluster
mycluster-lb

13 From the Converged Load Balancers node in the Admin Console, choose cluster-lb, and click
the Targets tab. Click the Edit Load Balancer Details link. In the Edit Load Balancer Details page,
click to enable the Automatically Apply Changes option and click Save. By default, this option is
disabled.
You can also use the asadmin set command to set this option to true. For more details, see
Chapter 2, “Configuring Converged Load Balancing,” in Sun GlassFish Communications
Server 2.0 High Availability Administration Guide.

Chapter 2 • Setting Up a Cluster 23

Creating a Cluster that Spans Multiple Machines

14 In the left pane, click Clusters.

15 In the right pane, select the checkbox next to mycluster and click the Start Cluster button,
The cluster and the two instances start.

The two instances in mycluster are running on different machines and are controlled by
different node agents. You can view the two node agents and see each instance associated with
it.

24 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Creating a Cluster that Spans Multiple Machines

If you deploy an application on mycluster, the application is accessible from two machines.

Chapter 2 • Setting Up a Cluster 25

Viewing Ports for Clustered Server Instances

Viewing Ports for Clustered Server Instances

▼ To View Ports for Clustered Server Instances

You can view the ports numbers and override the default values for the clustered server instance
you created in the previous section, “ Setting Up a Cluster with Converged Load Balancer ” on
page 19. By default, the HTTP ports are 38081 for instance1 and 38080 for instance2. If these
ports were busy on your machine when you created these clusters, or if you had already
assigned these ports to other instances and clusters, different port numbers were assigned.

To view the port numbers and optionally override the default values, follow these steps:

1 In the left pane, expand Clusters and click default-cluster to display the General Information
page for clusters.

2 Click the Instances tab to display instance1 and instance2, the instances that you created.

a. Click instance1 to examine this instance.

The HTTP and HTTPS ports assigned to the instance are displayed in the HTTP Ports field.
The SIP and SIPS Ports are displayed in the SIPS field.

26 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 3
C H A P T E R 3

Deploying an Application

This chapter explains how to deploy an application. If you are running a domain with developer
profile, see “Deploying a Sample Web Application” on page 29. If you are running a domain
with cluster profile, see “Deploying the Sample Enterprise Application to a Cluster” on page 31.

This chapter presents the following sections:

■ “Deploying a Sample SIP Module” on page 27
■ “Deploying a Sample Web Application” on page 29
■ “Deploying the Sample Enterprise Application to a Cluster” on page 31
■ “To Verify Application Deployment” on page 32

Deploying a Sample SIP Module

▼ To Deploy the CallSetup Application Using Admin

Console
1 Log in to the Admin Console if you have not already done so.

2 Start the Java DB database, as explained in the section, “To Start the Bundled Java DB Server”on
page 16.

3 Click Converged SIP Modules.

You can see the list of deployed web applications, if any.

4 Click Deploy.

5 Select the Local Packaged File or Directory that is Accessible to Application Server option.

27
Deploying a Sample SIP Module

6 Browse to the as-install/samples/sipservlet/CallSetup/ directory.

Tip – For more details about deploying this sample, see

as-install/samples/sipservlet/CallSetup/CallSetup.html.

7 Choose CallSetup.sar.

8 If you are running a domain with clustering capabilities, you need to specify a target. In the
Targets section of the page, select server from the Available list, and click Add to move it to the
Selected list

9 Click OK.
The application appears in the Converged SIP Modules list.

10 To verify that it was deployed properly, point your browser to the following location:
http://hostname:HTTPport/CallSetup/
The default HTTP port is 8080.

28 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Deploying a Sample Web Application

More Information Deploying Applications Using CLI Commands

You can deploy applications using the asadmin deploy command. You can also use the asant
commands for deployment. For detailed information on deploying applications, see the Sun
GlassFish Communications Server Application Deployment guide.

Deploying a Sample Web Application

These procedures assume that you are running a domain with developer profile.

▼ To Deploy the Hello Application Using Autodeploy

The Hello application is contained in a Web ARchive (WAR) file in the samples/quickstart
directory. Packaged applications can also be in the form of a Java ARchive (JAR) or Enterprise
ARchive (EAR) file.

Alternatively, you can download this application from https://glassfish.dev.java.net/

downloads/quickstart/hello.war.

Copying to a domain’s autodeploy directory lets you put a pre-packaged application into use
immediately, with minimal effort.

1 Find as-install/samples/quickstart/hello.war or download from https://

glasfish.dev.java.net/downloads/quickstart/hello.war.

2 Copy hello.war to the as-install/domains/domain1/autodeploy/ directory.

Tip – On Windows, you can create a shortcut to the autodeploy directory on your desktop, and
then drag and drop the hello.war file onto the shortcut.
When the server has finished deploying the application, it creates a file named
hello.war_deployed in the autodeploy directory. Depending on the speed of your system, the
process can take a few seconds. Until that file appears, a 404-File Not Found error occurs when
you try to visit the application page.

3 Access this URL to visit the application page: http://hostname:HTTPport/hello.

You see the application’s first page, which prompts you to fill in your name:

4 Type your name and click Submit.

The application displays a customized response, giving you a personal Hello.

Chapter 3 • Deploying an Application 29

Deploying a Sample Web Application

▼ To Deploy the Hello Application Using Admin Console

1 Open the Admin Console in a web browser if you have not done so already.

2 In the left pane, click the Applications node to expand it.

3 Click Web Applications.

You can see the list of deployed web applications, if any.

4 Click Deploy.

5 You can use the Hello application bundled with the Communications Server or you upload the
sample you have downloaded from https://glasfish.dev.java.net/downloads/
quickstart/hello.war. Do one of the following:

■ Select the option called Local packaged file or directory that is accessible to Application
Server and click Browse Files. Navigate to the as-install/samples/quickstart directory and
select hello.war.

6 If you have downloaded the Hello application, click Browse in the Packaged File to Upload text
box. Navigate to the directory to which you have downloaded the application.

7 Click OK.
The application appears in the Web Applications list.

8 To verify that it was deployed properly, in the Web Applications page, select the Hello
application and click Launch.

30 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Deploying the Sample Enterprise Application to a Cluster

More Information Deploying Applications Using CLI Commands

You can deploy applications using the asadmin deploy command. You can also use the asant
commands for deployment. For detailed information on deploying applications see the Sun
GlassFish Communications Server Application Deployment guide.

Deploying the Sample Enterprise Application to a Cluster

These procedures assume that you are running a domain with cluster profile. The procedures in
this chapter assume that you have already created a cluster called default-cluster, as
described in Chapter 2, “Setting Up a Cluster.” This section uses the clusterjsp sample
application to demonstrate HTTP load balancing capabilities.

▼ To Deploy the Sample Enterprise Application Using

Admin Console
1 Open the Admin Console in a web browser if you have not done so already.

2 Click Common Tasks on the left pane to go to the Common Tasks page, if you are not there
already.

3 On the right pane, under Common Tasks, click Deploy Enterprise Application (.ear).

4 Select the radio button to the left of the Local packaged file or directory that is accessible from
the Application Server option and then click the Choose File... button. Navigate to
as-install/samples/quickstart/clusterjsp/clusterjsp.ear.
If you are accessing Communications Server remotely, and if the sample application is
accessible from your client machine choose the Packaged file to be uploaded to the server
option and click Browse.

5 Click the Availability enabled check box to make your application highly available.
It is recommended that you set the heap size to a larger value, if you have available memory in
your system. For example, <jvm-options>-Xmx1000m</jvm-options>

6 In the Targets section of the page, select mycluster from the Available list, and click Add to
move it to the Selected list.

7 Click OK.
The clusterjsp application is now deployed to default-cluster. Before you launch this
application, you need to start the instances in the cluster.

Chapter 3 • Deploying an Application 31

Deploying the Sample Enterprise Application to a Cluster

Note – Ensure that you have enabled cookies in your browser before you deploy this application.
clusterjsp is a sample application. Please use with caution in a production environment.

More Information Deploying Applications Using CLI Commands

You can deploy applications using the asadmin deploy command. See the deploy man page in
the Reference Manual. You can also use the asant commands for deployment. For detailed
information on deploying applications see Deploying Modules and Applications in the
Application Deployment Guide.

▼ To Verify Application Deployment

1 Type the following URL in your browser:
http://hostname:port/clusterjsp
Replace the hostname variable with the name of the system that the Domain Admin Server is
running on.
Replace the port variable with the value of HTTP-LISTENER-PORT for instance4. This example
uses http://hostname:38081/clusterjsp.

2 Add some session attribute data.

3 Examine the Session and Host information displayed. For example:

32 Sun GlassFish Communications Server 2.0 Quick Start Guide • September 2009
 Deploying the Sample Enterprise Application to a Cluster

■ Executed From Server: localhost

■ Server Port Number: 38081
■ Executed Server IP Address: 198.19.255.255
■ Session Created: Tue Aug 23 15:26:07 PDT 2005

4 Add some session data and click the Add to Session button.

5 Repeat this procedure for instance instance3 by typing this URL in your browser:
http://hostname :38081/clusterjsp

Chapter 3 • Deploying an Application 33

34