Quick Start Guide
This guide describes basic steps for
starting the Sun JavaTM System Application Server software, (henceforth referred
to as Application Server), and packaging and deploying applications. It also provides
information about the Admin Console and command-line tools. You must have
already installed the product to use this Quick Start Guide.
For more information, see Sun Java System Application Server Platform Edition 9 Installation Guide.
The intended audience
for this guide is the system administrator, network administrator, Application Server administrator,
and developer who is interested in learning the basics about Application Server software.
This document contains information about the following topics:
For information about conventions used in this document, see Documentation Conventions.
Starting and Verifying the Server
This section provides procedures for administrators who want to start
and verify the Application Server software:
For administration tasks, the Application Server software provides these
tools, which enable administrators to manage server instances:
-
The Admin Console, a browser-based graphical user interface
(GUI)
-
The asadmin utility, a command-line tool
To Start the Application Server on Linux
and Solaris
You may have already started the server
when you installed, using the Start Server button on the last installation
screen. However, if your server is not running, start it using the steps below.
You start the server by starting the domain. A domain provides
authentication and administration for the server instance that belongs to
it. Starting the domain starts the server instance in the domain. A default
domain called domain1 is created when you install Application Server.
Note –
If you are using the Application Server that
comes bundled with the Solaris operating system, no default domain is created.
Instead, you must create one using asadmin create-domain.
See the documentation for create-domain(1) for more information.
Note –
If
you are using the Ubuntu Linux version of the server, a default domain is
created in /var/lib/sunappserver/domains. You can administer
this domain using the install-dir/bin/asadmin command.
If you do not have root access or you want to have domains running in your
home directory, you can use the asadmin convenience wrapper
script located in /usr/bin to create a domain in your home
directory. Running asadmin start-domain from the convenience
script creates and starts the domain. For more information on the convenience
script, type asadmin man at the command prompt.
If
you have root access, you can also create and start domains using the asadmin commands create-domain and start-domain from
the install-dir/bin directory. These
domains are created by default in /var/lib/sunappserver/domains.
For more information on create-domain and start-domain, see the asadmin help.
-
Add the install-dir/bin/ directory to the PATH environment variable.
-
Start the server by entering this command: asadmin start-domain
domain1.
When the server has started, a message appears
stating that the server has been started and is ready to receive requests.
The output also includes information on ports used by the Application Server.
To Start the Application Server on
Windows
You may have already started the server when you installed, using the
Start Server button on the last installation screen. However, if your server
is not running, start it using the steps below.
-
From the Start menu, choose Programs ⇒ Sun Microsystems ⇒
Application Server PE 9 ⇒ Start Default Server.
A command
window appears showing initialization messages. When the server has started,
a message appears stating that the server has been started and is ready to
receive requests. The output also includes information on ports used by the Application Server.
-
Press any key to dismiss the command window.
See Also
You can also use the asadmin start-domain domain1 command
to start the server. Before using asadmin, see To Configure the Windows Environment to Use the Command-Line Tools.
To Confirm That the Server Is Running
To verify that the server is running on your system, click this
URL: http://localhost:8080.
The
URL has two parts:
-
localhost is used if the both the
browser and the Application Server are running on the same system. If the Application Server is
running on another system, substitute the name of that system in the URL.
-
The default port number is 8080. If you changed the port number
during installation, use that number in your browser’s address field
instead. The port number is displayed in the asadmin start-domain output.
You should see the server Welcome page, shown below.
This page might take a few seconds to appear.
When you see
this page, you know that the server is running. If you
encounter problems, check your server and browser settings, as described in
the Sun Java System Application Server Platform Edition 9 Troubleshooting Guide.
To Deploy the Hello Application Using Autodeploy
The server installation includes a pre-packaged
application that says “Hello,” taken from The
Java EE 5 Tutorial. The Hello application
is contained in a Web ARchive (WAR) file in the samples directory.
Packaged applications can also be in the form of a Java ARchive (JAR) or Enterprise
ARchive (EAR) file.
Dragging or copying to a domain’s autodeploy directory
lets you put a pre-packaged application into use immediately, with minimal
effort.
-
Find install-dir/samples/quickstart/hello.war.
-
Copy hello.war to the install-dir/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.
-
Access this URL to visit the application page: http://localhost:8080/hello.
You see
the application’s first page, which prompts you to fill in your name:
-
Type your name and click Submit.
The application displays
a customized response, giving you a personal Hello.
Note –
You can also use the asadmin command-line utility
to deploy from the command line or in a shell script. The command is asadmin
deploy. For more information, see the deploy(1) command documentation
in the Sun Java System Application Server Platform Edition 9 Reference Manual. Other
deployment methods are discussed later in the Guide in To Deploy From the Admin Console, and To Deploy From a Development Directory. It is also possible to dynamically reload
changes to your application. For more information, see Dynamic Reloading in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
To Log In to the Admin Console
The Admin Console is a web-based interface that simplifies a variety
of administration and configuration tasks. It is commonly used to:
-
Deploy and undeploy applications
-
Enable and disable applications
-
Identify which applications are currently enabled
-
Configure Application Server settings
-
Configure Java Database Connectivity (JDBCTM) resources
-
Select and view recent entries in the log file
For further information about using
the Admin Console, consult the online help or the Sun Java System Application Server Platform Edition 9 Administration Guide.
-
Access http://localhost:4848/.
-
localhost is used if the both the
browser and the Application Server are running on the same system. If the Application Server is
running on another system, substitute the name of that system in the URL.
-
4848 is the Admin Console’s default
port number. If you changed the port number during the installation, use that
number instead. The port number is included in the output for asadmin
start-domain.
Tip –
Windows users can also use the
Start menu option: Programs ⇒ Sun Microsystems ⇒ Application Server
PE 9 ⇒Admin Console.
-
Enter the administration user name and password,
specified when you installed the product.
-
Click Log In.
When the Admin Console appears, it looks
like this:
Use the items in the tree to configure a variety of operational settings
for Application Server software. Launch online help from the button in the upper
right corner.
To see the server’s log file, click Search
Log Files under the Common Tasks heading in the right pane. When the Log Viewer
window appears, set criteria and click Search to display status messages from
the server and output from your Java EE application.
To Start the Bundled Java DB Server
The Application 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
command's help or the start-database(1) information in Sun Java System Application Server Platform Edition 9 Reference Manual.
Packaging and Deploying Applications
Before applications can be deployed, they must be packaged into Java
ARchive (JAR), Web ARchive (WAR), or Enterprise ARchive (EAR) files. The packaged
application includes deployment descriptors, which give the Application Server software
the information it needs to load the application, map a URL to it, and connect
it to the resources it uses. This section describes the following techniques
for packaging and deploying applications:
For more information, see “Getting Started With Web Applications”
in The
Java EE 5 Tutorial.
Using NetBeans IDE to Develop and Deploy Applications
NetBeansTM IDE
is an Integrated Development Environment you can use to create, package, and
deploy complex Java EE applications. The NetBeans IDE 5.0 is available for
download from http://www.netbeans.org/. NetBeans
IDE integrates the development environment with the deployment environment,
and automates many steps for producing Java EE applications. Once you register
the Application Server with the NetBeans IDE, you can easily deploy applications,
make changes, and redeploy them.
For more
information on using NetBeans IDE with Application Server, see the documentation
at: http://www.netbeans.org/.
To Package the Hello Application Using asant
If applications are not packaged with a tool such as NetBeans IDE, you
can use the asant utility shipped with the product. The asant utility is used to automate repetitive deployment tasks. It
is a shell script that initializes the Application Server environment and launches
the Jakarta Ant tool. For more information on the asant utility,
see the Sun Java System Application Server Platform Edition 9 Reference Manual,
and Chapter 3, The asant Utility, in Sun Java System Application Server Platform Edition 9 Developer’s Guide.
The Hello application deployed earlier was already packaged into a WAR
file. This section covers packaging the application's components into another
WAR file. The build.xml file included with the Hello
application contains the build targets.
-
If you have not already added install-dir/bin to
your PATH environment variable, do so now.
-
Go to install-dir/samples/quickstart/ directory.
-
Type asant war.
This command assembles
the WAR file for the application in install-dir/samples/quickstart/build/assemble/war.
To Deploy From the Admin Console
Now that you have packaged the Hello application, you can deploy it.
The following section discusses deploying the Hello application using the
Admin Console. You can also deploy using asant.
-
Click http://localhost:4848/asadmin.
-
localhost is used if the both the
browser and the Application Server are running on the same system. If the Application Server is
running on another system, substitute the name of that system in the URL.
-
4848 is the Admin Console’s default port number. If
you changed the port number during the installation, use
that number instead.
-
Enter the admin user name and password.
-
In the left pane, click the Applications node to expand it.
-
Click Web Applications.
-
If you already have a Hello application deployed, undeploy it
now by selecting the checkbox next to it and clicking Undeploy.
-
To deploy the newly assembled Hello application, on the Web Applications
page, click Deploy.
-
Select the Package file to upload to the Application Server option
and click Browse.
-
Navigate to
the install-dir/samples/quickstart/build/assemble/war directory
and select hello.war.
-
Click Next.
-
On the Deploy Web Module page, click Finish
The application
appears in the Web Applications list.
-
To verify that it was deployed properly, click Launch.
To Deploy From a Development Directory
You can deploy an application directly from a development directory,
if the appropriate directory hierarchy and deployment descriptors have been
created. This directory must be accessible from the machine where Application Server is
installed. Because the process is complex for non-trivial applications, it
is a procedure that is recommended only for advanced users, or simple applications.
But when it is feasible to do so, deploying directly from a directory can
speed up the development cycle.
The process can be performed interactively by using the Admin Console,
or by using asadmin deploydir from the command line or
in a script. The steps for the command line are presented here, because most
developers want to automate the procedure in command scripts.
Note –
Before using asadmin on Windows, see To Configure the Windows Environment to Use the Command-Line Tools.
-
In the install-dir/samples/quickstart/ directory, create a new directory called hello2/.
-
Unzip the contents of the hello.war file into
the hello2/ directory.
Preserve the directory
structure of the hello.war file when you unzip it. It is
a template for the kind of file structure you need to deploy directly from
a directory.
-
If you already have a Hello application deployed, undeploy it
now using the command asadmin undeploy hello at the
command line.
If you did not install the Application Server with the “Don’t
prompt” option, also specify the option --user username, where username is the admin
user name. You are prompted for the administration password.
-
Use the following command to deploy the application:
asadmin deploydir install-dir/samples/quickstart/hello2
Note –
Specify the full path to the hello2/ directory.
The following message appears: Command deploydir executed successfully.
-
Verify that the application is running by going to this URL: http://localhost:8080/hello.
Using Command-Line Tools
The Application Server software 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. This table lists
tools by name in the first column and describes them in the second column.
Table 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
|
Application Server administration tool for configuring the Application 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
|
Application Server administration tool for upgrading the Application 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 Application Server verifier, you must be in the install-dir/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.
|
To Configure the Windows Environment to Use the Command-Line
Tools
-
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, add or update the PATH variable.
-
In the User variables section, add the environment variable AS_ADMIN_USER and set it to the administrative user name that you
assigned during installation.
If you set this variable, you do
not need to enter the administrative user name when you run asadmin commands.
Note –
If you installed the server with the “Don't
Prompt for Admin User Name” option selected, you do not need to create
the AS_ADMIN_USER variable.
-
Click OK to commit the change and close the remaining open windows.
Where to Go Next
Other resources for learning about and using Application Server are available.
They include the following:
Documentation Conventions
This section describes the types of conventions used throughout this
guide.
General Conventions
The following general conventions are used in this guide:
-
File and directory paths are
given in UNIX® format (with forward slashes separating directory
names). For Windows versions, the directory paths are the same, except that
backslashes are used to separate directories.
-
Installation root directories for
most platforms are indicated by install-dir in this document.
By
default, the location of install-dir on most platforms
is:
-
Solaris bundled version:
/usr/appserver
-
Other Solaris and Redhat Linux installations, non-root user:
user’s-home-directory/SUNWappserver
-
Other Solaris and Redhat Linux installations, root user:
/opt/SUNWappserver
-
Ubuntu
Linux Users:
/usr/share/sunappserver
-
Windows, all installations:
SystemDrive:\\Sun\\AppServer
-
Domain root directory are indicated
by domain-root-dir in this document, which by default is an abbreviation for
the following:
-
Solaris bundled version:
/var/appserver/domains/
-
Ubuntu
Linux version:
/var/lib/sunappserver/domains
-
Ubuntu Linux version, when using asadmin convenience script:
/user's-home-directory/glassfish/domains
-
All other versions:
install-dir/domains/
However, for Solaris bundled installations, the directory containing
all the domains can be changed to another directory during installation.
Typographic Conventions
The following table describes the typographic changes that are used
in this document.
Table 2 Typographic Conventions
|
Typeface
|
Meaning
|
Example
|
|
AaBbCc123
|
The names of commands, files, and directories, and onscreen computer
output
|
Edit your .login file.
Use ls -a to list all files.
machine_name% you have mail.
|
|
AaBbCc123
|
What you type, contrasted with onscreen computer output
|
machine_name% su
Password:
|
|
AaBbCc123
|
A placeholder to be replaced with a real name or value
|
The command to remove a file is rm filename.
|
|
AaBbCc123
|
Book titles, new terms, and terms to be emphasized (note that some emphasized
items appear bold online)
|
Read Chapter 6 in the User's Guide.
A cache is a copy that is stored locally.
Do not save the file.
|
Download this book in PDF (616 KB)