HOME > Community > Projects > j2ee

NetBeans: web
UserView

Version: 1.0
Author: Petr Jiricka, Sun Microsystems

Abstract:: This document describes the functionality of the Web module from the point of view of an average user. Web module adds support for JSP (JavaServer Pages technology) into the IDE.

Document History:: [02-Sep-2000] : version 1.0 : Initial revision

Contents:: 1. Introduction; 2. Working with JSP objects; 3. Using the JSP code editor; 4. Compiling JSP pages; 5. Executing JSP pages

1. Introduction

The web module supports the development of Java Server Pages compliant with the JSP 1.1 specification. The support includes a code editor for JSPs, an internal JSP compiler, which allows convenient validation of JSPs without the necessity to run them, and support for running JSPs inside a web server and displaying in a web browser of the user's choice.

2. Working with JSP objects

2.1 Creating a new JSP

To create a new JSP, choose File | New from the main menu. In the Template Chooser dialog that appears, expand the node of the JSP folder, and you will find two templates: Choose JSP (HTML) to create a JSP with HTML content, or JSP (Plain Text) to create a JSP with plain text content. In the bottom right section of the dialog, choose the name and folder (package) of your JSP file and click Finish. The JSP file will be created in the specified folder.

2.2 JSP objects basics

JSP objects are identified in the Explorer by a special icon:

Icon Description

JSP object

The actions applicable to a JSP object are available in each object's context menu (right-click the object to get the context menu). Some of them are:

Open - opens the JSP page in the code editor. This can be also done by double clicking the JSP. See the chapter on JSP editing for more information.
View Servlet - opens the servlet generated from this page in the code editor (in read-only mode). This action is only enabled if the JSP has been compiled.
Compile - compiles the JSP into a servlet, and then the servlet into a .class file. See the chapter on JSP compilation for more information.
Execute and Execute (restart server) - executes the page in a web server. See the chapter on JSP execution for more information.

The behavior of a JSP object can be controled by its, accessible from the property sheet window. The meaning of individual properties is explained in the following chapters.

3. Using the JSP code editor

A JSP can be opened in the code editor by double clicking it. The following chapter describes the features available in the code editor.

3.1 Syntax colorizing

The code editor visually distinguishes individual components of a JSP page. A page may consist of three types of elements:

JSP elements - JSP tags (standard or custom), JSP directives, and JSP comments
Content language elements - sections of your page written in the language of the content (usually HTML)
Scripting language elements - scriptlets, expressions and declarations written in the scripting language (Java)

Individual types of elements are visually distinguished by a different background color. Individual elements are distinguisged by font face and color. The following picture shows an example of coloring of a sample JSP page for the default content and scripting languages (HTML and Java).

You can control the scripting and content language for each page by the appropriate properties of each JSP object. Setting the Content Language and Scripting Language properties affects the coloring of the page in the JSP code editor. Note that setting these properties does not affect the page directive (notably the contentType and language attributes), which provides information about the content type and the scripting language to the JSP runtime system. It is your responsibility to set these attributes correctly in your JSP page.

You can customize the coloring settings for all the elements as follows: Choose Tools | Global Options in the main menu. Expand the Editor Settings node in the Global Options window. Choose JSP Editor, and in the property sheet at the right hand side of the window, customize the Fonts & Colors property.

3.2 Abbreviations

Abbreviations help you in typing some frequently used fragments of code. When you type one of the designated abbreviation and then enter a space, the abbreviation is expanded into a longer string. The following table lists the default abbreviations for the JSP editor.

Abbreviation Expands To

ag

application.getValue("

ap

application.putValue("

ar

application.removeValue("

cfgi

config.getInitParameter("

jg

<jsp:getProperty name="

jspf

<jsp:forward page="

jspg

<jsp:getProperty name="

jspi

<jsp:include page="

jspp

<jsp:plugin type="

jsps

<jsp:setProperty name="

jspu

<jsp:useBean id="

oup

out.print("

oupl

out.println("

pcg

pageContext.getAttribute("

pcgn

pageContext.getAttributeNamesInScope("

pcgs

pageContext.getAttributesScope("

pcr

pageContext.removeAttribute("

pcs

pageContext.setAttribute("

pg

<%@ page

pga

<%@ page autoFlush="

pgb

<%@ page buffer="

pgc

<%@ page contentType="

pgerr

<%@ page errorPage="

pgex

<%@ page extends="

pgie

<%@ page isErrorPage="

pgim

<%@ page import="

pgin

<%@ page info="

pgit

<%@ page isThreadSafe="

pgl

<%@ page language="

pgs

<%@ page session="

rg

request.getParameter("

sg

session.getValue("

sp

session.putValue("

sr

session.removeValue("

tglb

<%@ taglib uri="

You can customize the abbreviations as follows: In the main menu, choose Tools | Global Options. Expand the Editor Settings node in the Global Options window. Choose JSP Editor, and in the properties at the right hand side of the window, customize the Abbreviations property.

3.3 Code completion

The code completion feature helps you type JSP code by offering you a list of possible tags, directives, attributes, values, methods, etc. When you press Ctrl+Space while editing JSP code, a code completion window, containing a list of choices, which can be applied at the position of the caret, is displayed. Then you make your choice by moving the highlighted line by "up" and "down" keys. Finally you apply the selected option by presing "Enter" or "Shift+Enter" (the text inserted into code may differ for "Enter" and "Shift+Enter").

Code completion can be used in the following situations:

Content language completion - when the caret is in a code fragment which belongs to the content language (e.g. HTML), the completion windows displays items defined for that language (i.e. HTML tags, attributes, character references, ...)
Completion of JSP fragments - when the caret is in a JSP code fragment, the completion window displays JSP related items: tag names, directive names and attribute names. It can also be used for completion of attribute values.
Completion of Java code - when the caret is in a scripting language fragment, the completion window displays items defined by Java completion.

Figure 1: Completion of JSP directive attributes

Figure 2: Completion of JSP attribute values

Figure 3: Completion of Java code in JSP

3.4 Choosing page encoding

You can use the JSP code editor for pages, which are stored on the disk with a different encoding than the default ISO8859-1 encoding. To select encoding on the disk for a JSP page, use the Encoding property of the JSP object.

Note that this property does not in any way affect the contentType attribute of the page directive, which provides information about the page encoding to the JSP runtime system.

4. Compiling JSP pages

4.1 The process of JSP compilation

The process of JSP compilation consists of two steps. First, the page is translated into a Java servlet source by a JSP compiler. Then, the servlet is compiled by an ordinary Java compiler into a .class file. When a JSP page is executed in a JSP container, the container actually runs the compiled servlet, as it would run any other servlet.

The process of development JSPs when using the IDE is somewhat different than when you use just a text editor and a JSP server.

Without the IDE, you edit the JSP file, save it, run the server, and then enter the page URL into your web browser. If your page contains an error, the server will print an exception into its console or into the web browser. This is not very helpful for analyzing the cause of the error.

Inside the IDE, the process is much simpler: you edit your page and execute it. This will first save your page and compile it inside the IDE. If your page contained an error, it will be shown in the Output Window. You can then double click the error to go to the line which contains it. Remember that an error can occur in either of the two compilation phases: if the error occurred during the transtation of the JSP to a servlet, the output window will bring you to the JSP source. If the error occurred while compiling the generated servlet, the servlet source will appear after double-clicking the error.

After compiling the page, the Execute action starts a web server and displays the page in a web browser.

4.2 Viewing the servlet, building and cleaning

When a JSP has been successfully compiled, you can see the generated servlet by choosing View Servlet in the page object's popup menu. This can help you better analyze what the page is doing.

You may notice that when you compile the same page several times, the name of the generated servlet changes: every compilation cycle increases the number appended to the end of the name. The reason for that is that this way the server can reload a new version of a JSP, just by loading a new class file. So the server does not need to be restarted to load a new version of the page. This means that during the process of JSP development, multiple generated servlets will exist on the disk.

You can delete all the versions of the page by running the Clean action (in the Build submenu of the main menu). You can use the Build action (in the same menu) to first clean the page and then compile it.

4.3 Dependencies among the compiled files

Every JSP page may have relationships to other files, Java classes and other JSP pages. For example, a page may include other files by the include directive. A page can also use JavaBeans, and it can delegate to other JSPs by the jsp:include and jsp:forward tags. Finally, every page can define its error page.

The above relationships play a significant role in the JSP compilation process.

When you compile a JSP, all beans used by this page will be automcatically compiled as well.
All files included in the JSP by the include directive will be saved to the disk, if they have been modified in the editor.

You may also choose to automatically compile all pages referenced by a JSP by the jsp:include and jsp:forward tags. To enable or disable this compilation, choose Tools | Global Options in the main menu. In the Global Options window, select the JSP node. The Also Compile Incl. and Forw. property controls this compilation.

Similarly, to enable or disable the compilation of a JSP's error page when compiling the primary JSP, set the Also Compile Error Page property to the desired value.

4.4 Setting the Java compiler

As was already mentioned above, the JSP compiler first translates the JSP into a servlet, and then compiles the servlet into a .class file. The compiler used for compiling the servlet is configurable by the following means.

You can set a servlet compiler for individual JSPs by the Servlet Compiler property in the JSP object's property sheet (Execution tab).

You can also set a default compiler, which will be used for pages for which no specific Java compiler has been set. This can be done by selecting Tools | Global Options in the main menu, and then setting the Default JSP Servlet Compiler property in the JSP node. If you do not set this property, the compiler set in Project | Settings | Java Sources | Default Compiler will be used.

5. Executing JSP pages

The JSP execution feature allows you to test your pages by running them in the Tomcat 3.2 server and displaying them in your favorite web browser.

5.1 Execute and Execute (restart server) actions

You can use the Execute and Execute (restart server) actions from a JSP object's context menu to test run this JSP in a web server. These actions do roughly the following:

Save and compile the JSP, if it is not up to date
If the Tomcat web server is not running, generate the configuration file for Tomcat
If the Tomcat web server is not running, start Tomcat
Display the URL of the web page in the web browser

The exact parameters of the web server are determined by several options. Most of them can be set in the JSP page's executor. These parameters are described in the next chapter.

The URL of the page in the web browser is largely determined by the location of the page. You can define the query string appended at the end of the URL by setting the Request Parameters property of the JSP page.

By default, if you run a JSP, the Tomcat web server is started, and subsequent executions of this or other pages use this instance of the server. If you have modified the page between executions, the new version of the page is always reloaded into the server, which eleminates the need to restart the server each time you modify a page.

In some cases, however, you may want to explicitly tell the IDE to restart the server. An example of such a situation is when you have modified a JavaBean used by the page. As beans can not be reloaded, the server needs to be restarted. You can force server restart by using the Execute (restart server) action. Alternatively, you can use the Terminate Process action on the server process node in the Execution window (Running workspace).

The IDE may restart the server in some cases also when you use the Execute action. The cases when the server is restarted include the situation when the executed JSP resides on a different filesystem than the originally executed page, or when you have used the Build or Clean actions on any page.

5.2 Setting executor properties

For every page, you can set an Executor in the page object's property sheet, in the Execution tab. This property determines which execution service will be used for executing this JSP. You can set up several JSP execution services, and each page may use a different executor.

JSP executors can be set up in the Project | Settings menu. Under Execution Types, you will find JSP Execution. Follows the meaning of some of the JSP Execution properties:

Port - port on which the server will be started
Context base URL - a URI which will be a "prefix" for the application within the web server. So for example, if Context base URI is myapp and you are running a page with URI /pages/hello.jsp, then the URL for this page in the web server will be http://localhost:8080/myapp/pages/hello.jsp.

These properties affect the server configuration file generated by the execute action. The configuration file is also affected by other ways. Notably, the document base of the server is set to the root of the filesystem, which contains the executed JSP.

5.3 Setting the web browser

By default, your pages will be displayed in the IDE built-in web browser (ICEBrowser 4.0). However, you can set any browser of your choice in the JSP options: choose Tools | Global Options in the main menu. In the Global Options window, select the JSP node. Then customize the Web Browser property.