Sun GlassFish Enterprise Server 2.1 Quick Start Guide

Chapter 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 Enterprise 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

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

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

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

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: enterprise, 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 Enterprise Server 2.1 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.

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

Choose Properties to display the System Properties dialog.

Click the Advanced tab.

Click Environment Variables.

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.

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

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

Start the Enterprise Server by clicking the Start Admin Server option within the Programs menu.

When a command prompt window opens to prompt you for the admin password and the master 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: enterprise, 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 Enterprise Server 2.1 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).

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 Enterprise Server 2.1 Administration Guide.

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.

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

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.

To View the Domain Administration Server Log File

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

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

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.

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 Enterprise 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 or enterprise 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.

In a terminal window, type this command:

asadmin start-node-agent nodeagentname

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

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 Enterprise Server 2.1 Release Notes for possible solutions to the problem.

After the node agent has been started once, you can view it in the Admin Console.

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.

Log on to the Admin Console. For instructions, see To Log On to the Admin Console.

From the left pane, click Application Server.

Click the Add Cluster Support button in the General tab.

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

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

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.

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

The restarted domain supports clustering.

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 Enterprise Server includes a bundled Java DB server. To start it, use the following procedure:

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

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, Enterprise 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 (JMX^TM) 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.

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

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 Enterprise Server administration tool that provides a set of subcommands for configuring the Enterprise 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`	Enterprise Server administration tool for upgrading the Enterprise 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 Enterprise 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.

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 Enterprise Server are available. They include:

Product details at as-install/docs/about.html.
Sample applications at as-install/samples
Sun GlassFish Enterprise Server 2.1 Release Notes
Sun GlassFish Enterprise Server 2.1 Reference Manual (man pages)
Sun GlassFish Enterprise Server 2.1 Application Deployment Guide
The Java EE 5 Tutorial
Java BluePrints guidelines for the Enterprise