Samples Index

Building, Deploying, and Running Sample Applications

This document provides common procedures to to build, deploy, and run the sample applications that come with the Sun Java System Application Server. For any additional application-specific steps, see the documentation for each application.

• Directories and Variables
• Building a Sample Application
• Deploying a Sample Application
• Running a Sample Application
• Troubleshooting
• Undeploying the application

IMPORTANT: Be sure to read the following section to understand the variables and directories used in the samples documentation.

Directories and Variables

The samples documentation uses the following variables and directories. The documentation for each individual sample application specifies their value for that application:

• install_dir is the directory where Application Server is installed.
• app_dir is the sample application's base directory. This directory contains all the application files. For example, for the "simple" sample application, app_dir is install_dir/samples/webapps/apps/simple/. All application base directories contain at least:
  • build.xml file: The Ant build file.
  • /src sub-directory: Contains all the application source code.
  • /docs sub-directory: Contains the application-specific documentation.
  • A pre-built EAR (enterprise application archive) or WAR (web application archive) file for the application.
  There may be other sub-directories, depending on the application.
• appname - The application's name, as defined in its deployment descriptors. In many cases, the application name is different from the name of the directory containing it.
• context_root - The "context root" or base URL for accessing the application, also defined in the deployment descriptors. In some cases, this is the same as appname, but not always.

Domain Directories

The location of the domain root directory, domain_root_dir, depends on which product you are using:

• Sun Java Enterprise System installations on the Solaris platform:

  /var/opt/SUNWappserver/domains/
  

• Sun Java Enterprise System installations on the Linux platform:

  /var/opt/sun/appserver/domains/
  

• All other installations (including Platform Edition):

  install_dir/domains/

Within domain_root_dir, each domain is in a sub-directory, domain_name, for example domain1. So, for example, with Application Server Platform edition, the "normal" default domain is install_dir/domains/domain1.

Building a Sample Application

Every sample application comes with a pre-built application archive: either a web application archive (WAR) file or an enterprise application archive (EAR) file. You can skip building the application and deploy the pre-built archive file. Go to Deploying the Sample Application. Or, you can build the application yourself. If you have made any changes to the application source code or deployment descriptors, then you must build it yourself for those changes to take effect.

This section contains instructions for building a sample application using asant, a command-line build tool provided with Application Server. The asant tool is based on Ant, developed by the Apache Software Foundation.

Prerequisite: Ensure that install_dir/bin is in your path.

To build a sample application, follow these steps:

1. Open a shell window
2. Change your current directory to the application base directory:

   cd app_dir
   

3. Build the application with the following command:

   asant
   

   This command executes the default target core and rebuilds the application archive (WAR or EAR) file.
4. Optional: Use this command to clean the application project area and remove the assemble and build directories:

   asant clean

Now the application archive (WAR or EAR) is ready for deployment.

NOTE: You can verify the syntax and semantics of all deployment descriptors by running asant verify from app_dir. This may be useful if you have made changes to the deployment descriptor files.

Generating Javadoc

To better understand the source code, you can generate Javadoc for the application. Javadocis a tool for generating API documentation in HTML format from doc comments in source code.

To generate Javadoc, use this command:

asant javadocs

This command generates a set of HTML files in the /javadocs sub-directory. Start by opening app_dir/javadocs/index.html in your web browser.

Deploying a Sample Application

• Deploying with asant.
• Deploying with Admin Console.
• Verifying Deployment.

Note: Most samples support reploying without having to first undeploy. In case of a problem, run asant undeploy and then redeploy the application. This ensures that all modules are undeployed and the resources are disabled.

Deploying with asant

NOTE: This is the recommended deployment method for sample applications, because the Ant script deploy target ensures that all neccessary resources (for example JDBC or JMS resources) are created. Follow these steps to deploy an application using the asant command-line tool:

1. Change your current directory to the application base directory:

   cd app_dir

2. Deploy the application with the following command:

   asant deploy

   This deploys the application archive (WAR or EAR file).

Deploying with Admin Console

Follow these steps to deploy using the browser-based Admin Console. In the basic procedure, the steps are similar for Enterprise applications and Web applications, except for the titles of the pages.

NOTE: If you deploy an application using the Admin Console instead of asant, then you must create any required resources (for example, JDBC or JMS resources) before running the application. When you use asant, they are automatically created for you.

1. Start the administration server if it is not already started:
   
   
   • On Unix, execute the command

     install_dir/bin/asadmin start-domain domain1

   • On Windows, click the Start menu and choose "Programs->Sun Microsystems->J2EE 5 SDK->Start Default Server"
2. Open the Admin Console by entering this URL in your browser:

   http://hostname:port/asadmin

   For Application Server Platform Edition, the default port number is 4848. For Application Server Enterprise Edition, the default port number is 4849. If you are using a server on your local machine, you can use localhost instead of the host name.
3. You are prompted for the administrator user name and password. Enter the values for your installation, then click on the "Login" button.
4. In the tree component in the left frame, click Applications-->Enterprise Applications. If you are deploying a Web Application, click Applications-->Web Applications.
5. In the right frame, click the "Deploy..." button.
6. Click the "Browse..." button to choose the application archive file to deploy. A file selection dialog box will appear.
7. Navigate to the desired file. The EAR or WAR file will be in the application base directory, app_dir. Select the file then click "OK."
8. Click "Next."
9. The Deploy Enterprise (or Web) Application page displays. Change any of the deployment settings, or keep the default values. For more information, click "Help" in the upper right corner of the browser window.
10. Click "OK" to deploy the archive to the server.
11. If deployment is successful, Admin Console will display the list of deployed enterprise (or web) applications, including the one you just deployed. Additionally, in the tree component, you will see the name of the application.

Verifying Deployment

If you want, you can verify the application has been properly deployed and registered on the server. This step is optional. If you want to skip it, proceed to Running the Sample Application.

You can verify deployment with asadmin or the Admin Console.

Use the following command to list all applications deployed to a server instance:

asadmin list-components --user username --password password

If the application has been successfully deployed, its name will be listed.

Alternately, use Admin Console and navigate to Applications > Enterprise Applications or Applications > Web Applications, depending on whether the application is a web application or an enterprise application with EJBs. If the application has been deployed, Admin Console will display the application name.

Running a Sample Application

To run a deployed application, load the following URL in your web browser:

http://hostname:port/contextRoot

If you are running the server on your local machine, you can use localhost instead of the host name.

NOTE: Some of the sample applications are not browser-based applications that use a "standalone" Java client, and some sample applications are not even J2EE applications. In these cases, run the application from the command line. See the specific instructions for that application.

Troubleshooting

If you encounter problems when running the application, review the log files at

domain_root_dir/domain_name/logs/server.log

See Directories and Variables for an explanation of the domain_root_dir and domain_name variables.

With Application Server Enterprise Edition, it may also be helpful to review node agent log files. Each node agent has its own log file located at:

node_agent_dir/node_agent_name/agent/logs/server.log

By default, node_agent_dir is install_dir/nodeagents.

Sometimes the node agent log instructs you to look at a server’s log to get a detailed message about a problem. The server logs are located at:

node_agent_dir/node_agent_name/server_name/logs/server.log

Undeploying the application

You can undeploy an application that has been deployed with asant, the asadmin command, or Admin Console. To undeploy the application with asant:

1. In a shell window, change your current directory to app_dir.
2. Enter the command asant undeploy

To undeploy the application with asadmin:

1. In a shell window, change your current directory to app_dir.
2. Enter the command:

   asadmin undeploy --user user-name --password password
   --host hostname
   --port admin-port
   appname
   

   If the server is localhost, you can omit the --host option. If you are using the default administration port, you can omit the --port option.

To undeploy with Admin Console:

1. Start the admin server and open Admin Console, as described in Deploying with Admin Console
2. In the tree component, expand the Applications node.
3. Select the node for the type of application or module want to undeploy.
4. In the table listing the deployed applications, select the checkbox for the application or module you want to undeploy.
5. Click Undeploy.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.