Getting Started With Sun Java Studio Creator

Starting a Project

A project is the equivalent of your working environment for a web application. When you create a project from the IDE, the IDE builds a supporting directory structure, which conforms to the standard directory layout for web applications. In addition, the IDE creates directories for building and deploying the application.

You create a project by choosing File > New Project from the main menu.

Start the IDE, using the appropriate step:

Create a project by choosing File > New Project from the main menu. Note that the default project type is a web application, then click Next. Click Finish to accept the default project name and location. The IDE creates the project directory Creator/Projects/web-application-name under your home directory by default. To change the default location, see the help topic "Setting the Location of Project Files."

Explore the Projects window, which is shown in the following figure. The Projects window groups items by category. Expand each of the nodes to see what type goes in each category. Notice the badges that are next to the Request Bean, Session Bean, and Application Bean nodes. These badges show that the files need to be compiled. The IDE compiles the files automatically when you build the project.

Under the Web Pages node is the Page1.jsp node. The IDE creates this page by default and makes it the start page. The arrow badge next to the node identifies the page as the start page. If you want to use a different page for the start page, right-click that page's node and choose Set as Start Page from the pop-up menu.

Click the Files header, or choose View > Files from the main menu, to bring the Files window to the front. This window organizes the items by their physical storage. Expand the nodes to see the structure. Hover the mouse over the nodes and subnodes to see the tool tips.

In Figure 2, notice the WebApplication1 > src > webapplication1 > Page1.java node. This Java class is the backing bean for the Page1.jsp file. Whenever you add a page to the project, the IDE creates both a .jsp file and a .java file for the page. You learn more about .jsp and .java files in the next section.

Creating Web Pages

With JavaServer pages (JSP) web applications, you use JSP pages and page beans (also known as backing beans) instead of HTML pages. The JSP page is a template from which the server generates the HTML response to be displayed in the browser (the client). The page bean contains the logic that the server executes when generating the HTML response and also after a user submits the page.

When you add a web page using the IDE, the IDE creates both a JSP file and a Java source file for you. You mostly use the Visual Designer and the Properties window to develop the web page. The IDE modifies the JSP code and Java code to implement what you design. Most of your work can be done from the Visual Designer.

Note: The JSP pages that the IDE generates are JSP documents. A JSP document is an XML document and, therefore, must be well-formed. While most JSP elements comply with XML syntax, there are some elements that are not XML compliant, such as comments, declarations, directives, expressions, and scriptlets. See the JavaServer Pages Syntax Reference for JSP document syntax.

In the Projects window, right-click the Web Pages node and choose New > Page, as shown in the following figure.

Name the page Page2 and click Finish. The IDE opens Page2 in the Visual Editor, which is in the editing area.

Click the Java button in the editing toolbar to see the source code for the page bean, as shown in the following figure. When the editing area shows the Java source, the Navigator window appears in the bottom-left corner. This window lists all the member fields and methods. Notice that the page's source code has methods to access the Application Bean, Session Bean, and Request Bean. See the Storing and Passing Data section in this tutorial for an explanation of these three types of beans.

The source also has methods that get invoked during certain lifecycle events between the time the page is requested and the time the page rendering is complete.

Tip: Double-clicking a member in the Navigator window positions the source code in the editing area on that member's declaration. You can also click in the Navigator window and start typing the first few characters of a member's name to raise a Quick Search dialog box. Continue typing until the IDE highlights the desired entry in the list, and press enter to position the source code to the matching member's declaration, as shown in the following figure.

Click the JSP button in the editing toolbar to see the JSP code for the page, as shown in the following figure. Notice how the JSP page uses JSP document syntax. If you are familiar with JSP pages, you might also note how the JSF tags, such as <ui:page>, use the #{...} expression language (EL) syntax instead of the ${...} syntax, so that the expression is evaluated by the tag handler.

Click Design in the editing toolbar to switch to the Visual Designer and to display the representation of the page in the Outline window, which is shown in the following figure. Note how the tags in the JSP file are represented as nodes in the Outline window.

Adding Components to a Web Page

You design a web page by dragging components from the Components tab of the Palette window and dropping them on the web page in the Visual Designer. The following figure shows Page2 with the Button, Calendar, Text Field, Message, Drop Down List, and Radio Button Group components. All of these components are available from the Basic section of the Palette. The components have been customized by changing the component properties. You learn about properties later in this section.

Note: The components that are available from the Palette are JSF 1.1 components, which have been enhanced according to the Design Time API so that they are available at design time. You can use other JSF 1.1 components in the web applications that you build using the IDE, but you will not be able to use the interactive design-time features of the IDE on these components, unless they have been customized according to requirements of the Design Time API.

Most of the components that you use are in the Basic, Layout, and Composite sections of the Palette window. The following tables show some of the most commonly used components.

Action Components

You use the component's property sheet in the Properties window to change the appearance and behavior of the component, to bind the component to data, and to associate the component with event handlers.

The following figure shows the properties sheet for a Listbox component.

Create a new page named Page2 or reuse the one that you created by following the Try It suggestions in the Creating Web Pages section.

Drag various components from the Basic section and the Layout section of the Palette window and play around with their properties. For example, try the following steps:

Getting Help About the IDE

The IDE provides a Help Viewer, which contains help topics about the IDE and the bundled components. To access the help topics, choose Help > Help Contents from the main menu. Also, when you press F1 on a window, dialog box, or Palette component, the Help viewer appears and displays information about that item.

The IDE also provides a Dynamic Help window, which shows links to information that is related to the current window or object. When you double-click a link in the Dynamic Help window, the IDE displays the information in the appropriate viewer, such as a browser, the Help viewer, or the Javadoc viewer.

Building and Testing a Web Application

When you are ready to test run a project, press Ctrl-F5 or click the Run Main Project button. The IDE takes the following actions:

If you have made massive changes, deleted several items, or you are seeing some unexpected behavior, you can choose Build > Clean and Build Main Project from the main menu. The IDE cleans out the project's build directory and dist directory, undeploys the web application, and then builds and deploys the application.

Linking Web Pages and Handling User Actions

When a user types in a URL, clicks a link, or clicks a button, the browser sends a request to the server. The server maps the request to a JSP page and uses that JSP page and its associated page bean to render a response.

You can specify page navigation in one of two ways:

To access the Page Navigation editor, right-click on a blank spot in the page in the Visual Designer and choose Page Navigation. The Page Navigation editor shows all the pages in the project. When you click a page in the Page Navigation editor, the page expands and shows all its action components. (An action component is a component that has an action property, such as a Button, a Hyperlink, or a Tab.) You drag from an action component to a page to create the mapping between that action's request and the page to be rendered as a response, as shown in the following figure.

Editing Java Code

The IDE's Java Editor is packed full of features to facilitate the programming process, many more than can be discussed in this introductory tutorial. The following list of examples of editing features is just the tip of the iceberg.

NOTE: The following exercises have you type code in the destroy method. The code that you type is meant to illustrate the editing features. You would not normally put this code like this in this method. After you complete the steps, you should remove the code.

Handling User Input

The IDE provides validator and converter objects to facilitate input checking and formatting. These objects can be found in their respective sections in the Palette.

You bind a validator to an input component, such as a Text Field component, by dropping the validator onto the input component. For example, after you add a Text Field component to a page in the Visual Designer, you can drag a Length Validator from the Validators section in the Palette and drop it on the Text Field.

Alternatively, you can drop the validator onto the page and set the input component's validator property to that validator object. For example, you can drop a Long Range Validator on a blank spot on the page, which adds longRangeValidator1 to the Outline window. You can then select an input component in the visual designer, such as the Text Field component, and choose longRangeValidator1 from its validator property's drop-down list. This method enables you to use the same validator for several components.

The same mechanisms are true for converters. You can also associate converters with output components, such as the Static Text component.

You use the validator's Properties window to set the validation rules, such as the minimum and maximum value or the minimum and maximum length. Similarly, you use the converter's Properties window to set the conversion rules, such as the pattern that the value should match or the method to call to do the validation. The Number converter has a special wizard that appears when you first drop the Number Converter onto the page or onto a visual component.

The Basic section of the Palette provides the Message component and the Message Group component for automatically displaying conversion errors, validation errors, and required-field messages. The Message Group component displays global error messages and, optionally, all the component error messages. A Message component displays only the messages for the component to which it is bound. You bind a Message component to another component by setting the Message component's for property or by pressing Ctrl-Shift on the Message component and dragging the mouse to the component that you want to bind the Message component to.

You can programmatically send custom error messages to the Message Group component using the error, warn, fatal, and info methods in any Page Bean. To learn more about these methods, see the entry in the Application Model Reference for the FacesBean class. To view the API for the FacesBean class, expand Javadoc API References in the Dynamic Help Window, double-click Application Model Reference, and click FacesBean in the All Classes list.

Storing and Passing Data

You use the Application Bean, the Session Bean, and the Request Bean to store information for use by other pages.

To add a property to the Session Bean, right-click the Session Bean node in the Projects window and choose Add > Property. The IDE adds a declaration, a getter method, and a setter method for the property. Use similar steps to add a property to the Request Bean or the Application Bean.

Tip: If you see syntax errors when you write code that correctly uses a new property, compile the class that the property is in to make the property's existence known to other parts of the IDE. For example, if the new property is in the Session Bean, right-click the Session Bean node in the Projects window and choose Compile File from the pop-up menu.

To associate a component with a bean's property, right-click the component and choose Bind to Data. In the Bind to Data dialog box, select the Bind to Object tab and choose the bean's property, as shown in the following figure.

Note: For most components, the pop-up menu provides two binding actions - Property Bindings and Bind to Data. The Property Bindings dialog box enables you bind any of the component's properties to a managed bean property or a data provider field. The Bind to Data dialog box is a shortcut for binding the component's value-holding property to a managed bean property or a data provider field. Use the Bind to Data Provider tab to bind to any data provider that you have added to the page or a managed bean. Use the Bind to an Object tab to bind to a page property or a managed bean property.

Connecting to Databases

The Servers window includes a Data Sources node, which shows all the data sources that are added to the IDE, as shown in the following figure. The Java Studio Creator IDE comes with an embedded database management system (DBMS), which is prepopulated with sample schemas.

Before you can access the bundled data sources, you must first start the database server.

If a red X appears on a data source's icon and an error appears when you try to expand it, the database server is not running. To start the database server, right-click the Bundled Database Server node in the Server Navigator and choose Start Bundled Database from the contextual menu. Then right-click the data source and choose Refresh.

Note: When you open an existing project, the Visual Designer might show an error screen. Typically, this is because the Visual Designer needs to get information from the database and the database server is not running. Try starting the database server and clicking the Continue button in the error screen to resolve the problem.

You add a datasource to the IDE by right-clicking the Data Source node in the Servers window and choosing Add Data Source from the pop-up menu. An Add Data Source dialog box appears with which you can supply information about the data source, such as host name, database name, user name, and password. After you add the data source, you can expand the data source's node and expand Tables to access the schema's tables.

You can connect a page with a database table by dragging the table from the data sources section and either dropping it on a component or dropping it on the page. When you do this, the IDE adds a data provider to the page and a rowset to the SessionBean1 class, as shown in the following figure. Later in this section, you learn how to add a data provider to the page and bind it to a component in a single step.

The rowset object makes the connection to the database, executes the queries, and manages the result set. The data provider object provides a common interface for accessing many types of composite data, from database tables, to Array objects, to Enterprise JavaBeans objects. Typically, the only time that you work with the rowset object is when you need to set query parameters. In most cases, you use the data provider object to access and manipulate the data.

To bind a component to the database, right-click the component and choose Bind to Data. In the Bind to Data dialog box, click the Bind to Data Provider tab to bring it to the front. The Choose a Data Provider drop-down list shows all the page's data providers from which you can select the data provider to bind to the component. To bind to a data provider that is not on the list, click Add Data Provider and select the appropriate data table from the Add Data Provider dialog box. After you select the data provider, choose the appropriate data column to be bound to the component. For some components, such as the Drop Down List component, you must choose both a Value field and a Display field.

You use the Query Editor for a rowset object to define the SQL query to use to retrieve the data, as shown in the following figure.

Debugging a Web Application

The IDE has a built-in debugger to help you troubleshoot your programs. You can use it to set breaks and watches, to step through code, and to run until it reaches the code statement that the cursor is on.

You set a breakpoint by clicking in the left margin of the Java Editor. You set a watch by right-clicking a variable or expression choosing New Watch. To run the debugger, choose either Run > Debug Main Project or Run > Run to Cursor from the main menu.

TIP: Here are some other features that you can use to diagnose and resolve problems:

Summary

More Developer Resources:

For more tutorials, articles, tips, forums, updates, and expert advice for developers, visit the Java Studio Creator developer resources on the Sun Developer Network (SDN) at http://developers.sun.com/jscreator/.