Part 2: Configure an application, then install its files

This case will demonstrate how to quickly configure an application using mostly the default settings. It will show where to move the application files to, allowing the application to work correctly.

If you selected the "default configuration" option during your Custom installation of WebSphere Application Server, you will already have a default application server, servlet engine, and other resources required to support an application. The default virtual host is installed regardless of whether you install the default configuration.

This tutorial does not assume you have the default configuration. The first step of this section demonstrates configuring your own application server and other supporting resources.

  1. Configure a virtual host

  2. Configure database support

  3. Configure a Web application and other resources

  4. Place the application files in WebSphere directories

  5. Configure an application

  6. Verification step

Note: Slight discrepancies in the screen captures in this tutorial and the actual WebSphere Administrative Console are possible.

2.1: Configure a virtual host

A virtual host is a configuration that allows a single physical machine to resemble multiple host machines. You can isolate applications so that they seem to be on entirely different boxes.

You can configure your own virtual host, but for the purposes of the tutorial, use the default virtual host. You do not need to change any of its settings. Simply verify that it exists.

To view the default host, click "default_host" near the bottom of the tree on the topology view.

When you click it, its properties are displayed on the right side of the console. Most notable are its aliases (click the Advanced tab). Because the default host represents your local machine, its aliases include "localhost," the loopback address (127.0.0.1), and the short and fully-qualified host names of the machine:

It might not be necessary for you to configure a new virtual host for your production environment. A production environment does not necessary require multiple virtual hosts. If yours requires only one virtual host, then the default_host is probably suitable. Next, configure resources for database support.

2.2: Configure database support

The "Account Bean" in the Account.jar file is a persistent entity bean that requires database access. Configure resources to support it. Configuring database support is necessary if any of your resources, such as servlets, require database access.

In this case, you can use the WebSphere administrative repository as the database. The tutorial assumes you are using DB2. If you are using another database (such as Oracle), the tutorial will still be helpful, but you might need to refer to product field help to determine appropriate field values.

You will:

For your everyday use, you can configure DB2 or Oracle databases separate from the administrative repository database.

Let's begin.

Click the Types button of the administrative console, right-click the JDBCDrivers folder on the Types tab and select its Create menu option:

You are going to specify the type of JDBC driver you will be using. A JDBC driver is the code that lets Java components access databases. The driver properties dialog will be displayed.

Specify properties for the JDBC driver:

Name
Specify AccountDB2Driver.

This is the name by which to administer the driver. Here, you have given it a name that indicates it is a DB2 driver for the Account application to use.

You can make up any value you like for this property.

Implementation class
Specify the DB2 choice, com.ibm.db2.jdbc.app.DB2Driver.

This is the implementation class of the driver code. If you instead were using another database, you would select the class for that database.

JTA enabled
Specify False if using DB2 5.2. Specify True if using DB2 6.1.

This specifies whether the database brand and version supports the Java transaction services.

The remainder of the properties are optional. Do not specify anything for them.

When you finish specifying the properties, click OK:

A confirmation dialog verifies that you configured the driver successfully. The main console window displays the driver in the JDBCDrivers list:

Next, configure a data source that specifies connection pool settings for your database brand and version. In the Types tree, right-click the DataSources folder and click Create.

The data source properties dialog will be displayed:

Specify properties for the data source:

Name
Specify AccountDB2Dsrc.

This is the name by which you will administer the data source. You have specified a name indicates it is a DB2 database for the Account application's use.

You can make up any value you like for this property.

Database Name
Specify WAS, assuming that is the name of the administrative repository you created during installation and configuration of the product.

Note that on AIX and Solaris, database names can be case-sensitive. Recall whether you named the database "was" or "WAS."

Driver
Select the AccountDB2Driver you configured recently.

The remainder of the properties are optional. Click the Advanced tab to see the default values for the connection pool settings. In this case, leave the default values as they are.

When you finish specifying the properties, click Create. A confirmation dialog tells you the data source configuration was successful.

Now that you have a data source, you can return to the JDBC driver and "install" it, specifying the location of the Java code for the driver. Switch to the Topology tab. Click the WebSphere Administrative Domain. You will see, among other things, the JDBC driver and data source you configured:

Click the AccountDB2Driver. Its properties are displayed on the right side of the console. Right-click it and click Install.

A browse dialog is displayed. Select your local machine (shown here as sna58) as the node on which to install the driver:

When you do that, the Browse button will become active. Click it to browse for the DB2 JDBC driver code. It should be in the sqllib\java directory of your DB2 installation root:

When you locate the db2java.zip file, select it and click the Open button to return to the driver installation dialog. It will be displayed in the Jar file field:

Click the Install button. Note, this operation does not change the location of the db2java.zip file. It simply specifies the location of the file to the WebSphere administrative server.

That's it. You now have the resources necessary to support database access by your applications.

2.3: Configure a Web application

In this step, you will configure a Web application containing your servlet, JSP, and HTML files. You will also configure an application server, servlet engine, container, and other resources to support your eventual enterprise application.

In the next step, you will configure an enterprise application containing the Web application and your enterprise beans.

Let's begin.

Press the Wizards button and select "Create Application Server:"

 

The first page of the wizard is displayed:

On this first panel, you have some choices:

In this case, select both Enterprise Beans and Web Applications. Click Next.

The next screen allows you to specify properties for the application server to handle applications containing enterprise bean and servlets:

Application Server Name
Specify MyAppServer.

This is the name by which to administer the application server.

You can make up any value you like for this property.

The remainder of the properties are optional. Keep the default values.

Click Next to continue. The next page lets you decide whether to start the server after configuring it. Specify "Do not start the server automatically after creating it." Later, you can practice starting it from the Topology tree.

Click Next to proceed. Now specify the node (physical machine) on which the application server will reside. In this case, select your local node. The hostname in this example is sna58. On your machine, it will be the hostname of your machine.

If you have a multinode administrative domain, you will see multiple nodes in the above panel. The nodes are all of the nodes that share an administrative repository (database). This panel provides the opportunity to remotely configure an application server process to run on another machine in the administrative domain.

Click Next to proceed. The next panel lets you specify enterprise beans for the application server.

Click the "Browse" button.

Recall, the Account.jar file resides in:

install_root\deployableEJBs

The "Browse" button produces a browse dialog that opens to the deployedEJBs directory:

Navigate to the deployableEJBs directory, which is under the install root of the product. You should see several JAR files. Put your cursor on the Account.jar file. Do not click the Select button yet:

It is very important that you now double-click Account.jar to display its deployment descriptor (.ser file). If you skip this step, things will seem to proceed without error, but you will encounter problems with later steps. Double-clicking Account.jar displays its .ser file:

Click the deployment descriptor (.ser file). Now click the Select button. A confirmation dialog asks whether to deploy the enterprise bean JAR file. Specify Yes because this bean JAR has to be deployed before you can use it.

  If you see this confirmation dialog instead, you have not selected the deployment descriptor. Click Cancel to return to the browse dialog. Make sure you click the .ser file before clicking the Select button.

Wait for the deployment to finish. A dialog box will let you know when it is done.

Now, back in the main console window, the deployment descriptor is displayed in the enterprise bean list:

If you select the Account Bean deployment descriptor and click Edit, you can edit it:

For now, close the edit dialog and click Next to proceed to the next panel in the task wizard. Every enterprise bean needs a container to support it. Configure one here:

Specify properties for the container:

EJB Container Name
Specify MyAppServerContainer. This should be the default value anyway.

This is the name by which to administer the container.

DataSource
Click the Change button. In the resulting dialog box, select AccountDB2Dsrc.

User ID, Password
Leave these blank, indicating they will be the default user ID and password for the data source. In this case, that means they are the user ID and password for accessing the administrative repository (the WAS database).

The remainder of the properties are optional. Do not specify anything for them.

Click Next to proceed to a panel for selecting a virtual host. Recall, you are using the default_host:

Notice there is also an option here for configuring a new virtual host, by specifying its name in the Virtual Host Name field. If you did that, the next panel or two of the wizard would let you configure the virtual host properties.

Select default_host and click Next to proceed. You will not see any virtual host configuration panels because you have already configured default_host. Instead, you will see servlet engine properties:

Specify properties for the servlet engine:

Servlet Engine Name
Specify MyAppServerServletEngine. This should be the default value anyway.

This is the name by which to administer the servlet engine.

The remainder of the properties are optional. Do not specify anything for them. To see the settings for communication between the servlet engine and the Web server (for routing requests for servlets from the Web server to the servlet engine), browse the Advanced tab. Notice the Settings button.

Click Next to proceed. Now you are ready to configure a Web application comprised of the servlet, JSP, and HTML files for the Account application.

Specify the following properties:

Web App Name
Specify AccountWebApp. This is more descriptive than the default value.

This is the name by which to administer the Web application, and part of the path by which users can access the Web application from a browser. That will be discussed shortly.

Note that when you type in this field, the Full Web Path below also changes.

Virtual Host
Specify default_host.

Full Web Path
Keep the default value.

Together, the virtual host and the Web path indicate a path for accessing the Web application from a browser:

http://Valid_default_host_Alias/webapp/AccountWebApp
where Valid_default_host_Alias is any valid alias for the virtual host named default_host.

The Web application properties should now look like this:

Click the Advanced tab to view some additional properties.

These Web application properties are most notable:

App Doc Root
Accept the default value, install_root\hosts\default_host\AccountWebApp\web

This specifies the location of the HTML and JSP files for the application. After completing this task wizard ("Configure an application server"), you are going to move the files there. It resembles the document root of a Web server.

App Classpath
Accept the default value, install_root\hosts\default_host\AccountWebApp\servlets

This specifies the location of the servlets for the application. You will later move the servlet class file there.

As with the above settings, it is optional that you change the rest of the settings from their default values. In this case, accept the default values.

Click Next to proceed. On this panel, you can add system servlets to the Web application. System, or internal, servlets are servlets shipped with WebSphere Application Server to support various functions in your Web applications.

Specify which system servlets to use. For the basic application configuration, this is especially important.

Enable File Servlet
Select this check box. It is required because you are using the basic application configuration procedure (Step 2a) and your Web application contains HTML and JSP files.

This enables Web pages to be served from the App Doc Root you specified on an earlier Web application configuration panel. It adds a file servlet to your Web application for this purpose.

In addition to selecting this check box, make sure your Web server configuration file does not contain any pass rules that will override the App Doc Root.

Serve Servlets By Classname
Select this check box. It is required because you are using the basic application configuration procedure (Step 2a) and your Web application contains servlets.

This enables servlets to be served from the servlets directory named in the Web application classpath. Any servlet class you drop into the directory can be loaded by the WebSphere administrative server, without requiring that you identify the servlet by name.

Enable JSP 1.0, Enable JSP .91
Select JSP 1.0. It is required because your Web application contains JSP files.

This specifies to include the JSP enabler servlet supporting the 1.0 level of the JavaServer Pages (JSP) specification. The JSP file for the Account application is written against the 1.0 specification.

  All three of these settings are required in order for your Web application containing HTML, servlets, and JSP files to work correctly using the basic application configuration procedure:

Here's a tip. Suppose you forget to select one of the check boxes. You can use the "Add a servlet" wizard on the Wizards button to add the file servlet, enable servlets to be served by class name, and add a JSP enabler.

Add a servlet (explicitly configure it)

Now let's explicitly define the CreateAccountJSP.class servlet in the administrative domain. This is not necessary in order to use the servlet, because you have already configured a servlets directory in the Web application classpath and specified to include the Invoker servlet (Serve servlets by classname) so that you do not have to explicitly define servlets.

However there are advantages to defining servlets. For example, you cannot track servlet performance with the Resource Analyzer unless you explicitly configure the servlet.

Press the Wizards button and select the "Add a servlet" task. Specify to select an existing servlet because the servlet class file already exists in a directory (recall the Sample files used in the tutorial section above):

On the next page, specify to add the servlet to the AccountWebApp:

On the next page, you can browse for the servlet file. Click the Browse button to display a browse dialog in which you can specify the servlet name and directory:

When you return from the browse dialog, the panel will list the path of the file you chose:

Next, specify that this is a user-defined servlet. For more information about the other options, consult the Add a servlet task help.

Specify a name and class for the servlet. The class should be the exact class name, but the name can be anything by which you want to administer this servlet -- it is a logical name:

You can specify startup parameters and other options for the servlet. Do not specify anything right now. For more information about the settings on this screen, consult servlet properties help.

Click Finished to add the servlet to the Web application AccountWebApp.

Now you are ready to finish configuring the application server and its contents. Click Finished.

You have configured many resources. Use the Topology panel to view them:

Notice that when you click a resource, such as MyAppServer, its properties are displayed on the right side of the console. You can edit most of them, including adding values for properties you formerly left blank.

You can confirm that the AccountWebApp contains the system servlets you intended. Under the AccountWebApp in the Topology tree, you can see the:

Notice you do not see the CreateAccountJSP.class servlet listed under the Web application. This is because you have used the basic application configuration procedure in which you do not specify servlets by name in the administrative domain. You would have to configure a servlet resource in the administrative domain and associate it with the Web application in order to see it displayed here.

You can also view the properties of your AccountBean by clicking on it in the Topology tree.

So, now you have a Web application and the infrastructure to support it and your Account enterprise application, once you configure one. You have also deployed the Account Bean and configured its database access information, readying it for use.

2.4: Place the application files in WebSphere directories

Now you must place the Web application files where WebSphere Application Server expects them to be, based on the Web application configuration you specified.

  1. Create any necessary directories to place the files in.

    In this case, recall you accepted the default values for the Web application document root and classpath, which are:

    In the WebSphere Application Server installation root, create the directory structure to support the Web application configuration.

  2. Place the HTML and JSP files in directory you specified as the document root of the Web application (i.e., the 'web' directory).

  3. Place the servlet class and the CreateAccountJSP.servlet files in the 'servlets' directory:
      

Click here to review the names and locations of the HTML, JSP, and servlet files in the Account sample.

Note, you do not have to move the Account bean. It has been configured "in place."

As an example, the directory structure on Windows NT looks like this:

2.5: Configure an application

In this step, you will in essence "wrap" your Web application with an application and add the Account Bean to the application. This is necessary because security is applied to enterprise applications, not to Web applications.

Start the Configure a new Application task on the Tasks tab:

This task is for creating an enterprise application.

Name the enterprise application AccountApp. Click Next to proceed.

For the contents of the application, select the Web application you configured earlier. Click Add:

The Console Messages area displays a confirmation message that the operation was successful.

Add the AccountBean (from the Enterprise Beans folder) in the same way.

When finished adding resources, click Next to proceed. The next panel is for removing resources you did not really want to add. It also provides the opportunity to confirm that everything was added. Expand the tree to ensure all of the resources are there.

When satisfied with the content of the application, click Finish. If some files are missing, click the Back button to return to the panel for adding resources.

2.6: Verification step

Now is a good time to verify that the enterprise application works, before you apply security to it.

First, make sure the default server is started. Locate it in the Topology tree and click the green toolbar button if the server is not already running.

After waiting for the server and all of its children to start, open a browser and try the URL for the enterprise application:

http://Valid_default_host_Alias/webapp/AccountWebApp/createjsp.html
where Valid_default_host_Alias is any of the valid aliases for the default host. Recall, to view valid aliases, simply click the default host in the Topology tree so that its properties, including aliases, are displayed in the right side of the console.

If you do not receive an error page, the application is working correctly. It should present a form for creating accounts.

Go to next part of tutorial

Return to beginning