iPlanet Application Builder Beta 6.0 Tutorial

This tutorial introduces features of the iPlanet Application Builder by walking you through the creation of a simple application. This sample application enables users to purchase and sell compact discs.

This tutorial assumes that you have successfully installed:

Additionally, your development machine must have an HTTP server installed and running. Also, the tutorial database should already be set up by running the tutorial DB scripts. For additional information, such as which drivers to use, how to create ODBC & JDBC data sources, and how to register the tutorial files, see the iPlanet Application Builder 6.0 installation instructions.

This tutorial includes the following tasks:

You can use Symantec Visual Cafe Pro to edit, compile, and debug your Java servlets. For more information, see Using iPlanet Application Builder with Symantec Visual Café.

Task 1: Starting a New Project

This part of the tutorial describes launching iPlanet Application Builder, creating a new project, creating a data model to link the application with a database, and saving the project files to disk.

To create a new project, perform the following tasks:

Launch iPlanet Application Builder

Launch iPlanet Application Builder from the Windows Start Menu by choosing the iPlanet Application Builder 6.0 menu item. iPlanet Application Builder starts the New Project wizard.

Create a New Project

Name the new project cdx1 in directory "<iasRoot>\cdx1".

Note that the sample tutorial created uses the directory "cdx", you cannot copy pieces of the cdx tutorial into your cdx1 project without modifications, such as query (.gxq) paths, JavaServer Page (.jsp) paths, and class definitions.

  1. Click Next to create each of the project starter files.

    2. In this tutorial, you need not create an index.html page, because you will copy an existing file when you come to the section on Adding Any Pre-Existing HTML Files. The purpose of this dialog box is to allow you some flexibility in which files are created initially. For example, if you wanted to keep an existing index.html file in your web server's doc directory, you would uncheck this file; otherwise, your file would be overwritten by the empty index.html file created by this wizard.

  2. Click Next. The New Project wizard displays the files it will create.

  3. Click Finish.

    4. The iPlanet Application Builder creates the following files:

    File Type File Names
    Project cdx1.xml
    HTML start page index.html
    JavaScript source code validate.js

You only use the project file to open an existing project. You should not modify the project file; iPlanet Application Builder handles all changes to the project file for you.

Create a Data Model

  1. Click the Yes, Add a Data Model button in the Create Data Model dialog.

  2. Double-click the Data Model icon under New file(s).

  3. Specify a name and directory for your data model and click Continue.

  4. Specify "Create a new connection" and click OK.

  5. Specify the following values for the listed fields:

    Field Value
    Driver The name of your driver, such as ODBC
    Data Sources cdx
    User name The data source's user name, such as netscape
    Password The associated password, such as netscape

    Note that if you select another driver, such as select ORACLE_OCIfor the table, iPlanet Application Builder displays an additional field, Database; the proper value you should supply is nsample.

  6. Click OK and the Add Tables dialog appears.
  7. Add cdxinventory and cdxuser to the Data Model by selecting them from the available tables and clicking the right-arrow button to move them to the "Tables in data model" pane.

  8. Click OK to finish.
  9. Click OK to add relationships.

Creating Aliases

You will see each table with its list of columns in the Data Model editor.

You are then ready to establish relationships between these tables. In the cdx application, three columns of the cdxinventory table are related to the same column (id) in the cdxuser table.

To represent this in iPlanet Application Builder, you create two aliases of the cdxinventory table.

  1. Right-click the cdxinventory table and select Insert Table Alias from the pop-up menu.

    iPlanet Application Builder displays the table cdxinventory_2.

  2. Repeat this step to create another table (cdxinventory_3).

Joining Tables

To create the joins, first drag the table boxes so they do not overlap, then perform the following steps:

  1. Click the cdxuser.id field and drag it to cdxinventory.owner.

    This step creates a one-to-many join from cdxuser.id to cdxinventory.owner.

  2. Drag the cdxuser.id field to cdxinventory_2.buyer.
  3. Drag the cdxuser.id field to cdxinventory_3.xlock.

    The data model now allows one user to own many titles, purchase many titles, and have many purchases pending.

  4. Click the close box [x] to close the data model editor.
  5. Save the cdx1.kdm file when prompted.

Alternatively, you can access the existing data model. To specify an existing data model, perform the following steps:

  1. Yes, Add a Data Model.
  2. Click the Existing tab.
  3. Select cdx\cdx.kdm.
  4. Double click cdx.kdm in the project tree to view the data model.

Clean Up Project File

Since the tutorial already includes a file named index.html, you need to remove the file of the same name iPlanet Application Builder automatically creates for you.

  1. Right-click index.html in the iPlanet Application Builder Project tree, and select "Remove".
  2. Check "Also remove index.html from the file system" so that the actual file is deleted.
  3. Click Yes to remove the file from the project and from disk.

Add Any Pre-Existing HTML Files

Now, it's time to add any pre-existing HTML files, or images to the project. For this tutorial, we will start with the files installed in <iasroot>/APPS/GXAPP. To add these pre-existing HTML files to the tutorial application, perform the following steps:

  1. Using Windows Explorer, copy the files and sub-folders in <IABroot>\tutorial\starters to the web server's project directory under <WebRoot>\docs\cdx1.
  2. Using iPlanet Application Builder, select Project - Add File(s) then select the Existing tab to add existing files to the project.
  3. Select the Existing tab and, Under Web Server root\cdx1, select the following files:

  4. Click Add.

    The iPlanet Application Builder adds the files to the project.

    5. You must copy the logo image file to your project directory as well, so that .jsp templates will properly display the logo.

    The cdx\templates subdirectory includes a Macromedia Dreamweaver template that can be applied within Dreamweaver to the pages generated by iPlanet Application Builder. You do not need to add this file to your iPlanet Application Builder project.

Save Your Work

Now is a good time to save your work. Click the double-disk toolbar icon to save all project files. If the Save All option is not enabled, then Click Save.

Task 2: Creating Static Links

iPlanet Application Builder provides easy-to-use code generation wizards to create sets of HTML and JavaServer pages, servlets, and database queries. To use these wizards most effectively, it is best to think of your application in terms of activities, and from there, map each activity to the use of one or more Wizards.

This tutorial illustrates this process as you first create and link in the activities for the Main Menu page and the User Menu page. The primary difference between these pages, is that the User Menu page presents some activities that require a user to have previously logged in.

Create and/or Link the Destinations for the Main Menu (index.html)

  1. From the Project tree, double-click the HTML Page "index.html" to open it in iPlanet Application Builder's integrated HTML editor.

    2. You may use an HTML editor of your choice by specifying a third-party HTML editor in the Tools -> Development Options dialog. However, to create or modify links, especially those that call servlets, it is much easier to use the iPlanet Application Builder "built-in" HTML editor.

  2. Perform the following steps to convert the static text "Instructions" to a hyperlink to the instructions.html page:

    1. Select the text of the first bullet: Instructions.
    2. Click the Create Link icon at the far right of the toolbar. If the Create Link icon is not present, then select View -> Toolbars -> Standard.

    Note that you can also right-click the highlighted text and choose "Create Link" from the pop-up menu to create the link.

    The text becomes a link.

  3. In the Properties inspector, click the Destination URL property editor button.

  4. In the HTML File drop-down, select the file Instructions.html.
  5. Click OK to complete the link.

Task 3: Creating an Input Form

To create the "New Account" data entry form, perform the following tasks:

For the new account activity, use the Input Wizard to generate a data entry form and a servlet to process the form data.

  1. Select File -> New -> Input.
  2. Type "CreateAccount" for Name.

  3. Store to a database table.

  4. Select the project data model (cdx1.kdm).

  5. Select Use the existing connection and verify that the name is "cdx".

  6. Select the table cdxuser to specify name, email, phone, and password fields for stored input data (uncheck "id" so it does not appear on the form).

  7. Click Next.
  8. Click Finish.

The iPlanet Application Builder generates the following project files, which are identified in the project window:

Edit the JavaServer Page

Next, edit the CalledCreateAccount.jsp response page to add an identifying message and a link to index.html. To create link:

  1. Type in the text "Main Menu" and select the text.
  2. Click the Create Link icon at the far right of the toolbar.

    3. If the Create Link icon is not present, then select View -> Toolbars -> Standard. Note that you can also right-click the highlighted text and choose "Create Link" from the pop-up menu to create the link.

    The text becomes a link.

  3. In the Properties inspector, click the Destination URL property editor button.

  4. In the HTML File drop-down, select the file "index.html".

  5. Click OK to complete the link.
  6. Close and save the file.

Edit the Query File

  1. Double-click CalledCreateAccount.gxq in Project tree to open the query file.
  2. Double-click the CalledCreateAccount_Insert query.

    3. The iPlanet Application Builder displays the InsertQuery Properties Dialog.

  3. Click the Fields tab, and set the Value for the "id" column to be :id.

    4. This action tells iPlanet Application Builder to bind the id column to the value of the 'id' valList parameter.

  4. Click Finish.
  5. Close and save the file.

Edit the Servlet File

  1. Add the code to set the "id" parameter in the servlet, CalledCreateAccount.java.
  2. Double-click the CalledCreateAccount.java file to open it.
  3. Find the defaultAction() method and before the insertStmt.executeUpdate() statement, add the following code to the servlet file:

    4. 	String sname = (String)req.getParameter("NAME");
	int code = sname.hashCode();
	insertStmt.setInt(((Integer)params.get("ID")).intValue(), code);

  4. In order to display the "CalledCreateEntry.jsp" on successful creation of the new account, enter the following code after the statement "insertStmt.executeUpdate( );": 

    	String addJsp = "/CalledCreateAccount.jsp"; 
	RequestDispatcher dispatcher = getServletContext().getRequestDispatcher(addJsp);
	res.setContentType("text/html");
	dispatcher.forward(req, res);

  5. Delete or comment-out the line "displayMessage( req, res, "Insert Success");"
  6. Save all modified files.
  7. Compile (and test, if desired).

Add the Link in index.html

  1. Open the index.html file and select the "Create New Account" text.
  2. Click the link icon.
  3. Select the destination URL Property Editor.

  4. Select the html page CreateAccount.html.
  5. Click OK.
  6. Close and save the file.

Task 4: Creating a Login Sequence

To create the login page and associated servlet, perform the following tasks:

Create the Login Page and Servlet to Process Login Data

  1. Select File -> New -> Login.
  2. Type "Login" for Name.

  3. The Username and Password parameters are already specified; select Next.

  4. Check Authenticate with a Database Table.

  5. Select the project's data model (cdx1.kdm).
  6. Select Use the existing connection and verify that the name is "cdx".
  7. Select Table "cdxuser" and bind Username and Password to name and pswd columns, respectively; click Next.

  8. Make sure "id" and "name" are checked to save to session.

  9. Click Next.
  10. Click Finish.

    11. The iPlanet Application Builder creates the following files: 

    	Login.html
	CalledLogin.java
	CalledLogin.jsp
	CalledLogin.gxq

Edit the CalledLogin.jsp file

  1. Open CalledLogin.jsp.
  2. Select the Layout view by clicking on the Layout tab at the bottom of the editor frame.
  3. Type in "UserMenu" below the "Login Successful" text.
  4. Highlight and link the "UserMenu" text to index.html.
  5. Type in "Try Again" below the "Login Failed" text.
  6. Highlight and link the "Try Again" text to Login.html.

Link the Login Page to the Main Menu

  1. Open index.html.
  2. Select Log In and specify it as a link.
  3. Click the link icon.
  4. Select the destination URL Property Editor.

  5. Select the html page Login.html.
  6. Close and save the file.

Task 5: Creating a Database Form

  1. Create the List Users destination.
  2. Select File -> New -> Database Forms.
  3. Type "ListUsers" for Name.

  4. Click Next and specify "Use data model."

  5. Click Next and specify cdx1.kdm for your data model.
  6. Select Single page, Multiple record master.

  7. Specify the project's data model (cdx1.kdm).
  8. Select Use the existing connection and verify that the name is "cdx".
  9. Select the cdxuser table and the name, email, and phone fields.

  10. Select display all records at once.

  11. Select cdxuser.name to sort.

  12. Click Next.
  13. Click Finish.

    14. The iPlanet Application Builder creates the following files: 

    	ListUsers.gxq
	ListUsers.java
	ListUsers.jsp

  14. Open ListUsers.jsp and add a link back to the main menu.
  15. Type the text "Main Menu" and select it.
  16. Click the Link icon.
  17. Set destination URL property to index.html.

    18. You can also drag index.html to the page, and change text to "Main Menu".

  18. Open index.html and convert the text "List Users" to a link.
  19. Select the text, then click the Create Link icon at the far right of the toolbar.

    20. If the Create Link icon is not present, then select View -> Toolbars -> Standard. Edit Destination URL in Properties.

  20. Select the ListUsers servlet from the Servlet drop-down and click OK.

    21. You can also right-click the highlighted text and choose Create Link from the pop-up menu to create the link.

Task 6: Creating Browse Activities

To create the browse activities, perform the following tasks:

Create Browse Titles By Artist Activity

  1. Select File -> New -> Database Forms.
  2. Type "BrowseArtist" for Name; then click Next.
  3. Choose "Use a data model;" then click Next.
  4. Specify the project's data model (cdx1.kdm); then click Next.
  5. Select Single page, Multiple Record Master; then click Next.
  6. Select Use the existing connection and verify that the name is cdx; then click next.
  7. Select table: cdxinventory.
  8. Select table fields: id, artist, title, and price.
  9. Click Next.
  10. Select Browse 20 records at a time; then click Next.

  11. Select Sort by cdxinventory.artist; then click Next.
  12. Click Next.
  13. Click Finish.

    14. The iPlanet Application Builder creates the following files: 

    	BrowseArtist.gxq
	BrowseArtist.java
	BrowseArtist.jsp

Adding Select Conditions

Now must edit the query to only display available CDs. In the data model, CDs that have already been purchased or are pending purchase will be marked with the buyer's id in the buyer or xlock field.

  1. Open the query, BrowseArtist.gxq.
  2. Double-click the BrowseArtist.
  3. Select the Conditionals tab on the query properties dialog.
  4. Click Add Condition.
  5. Select the cdxinventory table, buyer field, and = operator, and enter 0 as the value.

  6. Click OK, then repeat steps 4 and 5 for the xlock field.

    7. The Conditions panel of the Query Designer displays the new query conditions.

  7. Click Finish.

Converting a Column to Links

Convert the id column to the Buy! link in the BrowseArtist.jsp file:

  1. Open BrowseArtist.jsp.
  2. Click the BrowseArtist.id data-bound label.
  3. Press the Delete key to delete it.
  4. Drag the Data-Bound HTML hyperlink from the Palette to the cell, creating a hyperlink
  5. Select the Hyperlink and change the text to Buy!

    6. You can also right-click the highlighted text and choose "Create Link" from the pop-up menu to create the link.

    After you create the Buy! activity (see Task 8: Using Queries and Result Sets), you will use the Destination URL property editor to complete the data-bound link.

Create Browse Titles By Price Activity

  1. Select File -> New -> Database Forms.
  2. Type "BrowsePrice" for Name; then click Next.
  3. Click Use a data model; then click Next.
  4. Specify the project's data model (cdx1.kdm); then click Next.
  5. Select Single page, Multiple Record Master; then click Next.
  6. Specify the project's data model (cdx1.kdm); then click Next.
  7. Select Use the existing connection and verify that the name is cdx; then click Next.
  8. Select table: cdxinventory; then click Next.
  9. Select table fields: id, artist, title, and price; then click Next.
  10. Choose Browse 20 records at a time; then Click Next.
  11. Select Sort by cdxinventory.price; then click Next.
  12. Click Next.
  13. Click Finish.

The iPlanet Application Builder creates the following files: 

	BrowsePrice.gxq
	BrowsePrice.java
	BrowsePrice.jsp

Adding Select Conditions

  1. Open the query, BrowsePrice.gxq; double-click the BrowsePrice select query; and select the Conditionals tab on the query properties dialog.
  2. Click Add Condition.
  3. Select the cdxinventory table, buyer field, and = operator, and enter 0 as the value.
  4. Click OK, then repeat steps 2 and 3 for the xlock field. The Conditions panel of the Query Designer displays the new query conditions; then click Finish.

Converting Columns to Links

  1. Convert the id column to the Buy! link in the BrowserPrice.jsp file.
  2. Open the BrowsePrice.jsp file.
  3. Select BrowsePrice.id data-bound label.
  4. Press the Delete key to delete it.
  5. Drag the Data-Bound HTML hyperlink from the Palette to the cell, creating a hyperlink
  6. Select the Hyperlink and change the text to Buy!

    7. If the Create Link icon is not present, then select View -> Toolbars -> Standard. Note that you can also right-click the highlighted text and choose "Create Link" from the pop-up menu to create the link.

    After you create the Buy! activity (see Task 8: Using Queries and Result Sets), you will use the Destination URL property editor to complete the data-bound link.

Connect Main Menu Links to the Browse Activities

To connect the Main menu links to the Browse By Artist & Browse by Price activities, perform the following steps:

  1. Open UserMenu.html.
  2. Select the text to become a link, either Browse Available Titles [Sorted by Price] or Browse Available Titles [Sorted by Artist].
  3. Click the Create Link icon at the far right of the toolbar.

    4. If the Create Link icon is not present, then select View -> Toolbars -> Standard. Note that you can also right-click the highlighted text and choose "Create Link" from the pop-up menu to create the link.

  4. Bring up Destination URL Property Editor from Properties.
  5. Select BrowseArtist or BrowsePrice servlet as necessary.
  6. Click OK.
  7. Repeat steps 2-6 for the other link.

Task 7: Creating a Search Activity

Now you are ready to create the User Menu activities. You will also create the "Buy CD" activity and connect it to the "Browse CD Buy!" links. To perform this task, you need to create the CD Browser master/detail/search set, which is designed for browsing after login with view of owner detail for purchase.

  1. Select File -> New -> Database Forms.
  2. Type CDBrowser for Name; click Next.

  3. Select the option "Use a data model" and click Next.
  4. Specify the project's data model.
  5. Select cdx1.kdm and click Next.
  6. Select Multiple record master and single record detail.
  7. Select the "Create a search page" checkbox.

  8. Click Next.
  9. Select "Use an existing connection" and verify that the name is cdx; then click Next.
  10. Select fields to display in master in the following order:

    11. 	cdxinventory.id
	artist
	title
	price
	cdxuser.name
	cdxinventory.notes

    The id will be converted to the Buy! link later.

  11. Select browse 20 records at a time; then click Next.
  12. Select sorting by cdxinventory.artist and cdxinventory.title; then click Next.
  13. Select the fields to display in the detail; then click Next.
  14. Choose cdxuser: name, email, and phone.

  15. Leave detail fields display-only; then click Next.

  16. Select name for Display Field; this is the drill-down field.
  17. Specify join as (Master) cdxinventory.owner= (Detail) cdxuser.id.

  18. Click Next.
  19. Specify columns for search page: title and artist; then click Next.

  20. Click Next.
  21. Click Finish.

    22. The iPlanet Application Builder creates the following files: 

    	CDBrowser_Search.html
	CDBrowser.gxq
	CDBrowser.java
	CDBrowser.jsp
	CDBrowserDetail.java
	CDBrowserDetail.jsp

Modifying a SQL Query

Next, you need to edit the generated query, CDBrowser.gxq to ensure that only CDs that are available for purchase are displayed.

  1. Open the CDBrowser.gxq query file.

  2. Double-click the CDBrowser select query.

    3. This time, the Conditionals panel is disabled because the query includes the variable ":Whereclause" and is considered a custom query.

  3. Select the SQL panel where you can enter the additional where conditions directly into the SQL SELECT statement.

  4. Edit the statement to include the conditions:

    5. 	cdxuser.id = cdxinventory.owner and
	cdxinventory.xlock = 0 and cdxinventory.buyer = 0
	and :WhereClause

  5. Click Finish.
  6. Close and save the file.

Deleting From a JavaServer Page

Edit the CDBrowser.jsp JavaServer page as follows:

  1. Select "id" text in column header.
  2. Right click and choose Table options.
  3. Select Delete column to delete "id" column.
  4. At the bottom of the page enter text "Usermenu".
  5. Select the text "UserMenu".
  6. Click the Create Link icon at the far right of the toolbar.
  7. Set destination URL property to Usermenu.html.
  8. Close and save the file.

Edit the CDBrowserDetail.jsp JavaServer page as follows:

  1. At the bottom of the page, enter the text "Usermenu."
  2. Select the text "UserMenu."
  3. Click the Create Link icon at the far right of the toolbar.
  4. Set the destination URL property to Usermenu.html.
  5. Close and save the file.

Add the Link in Usermenu.html

  1. Open UserMenu.html.
  2. Select the text to become a link "Search for CDs".
  3. Click the Create Link icon at the far right of the toolbar.

    4. If the Create Link icon is not present, select View -> Toolbars -> Standard. You can also right-click the highlighted text and choose "Create Link" from the pop-up menu to create the link.

  4. Bring up Destination URL Property Editor from Properties.
  5. Select CDBrowse_search.html.

Task 8: Using Queries and Result Sets

To create the Buy! browse activities, perform the following tasks:

Create SELECT Query

To create a SELECT query to specify purchase item, perform the following steps:

  1. Select File -> New -> Query.
  2. Type cdrecord for Name.

  3. Specify the project's data model (cdx1.kdm).
  4. Specify Select for the query type; then press Continue.

  5. Using the Select Query Properties dialog box, perform the following actions:

    • Under the Name Tab, specify cdrecord; then click Next.

    • Under the Fields Tab, specify All from cdxinventory, then click Next.

    • Under the Conditionals Tab, select Add Condition and set cdxinventory.id to :id.

    • Click OK to continue.

    • Click Finish.

      • The iPlanet Application Builder creates the cdrecord.gxq SELECT query.

Create UPDATE Query

To create an UPDATE query for locking the purchase, perform the following steps:

  1. Select File -> New -> Query.
  2. Type updatelock for Name; then click Next.
  3. Specify the project's data model (cdx1.kdm); then click Next.
  4. Select Update for the query type; then click Continue.
  5. Using the UpdateQuery Properties dialog, perform the following steps:

Create New Database Form

  1. Select File -> New -> Database Forms.
  2. Type BuyCD for Name; then click Next.
  3. Specify "Use an existing query file."
  4. Select cdrecord.gxq query; then click Next.

  5. Select "Multiple Records" to get a tabular layout; then click Next.

  6. Specify "Use an existing connection" and verify that it is cdx; then click Next.
  7. Click Next.

    8. Do not check the "Create input page" checkbox.

  8. Click Next.
  9. Click Finish.

    10. The iPlanet Application Builder creates the following files: 

    	BuyCD.java
	BuyCD.jsp

Edit BuyCD JavaServer Page

  1. Open the BuyCD.jsp file.
  2. From the Palette Form tab, drag a push button component below the table.

  3. Use the Properties editor to change the Label property to Buy It!.

  4. Drag the BuyCD.id column to the form.
  5. Right click on the field and choose "Change Type To Data-Bound Text Field."

  6. Reselect the BuyCD.id text field.
  7. In the Properties window, change the Type of field attribute to HIDDEN.
  8. Select the owner, buyer, xlock, and genre column headings.
  9. Press the Delete key to delete them.
  10. Select the empty id column and delete it.

    11. You may need to change to Outline view first.

  11. Repeat the above steps to delete the owner, buyer, xlock, and genre columns.

    12. After the BuyCD pages is presented and the user confirms the purchase, the BuyCommit servlet updates the cdxinventory table and sends mail to the seller.

Create Transaction Confirmation Page

Use the iPlanet Application Builder Results wizard to get started on the BuyCommit servlet and transaction confirmation page.

To create the transaction confirmation page, perform the following tasks:

Using the Results Wizard

  1. Select File -> New -> Results.
  2. Type BuyCommit for Name.

  3. Enter the input parameter id and check Required.

  4. Click Next.
  5. Click Finish.

    6. The iPlanet Application Builder creates the following files: 

    	BuyCommit.java
	BuyCommit.jsp

  6. Copy the implementation inside the BuyCommit class from <IASRoot>\Apps\cdx\BuyCommit.java to your BuyCommit.java file; do not change import, or class declarations.
  7. Change the package name at the beginning of BuyCommit.java to cdx1.
  8. Change the directories for cdrecord.gxq, updatelock.gxq, and CDBrowser.gxq from cdx to cdx1:

    9. 	cdx1/cdrecord.gxq
	cdx1/updatelock.gxq
	cdx1/CDBrowser.gxq

Link BuyCommit to the BuyCD Confirmation Page

Next, you need to link the BuyCommit servlet to the BuyCD confirmation page.

  1. Open the BuyCD.jsp file.
  2. Select Form: Form1.
  3. Open Action property editor.
  4. Select Action.
  5. Click within the rightmost part of a blank field to activate the custom property button .
  6. Click the property button .
  7. Select BuyCommit from the servlet drop-down list.
  8. Open the <IASRoot>\Apps\cdx\BuyCD.jsp file.
  9. Copy the following line.

    <rdbm:param name="ID" type="String" bindOnLoad="true">
    <attr:getParametername="ID">1=1</attr:getParameter></rdbm:param>

  10. Open the BuyCD.jsp in source view and replace the following line:

    11. <rdbm:param name="WhereClause" type="String" bindOnLoad="true">
    <attr:getAttribute name="whereClause">1=1</attr:getAttribute></rdbm:param>

  11. In BuyCD.jsp search for the following code:

    12. <INPUT TYPE="HIDDEN" NAME="ID" VALUE="<rdbm:field query="BuyCD" name="ID" urlEncode="true" />" FILEREFS="validate.js" EBPROPS="{ dataField = ID;dataSet = BuyCD;}" EBCLASS="netscape.blizzard.components.TextField">

  12. Delete the above code.
  13. Now, insert the following code:

    <rdbm:goRecord query="BuyCD" start="1" execute="true"/>
    <INPUT TYPE="HIDDEN" NAME="ID" VALUE="<rdbm:field query="BuyCD" name="ID" />">

    The Buy! Activity is now complete. Next, return to Browse pages to connect the "Buy!" JSP to the BuyCD servlet.

Link Buy! to BuyCD Servlet

  1. Open the BrowseArtist.jsp file.
  2. Select Buy! to edit the Destination URL property.
  3. Select the BuyCD servlet.
  4. Click the Add button, Click in name field, enter ID and press Enter.
  5. Select Data Bind-Value.
  6. In the cell editor dialog box, select BrowseArtist in the ResultSet drop-down list and select id in the DataField drop-down list; click Add.

    7. The iPlanet Application Builder displays the data-binding expression.

  7. Click OK in the Cell editor.
  8. Click OK in the Edit property dialog box.
  9. Repeat steps 1-7 for BrowsePrice.jsp.
  10. Select BrowsePrice in step 5.

Task 9: Inserting Form Data Into a Database

To add the "CD for Sale/Exchange" buyer destination functions, perform the following steps:
  1. Select File -> New -> Input.
  2. Type "CreateEntry" for Name.
  3. Select "Store to a database table."
  4. Specify the project's data model (cdx1.kdm).
  5. Use an existing connection (cdx).
  6. Select table cdxinventory.
  7. Deselect all fields except those that you want to appear on the form: price, title, artist, and notes, to appear on the form.

  8. Click Next.
  9. Click Finish.

    10. The iPlanet Application Builder creates the following files: 

    	CreateEntry.html
	CalledCreateEntry.gxq
	CalledCreateEntry.java
	CalledCreateEntry.jsp

Editing Called Code

  1. Open CalledCreateEntry.java

    2. Before the statement, insertStmt.executeUpdate( ); in defaultAction method, add the following code: 

    	String sname = (String)req.getParameter("TITLE");
	int code = sname.hashCode();
	insertStmt.setInt(((Integer)params.get("ID")).intValue(), code);
	HttpSession session=req.getSession(true);
	String curUser = (String)session.getAttribute("NAME");
	String ids = ((String)session.getAttribute("ID")).trim();
	int idFromSession = new Integer(ids).intvalue();
	insertStmt.setInt(((Integer)params.get("OWNER")).intValue(),idFromSession);

    To display the corresponding jsp, add the following code after the insertStmt.executeUpdate(); in defaultAction method: 

    	String addJsp = "/CalledCreateEntry.jsp";
	RequestDispatcher dispatcher = getServletContext().getRequestDispatcher(addJsp);
	res.setContentType("text/html");
	dispatcher.forward(req, res);

    If you do not add the above code, the dynamically generated page will display.

  2. Comment out or delete the line, displayMessage( req, res, "Insert Success");

Creating a Custom Query

To edit CalledCreateEntry.gxq to create the CalledCreateEntry_Count custom query perform the following steps:

  1. Open the CalledCreateEntry.gxq file.
  2. Right-click the view and select the Insert Select Query pop-up menu item.
  3. In the SelectQuery Properties dialog, name the query "CalledCreateEntry_Count".

  4. Select the SQL tab and edit the SQL statement to read:

    5. 	/* CalledCreateEntry_Count:  */
	query CalledCreateEntry_Count using (ODBC, cdx, iPlanet) is 
	select count(*) from cdxinventory

  5. Click Finish.

    6. The query is now a custom query.

    A warning message displays indicating that this is a custom query.

Editing Insert Query Properties

You now need to add the id, buyer, and xlock fields to the query; setting id to the new record identifier and initializing the buyer and xlock fields to 0.

  1. With the CalledCreateEntry.gxq file still open in the Query Editor view, double-click the CalledCreateEntry_Insert icon to display the InsertQuery Properties dialog box.
  2. Select to the SQL tab and edit the SQL statement to contain the following code:

    3. 	/* CalledCreateEntry_Insert:  */
	query CalledCreateEntry_Insert using (ODBC, cdx, iPlanet) is 
	insert into cdxinventory 
		(id, owner, buyer, xlock, price, title, artist, notes)
	values (:id, :owner, 0, 0, :price, :title, :artist, :notes)

  3. Click Finish.

    4. The query is now a custom query.

Linking to an HTML File

To link the "Add CD for Sale" item to the Create Entry page:

  1. Open the UserMenu.html file.
  2. Select the text "Add CD for Sale/Exchange".
  3. Click the Create Link icon, or right-click the text selection and choose Create Link from the pop-up menu.
  4. From the Properties editor, open the Destination URL property editor.
  5. Select CreateEntry.html from the HTML File drop-down list.
  6. Click OK to complete the link.

Task 10: Using Queries With Database Forms

Since the queries for this report are more complicated than for previous reports, this tutorial first uses the query editor to create the queries. Then, we use the Database Forms wizard to use the generated queries. Recall that in the data model, the alias cdxinventory_3 is joined by xlock to user. For the required SELECT query, you need to take any inventory fields from this alias because the xlock field identifies CDs with pending transactions.

To create the "view pending transactions" activity, perform the following tasks:

Creating SELECT Queries

First you must create a query for the report itself.

  1. Select File -> New -> Query.
  2. Type PendingSeller for Name.
  3. Specify the project's data model (cdx1.kdm).
  4. Specify Select for Type.
  5. Click Continue.

Selecting Query Properties

Using the SelectQuery Properties dialog box, perform the following steps:

  1. Type PendingSeller for Name.

  2. Select the title, price, and artist fields from the cdxinventory_3 table. Choose the cdxinventory_3 table to display related information about the prospective buyer.
  3. Select name from the cdxuser table.
  4. Select xlock and id from the cdxinventory_3 table.

Specifying Select Conditions

To add conditions for the select query:

  1. Click Add Condition to add the following conditions:

    2. 	cdxinventory_3.xlock <> 0

  2. Click the Join tab.
  3. Remove the join from cdxuser.id to cdxinventory_3.xlock.
  4. Click SQL tab and add the following condition in the where clause:

    5. 	cdxuser.id = cdxinventory_3.owner

    The SQL code appears as follows: 

    	query PendingSeller using (oracle_oci, cdx, nsample, netscape) is
	select cdxinventory_3.title as title3 ,
		cdxinventory_3.price as price3 ,
		cdxinventory_3.artist as artist3 ,
		cdxuser.name as name ,
		cdxinventory_3.xlock as xlock3 ,
		cdxinventory_3.id as id4
	from cdxinventory cdxinventory_3,
		cdxuser
	where (cdxinventory_3.xlock <> 0)
		and cdxuser.id = cdxinventory_3.owner

    The iPlanet Application Builder creates the PendingSeller.gxq query file.

Creating UPDATE Queries

Next, you need to create an UPDATE query to accept the transaction and sell the CD.

  1. With the PendingSeller query view still active, select Insert -> Update Query from the menu or by right-clicking in the query window.
  2. Type AcceptSale for Name.
  3. From the Fields tab, using the cdxinventory table, set fields buyer and xlock to:

    4. 	buyer = :buyer
	xlock = 0

  4. From the Conditionals tab, click Add Condition to add the following condition:

    5. 	cdxinventory.id = :id

  5. Click OK.
  6. Click Finish.

    7. The iPlanet Application Builder adds the query to the query file.

    Next, you need another UPDATE query to cancel a sale.

  7. With the PendingSeller query view still active, select Insert -> Update Query from the menu or by right clicking in the query window.
  8. Type CancelSale for Name.
  9. From the Fields tab, using the cdxinventory table, set field xlock to:

    10. 	xlock = 0

  10. From the Conditionals tab, click Add Condition to add the following condition:

    11. 	cdxinventory.id = :id

  11. Click Finish.

    12. The iPlanet Application Builder adds the query to the query file.

Build Pending Sales Report

Now you are ready to build the pending sales report.

  1. Select File -> New -> Database Forms.
  2. Type PendingSeller for Name then click Next.
  3. Specify the existing query file: PendingSeller.gxq then click Next.
  4. Specify Parent query: PendingSeller then click Next.
  5. Specify Multiple records then click Next.
  6. Choose "Use an existing connection" and verify that it is cdx then click Next.
  7. Do not check "Create input page."
  8. Click Next.
  9. Click Finish.

    10. The iPlanet Application Builder creates the following files: 

    	PendingSeller.java
	PendingSeller.jsp

Converting Fields to Links

You need to convert the id and xlock fields in the report to "Sold" and "Cancel" links, which enable the user to accept or cancel the sale:

  1. Open the PendingSeller.jsp file.
  2. Edit the column headers for the two right-most columns by replacing the field text "id4" with "Accept" and "xlock3" with "Cancel".
  3. Select the PendingSeller.id4 data-bound label and delete it.
  4. Type in the text "Accept" and make it a link.
  5. Select the PendingSeller.xlock3 data-bound label and delete it.
  6. Type in the text "Cancel" and make it a link.

Create AcceptSale Servlet

Before you can fill in the Destination URL properties for the two prior management links, you need to create two servlets, one that accepts the transaction, and one that cancels it. For such servlets that return simple confirmation pages, you can use the iPlanet Application Builder Results wizard.

  1. Select File -> New -> Results.
  2. Type AcceptSale for Name.
  3. To execute the AcceptSale query, you need theid and buyer inputs, so specify these parameters as required inputs.

  4. Click Next.
  5. Click Finish.

    6. The iPlanet Application Builder creates the following files: 

    	AcceptSale.java
	AcceptSale.jsp

Edit Servlet to Load and Execute Update Query AcceptSale

Next, you need to enter the code necessary to load and execute the associated query from the query file. You will find this code in the completed file installed in <IASRoot>\Apps\cdx\AcceptSale.java.

This code is similar to the Insert or Update code produced for a data-entry form by the Database Forms Wizard of the Input Wizard.

  1. Copy the implementation inside the AcceptSale class from <IASRoot>\Apps\cdx\AcceptSale.java to your AcceptSale.java file; do not change import, or class declarations.
  2. Change the package name to cdx1.
  3. In AcceptSale.java, change the directories for PendingSeller.gxq  from cdx to cdx1:

    4. 	cdx1/PendingSeller.gxq

Create CancelSale Servlet

To create the CancelSale servlet, use the Results wizard and perform the following steps:

  1. Select File -> New -> Results.
  2. Type CancelSale for Name; click Next.
  3. Specify the id input as a required input; then click Next.
  4. Click Finish.

    5. The iPlanet Application Builder creates the following files: 

    	CancelSale.java
	CancelSale.jsp

Edit Servlet to Load and Execute Update Query CancelSale

Next, you need to enter the code necessary to load and execute the associated query from the query file. You will find this code in the completed file installed in <IASRoot>\Apps\cdx\CancelSale.java.

This code is similar to the Insert or Update code produced for a data-entry form by the Database Forms Wizard of the Input Wizard.

  1. Copy the implementation inside the CancelSale class from <IASRoot>\Apps\cdx\CancelSale.java to your CancelSale.java file; do not change import, or class declarations.
  2. Change the package name to cdx1.
  3. In CancelSale.java, change the directories for PendingSeller.gxq from cdx to cdx1:

    4. 	cdx1/PendingSeller.gxq

Connect Links to Servlets

Next, return to the PendingSeller.jsp file to connect the Accept and Cancel links to the update servlets. Start by opening the PendingSeller.jsp file.

Connecting the Accept Link

  1. Click the Accept link and edit the Destination URL property.
  2. In the Servlet drop-down list, select the AcceptSale servlet.
  3. Click the Add button.
  4. Click in the name cell, add "ID4" and press enter.
  5. Then click the Data-bind value button.
  6. In the cell editor drop-down lists, select the PendingSeller ResultSet and the DataField, ID4.
  7. Click Add, then click OK.
  8. Repeat the above steps for the buyer value, setting XLOCK3 in the name cell, and selecting XLOCK3 in the cell editor as the source DataField.

  9. Click OK on the main property editor to complete the Accept URL specification.

Connecting the Cancel Link

Continuing with the Cancel link, click Cancel and edit the Destination URL with the URL property editor:

  1. In the Servlet drop-down list, select the CancelSale servlet.
  2. Click the Get Arguments button.
  3. Click in the name cell, add "ID4" and press enter.
  4. Click the Data-bind value button.
  5. In the cell editor drop-down lists, select PendingSeller ResultSet and the DataField, ID4.
  6. Click Add, then click OK.
  7. Click OK on the main property editor to complete the Cancel URL specification.

Link View Pending Transactions Activity to User Menu

This completes the View Pending Transactions activity. You can now return to the User Menu and hook up the associated link.

  1. Open the UserMenu.html file.
  2. Select the "View pending transactions on your CDs" text.
  3. Click the Create Link icon at the far right of the toolbar. If the Create Link icon is not present, then select View -> Toolbars -> Standard. Note that you can also right-click the highlighted text and choose "Create Link" from the pop-up menu to create the link.
  4. Display the Destination URL property editor, and select the servlet PendingSeller.
  5. Click OK.

Add Links in the AcceptSale and CancelSale Java Server pages:

  1. Open AcceptSale.jsp, enter text "UserMenu".
  2. Click on the create link and in the destination url, specify Usermenu.html.
  3. Repeat the above step for CancelSale.jsp.

Task 11: Creating Enterprise JavaBeans

The iPlanet Application Builder allows you to create Enterprise JavaBeans or import existing JavaBeans from jar files. This task shows you how to create a session bean using the Session Bean wizard.

  1. Choose New from the File menu and select Session Bean.
  2. Choose CreditCheck for the name of the bean.
  3. Click Next.

    4. The directory specifies the package that contains the bean. The name specifies the names of the bean class and interfaces. You can change the class and interface names in the next panel in the dialog box. You can also specify control descriptors as well. For information about control descriptors, see the Programmer's Guide. No changes are required for this example.

    The next dialog box allows you to specify whether the bean is a stateful or stateless session bean.

  4. Choose Stateless; then click Next.

  5. Click Finish.

    6. The iPlanet Application Builder creates the following files: 

    	ICreditCheckHome.java
	ICreditCheck.java
	CreditCheckBean.java

  6. Edit the bean's interface file to define the CheckCredit() method.

  7. Open ICreditCheck.java which is the remote interface and define the checkCredit() method.

    8. 	public interface ICreditCheck extends javax.ejb.EJBObject
	{
	public boolean checkCredit(String name) throws RemoteException;
	}

  8. Add an implementation of the checkCredit() method to the CreditCheckBean.java file.

    9. 	public boolean checkCredit(String name) throws RemoteException
		{
			return (!name.equals("deny"));
		}

  9. In the Project window, right-click on cdx1.iab to display a context-sensitive submenu.
  10. Select the Project Metadata ... option.

    The Project Metadata Editor window appears.

  11. Select the EJB References tab.
  12. Add a new reference with the following values:

    Reference: CreditCheck
    BeanType: Session
    Bean Home Interface: ICreditCheckHome
    Bean Remote Interface: ICreditCheck
    Linked To Bean: CreditCheck
    JNDI Name: ejb/cdx1Ejb/cdx1/CreditCheck

  13. Press enter.

    The entire line is highlighted in blue.

  14. Close the Project Meta Editor window and save your project.
  15. Rebuild your project.
  16. Modify the BuyCD.Java file to use the credit check session bean.
  17. Replace occurences of cdx with cdx1.

    18. 	public class BuyCD extends HttpServlet
	{
		ICreditCheckHome home = null;
		ICreditCheck remote = null;
		String JNDI_NAME = "java:comp/env/CreditCheck";
	public void doGet(HttpServletRequest req, HttpServletResponse res)
			throws ServletException, IOException
	{
		defaultAction(req, res);
	}
	public void doPost(HttpServletRequest req, HttpServletResponse res)
			throws ServletException, IOException
	{
		defaultAction(req, res);
	}
	public void displayMessage(HttpServletRequest req,
			  HttpServletResponse res,
			  String messageText)
			throws ServletException, IOException
	{
		res.setContentType("text/html");
		PrintWriter out = res.getWriter();
		out.println(messageText);
	}
	public void defaultAction(HttpServletRequest req, HttpServletResponse res)
		throws ServletException, IOException
	{
	int result = formAction(req,res);
	if(result == 1){
		RequestDispatcher dispatcher = getServletContext().getRequestDispatcher(_defaultTemplate);
		res.setContentType("text/html");
		dispatcher.forward(req, res);
	     }
	     else{
	     // replace the Below with a suitable Error jsp
	     displayMessage(req,res,"Credit Check Failed");
	     }
	}
	public int formAction(HttpServletRequest req, HttpServletResponse res)
		throws ServletException, IOException
	{
	     int result = -1;
	     HttpSession session = req.getSession(true);
	     javax.naming.Context initContext = null;
	     java.util.Hashtable env = new java.util.Hashtable(1);
	 try {
	     initContext = new javax.naming.InitialContext(env);
	     }
	     catch(Exception e) {
		System.out.println("oops.. couldn't get initContext. caught exception");
	     }
	     Object beanObject = null;
	     try {
	     String sName = (String)session.getAttribute("NAME");
	     beanObject = initContext.lookup(JNDI_NAME);
	     ICreditCheckHome home = (ICreditCheckHome) beanObject;
	     ICreditCheck remote = home.create();
	     boolean bCreditOK = remote.checkCredit(sName);
		if (!bCreditOK) {
				return result;
		}
		else {
			result = 1;
			System.out.println(sName + " passed the Credit Check");
		}
	     }
	     catch(Exception e)
	     {
		e.printStackTrace();
	     }
		return result;
	  }
	  public int delete(HttpServletRequest req, HttpServletResponse res)
		throws ServletException, IOException	
	  {
	     return SUCCESS;
	}
	     String _defaultAction = "/.jsp";
	String _defaultTemplate = "/BuyCD.jsp";
	static final int SUCCESS = 0;
	static final int STREAM_SUCCESS = 1;
	static final int STREAM_ERROR = -1;
	}

    Task 12: Building and Testing the Application

    You have finished constructing the CD Exchange tutorial application. You can build and test your application.

    1. Choose Build Project from the Build menu.
    2. Choose Start Server from the Test menu if your server is not running.
    3. Choose Restart Server from the Test menu, if your server is running.

      4. You must restart your server each time you modify source code.

      An informational message appears in the Java Server tab of the Messages window indicating that the server is ready: info: ENGINE-ready: ready: <server port number>.

    4. Choose Test Project from the Test menu.
    5. Registration messages are displayed in the Registration tab of the Messages window.

      6. You can ignore "No GUID" messages for EJBs. iPlanet Application Builder brings up the browser with the initial screen:

    6. Test your application.