Introduction to the Custom Home Page example

The Custom Home Page example features a per-employee, self-customized home page with links to existing Web-based resources. Each employee may easily access current company information on a consistent basis via subwindows, and may add or delete links or subwindows as well.

The subwindows concept is patterned after the popular portal site layout. However, it is not implemented with standard portal technology so there is no requirement for a portal server. This example follows the Model 1 web application design pattern and uses JSPs, tag libraries, and Java beans along with the JSP include mechanism to simulate a portal look. In this example, subwindows feature company bulletins, news, stock quotes, and an employee directory. Key features include:

• Personalization based on cookies
• Subwindows
• Search capability
• Sorting
• Stock quote Web Service consumption
• Weather service Web service consumption

Hint: You can view the summary and outline information of pages for this example.

Contents

Database overview

The CustomHomePage example runs on a pre-configured, development-use only Cloudscape database when deploying to an Express Application Server. A GUI for Cloudscape is included in WebSphere Application Server -Express, providing easy access to the databases for the purpose of modifying the samples.

The Web Express examples only work with the pre-populated Cloudscape databases if you have installed the Express unit test environment (UTE) or the Application Server - Express production server. They will not work out-of-the-box with with the v4.0 UTE, or the v5.0 UTE that are available in WebSphere Studio Site Developer and WebSphere Studio Application Developer.

For Windows

When you are making a modification to a Web Express example requiring a Cloudscape database change, do one of the following to open the Cloudscape database GUI:

• Open a command prompt, and change to the <Expressinstall>/Express/bin directory. Type EXPcview.
• In Windows Explorer, navigate to <Expressinstall>/Express/bin. Double-click EXPcview.bat.

For Linux

For Linux, use the shell script EXPcview.sh provided in the directory /opt/IBM/WebSphere/Express/Express/bin.

From the Cloudscape GUI, open the Custom Home Page database :

1. Select File > Open >
2. Browse to <Expressinstall>/SiteDeveloper/runtimes/express_v5/bin/HomePgC5.
3. Double-click HomePgC5.

DB2

A development-use only version of DB2 is included in WebSphere Application Server - Express, and is available for install on the product CD. If you wish to deploy to a production database, you must purchase a licensed, production-use DB2 database. Please refer to the following section, Database access using DB2 , if you wish to run the application using a DB2 database.

The DB2 database serves as a testing environment if you wish to test your applications on DB2. All example applications in Application Server - Express can run on DB2, which may be installed from the product CD.

To use this application with databases other than Cloudscape, you need to specify the data source on your server configuration for your database. The JNDI name for the data source must match the JNDI name defined in misc/dbConn.jspinc file in the Web Content directory. This file has the logic to connect to the appropriate database for the application.

SQL statements

There are SQL examples for DB2 and Cloudscape in the setup/databases directory for each project. The SQL statements are database specific. For example, the createDB2.sql is for DB2 and createCloud.sql is for Cloudscape.

Since we provide a pre-populated database for Cloudscape, you do not need to use it for WebSphere Application - Server Express. Instead, the SQL statement for Cloudscape is provided in case your samples are located in other products, or if you delete the database, or if you want to modify the database. You can use this SQL as a model to create the appropriate database on your database system.

To learn how to create and execute SQL statements, from the menu bar click Help > Help Contents > Web developer information > Relational database tools > Tasks > Creating SQL statements, to access the on-line help.

Getting a SQL database driver

If you need a MS SQL database driver, go to the IBM WebSphere - Express Web site: Download the JDBC drivers for use with MS SQL Server

Database access using DB2

A development-use only version of DB2 is also included in this product, and is available for install on the product CD. The DB2 database serves as a testing environment if you wish to test your applications on DB2.

Only minor configurations are necessary to configure a DB2 database for this application. The following instructions assume you have already installed and configured DB2 on your local machine following the installation instructions provided by DB2. See other instructions for Database access for iSeries.

There are 5 steps required to configure your DB2 database:

Step 1: Create the HOMEPGD7 database

• From a Windows NT/2000 DOS prompt type 

  >db2cmd 
  >db2 create db HOMEPGD7

• From Linux

  >login as the db2 instance owner id
  >db2 create db HOMEPGD7

Step 2: Run the usejdbc2.bat (DB2 version 7.x and earlier)

• This file needs to be run because DB2 driver by default uses java 1.1 but we need to use java 1.2 for the database connectivity.
• Locate the file usejdbc2 script in the java12 folder of your DB2 installation.
• For example by default is located at  
  • Program Files\SQLLIB\ java12\usejdbc2.bat on Windows
  • $home/SQLLIB/java12/usejdbc2 on Linux
    • Note: Korn Shell required
• Run the script file.

Step 3: Populate the database

In the CustomHomePageExample project, an sql file is provided that will create and populate the DB2 database schema and tables for this example. Locate Web Content/setup/Database/createDB2.sql in the navigator view of this project.

To run the sql file on the database server:

• Right-click createDB2.sql.
• Select Run on Database Server from the context menu.
• Complete each page of the "Run Script" wizard, then click "Finish" to execute the db2 script.
  • Ensure you select all of the commands to be executed
  • The wizard will assist you in connecting to your DB2 database server. You will need to connect to the database with a userid that has the appropriate database privileges to create tables and insert data.

NOTE: For Linux, the db2java.zip file is located at $home/SQLLIB/java12

Your Database connection page should be completed similar to the following image. The database name should be HOMEPGD7.

Now that the DB2 database has been created, you need to configure the example application to connect to this database. To do this, simply create a new data source that references the DB2 database you just created.

Step 4: Rename existing data source that references the Cloudscape database

If using WebSphere Application Server - Express, there is a pre configured data source for the Cloudscape database. This data source references a JNDI name that our applications depend upon. In order to avoid code modifications in the example application, we want our new data source for DB2 to reference the same JNDI name. Therefore, complete this step to rename the JNDI name specified in the pre-configured data source before performing the next step, Step 5: Create a new data source for the database.

To work with datasources: Open the Server Perspective by clicking on the Open A Perspective button located above the shortcut bar on the left side of the workbench.

1. Select Other from the menu list.
2. On the Select Perspective dialog, click Server.
3. The server perspective is now open and the server perspective icon has been added to the shortcut bar.

   The Server Perspective contains the following helpful views:

   • Server Configuration view that helps you configure additional servers or modify the configuration of an existing server.
   • Servers View that allows you to start and stop servers. The Servers View also allows you to view console messages from a running server.
4. While working with the server configuration, it is a good idea to stop the server. If your server status is started, proceed with this step to to stop the server.
   • In the Servers View, Click on the Servers tab to ensure the servers page is displayed.

     You will see your WebSphere Express v5.0 Test Environment Server listed. Notice the server status column for our server. If the server is Started, We need to stop it.

   • Highlight the WebSphere Express v5.0 Test Environment Server and click on the Stop Server located in the Servers View. When the server stops, the server status will change to Stopped.
5. Double-click on WebSphere Express v5.0 server configuration in the Server Configuration view located in the lower left corner of the workbench. This displays the configuration file in the editor window. It is in this configuration file that the data source configuration tasks are done.
6. Click on the Data source tab, then scroll to the bottom half of the page and locate the server settings section. Here you will find the pre-configured JDBC Providers and Data sources.
7. Locate Custom Home Page datasource, then click Edit.
8. Complete the fields as follows to rename the datasource.
   • Name: Custom Home Page C5
   • JNDI name: jdbc/HomePgExC5
9. Click Finish
10. Save the configuration by clicking on the Save button located on the tool bar.

    Now we are ready to create a new datasource using the original name, Custom Home Page, to reference the DB2 database HOMEPGD7.

Step 5: Create a new data source for the database

We will continue working with the datasource page of the server configuration to define a JDBC Provider and a new datasource for DB2.

Define the JDBC Provider:

1. Locate the server settings section of the datasource page, then click on the Add button located next to the JDBC Provider List.
2. On the Create a JDBC Provider page, make the following selections:
   • Database Type: IBM DB2
   • JDBC provider type: DB2 Legacy CLI-based Type 2 JDBC Driver
   • Accept the defaults for all other fields.
3. Click Next
4. On the Enter the properties of the JDBC provider page:
   • Name: DB2 Provider
   • Accept the defaults for all other fields.
5. Click Finish

Define the Datasource:

1. Again, locate the server settings section of the datasource page, then click on the DB2 Legacy CLI-based Type 2 JDBC Driver in the JDBC Provider list to select it.
2. Click on the Add button located next to the Data source defined in the JDBC Provider selected above section.
3. On the Select a type of data source page, select Version 5.0 data source.
4. Click Next
5. On the Modify Data Source page, complete the fields as follows:
   • Name: Custom Home Page
   • JNDI name: jdbc/HomePgEx
6. Click Next
7. On the Modify Resource Properties page:
   • Click on the databaseName resource property
   • type HOMEPGD7 in the value field.
8. Click Finish
9. Save the configuration by clicking on the Save button located on the tool bar.

For additional help working with datasources, follow these steps to access the Help system.

From the Help menu bar, navigate to the following on-line help section for guidance through the steps of creating and working with data sources:

• Select Help from the menu bar.
• Select Help Contents
• Select Web Developer Information from the navigation section of the Help Dialog
• Select Application Testing and Publishing
• Select Tasks
• Select Managing Servers and server configurations
• Select Setting up a server configuration to test data sources

Login ID

Each time you login, your custom windows will open the way you left them. This application uses persistent cookies to store a small amount of information on your computer to verify that you are a valid user of this site.

On subsequent visits, the login routine will look for the cookie stored on your computer. Once the cookie is found and verified, the application will bypass the user login process and launch your personalized page content. Log-off will remove the cookie, and subsequent visits to the site will require login. Any personalized settings that were stored earlier are maintained.

Customizing subwindows

Customization is a key feature of this sample. Each subwindow is independent from others, and is created and saved locally according to your user ID. You can decide which subwindows you want to view at any given time by using the Personalize Page Layout link.

When you click Personalize Page Layout, you have a choice of 10 subwindows: welcome, sports, entertainment, news, stocks, weather, events, bulletins, favorites, and blank. Blank is a subwindow that does not display information, but serves instead as a design feature for constructing the layout of your page. For example, you could have columns on the page that are empty, or some much longer than others.

Editing subwindows

The Edit button allows you to configure or modify information specific to each subwindow. For example, the News subwindow offers you choices of headlines, World, US, and technology news. Any configuration will be preserved in the database and become part of your personalized content.

Employee search

The search function is used to search for employee records in the employee database, and will display detailed information about the employee found. If multiple records are found during the search, each employee is listed as an href link. When you registered to use this site, an employee record was created for you using the first and last name specified on the registration page.

The employee record includes the other information you provided about yourself (e.g. education level), and is saved and stored in the database. Therefore, the personal information available publicly is at your discretion, and you may view or update your personal information at any time.

When you attempt to update an employee record, a confirmation window opens where you must provide your userid and password. If the userid and password you enter matches the owner of the employee record, you will be presented with an employee record update page. Otherwise, the request will be denied.

Web services

The stock quote and weather subwindows are Web service clients. The client code was created very easily using the Web Services Client Creation Wizard in the WebSphere Studio tool. The personalization of Web services are determined by the Web service we connect to.

Cookies

This sample application requires that your browser be configured to accept "per-session" cookies. If you configure your browser to allow cookies to be stored on your computer, then you will not have to login for each visit, as the application will use the information stored in the cookie to automatically log you in.

Per-session cookies are not stored on your computer, but are stored in memory until your browser is closed. If your browser is configured so that cookies cannot be stored on your computer, this sample application will function normally and your personalized content will be maintained in our database. However, you will be required to login each time this application is run.

Running Custom Home Page

Follow these steps to run and test the Custom Home Page example in the WebSphere test environment.

1. From the workbench menu, select File > New > Example > Web.
2. Select Custom Home Page, then click Next. A window is displayed showing the default project name, the default Enterprise Application project name (EAR), and the default context root name. The project definition panel opens with the project name specified.
3. Type a new or existing EAR. If you wish to use an existing EAR, use the Browse button to locate it on your system. If you uncheck the default for project location, use the Browse button to specify a location for this project.
4. Click Finish to accept the default settings and load the example. The project name will appear in the J2EE Navigator view.
   
5. In the Navigator, right-click the project name CustomHomePageExample or the index.jsp file.
6. Select Run on server.
7. In the Server Selection dialog box:
   • Select Create a new server.
   • Expand WebSphere version 5.0.
   • Select Express Test Environment
   • Select Finish.
   • Select Yes to create a new server project. You will see the server starting in the Console view at the bottom of your screen.

If a server has not has not been defined, then WebSphere Studio does the following tasks for you:

• Creates a server project.
• Creates the server instance and the server configuration.
• Sets the server instance to use the server configuration.
• Adds your project to the server configuration.
• If the Automatically publish before starting the server check box on the Windows >Preferences > Server is selected, WebSphere Studio checks to see if your project and files on the server are synchronized. If they are not, the project and the files are automatically updated on the machine when the server is restarted.
• Starts the server instance. (This may take time to start depending on the server configuration settings.)
• Displays the example home page in the Web browser.

Limitations

Disclaimer:
The following [enclosed] code is sample code created by IBM
Corporation. This sample code is not part of any standard IBM product
and is provided to you solely for the purpose of assisting you in the
development of your applications. The code is provided 'AS IS',
without warranty or condition of any kind.  IBM shall not be liable for any damages
arising out of your use of the sample code, even if IBM has been
advised of the possibility of such damages.