JSP page authoring
JSP pages can be written in any well-formed language, including
XML, but they are usually written in HTML. In PowerBuilder, you
create JSP pages using any of the page wizards on the Web page of
the New dialog box, and you edit them in much the same way as any
other HTML page. When you create a new Web page, the wizard gives
it the extension .jsp by default instead of .htm.
JSP authoring elements
The standard HTML elements, controls, and client-side scripts
you can add to a Web page that you deploy to PowerDynamo or ASP
are also available to JSP pages. In addition, JSP-specific elements
are available in the development environment for editing JSP Web
pages:
Page view icons
In the Page view, JSP standard actions and scripting elements
are represented by icons showing the element’s delimiters.
When you select a scripting element or a 4GL server-side
event, Java is the only language available in the script editor.
| Icon | Description |
|---|---|
| <%> | Server side scriplet |
| <%=> | Server side expression |
| <%!> | Server side declaration |
| <jsp:> | Standard action, such as <jsp:useBean …> |
| </jsp:> | Close tag of standard action, such as </jsp:useBean> |
| <jsp:/> | Self-closing standard action, such as <jsp:getProperty … /> |
| <ctl:> | Custom tag, such as <j2ee:action …> |
| </ctl:> | Close tag of custom tag, such as </j2ee:action> |
| <ctl:/> | Self-closing custom tag, such as <j2ee:action … /> |
| <?:> | Unknown custom tag |
| <%@ins> | Include page directive, such as <%@ include … %> |
JSP actions
Actions are standard tags that
perform common actions. All JSP standard actions use the prefix jsp.
You can insert any of the following actions:
<jsp:useBean>
The useBean, getProperty,
and setProperty actions are all used with JavaBeans components.
The useBean id attribute is the name of the bean
and corresponds to the name attribute for getProperty and setProperty.
The useBean action locates or instantiates a
JavaBeans component:
|
1 |
<jsp:useBean id="labelLink" scope="session" class="LinkBean.labelLink" /> |
The bean class and classes required by the bean class must
be deployed under a JavaCode base that is available to the Web Application
where the JSP is installed.
<jsp:getProperty>
The getProperty action
gets the value of a JavaBeans component property so that you can
display it in a result page:
|
1 |
<jsp:getProperty name="labelLink" property="url" /> |
<jsp:setProperty>
The setProperty action
sets a property value or values in a JavaBeans component:
|
1 |
<jsp:setProperty name="labelLink" property="url" value="<%= labelLink.getURL() %>"/> |
<jsp:include>
The include action
includes a static file or sends a request to a dynamic file:
|
1 |
<jsp:include page="cart.html" flush="true" /> |
<jsp:forward>
The forward action
forwards a client request to an HTML file, JSP file, or servlet
for processing:
|
1 |
<jsp:forward page="/jsp/datafiles/ListSort.jsp" /> |
<jsp:param>
The param action
specifies request parameters in the body of an include or forward action.
It can also be used in the body of a params action.
|
1 |
<jsp:forward page="/jsp/datafiles/ListSort.jsp" /><br /> <jsp:param name="bgColor" value="blue" /><br /> </jsp:forward> |
<jsp:params>
The params action
can be used only in the body of a plugin action
to enclose the applet parameters specified by param actions.
<jsp:plugin>
The plugin action
downloads plug-in software to the Web browser to execute an applet
or JavaBeans component. It generates HTML <embed> or <object> elements
in the page. You can use the params and param actions
to specify parameters required by the plug-in, and the fallback action
to specify the text that displays if the browser does not support <embed> or <object> elements:
|
1 |
<jsp:plugin type=applet code="Calc.class" codebase="/mathutils" ><br /> <jsp:params><br /> <jsp:param name="multiplier" value="multipliers/tax.val"/><br /> </jsp:params><br /> <jsp:fallback><br /> <p> unable to start plugin </p><br /> </jsp:fallback><br /> </jsp:plugin> |
<jsp:fallback>
The fallback action
can be used only in the body of a plugin action
to specify the text that displays if the browser does not support <embed> or <object> elements.
Inserting an action
To insert an action in a JSP page:
-
Select Insert>JSP Standard Action
from the menu bar and select an action:
-
In the dialog box that displays, specify the values
of the action’s attributes.A Y in the Required
column indicates that you must specify a value for the attribute:
For a description of each of the values available for the
scope attribute of the <jsp:usebean> action,
see “Scopes”.
Adding applets and JavaBeans
Adding applets and JavaBeans to a JSP page inserts the appropriate
JSP action. To view JavaBeans and applets on the Components tab
of the System Tree, you must make sure that the component that you
want and the WTInfo90.jar file are included
in the Java class path. The WTInfo90.jar is
installed in the SybaseSharedWeb Targets directory.
It should be included in the class path by default.
Adding applets
When you drag an applet from the Components tab to a JSP page
in Page view or Source view, the jsp:plugin Properties dialog box
displays with default values for the applet you selected. When you
click OK, the applet is added to the page in a jsp:plugin action
tag.
When you add an applet to a JSP page, you must make sure the
applet classes are stored in a location accessible to client browsers.
You can assign this location, using a file or http protocol, to
the codebase attribute of the jsp:plugin directive.
Adding JavaBeans and JavaBean properties
When you drag a JavaBean from the Components tab to a JSP
page in Page view or Source view, the jsp:useBean Properties dialog
box displays with default values for the JavaBean you selected.
When you click OK, the JavaBean is added to the page in a jsp:useBean
action tag. If the JavaBean is in a class file, the class file is
added to the Web-Infclasses directory for your target.
If the JavaBean is in an archive file, the archive file is added
to the Web-Inflib directory
for your target.
JavaBean properties with both read and write permissions are
listed twice on the Components tab: one time for the read property
and another time for the write property. The icon for the read-enabled
property is a yellow arrow pointing upward. The icon for the write-enabled
property is a green arrow pointing downward.
When you drag a read-enabled JavaBean property from the Components
tab to a JSP page, the jsp:getProperty Properties dialog box displays
with default values for the JavaBean property you selected. When
you drag a write-enabled JavaBean property from the Components tab
to a JSP page, the jsp:setProperty Properties dialog box displays
with default values for the JavaBean property you selected.
Directives
Directives are messages
to the JSP engine that provide global information for the page or
include a file of text or code. Directives begin with the character sequence <%@ followed
by the name of the directive and one or more attribute definitions.
They end with the character sequence %>.
There are three directives: page, include,
and taglib.
Page directive
The page directive
defines attributes that apply to an entire JSP page, including language,
the class being extended, packages imported for the entire page,
the size of the buffer, and the name of an error page. For example:
|
1 |
<%@ page language="java" import="mypkg.*"<br /> session="true" errorPage="ErrorPage.jsp" %> |
For more information about error pages, see “Error handling”.
Include directive
The include directive
includes a static file, parsing the file’s JSP elements:
|
1 |
<%@ include file="header.htm" %> |
Include directive and include standard
tag Note that the include directive parses the file’s
contents, whereas the include tag does not.
Taglib directive
The taglib directive
defines the name of a tag library and its prefix for any custom
tags used in a JSP page:
|
1 |
<%@ taglib uri="http://www.mycorp/printtags"<br /> prefix="print" %> |
If the tag library with the prefix print includes
an element called doPrintPreview, this is the
syntax for using that element later in the page:
|
1 |
<print:doPrintPreview> |
|
1 |
... |
|
1 |
</print> |
For more information, see “Custom tags”.
Inserting a directive
To insert a directive in a JSP page:
-
Right-click inside a page in Page view
and select Page Properties from the pop-up menu.or
Right-click inside the <BODY
…> tag in Source view and select Properties
from the pop-up menu. -
In the Page Properties or Body Properties dialog
box, select the JSP Directives tab and click the New icon. -
Select the type of directive you want to add in
the drop-down list box in the Name column.
-
Click inside the Value column, then click the
Browse (…) button that displays at the right of the Value column.Complete the dialog box that displays.
The type of dialog box that displays depends on the type of
directive you are adding. The Page Directive Attributes dialog box
looks like this:
JSP scripting elements
Scripting elements manipulate
objects and perform computations. The character sequence that precedes
a scripting element depends on the element’s type: <% for
a scriptlet, <%= for
an expression, and <%! for
a declaration. Scriptlets, expressions, declarations, and server-side
comments are all closed with the sequence %>.
Scriptlets
A scriptlet contains
a code fragment valid in the page-scripting language (usually Java,
but other languages can be defined in the page directive):
|
1 |
<% cart.processRequest(request); %> |
Expressions
An expression contains an expression valid in the page-scripting
language:
|
1 |
Value="<%= request.getParameter("amount") %>" |
Declarations
A declaration declares
variables or methods valid in the page-scripting language:
|
1 |
<%! Connection myconnection; String mystring; %> |
Comments
You can add two types
of comments to a JSP file:
- HTML comments optionally
contain an expression. They are sent to the client and can be viewed
in the page source:1<!-- Copyright (C) 2002 Acme Software --> - Hidden comments document the source file and are
not sent to the client:1<%-- Add new module here --%>
To insert a comment, type it in the Source view.
Inserting a scripting element
To insert a scripting element in a JSP page:
-
Open a JSP page, select the Page tab, and
right-click in the Script editor. -
From the pop-up menu, select New Script>Server>JSP
and then the delimiters for the type of scripting element you want.
-
Type the script, expression, or declaration in
the Script editor.
Implicit objects
When a JSP page processes
a request, it has access to a set of implicit objects, each of which
is associated with a given scope. Other objects can be created in scripts.
These created objects have a scope attribute that defines where
the reference to that object is created and removed.
References to an object created in script are stored in the pageContext, request, session,
or application implicit object, according to
the object’s scope.
| Implicit object | Description | Scope |
|---|---|---|
| request | The request triggering the servlet invocation. | Request |
| response | The response to the request that triggered the servlet invocation. |
Page |
| pageContext | The page context for this JSP. | Page |
| session | The session object created for the requesting client (if any). |
Session |
| application | The servlet context obtained from the servlet configuration, as in the call getservletConfig().getContext(). |
Application |
| out | An object that writes to the output stream. | Page |
| config | The ServletConfig instance for this JSP. |
Page |
| page | The instance of this page’s implementation class that is processing the current request. A synonym for this when the programming language is Java. |
Page |
| exception | The uncaught Throwable exception that caused the error page to be invoked. |
Page |
Implicit objects display on the Language tab page in the System
Tree.
With the exception of the exception object,
implicit objects are always available within scriptlets and expressions.
If the JSP is an error page (the page directive’s isErrorPage attribute
is set to true), the exception implicit object
is also available.
You can often use an implicit object or a Web Target object
model wrapper class to obtain the same functionality. For example,
calling out.println in a server-side
event is equivalent to calling psDocument.Write.
For more information about the exception implicit object,
see “Error handling”.
For more information about server-side events, see “Writing server scripts”.
Scopes
There are four scopes for objects in a JSP application.
| Scope | Description |
|---|---|
| Page | Accessible only in the page in which the object is created. Released when the response is returned or the request forwarded. |
| Request | Accessible from pages processing the request in which the object is created. Released when the request has been processed. |
| Session | Accessible from pages processing requests in the same session in which the object is created. Released when the session ends. |
| Application | Accessible from pages processing requests in the same application in which the object is created. Released when the runtime environment reclaims the ServletContext. |
Custom tags
Custom tags, also called
tag extensions or custom actions, extend the capabilities of JSP
pages. Tag libraries define a set of actions to be used within a
JSP page for a specific purpose, such as handling SQL requests.
The tag libraries you use in PowerBuilder must be built using another
tool such as PowerJ, although you can create custom tags for Web
services using a PowerBuilder wizard (see “JSP Web services”).
The URI identifying a tag library is associated with a Tag
Library Descriptor (TLD) file and with tag handler classes.
Tag handlers
A tag handler is a Java class that defines the semantics of
an action. The implementation class for the JSP instantiates a tag
handler object for each action in the page. Tag handler objects
implement the javax.servlet.jsp.tagext.Tag interface,
which defines basic methods required by all tag handlers, including doStartTag and doEndTag.
The BodyTag interface extends the Tag interface
by adding methods that enable the handler to manipulate its body.
Packaging tag libraries
To associate a tag library with a JSP page, you use a taglib directive
that identifies the URI where the tag library’s TLD file
can be located. The TLD file must be in (or deployed to) the class
path of the JSP container and is usually placed in the Web application’s WEB-INF /tlds directory.
The class files for the tag library must also be in the class path
of the JSP container. Typically they are placed in the Web application’s WEB-INF/classes directory
or in a JAR file in the WEB-INF/lib directory.
For information on adding a taglib directive
to a JSP page, see “Taglib directive”.
Using tag libraries in PowerBuilder JSP pages
In PowerBuilder, you can add tag libraries to a JSP page from
the Components tab of the System Tree as well as from the JSP Directives
page of the Page Properties dialog box. A tag library must be in
the PowerBuilder custom tag library search path in order to be listed
on the Components tab. You can add directories or tag library descriptor
files to the custom tag library search path on the JSP page of the
System Options dialog box.
When you add a tag library to a JSP page, a dialog box prompts
you to enter a prefix. The prefix you enter is used as a shorthand
entry to refer to the tag library when you add a tag from the library
to the page. PowerBuilder automatically includes the path to the
TLD file in the web.xml file for the target to
which the page belongs. PowerBuilder also adds an entry for the
tag library on the Tag Libraries page of the Deployment Configuration
Properties dialog box for the target.
For more information about the Tag Libraries page of the Deployment Configuration
Properties dialog box, see “Tag Libraries”.
Error handling
When a client request
is processed, runtime errors can occur in the body of the implementation
class for the JSP or in Java code that is called by the page. These
exceptions can be handled in the code in the JSP page, using the
Java language’s exception mechanism.
Uncaught exceptions
Exceptions that are thrown from the body of the implementation
class that are not caught can be handled using an error page. You
specify the error page using a page directive. Both the client request
and the uncaught exception are forwarded to the error page. The java.lang.Throwable exception
is stored in the javax.ServletRequest instance
for the client request using the putAttribute method,
with the name javax.servlet.jsp.jspException.
Using an error page JSP
If you specify a JSP page
as the error page, you can use its implicit exception variable
to obtain information about the exception. The exception object
is of type java.lang.Throwable and is initialized
to the Throwable reference when the uncaught
exception is thrown. For more information about the exception object,
see “Implicit objects”.
To specify an error page for a JSP, set its errorPage attribute
to the URL of the error page in a page directive:
|
1 |
<%@ page errorPage="ErrorPage.jsp" %> |
To define a JSP as an error page, set its isErrorPage attribute
to true:
|
1 |
<%@ page isErrorPage="true" %> |
This sample error page uses the exception object’s toString method
to return the name of the class of the object causing the exception
and the result of the getMessage method for the
object. If no message string was provided, toString returns
only the name of the class.
The example also uses the getParameterNames and getAttributeNames methods of
the request object to obtain information about the request.
|
1 |
<%@ page language="java" import="java.util.*"<br /> isErrorPage="true" %><br /> <H1 align="Center">Exceptions</H1><br /> <br><br /> <%= exception.toString() %><br /> <%! Enumeration parmNames; %><br /> <%! Enumeration attrNames; %><br /> <br>Parameters:<br /> <%<br /> parmNames = request.getParameterNames();<br /> while (parmNames.hasMoreElements()) {<br /> %><br /> <br><%= parmNames.nextElement().toString() %><br /> <%<br /> }<br /> %><br /> <br><br /> Attributes:<%<br /> attrNames = request.getAttributeNames();<br /> while (attrNames.hasMoreElements()){<br /> %><br /> <br><%= attrNames.nextElement().toString() %><br /> <%<br /> }<br /> %> |