Chapter 8   Using Wizards to Generate Project Files


This chapter describes the iPlanet Application Builder code generation wizards that help you perform common tasks associated with building an iPlanet application.

The wizards provide a quick method for automatically generating and linking together files needed for advanced application features. The following topics are described in this chapter:

• About iAB Wizards

• Using the Data Model Wizard

• Using the Input Wizard

• Using the Results Wizard

• Using the Database Forms Wizard

• Using the Query Wizard

• Using the HTML Page Wizard

• Using the JSP Wizard

• Using the Servlet Wizard

• Using the Java File Wizard

• Using the Session Bean Wizard

• Using the Entity Bean Wizard

About iAB Wizards

---

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.

The tasks common to most applications involve interactions between application users and the Servlets and JSPs that make up the application's business logic. iPlanet Application Builder provides two generic wizards to help you create the files necessary for gathering input from a user (the Input wizard) and giving information to the user by way of an HTML template (the Results wizards). There is also one wizard for generating input forms and output reports from a relational database (the Database Forms wizard), and one for implementing a login page with optional password validation (the Login wizard).

Wizards are invoked from the New File(s) dialog box. The following table describes the available wizards, shows their icons, and describes the types of files generated by each wizard (note that you can choose from existing files rather than generate new ones):

Table 8-1 Application Builder Wizards 

Icon	Wizard	Description	Generated Files
	Data Model	Creates a data model.	Data model
	Input	Creates a generic input form and a servlet to handle the input.	HTML page with a data input form Servlet to process the form, optionally accessing a query Empty JSP to display results Insert query to store data to a data source (optional)
	Results	Creates a generic servlet and JSP	Generic servlet linked to the JSP Empty JSP
	DatabaseForms	Enables the user to perform interactions with a relational database and generate complex reports and forms.	HTML page with a data input or query form and optional search form Query to retrieve data from database Servlets to process the query JSP(s) to display the results of the query
	Login	Creates login functionality, optionally with password verification.	HTML page with a login form Servlet to process the form JSP to use as a results page for successful login
	Query	Creates a SQL statement.	Query to perform the SQL operation.
	HTML Page	Creates an HTML page.	Empty HTML page
	Java-Server Page	Creates a JavaServer page.	Empty JavaServer page
	Servlet	Creates a servlet.	Java code file
	Java File	Creates a java class.	Empty Java code file
	Session Bean	Creates a session bean.	home interface source file remote interface source file enterprise-bean class source file <projectname>.xml files
	Entity Bean	Creates an entity bean.	home interface source file remote interface source file enterprise-bean class source file .xml files

In all of these wizards, click Next to move on to the next step, or click Back to return to a previous step.

Using the Data Model Wizard

---

The data model wizard allows you to specify the database tables and relationships between them. You must create a data model before you can create a query or form. The following files are generated, with filenames based on the name you specify:

Table 8-2 Data Model Wizard Generated Files

Generated File	File Name
Data model definition	filename.kdm

To launch the Data Model wizard, select New File(s) from the Project menu. Select Data Model and click Add. The Insert Tables dialog appears, which allows you to use an existing connection or create a new one. Previously established connections are defined as a *.xml file in iAS's Connections folder. If you create a new connection, you must specify the driver, data source, username, password, and, optionally, a database name, for your connection.

After choosing or creating the connection, the Add Tables dialog appears, allowing you to specify the tables you want to include in your data model. Once the tables have been identified, you complete the data model by defining relationships between fields in the tables. iPlanet Application Builder displays a visual representation of the tables from which you select a field from one table and drag it to its related field in another table. By default, each relationship you create is one-to-many from the dragged field to the destination field. You can change the kind of relationship by selecting the line between the fields and modifying the Relationship property in the Properties editor.

When you finish defining relationships and close the window, iPlanet Application Builder prompts you for the file name in which to save your data model.

Using the Input Wizard

---

The Input wizard creates a generic input form and a servlet to handle the input. The following files are generated, with filenames based on the name you specify:

Table 8-3 Input Wizard Generated Files

Generated File	File Name
HTML page with a data input form	filename.html
Servlet to process the form	Calledfilename.java
Empty HTML template to display the results	Calledfilename.jsp
Insert query to store data to a data source (optional)	Calledfilename.gxq

The generated HTML form consists of a basic form structure containing the input parameters you specify in the wizard. The form's SUBMIT button submits the form to the generated servlet, which processes the input and merges results with the generated JSP.

1. To launch the Input wizard, select New File(s) from the Project menu.

2. Select Input and click Add.

   The Specify Page Name and Location dialog box appears.

3. Enter a base filename and location for the generated files.

4. Choose how you would like to process the input information, depending on how the input parameters are processed.

   You can choose Handle Information with Custom Code or Store to a Database Table, described in the following sections.

Handle Information with Custom Code
If you choose to handle the input with custom code, the wizard prompts you for the input values that you want to make available to your servlet. Choosing to use custom code causes the wizard not to generate a query file.

Store to a Database Table
To enable the input to be inserted directly into a database using a new INSERT query, choose "Store to a database table" and click Next.

Perform the following steps to store the input to a database:

1. First, select a data model on the Specify Data Model dialog box.

   If you have not yet created a data model for this project, or if your data model is not appropriate for this input, select Create a New Data Model to exit the Input wizard and create a new data model.

2. In the Specify Data Connection dialog box, choose "Use an existing connection".

   If you have already set up a database connection. Otherwise, choose "Create a new connection" and click Next. Choose a database driver, a data source, and a user name and password.

3. In the Select Input Fields dialog box, choose a table from your data model.

   The fields in the table appear in the left column. For each table, choose whether the field appears on the form at runtime.

You must edit the generated JSP to display the results.

Using the Results Wizard

---

The Results wizard creates a generic servlet that is not linked to an empty JavaServer Page (JSP). You can then create presentation logic in the JSP and transaction logic in the servlet. The following files are generated, with filenames based on the name you specify:

Table 8-4 Results Wizard Generated Files

Generated File	File Name
Empty JavaServer Page	filename.jsp
Generic servlet (not linked to the JSP)	filename.java

The generated servlet is a generic stub you can use to develop a piece of your application. The results of the servlet activities merge with the generated JSP to produce an HTML page at runtime.

To launch the Results wizard, select New File(s) from the Project menu. Select Results and click Add. The Specify Servlet Name and Location dialog box appears. Enter a base filename and location for the generated files.

Specify input parameters for the servlet. If you already have an HTML input page, you can read input parameters from it automatically. Alternatively, you can enter the parameters by hand using the Specify Input dialog box, shown here:

To read parameters from an existing page, select the page from the drop-down box at the bottom of the Specify Input dialog box, or click Browse to search the filesystem for the page. To specify parameters by hand, enter the name and select the appropriate settings for other properties.

Using the Database Forms Wizard

---

The Database Forms wizard enables you to set up interactions with a relational database and generate complex reports. The following files are generated, with filenames based on the name you specify:

Table 8-5 Database Forms Wizard Generated Files

Generated File	File Name
HTML page with a data input form and optional search functionality	filename_Search.html
Optional query file to retrieve data from database	filename.gxq
Servlets to process the transaction query	filename.java
JavaServer Page to display the results	filename.jsp
Servlets to process the detail transaction query (optional)	filenameDetail.java
JavaServer Page to display the detail results (optional)	filenameDetail.jsp

The generated servlet processes form for transaction (such as update, insert, delete,or search data from generated HTML files). JSP extended taglibs use the data model and query file to retrieve data from a relational database, and merges this data with the generated JSP to display the results as a static report or an editable form.

To launch the Database Forms wizard, select New File(s) from the Project menu. Select Database Forms and click Add. The Specify Servlet Name and Location dialog box appears. Enter a base filename and location for the generated files.

Choose how you would like to define the data used on your forms and reports. You can choose Use an Existing Query File, or choose Use a Data Model to create a new query file.

Use an Existing Query File

Choose a query file from the drop-down list, or browse for one. When you find the file you want to use, the Select a Query dialog box prompts you to choose a single query from the queries in the file.

If you choose a select query, the Select Records Display dialog box prompts you to choose whether records should be displayed as a single record, in which only the first row of data found by the query appears in the final output, or multiple records, where all rows of data appear in the final output.

Use a Data Model

If you choose to create the details of your query from scratch, use the Select Pages to Create dialog box to choose what kind of output pages you want to produce.

A master record is the primary target of a query. A detail record is the result of a secondary query, based on the master record. Combinations of master and detail queries are shown. If a set of pages can be produced, they are linked together with standard VCR-type navigation tools (first record, next record, previous record, and last record).

The types of output pages are described below:

Table 8-6 Types of Output Pages

Type of Pages	Example
Single record master	An account
Multiple record master	A list of accounts
Single record master and multiple record detail (single page)	A single accounts and a list of transactions on that account
Single record master and multiple record detail (multiple, linked pages)	A single account and a list of all transactions on that account
Multiple record master and single record detail	A list of accounts, and a detailed view on each account
Multiple record master and multiple record detail	A list of accounts, and a list of all transactions on each account

Additionally, you can check the "Create a search page" checkbox to generate a form that enables users to search for certain records by specifying search criteria.

Specify a data model (or exit the wizard to create one). On the Specify Data Connection dialog box, choose "Use an existing connection" if you have already set up a database connection. Otherwise, choose "Create a new connection" and click Next. You are prompted to choose a database driver, a data source, and a user name and password.

Depending on the type of output you want to produce, you are prompted for display field information, first for the master query and next for the detail query. Complex pages are shown with either a master section (for single-page output) or a master page (for multiple-page output).

In each case, you must provide the following information if it is relevant to your selected output scenario:

Table 8-7 Required Information for Dialog Boxes

Dialog Box	Information to Provide
Select Display Fields	Choose the fields you want to display on the page or section by selecting a table and one or more fields, and moving the fields into or out of the "Fields to display" column using the left and right arrow buttons between columns. Doubled arrows move all fields at once. You can use the up and down arrows on the right to adjust the order of the fields. You can use fields from multiple tables.
Select Table Format	Choose which fields are editable if you are creating a form as output, or choose "Display-only fields" to create a database report.
Select Sort Fields	Choose which field(s) to use as a sort key when displaying multiple records. This dialog box functions similarly to the Select Display Fields dialog box described above, with the addition of buttons you can use to specify the field to be sorted ascending or descending.
Specify Primary Key(s)	Choose a field that guarantees the uniqueness of a row in the query. Note that database-controlled fields (such as auto-increment fields) usually cannot be updated by a normal database transaction; in this case, be sure to specify any auto-increment fields as noneditable when prompted.
Select Drilldown Field	Choose a field to use as a hypertext link from the master page to the detail page by selecting a field from the "Display field" drop-down box. Then specify columns to join, and the operator for joining them. The master fields automatically become links to the appropriate detail pages.
Select Columns for Search Page	If you chose to create a search page, choose which fields in the query should appear on the search page, and what kind of search should be possible.

Using the Login Wizard

---

The Login wizard enables you to create login functionality, optionally with password verification. The following files are generated, with filenames based on the name you specify:

Table 8-8 Login Wizard Generated Files

Generated File	File Name
Static HTML page with a data input form	filename.html
Optional query file to retrieve data from database if login is authenticated by database table	Calledfilename.gxq
Servlet to process the login	Calledfilename.java
JavaServer Page to display the results of a successful login	Calledfilename.jsp

To launch the Login wizard, select New File(s) from the Project menu. Select Login and click Add. The Specify Page Name and Location dialog box appears. Enter a base filename and location for the generated files.

Specify input parameters in the Specify Input dialog box. These parameters appear as text input boxes in a form on your login page. The servlet uses these parameters to verify the login. Default input parameters are Username and Password.

For each parameter, enter or choose the following information:

Table 8-9 Parameter Attribute Options

Parameter Attribute	Description
Name	Parameter name
HTML Type	Type of entry box for this parameter. Valid types include the following: Text (plain text on a single line) TextArea (plain text on multiple lines) Password (entry replaced on user's screen with asterisks) Checkbox (checked yields true, unchecked yields false)
Default Value	The value submitted with the form if the user enters nothing.
Validation	Optional validation for Text, TextArea, or Password fields.
Required	Check this box if this parameter is required.

The Select Login Authentication dialog box prompts you to choose a method for verifying that the provided parameters constitute a valid login. The available options, Database Table, LDAP Server, and Custom, are described in the following sections.

Database Table

To authenticate your login against a database, first choose a data model, or exit the wizard and create one if needed. Create a database connection by providing a database driver, a data source, and a user name and password.

On the Specify Database Login Information dialog box, choose a database table that contains login fields, and then match your input parameters with database fields.

You can save any of the fields in the table as session variables by checking the Save to Session checkbox for that field on the Specify Query Outputs to Save to Session dialog box.

LDAP Server

The Specify LDAP Server Information dialog box prompts you for information to enable a connection to the LDAP server to authenticate the login. Specify the same server name, port, organization and country as you did when you installed your directory server. Use the drop down list to choose the source of the values for the name and password.

Custom

For Custom authentication, you must provide code in the generated servlets to authenticate your users.

Using the Query Wizard

---

The Query wizard creates a SQL query from the tables in your data model. The following files are generated, with filenames based on the name you specify:

Table 8-10 Query Wizard Generated Files

Generated File	File Name
Query file	name.gxq

To launch the Query wizard, select New File(s) from the Project menu. Select Query and click Add. The Specify Base Name and Location dialog box appears. Enter the name and location for the generated file. The Specify Data Model dialog appears next; you can select a data model from within the current project or browse for a data model in another project.

You are then prompted for the kind of query, which is either Select, Insert, Update, or Delete. A dialog that matches the kind of query appears. These dialogs are explained in Creating Queries.

Using the HTML Page Wizard

---

The HTML Page wizard creates an empty static HTML page. The following files are generated, with filenames based on the name you specify:

Table 8-11 HTML Page Wizard Generated Files

Generated File	File Name
HTML file	name.html

To launch the HTML Page wizard, select New File(s) from the Project menu. Select HTML Page and click Add. The Specify Base Name and Location dialog box appears. Enter the name and location for the generated file. iPlanet Application Builder creates a minimal HTML page, which sets the title and colors, in the project's HTML Pages folder and allows you to start editing the file.

Using the JSP Wizard

---

The JSP wizard creates an empty JSP file that is used to display dynamic data-bound HTML output. The following files are generated, with filenames based on the name you specify:

Table 8-12 JSP Wizard Generated Files

Generated File	File Name
JavaServer page file	name.jsp

To launch the JSP wizard:

1. Select New File(s) from the Project menu.

2. Select JSP and click Add.

   The Specify Base Name and Location dialog box appears.

3. Enter the name and location for the generated file.

   iPlanet Application Builder creates a minimal JavaServer page, which sets the title and colors, in the project's Java Server Pages folder and allows you to start editing the file.

Using the Servlet Wizard

---

The Servlet wizard creates a Java code file that you can use to define your business logic. The following files are generated, with filenames based on the name you specify:

Table 8-13 Servlet Wizard Generated Files

Generated File	File Name
Servlet file	name.java

To launch the Servlet wizard:

1. Select New File(s) from the Project menu.

2. Select Servlet and click Add.

   The Specify Base Name and Location dialog box appears.

3. Enter the name and location for the generated file.

   iPlanet Application Builder creates a Java code file, which defines the package, imports, class, and the class' defaultAction(), doGet(), and doPost() methods, in the project's Java folder and allows you to start editing the file.

4. If you do not wish to register the JSP, uncheck the checkbox. The default setting is to register the JSP.

Using the Java File Wizard

---

The Java File wizard creates an empty Java code file that you can use to implement non-servlet code, such as helper or utility classes. The following files are generated, with filenames based on the name you specify:

Table 8-14 Java File Wizard Generated Files

Generated File	File Name
Java code file	name.java

To launch the Java Class wizard:

1. Select New File(s) from the Project menu.

2. Select Java file and click Add.

   The file is given the name Blankn.java.

   You are prompted to change the name of the file when you close it after you modify the contents.

Using the Session Bean Wizard

---

The session bean wizard creates the Java files and an EJB Descriptors file needed to implement a session bean. The following files are generated, with filenames based on the name you specify:

Table 8-15 Session Bean Wizard Generated Files

Generated File	File Name
EJB remote interface source file	Ihomename.java
EJB enterprise bean source file	homenameBean.java
EJB home interface source file	IhomenameHome.java
EJB Descriptor	projectnameEjb.xml
iAS specific EJB Descriptor	ias-projectnameEjb.xml

You place methods in the enterprise bean source file to implement application-specific behavior in an EJB. The source files generated by the EJB wizard compile but have no application-specific behavior. You will have to add code to all three source files to create useful behavior; see http://java.sun.com:8081/ejb/docs.html for more information.

To launch the Session Bean wizard, select New and then Session Bean from the File menu. The Specify Base Name and Location dialog box appears. Enter the string that you want to use to construct the EJB's home name for JNDI registration as well as to create names for the iAB-generated Java files. You can change the directory if you wish. By default, it is the combination of the iAS installation directory, the relative pathname of the server's application root, and one of the following:

• the EJB default package name as specified in the Java panel of the Tools menu's Development options dialog box, if a package name is specified

• the project directory if a package name is not specified in the Java panel of this dialog

The package part of the directory name, which is the part after the application root, is used as the package name for iAB-generated source files. Consider the following example, in which iAS is installed a C:\iPlanet\ias6, the relative pathname for the application root is ias\Apps, the package is cdx. The bean name is CreditCheck. The generated path and file names would be as follows:

Table 8-16 Session Bean Wizard Generated path and File Names

Generated File	File Name
EJB remote interface source file	C:\iPlanet\ias6\ias\Apps\cdx\ ICreditCheck.java
EJB enterprise bean source file	C:\iPlanet\ias6\ias\Apps\cdx\ ICreditCheckBean.java
EJB home interface source file	C:\iPlanet\ias6\ias\Apps\cdx\ ICreditCheckHome.java

In this example, the JNDI name is java:comp/env/CreditCheck.

You can change the names of the generated files in the next dialog box. The next dialog box also allows you to specify the following bean properties and control descriptors:

Table 8-17 Bean Properties and Control Descriptors 

Property or Control Descriptor	Values
Bean class name	any valid class name
Bean home interface name	any valid class name
Bean remote interface name	any valid class name
Isolation level	One of the following levels: TRANSACTION_READ_COMMITTED TRANSACTION_READ_UNCOMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE
Run mode	One of the following modes: CLIENT_IDENTITY SPECIFIED_IDENTITY SYSTEM_IDENTITY
Transaction attribute	One of the following attributes: TX_BEAN_MANAGED TX_MANDATORY TX_NOT_SUPPORTED TX_REQUIRED TX_REQUIRES_NEW TX_SUPPORTS

The next dialog box allows you to specify whether the bean is stateless or stateful. If the bean is stateful, you can specify a timeout value for the bean, which is 10,000 seconds by default.

Using the Entity Bean Wizard

---

The entity bean wizard creates the Java files and EJB Descriptors needed to implement an entity bean. The following files are generated, with filenames based on the name you specify:

Table 8-18 Entity Bean Wizard Generated Files

Generated File	File Name
EJB remote interface source file	Ihomename.java
EJB enterprise bean source file	homenameBean.java
EJB home interface source file	IhomenameHome.java
EJB Descriptor	projectnameEjb.xml
iAS Specific EJB Descriptor	ias-projectnameEjb.xml

The same EJB descriptor files are shared by all EJBs.

You place methods in the enterprise bean source file to implement application-specific behavior in an EJB. The source files generated by the EJB wizard compile but have no application-specific behavior. You will have to add code to all three source files to create useful behavior; see http://java.sun.com:8081/ejb/docs.html for more information.

To launch the Entity Bean wizard, select New and then Entity Bean from the File menu. The Specify Base Name and Location dialog box appears. Enter the string that you want to use to construct the EJB's home name for JNDI registration as well as to create names for the iAB-generated Java files. You can change the directory if you wish. By default, it is the combination of the iAS installation directory, the relative pathname of the server's application root, and one of the following:

the EJB default package name as specified in the Java panel of the Tools menu's Development options dialog box, if a package name is specified

the project directory if a package name is not specified in the Java panel of this dialog

The package part of the directory name, which is the part after the application root, is used as the package name for iAB-generated source files. Consider the following example, in which iAS is installed a C:\iPlanet\ias6, the relative pathname for the application root is ias\Apps, the package is cdx. The bean name is CreditCheck. The generated path and file names would be as follows:

Table 8-19 Entity Bean Wizard Generated Path and File Names

Generated File	File Name
EJB remote interface source file	C:\iPlanet\ias6\ias\Apps\ cdx\ICreditCheck.java
EJB enterprise bean source file	C:\iPlanet\ias6\ias\Apps\ cdx\ICreditCheckBean.java
EJB home interface source file	C:\iPlanet\ias6\ias\Apps\ cdx\ICreditCheckHome.java

In this example, the JNDI name is java:comp/env/CreditCheck.

You can change the names of the generated files in the next dialog box. The next dialog box also allows you to specify the following bean properties and control descriptors:

Table 8-20 Bean Properties and Control Descriptors

Property or Control Descriptor	Values
Bean class name	any valid class name
Bean home interface name	any valid class name
Bean remote interface name	any valid class name
Isolation level	One of the following levels: TRANSACTION_READ_COMMITTED TRANSACTION_READ_UNCOMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE
Run mode	One of the following modes: CLIENT_IDENTITY SPECIFIED_IDENTITY SYSTEM_IDENTITY
Transaction attribute	One of the following attributes: TX_MANDATORY TX_REQUIRED TX_REQUIRES_NEW TX_SUPPORTS