Sun ONE Studio 4, Enterprise Edition for Java Tutorial Table of ContentsPrevious ChapterNext ChapterBook Index


C H A P T E R  1
Getting Started

This chapter describes what you must do before starting the Sun ONE Studio 4, Enterprise Edition for Java tutorial. The most important task is to get the Sun ONE Studio 4 IDE and the Sun ONE Application Server 7 application server to recognize each other, and to get both to communicate with the Oracle database.

The topics covered in this chapter are:

This chapter does not describe how to install the following required software:

For installation instructions, see the Sun ONE Studio 4, Enterprise Edition for Java Getting Started Guide, available from
http://docs.sun.com/source/816-7859-10.
To download the application server, go to http://sun.com/software/products/appsrvr/appsrvr_download.html
Installation information is available from http://docs.sun.com/source/816-7145-10/.

The Sun ONE Studio 4 and Sun ONE Application Server 7 products can be installed together as the Sun ONE Application Server 7, Sun ONE Studio 4 bundle. The Sun ONE Studio 4, Enterprise Edition for Java with Application Server 7 Tutorial describes how to configure them when they are installed together. This chapter assumes that you have installed them separately.

Software Requirements for the Tutorial

Supported versions of the required software are provided in the release notes, available on http://forte.sun.com/ffj/documentation/index.html.

The following software is required for the DiningGuide tutorial:

Both the IDE and the application server require the J2SE SDK. Supported versions are listed in the Sun ONE Studio 4, Enterprise Edition for Java Getting Started Guide, available from http://docs.sun.com/source/816-7859-10. The application server requires J2SE SDK v. 1.4.0_02, which is bundled with the application server. You can create the EJB tier of the tutorial with the IDE using a different version of the compiler, but you can't run the web services portion unless the IDE is using v. 1.4.0_02 or later of the J2SE SDK.
The most convenient scenario for installing the J2SE SDK, if you are installing the application server locally, is to install it with the application server. Then when you install the IDE, point to this J2SE SDK when prompted during the install.
Alternatively, you can download the J2SE SDK from the Java Developer's portal at http://java.sun.com/j2se/. If your application server is installed on a remote machine, you must install v. 1.4.0_02 or later of the J2SE SDK locally.
A web browser is required to view the pages of the test application client.
This tutorial requires an Oracle server or an Oracle client that accesses an Oracle server to be installed on the same machine as the IDE. The JDBC driver is also required. See the release notes for supported versions.
This tutorial requires the Sun ONE Application Server 7 application server to deploy the tutorial application.
This tutorial also uses the web server included in the Sun ONE Application Server 7 software to run the tutorial's test client.
The Sun ONE Application Server 7 server can be installed on the following platforms:

Requirements for IDE-to-Application Server Communication

Setting up the IDE to communicate with the Sun ONE Application Server 7 server requires the right software installed in the right location. There are many options, which this section attempts to clarify.

Software Requirements

For the IDE and the application server to communicate requires:

Consists of JAR and configuration files that are installed in either the IDE's home directory, or your IDE user directory.
Consists of JAR files that support the server's administrator. These files must be available on the same machine as the IDE.

Installation Options

How you install the application server plugin and admin client libraries depends on whether the application server and the IDE are on the same machine or not, as follows:

Option 1: Obtain the plugin from the IDE's Update Center. The plugin can use the administrative libraries of the application server installed on your machine.
Option 2: Install the plugin with the Sun ONE Application Server 7 installer.
Option 1: Install the plugin with the Sun ONE Application Server 7 installer. The admin libraries are included with the plugin.
Option 2: Install the application server on your local machine. Then obtain the plugin from the IDE's Update Center. The plugin can use the admin libraries of the local server to administer the remote server.

If you choose to install the plugin with the Sun ONE Application Server 7 installer, you must use the correct installer, as follows:

Installing the Oracle Type 4 Driver in the IDE and the Application Server

Now, install Oracle into both the IDE and the application server. To do this, you need the Oracle Type 4 JDBC driver. You can download this driver from the Oracle portal. Copy the JDBC Type 4 driver into the program files of both products before you start either product.

To install the Oracle Type 4 driver in both the application server and the IDE.

1. Install Oracle in the Sun ONE Application Server 7 server by copying the Oracle Type 4 driver library to the /lib directory of the server's instance.

For example, copy the classes12.zip file to
c:\Sun\AppServer7\domains\domain1\server1\lib\.

2. Install the Oracle Type 4 driver library in the IDE, by copying the Oracle Type 4 driver library to the IDE's /lib/ext directory.

For example, copy the classes12.zip file to
c:\Program Files\s1studio\ee\lib\ext\.

Starting the Software

This section assumes you have already installed the IDE, the Sun ONE Application Server 7 server and the plugin, and the Oracle server (or the Oracle client, if the server is installed remotely). Although there are several startup methods, only one option is described here. See the installation documentation for the separate products for other options.

To start up the software:

1. Start the application server according to the server's Getting Started Guide.

The method depends on your platform.

A command window appears and displays a message that the server instance has started. A second command window is then displayed showing server event log file content. Event messages appear, and after a few seconds a message appears confirming that the server instance has started successfully. You can close the first window, but do not close the second window.
The appserver-install-dir variable stands for the application server's home directory, which depends on your platform and type of installation. This command starts the initially configured domain, domain1, on your system.

2. Start the IDE.

If this is the first time you have started the IDE, a dialog prompts you for a user settings directory. Use a complete specification, for example, C:\MySettings.

Sun ONE Studio 4 IDE dialog box for Microsoft Windows showing sample directory specification. The buttons are OK and Cancel. 

This value is stored in the registry for later use. For a given session, you can specify a different user settings directory by using the -userdir command-line switch when launching the IDE.
The s1studio-home variable stands for the IDE's home directory, for example, $HOME/s1studio/ee. The user settings directory is by default located in user-home/ffjuser40ee. You can specify a different directory with the -userdir command-line switch when you start the IDE.

3. If not already started, start your Oracle database server.

Consult your Oracle documentation for this step.

Installing the Application Server Plugin

If the application server you will access is installed on a remote machine, you must use the Sun ONE Application Server 7 "non-evaluation" installer to install either the plugin or the entire application server. For information on how to do this, see the Sun ONE Application Server 7 Standard Edition Installation Guide, obtainable from http://docs.sun.com/source/816-7145-10/.

If your application server is installed on the same machine as the IDE, you can install the plugin from the IDE's Update Center, as follows:

1. In the Sun ONE Studio 4 IDE, choose Tools right arrow Update Center.

The Update Center wizard is displayed.

2. Select the Sun ONE Studio Update Center as the Update Center, and deselect NetBeans Update Center.

3. Click the Proxy Configuration button to set your proxy configuration, if needed.

The Proxy Configuration dialog box is displayed.

4. Modify the values as needed and click OK to return to the Update Center wizard.

5. Click Next, and type your Sun ONE Studio Update Center login name and password.

See the Sun ONE Studio 4, Enterprise Edition for Java Getting Started Guide for information on registering and creating a login name and password.

The Update Center displays the modules that are available to you.

6. Expand the Sun ONE Studio Update Center node and select the Sun ONE Application Server 7 Plug-in and click the arrow pointing to the right.

The plugin is moved to the right pane.

7. Follow the Update Center installation procedures.

The IDE installs the plugin and then restarts itself.

Once restarted, the IDE has the means to connect with the Sun ONE Application Server 7 server.


Note - When you install the plugin through the IDE's update center, the IDE may place it in your user directory (depending on user option settings). When you install the plugin using the Sun ONE Application Server 7 installer, it places the plugin in the IDE distribution. If you reinstall the plugin with a different method, you must delete the old plugin files, wherever they are located.


Connecting the IDE to the Application Server

Now configure the IDE to use the Sun ONE Application Server 7 server and make it the default server.

Configuring the IDE to Use the Application Server

1. In the Sun ONE Studio 4 IDE, click the Explorer's Runtime tab.

2. Expand the Server Registry node and its Installed Servers subnode.

3. Select the Sun ONE Application Server 7 node to display its properties in the Properties window.

The Properties window is usually below the Explorer. If the Properties window is not displayed, choose View > Properties to display it.

4. Locate the Sun ONE App Server Home property and click in its value field.

An ellipsis button appears.

5. Click the ellipsis button.

A file finder window is displayed.

6. Use the file finder to select the Sun ONE Application Server 7 home directory.

For example: c:\Sun\appServer7

7. Click OK to close the file finder window.

8. Right-click the Sun ONE Application Server 7 node again and choose Add Admin Server.

The Add Admin Server dialog box is displayed.

9. Type the server's host name in the Admin Server Host field.

If the application server that you want to use is installed on the same machine as the IDE, type localhost. If the server is remote, type the host name of the remote machine.

10. Type your admin port number in the Admin Server Port field, your server user name in the User Name field, and your server password in the User Password field.

During the installation of the Sun ONE Application Server 7 server, the following values were suggested for these fields:

If you did not use these defaults, specify the values that you did use. If you don't know the values to use, consult Getting Started with Sun ONE Application Server 7 for instructions on where to look for this information.

11. Click OK to close the dialog box.

A node labeled hostname:admin-server-port (for example, localhost:4848) is created under the Sun ONE Application Server 7 node. This node represents the admin server. You can issue commands to this node and the admin server will execute them.

12. Expand the hostname:admin-server-port node.

A node representing an instance of the application server is displayed.

Making the Sun ONE Application Server the Default Server

By default, Sun ONE Studio 4 is configured to use the J2EE reference implementation for its application server. To make the Sun ONE Application Server 7 server the default:

1. Expand the Sun ONE Application Server 7 node and the admin representative subnode.

For example, this node might be labeled localhost:4848. An application server instance node (labeled something like server1(localhost:4848)) is a subnode of the admin node.

2. Right-click the instance node and choose Set As Default.

3. Expand the Default Servers node under the Server Registry node.

If the Server Registry looks like this, then the IDE is using the correct servers.

The Default Servers node in the Runtime pane of the Explorer shows the application server is server1(localhost:4848).[ D ] 

Connecting the IDE and the Application Server to the Database

Now, configure the Sun ONE Application Server 7 application server to connect to the Oracle database. Do this by creating and registering a new connection pool, a JDBC data source, and a JDBC persistence manager. These items are required when you deploy an application that includes entity beans that use container-managed persistence (the CMP EJB components used in the tutorial's EJB tier).

Before you continue, make sure you have added the Oracle JDBC Type 4 driver to both the IDE and the application server, as described in Installing the Oracle Type 4 Driver in the IDE and the Application Server.

Defining a JDBC Connection Pool

1. In the Explorer, click the Runtime tab.

2. Expand the Server Registry, Installed Servers, and Sun ONE Application Server 7 nodes.

3. Right-click the Unregistered JDBC Connection Pools node and choose Add New JDBC Connection Pool.

This opens the JdbcConnectionPool property window and a new node is created under the Unregistered JDBC Connection Pools node.

4. For the Datasource Classname property, type oracle.jdbc.pool.OracleDataSource.

5. For the Name property, type OraclePool.

6. Select the ellipsis button for the Properties property.

The Properties property editor is displayed.

7. Click the Add button.

The Add Extra Property Info dialog box is displayed.

8. Type URL in the Property Name field.

9. Type jdbc:oracle:thin:@oraclehost:1521:oracle_SID in the Property Value field.

The Add Extra Property Info dialog box looks similar to this:

Add Extra Property Info editor window shown with the example values. 

10. Click OK to create the property and close the dialog box.

11. Repeat Step 7 through Step 10 to add two more new properties with the following values:

Property Name

Property Value

User

your_username

Password

your_password


The values for these properties are the user name and password you use to access your database. When you are done, the property editor looks similar to this:

New property editor is shown, displaying URL, User, and Password properties and values. Buttons are Add, Edit, Remove, OK, Cancel, Help. 

12. Click OK to close the property editor, and close the connection pool's property window.

Registering the Connection Pool

To register the connection pool you just created:

1. Expand the Unregistered JDBC Connection Pools node.

Note the new node for OraclePool.

2. Right-click the OraclePool node and choose Register.

The Select Server to Register to dialog box is displayed.

3. Select the entry (for example, server1(localhost:4848) and click the Register button.

When the connection pool is registered, an information window is displayed, indicating success.

4. Close the information window and the Select Server to Register to dialog box.

5. Expand the server instance under the Sun ONE Application Server 7 node.

Nodes for registered resources are displayed.

6. Expand the Registered JDBC Connection Pools node in this list.

The registered OraclePool connection pool is displayed.

Expanded Server Registry nodes and subnodes shown; OraclePool node displayed under Registered JDBC Connection Pools node.[ D ] 

If you do not see the OraclePool connection pool, right-click the Registered JDBC Connection Pools node and choose Refresh List.

Defining a JDBC Data Source

To define a JDBC data source for the Oracle database:

1. If necessary, expand the Server Registry, Installed Servers, and Sun ONE Application Server 7 nodes in the Explorer's Runtime pane.

2. Right-click the Unregistered JDBC Data Sources node and choose Add New Data Source.

This opens the DataSource property window and a new node is created under the Unregistered JDBC Data Sources node.

3. Type jdbc/jdbc-oracle for the JNDI Name property.

4. Select OraclePool(server1:hostname:admin-server-port) from the list for the Pool Name.

5. Close the property window.

Registering the JDBC Data Source

Register the JDBC data source you just created the same way you registered the connection pool in Registering the Connection Pool, namely:

1. Expand the Unregistered JDBC Data Sources node.

2. Right-click the jdbc/jdbc-oracle node and choose Register.

The Select Server to Register to dialog box is displayed.

3. Select the entry (for example, server1(localhost:4848) and click the Register button.

When the data source is registered, an information window is displayed, indicating success.

4. Close the information window and the Select Server to Register to dialog box.

If you do not see the jdbc/jdbc-oracle node, right-click the JDBC Data Sources node and choose Refresh List.

Defining a JDBC Persistence Manager

To define a JDBC persistence manager to support container-managed persistence (CMP) for the Oracle database:

1. If necessary, expand the Server Registry, Installed Servers, Sun ONE Application Server 7, and the nodes in the Explorer's Runtime pane.

2. Right-click the Unregistered Persistence Managers node and choose Add a Persistence Manager.

This opens the PersistenceManagers property window and a new node is created under the Unregistered Persistence Managers node.

3. Type jdbc/jdbc-oracle for the JDBC Resource JNDI Name property.

4. Type jdo/OraclePm for the JNDI Name property.

5. Close the property window.

Registering the JDBC Persistence Manager

Register the JDBC persistence manager you just created in the usual way, namely:

1. Expand the Unregistered Persistence Managers node.

2. Right-click the jdo/OraclePm node and choose Register.

The Select Server to Register to dialog box is displayed.

3. Select the entry (for example, server1(localhost:4848) and click the Register button.

When the data source is registered, an information window is displayed, indicating success.

4. Close the information window and the Select Server to Register to dialog box.

Right-click the Registered Persistence Managers node and choose Refresh List if you don't see the jdo/OraclePm node.

Creating the Database Tables

The DiningGuide tutorial uses two database tables, which you must create in an Oracle Server database. The instructions that follow describe how to use the provided SQL script to create your tables. Microsoft Windows users can copy and paste the SQL script provided in Appendix B to create these tables. Solaris and Linux users can use a script file, rest_pb.sql, which is available within DiningGuide application files.


Note - There are several references in this book to the DiningGuide application files. These files include a completed version of the tutorial application, a readme file describing how to run the completed application, and a SQL script file for creating the required database tables. These files are compressed into a ZIP file you can download from the Sun ONE Studio 4 Developer Resources portal at http://forte.sun.com/ffj/documentation/tutorialsandexamples.html


To install the tutorial tables in an Oracle database on Microsoft Windows systems:

1. Open the Oracle Console by choosing Start > Programs > Oracle (your version) > Application Development > SQL Plus.

2. Log in to SQL Plus using your user name and password.

For example, use the user name (scott) and password (tiger) for the default Oracle installation.

3. When the SQL prompt appears, copy the script from Chapter B and paste it next to the prompt.


Tip - Avoid the first two DROP statements, which refer to tables that have not yet been created and will create harmless errors. These DROP statements are useful in future, however, if you want to rerun the script to initialize the tables.


To install the tutorial database in an Oracle database on Solaris or Linux environments:

1. Unzip the DiningGuide2.zip file from the Developer Resources portal.

For example, unzip it to the /MyZipFiles directory.

2. At a command prompt, type: 

$ cd your-unzip-dir/DiningGuide2/db

$ sqlplus db-userid/db-password@db-servicename @rest_ora.sql

For example, 

$ cd /MyZipFiles/DiningGuide2/db

$ sqlplus scott/tiger@MyDB @rest_ora.sql

The two DROP statements will generate errors, but they are harmless.

Tutorial Database Table Descriptions

The script in Appendix B creates the database schemas shown in TABLE 1-1.

TABLE 1-1 DiningGuide Database Tables

Table Name

Columns

Primary Key

Other

Restaurant

restaurantName

yes

 

cuisine

 

 

neighborhood

 

 

address

 

 

phone

 

 

description

 

 

rating

 

 

CustomerReview

restaurantName

yes

Compound primary key with CustomerName; references Restaurant(restaurantName)

customerName

yes

 

review

 

 


The Restaurant table contains the records shown in TABLE 1-2.

TABLE 1-2 Restaurant Table Records

restaurant-Name

cuisine

neighborhood

address

phone

description

rating

French Lemon

Mediterranean

Rockridge

1200 College Avenue

510 888 8888

Very nice spot.

5

Bay Fox

Mediterranean

Piedmont

1200 Piedmont Avenue

510 888 8888

Excellent.

5


The CustomerReview table contains the records shown in TABLE 1-3.

TABLE 1-3 CustomerReview Table Records

restaurantName

customerName

comment

French Lemon

Fred

Nice flowers.

French Lemon

Ralph

Excellent Service


Now you are ready to start the tutorial application. Either continue to Chapter 2 to get an overview of the application you will build, or go directly to Chapter 3 and start building it.



  Sun ONE Studio 4, Enterprise Edition for Java Tutorial 816-7860-10 Table of ContentsPrevious ChapterNext ChapterBook Index


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