5
JSP Primer

Oracle Application Server Containers for J2EE (OC4J) includes a JavaServer Pages (JSP) container that is fully compliant with the JSP 1.2 specification. This chapter covers the basics of running JSP applications in the OC4J environment. There is also a brief JSP review, although it is assumed that you are at least somewhat familiar with JSP technology.

There are a few assumptions before you try running the primers. See "Introduction to OC4J Standalone".

This chapter includes the following sections:

For a complete description of Web application deployment, see "Deploying Applications".

For detailed information about the Oracle JSP implementation, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide .

A Brief Overview of JavaServer Pages Technology

Here is a quick JSP overview in the following sections:

What Is JavaServer Pages Technology?

JavaServer Pages, a part of the J2EE platform, is a technology that provides a convenient way to generate dynamic content in pages that are output by a Web application. This technology, which is closely coupled with Java servlet technology, allows you to include Java code snippets and calls to external Java components within the HTML code, or other markup code such as XML, of your Web pages. JSP technology works nicely as a front-end for business logic and dynamic functionality encapsulated in JavaBeans and Enterprise JavaBeans (EJB).

Traditional JSP syntax within HTML or other code is designated by being enclosed within <%...%> syntax. There are variations on this: <%=...%> to designate expressions or <%!...%> to designate declarations, for example.

Note:

The JSP 1.2 specification introduces an XML-compatible JSP syntax as an alternative to the traditional syntax. This allows you to produce JSP pages that are syntactically valid XML documents. The XML-compatible syntax is described in the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

A JSP page is translated into a Java servlet, typically at the time that it is requested from a client. The JSP translator is triggered by the .jsp file name extension in a URL. The translated page is then executed, processing HTTP requests and generating responses similarly to any other servlet. Coding a JSP page is more convenient than coding the equivalent servlet.

JSP pages are fully interoperable with servlets. A JSP page can include output from a servlet or forward to a servlet, and a servlet can include output from a JSP page or forward to a JSP page.

Here is the code for a simple JSP page, welcomeuser.jsp:

<HTML> 
<HEAD><TITLE>The Welcome User JSP</TITLE></HEAD> 
<BODY> 
<% String user=request.getParameter("user"); %> 
<H3>Welcome <%= (user==null) ? "" : user %>!</H3> 
<P><B> Today is <%= new java.util.Date() %>. Have a fabulous day! :-)</B></P> 
<B>Enter name:</B> 
<FORM METHOD=get> 
<INPUT TYPE="text" NAME="user" SIZE=15> 
<INPUT TYPE="submit" VALUE="Submit name"> 
</FORM> 
</BODY> 
</HTML>

This JSP page will produce something like the following output if the user inputs the name "Amy":

Welcome Amy! 

Today is Wed Jun 21 13:42:23 PDT 2000. Have a fabulous day! :-)

JSP Translation and Runtime Flow

Figure 5-1 shows the flow of execution when a user runs a JSP page, specifying its URL in the browser. Assume that Hello.jsp accesses a database.

Because of the .jsp file name extension, the following steps occur automatically:

The JSP translator is invoked, translating Hello.jsp and producing the file Hello.java.
The Java compiler is invoked, creating Hello.class.
Hello.class is executed as a servlet, using the JSP runtime library.
The Hello class accesses the database through JDBC (or perhaps SQLJ), as appropriate, and sends its output to the browser.

Figure 5-1 JSP Translation and Runtime Flow

Text description of the illustration o_1017.gif

Key JSP Advantages

For most situations, there are at least two general advantages to using JSP pages instead of servlets:

Coding convenience: JSP syntax provides a shortcut for coding dynamic Web pages, typically requiring much less code than equivalent servlet code. The JSP translator also automatically handles some servlet coding overhead for you, such as implementing standard JSP or servlet interfaces and creating HTTP sessions. JSP tag libraries, typically supplied with J2EE products such as OC4J, provide even further programming convenience.
Separation of static content and dynamic content: Realistically, a JSP developer will need some knowledge of Java. However, JSP technology attempts to allow some separation between the HTML code development for static content, and the Java code development for business logic and dynamic content. This makes JSP programming accessible and attractive to Web designers, as it simplifies the division of maintenance responsibilities between presentation and layout specialists who might be more proficient in HTML than in Java, and code specialists who might be more proficient in Java than in HTML. In a typical JSP page, most Java code and business logic will not be within snippets embedded in the JSP page. Instead, business logic will be in JavaBeans or Enterprise JavaBeans that are invoked from the JSP page.

Overview of Oracle Value-Added Features for JSP Pages

The OC4J JSP implementation provides the following extended functionality through custom tag libraries and custom JavaBeans and classes that are generally portable to other JSP environments. These features are documented in the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.

Support for the JavaServer Pages Standard Tag Library (JSTL)
Extended types implemented as JavaBeans that can have a specified scope
JspScopeListener for event-handling
Integration with XML and XSL
Data-access tag library (sometimes referred to as "SQL tags") and JavaBeans
The JSP Markup Language (JML) custom tag library, which reduces the level of Java proficiency required for JSP development
Oracle Personalization tag library
OracleAS Web Services tag library
Tag libraries and JavaBeans for uploading files, downloading files, and sending e-mail from within an application
EJB tag library
Additional utility tags (such as for displaying dates and currency amounts appropriately for a specified locale)

In addition, the OC4J JSP container offers integration with caching technologies, documented in the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference:

JESI tags for Edge Side Includes
Web Object Cache tags and API

The OC4J JSP container also supports Oracle-specific programming extensions, such as for globalization support. These are documented in the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide:

Running a Simple JSP Page

This section shows you how to run the elementary JSP example from earlier in this chapter.

Create and Deploy welcomeuser.jsp

Copy or type the sample code from "What Is JavaServer Pages Technology?" into a file, and save it as welcomeuser.jsp.

For convenience, you can place this file under the OC4J default Web application, the base location of which is the j2ee/home/default-web-app directory. For example, you can place welcomeuser.jsp in the j2ee/home/default-web-app/examples/jsp directory.

Run welcomeuser.jsp

When specifying a URL to execute a JSP page in OC4J, note the following:

By default, OC4J standalone uses port 8888.
The context path for the OC4J default Web application is "/".
The URL path maps to the directory path beneath the default Web application directory (or other Web application directory, as applicable).

For example, if you place welcomeuser.jsp in the j2ee/home/default-web-app/examples/jsp directory, you can run the page through the OC4J Web server with a URL such as the following:

http://host:port/examples/jsp/welcomeuser.jsp

When you first run the page, you will see something like the following output:

Text description of jspprima.gif follows

Text description of the illustration jspprima.gif

Submitting a name, such as "Amy", rewrites the URL to indicate the input:

http://host:port/examples/jsp/welcomeuser.jsp?user=Amy

and updates the page:

Text description of jspprim2.gif follows

Text description of the illustration jspprim2.gif

Running a JSP Page That Invokes a JavaBean

As mentioned earlier, JSP technology works nicely as a front-end for business logic and dynamic functionality encapsulated in JavaBeans. This section contains the code for a JavaBean and a JSP page that calls it.

The steps involved are covered in the following sections:

Create the JSP: usebean.jsp

This section lists the source for a JSP page that uses the standard JSP jsp:useBean tag to invoke a JavaBean. To run the code, you can copy or type it into a file called usebean.jsp. The numbers in JSP comment statements along the right edge correspond to the notes following the code.

<%@ page import="beans.NameBean"  %>                            <%--1--%>

<jsp:useBean id="pageBean" class="beans.NameBean" scope="page" /><%--2--%>
<jsp:setProperty name="pageBean" property="*" />                <%--3--%>

<HTML>
<HEAD> <TITLE> The Use Bean JSP </TITLE> </HEAD>
<BODY BGCOLOR=white>

<H3> Welcome to the Use Bean JSP </H3>

<% if (pageBean.getNewName().equals("")) { %>
  I don't know you. 
<% } else { %>
  Hello <%= pageBean.getNewName() %> !
<%  } %> 

<P>May we have your name?
<FORM METHOD=get>
<INPUT TYPE=TEXT name=newName size = 20>
<INPUT TYPE=SUBMIT VALUE="Submit name">
</FORM>
</BODY>
</HTML>

Code Notes

This is a JSP construct called a page directive. In this case, it imports the JavaBean class. (There are other uses for page directives, and other kinds of directives.)
The standard jsp:useBean tag instantiates the JavaBean, specifying the package name, class name, and instance name. A scope setting of page specifies that the JavaBean instance is accessible only from the JSP page where it was created. Other possible scopes are request, session, and application.
The standard jsp:setProperty tag sets the values of one or more properties for the specified bean instance. A property setting of * results in iteration over the HTTP request parameters, matching bean property names with request parameter names, and setting bean property values according to the corresponding request parameter values. In this case, the only bean property is newName. This corresponds to the newName HTTP request parameter specified in the HTML forms code in the page. (For use with the jsp:useBean tag, in addition to the jsp:setProperty tag, there is a jsp:getProperty tag to retrieve parameter values.)

For general information about any of these topics, see the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

Create the JavaBean: NameBean.java

Here is the code for the JavaBean class, NameBean. The package name specified here must be consistent with the page directive and the jsp:useBean tag of the JSP page. To run the JSP page, you can copy or type this code into a file called NameBean.java and then compile it. The resulting NameBean.class file must be placed in a beans subdirectory under WEB-INF/classes in the WAR file you use for deployment, according to the beans package name.

package beans;

public class NameBean {

  String newName="";

  public void NameBean() {  }

  public String getNewName() {
    return newName;
  }
  public void setNewName(String newName) {
    this.newName = newName;
  }
}

Deploy usebean.jsp and Namebean.java

As with the earlier JSP example in this chapter, you can place usebean.jsp in the j2ee/home/default-web-app/examples/jsp directory.

Files for the JavaBean class--NameBean.class and optionally NameBean.java--should go under the WEB-INF directory, which is a standard J2EE Web application mechanism. In this case, this would be specifically as follows (for UNIX, or equivalently for Windows NT):

j2ee/home/default-web-app/WEB-INF/classes/beans

The WEB-INF/classes directory and any subdirectories are automatically in your Web application classpath. In this example, NameBean.class must be in the beans subdirectory, because that is the package name specified in the code. You must create the beans subdirectory.

Run usebean.jsp

With usebean.jsp being in the default-web-app/examples/jsp directory, as with the earlier example in this chapter, you will use a similar URL to run it from a browser:

http://host:port/examples/jsp/usebean.jsp

This example, as before, uses host as the name of the system where OC4J and the application are installed. The default port is 8888.

When you run this page, you will initially see the following output:

Text description of jspprim3.gif follows

Text description of the illustration jspprim3.gif

Once you submit a name, such as "Ike", the page is updated (but still prompts you in case you want to enter another name):

Text description of jspprim4.gif follows

Text description of the illustration jspprim4.gif

Running a JSP Page That Uses Custom Tags

The Sun Microsystems JavaServer Pages specification includes standard tags to use in JSP pages to perform various tasks. An example is the jsp:useBean tag employed in "Running a JSP Page That Invokes a JavaBean". The JSP specification also outlines a standard framework that allows vendors to offer their own custom tag libraries in a portable way.

Each custom tag library has a tag library descriptor (TLD) file that specifies the tags, tag attributes, and other properties of the library. Each tag requires support classes, at least a tag handler class with the code to execute tag semantics. (Tag handler classes implement standard tag interfaces, according to the JSP specification.) These classes must be available to your Web application.

OC4J supplies portable tag libraries with functionality in several areas. This section shows an example that uses tags from the Oracle data-access (SQL) tag library to access and query a database and output the results to the browser. A standard JSP taglib directive is used to access the TLD file and to specify a tag prefix to use for the tags of this library.

Here are the steps in using a JSP tag library:

The steps involved are covered in the following sections:

For information about the standard tag library framework, including TLD files, tag handler classes, and the taglib directive, refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

Create the JSP Page: sqltagquery.jsp

This section provides the source for a JSP page that uses data-access tags, supplied with OC4J, to open a database connection, run a simple query, and output the results as an HTML table. To run the page, you can copy or type the code into a file called sqltagquery.jsp. The numbers in JSP comment statements along the right edge correspond to the notes following the code.

<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/sqltaglib.tld"
           prefix="sql" %>                                   <%--1--%>
<HTML>
  <HEAD>
    <TITLE>The SQL Tag Query JSP</TITLE>
  </HEAD>
  <BODY BGCOLOR="#FFFFFF">
    <HR>
    <sql:dbOpen dataSource= "jdbc/OracleDS" >                <%--2--%>
       <sql:dbQuery>                                         <%--3--%>
             select * from EMP  
       </sql:dbQuery>
    </sql:dbOpen>                                            <%--4--%>
    <HR>
  </BODY>
</HTML>

Code Notes

The taglib directive uses a JSP 1.2-style uri value, which is used as a keyword instead of actually indicating a physical location. (See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about such URI functionality.) The taglib directive also specifies the tag prefix, "sql", to use in any tag statements.
OracleDS is the JNDI name of a data source that is available by default through the OC4J data-sources.xml file. Verify that the data source points to an appropriate database. For introductory information about data sources, see Chapter 3, "Data Sources Primer".
By default, the dbQuery tag uses the database connection established by the surrounding dbOpen tag. Also by default, the dbQuery tag outputs its results as an HTML table. Other choices are JDBC result set, XML string, or XML DOM object.
Because no explicit connection ID is specified in the dbOpen start-tag, the database connection is automatically closed when the dbOpen end-tag is reached.

For more information about the data-access tag library that is supplied with OC4J, refer to the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.

Files for Tag Library Support

JSP applications require some JAR files that are installed with OC4J:

ojsp.jar (JSP container)
ojsputil.jar (OC4J tag libraries and utilities)
xmlparserv2.jar (XML parser)
xsu12.jar (XML-SQL utility)

The tag handler class files and TLD files, including the tag handlers and TLD file (sqltaglib.tld) for this example, are in ojsputil.jar. Verify that ojsp.jar, ojsputil.jar, xmlparserv2.jar, and xsu12.jar are available to the Web application.

Note:

The library ojsputil.jar also gives you access to data-access JavaBeans and other Java utility classes that come with OC4J. These classes are described in the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.

Deploy sqltagquery.jsp

As with the earlier JSP examples in this chapter, you can place sqltagquery.jsp in the j2ee/home/default-web-app/examples/jsp directory.

Run sqltagquery.jsp

With sqltagquery.jsp being in the j2ee/home/default-web-app/examples/jsp directory, as with earlier examples in this chapter, you will use a similar URL to run the page from a browser. This example, as before, uses host as the name of the system where OC4J and the application are installed:

http://host:port/examples/jsp/sqltagquery.jsp

This assumes that the OC4J Web server is running, and that you have run the standard SQL scripts for Oracle demos to set up a database. The default port is 8888.

This page produces output such as the following.

Text description of scn_stag.gif follows.

Text description of the illustration scn_stag.gif

Important:

The Oracle JDBC driver classes are supplied with Oracle Application Server, but you must ensure that they are compatible with your JDK and your database version. The classes12.zip or classes12.jar library is for JDK 1.2.x or higher. Also, the driver release number must be compatible with your database release number.

5 JSP Primer

A Brief Overview of JavaServer Pages Technology

What Is JavaServer Pages Technology?

JSP Translation and Runtime Flow

Figure 5-1 JSP Translation and Runtime Flow

Key JSP Advantages

Overview of Oracle Value-Added Features for JSP Pages

Running a Simple JSP Page

Create and Deploy welcomeuser.jsp

Run welcomeuser.jsp

Running a JSP Page That Invokes a JavaBean

Create the JSP: usebean.jsp

Code Notes

Create the JavaBean: NameBean.java

Deploy usebean.jsp and Namebean.java

Run usebean.jsp

Running a JSP Page That Uses Custom Tags

Create the JSP Page: sqltagquery.jsp

Code Notes

Files for Tag Library Support

Deploy sqltagquery.jsp

Run sqltagquery.jsp

5
JSP Primer