If session data must be of a user-defined type, the data class should be serializable. Furthermore, the session should store the serialized representation of the data object, and serialization should, of course, be compatible across versions of the data class.
Quick reference
If you are familiar with the JSP specification, you might find this
quick reference useful. The following table gives a brief description of the
JSP tags and reserved words.
JSP tags
The following table describes the basic tags in a JSP page. Each short-hand
tag has an XML equivalent. For more details, see the related section later in
this document.
| JSP tag |
Syntax
|
Description |
| Scriptlet |
<% java_code %>
...or use XML equivalent...
<jsp:scriptlet>
java_code
</jsp:scriptlet>
|
Embeds Java source code scriptlet
within your HTML. The Java is executed and its output is inserted in sequence
with the rest of the HTML in the page. For more, see Scriptlets.
|
| Directive |
<%@ dir_type dir_attr %>
...or use XML equivalent...
<jsp:directive.dir_type
dir_attr /> |
Gives a directive to the Application
Server. The dir_type determines the type of directive being given,
which can accept a list of directives given as name="quotedValue" pairs
separated by white space.
See Directives.
|
| Declaration |
<%! declaration %>
...or use XML equivalent...
<jsp:declaration>
declaration;
</jsp:declaration>
|
Declares a variable or method that may be referenced
by other declarations, scriptlets, or expressions in the page.
See Declarations.
|
| Expression |
<%=
expression %>
...or use XML equivalent...
<jsp:expression>
expression
</expression>
|
Defines a Java expression that is evaluated
at page request time, converted to a String, and sent inline to the output stream of the JSP response.
See Expressions.
|
| Actions |
<jsp:useBean ... >
JSP body is included if
bean is instantiated here
</jsp:useBean>
<jsp:setProperty ... >
<jsp:getProperty ... >
<jsp:include ... >
<jsp:forward ... >
<jsp:plugin ... >
|
JSP Actions encompass the more advanced features of JSP, and only use XML
syntax. All these actions are supported as defined in the JSP 1.0
specification. See Action.
|
Reserved words
JSP reserves these words for 'implicit objects' in scriptlets and
expressions. These implicit objects represent java objects that provide useful
methods and information for your JSP page. WebLogic JSP implements all of the
implicit objects defined in the JSP 1.0 specification. The JSP API is
described in the JavaDoc available at the The JSP
Homepage.
Note: You may only use these implicit objects within scriptlets or expressions. Using these
keywords from a method defined in a declaration will cause a translation-time
compilation error, since your page is referencing an undefined variable.
- request
- request represents the HttpServletRequest object. It contains information
about the request from the browser, and has several useful methods for
getting cookie, header, and session data.
- response
- response represents the HttpServletResponse object, and several useful
methods for setting the response sent back to the browser from your
JSP page such as cookies, and other header information.
Warning: You cannot use the response.getWriter() method from within a JSP page, or a
runtime Exception will be thrown. You should use the out keyword to send the JSP response back to the browser from
within your scriptlet code wherever possible. WebLogic's implementation of the
JspWriter uses the
ServletOutputStream.
This implies that you can use
response.getServletOutputStream(), but
this is implementation specific. To keep your code maintainable and portable,
you should use the out keyword.
- out
-
out is an instance of
javax.jsp.JspWriter
which has several methods you can use to send output back to the browser.
Hint: If you are using a method that requires an outputStream, then JspWriter will not work. You can work around this by supplying a
buffered stream, then writing this to out. For example, here is how to write an exception stack trace to out:
ByteArrayOutputStream ostr = new ByteArrayOutputStream();
exception.printStackTrace(new PrintWriter(ostr));
out.print(ostr);
- pageContext
- pageContext represents a javax.servlet.jsp.PageContext object. It is
a convenience API to access various scoped namespaces, servlet-related
objects, and provides wrapper methods for common servlet-related
functionality.
- session
- session represents a javax.servlet.http.HttpSession object for the
request. The session directive is set to true by default, so the session is valid by default. The JSP
1.0 specification states that if the session directive is set to
false, then the session
keyword will result in a fatal translation time error. For more
information on using sessions with servlets, see the Developer Guide,
Using WebLogic HTTP
Servlets.
- application
- application represents a
javax.servlet.ServletContext. This can be useful for finding information
about the servlet engine and the servlet environment. The servlet requestDispatcher can also be accessed
through the ServletContext, but JSP
also provides the forward directive
for forwarding requests to other servlets, and the include directive for including output from other servlets.
- config
- config represents a
javax.servlet.ServletConfig. This provides access to the servlet instance
initialization parameters. Currently, there is no way to set initialization
arguments for a JSP page, unless you precompile is with the JSP Compiler and register it as a regular HTTP servlet.
For details, see
Registering user-written servlets.
- page
- page represents the servlet
instance generated from this JSP page. It is synonymous to the java keyword
this within your scriptlet code.
To use page, you must cast it up to
the class type of the servlet that
implements the JSP page, since it is defined as an instance of java.lang.Object. By default, the servlet
class is named after the JSP filename. Instead, we recommend that you simply
use the Java keyword this to reference
the servlet instance.
a
javax.servlet.ServletConfig. This provides access to the servlet instance
initialization parameters.
For more information on the underlying HTTP servlet framework, see the related
Developers Guide, Using WebLogic HTTP
Servlets.
Directives
You use directives to instruct WebLogic JSP to perform certain
functions or interpret the JSP page in a particular way. You can insert a
directive into the JSP page anywhere. The position is generally irrelevant
(except for the include directive), and you can
use multiple directive tags. The syntax can be written in two forms, shorthand
and XML, as shown here:
- Shorthand:
<%@ dir_type dir_attr %>
- XML:
<jsp:directive.dir_type dir_attr %>
Where dir_type specifies the directive
type, and dir_attr can be a list of
one or more directive attributes for that directive type.
All JSP1.0 directives are supported in WebLogic JSP.
Using a directive to set the character encoding
To specify a character encoding set, use the following directive at the top of the page:
<%@ page contentType="text/html; charset=custom-encoding" %>
Where custom-encoding is the cannonical name of the character set that is returned by the getEncoding methods of the InputStreamReader and OutputStreamWriter classes.
The taglib directive
The taglib directive is recognized,
but not supported. Its implementation mechanism is not defined in the JSP 1.0
specification. This would otherwise allow you to define and use custom JSP
tags. A taglib directive will raise a translation error.
Declarations
Use declarations to define variables and methods at the class scope level
in the generated JSP servlet. Declarations made between these tags are
accessible from other declarations and scriptlets in your JSP page.
For example:
<%!
int i=0;
String foo= "Hello";
private void bar() {
// ...java code here...
}
%>
Remember that class scope objects are shared between multiple threads
executing in the same instance of a servlet.
To guard against sharing violations, you should
synchronize class scope objects. If you are not confident writing thread-safe
code, you can declare your servlet as not-thread-safe, by including the
following directive:
<%@ page isThreadSafe="false" %>
Note: By default this is set to true. When you set this attribute to false,
the generated servlet implements the SingleThreadModel, which prevents multiple threads running in
the same servlet instance.
JSP scriptlets make up the Java body of your JSP servlet's HTTP response. You
may include a scriptlet in your JSP page using the shorthand or XML scriptlet
tags shown here:
- Shorthand:
<%
// Your Java code goes here
%>
- XML:
<jsp:scriptlet>
// Your Java code goes here
</jsp:scriptlet>
Notice these basics features:
- You can have multiple blocks of scriptlet Java code mixed with plain HTML.
The HTML response page provided by the generated JSP servlet is given by the
HTML and the output from the Java scriptlets in the sequence they appear in the
JSP page.
- You can switch between HTML and Java code anywhere, even within Java
constructs and blocks. Note in the example shown below
that we declare a Java loop, switch to HTML, then switch back to Java to close
the loop. The HTML within the loop is output multiple times as the loop
iterates.
- You can use the predefined variable out to print HTML text directly to the servlet output stream
from your Java code. Here we call the print() method to add a string to the HTTP page response.
- The Java tag is an "inline" tag; it doesn't force a paragraph.
You can include an expression in your JSP file using the tag:
<%= expr %>
Where expr is a Java expression
that is evaluated and its String
representation is placed inline in the HTML response page. It is shorthand for
<% out.print( expr ); %>
You can use it to make your HTML more readable in the JSP page. (This is
equivalent to the backtick in JHTML.) Note the use of the expression tag in the
next example.
A simple example
Here is a very simple JSP example that mixes HTML with embedded Java. The JSP
tags are highlighted in red.
<html>
<head><title>Hello World Test</title></head>
<body bgcolor=#ffffff>
<center>
<h1> <font color=#DB1260> Hello World Test </font></h1>
<font color=navy>
<%
out.print("Java-generated Hello World");
%>
</font>
<p> This is not Java!
<p><i>Middle stuff on page</i>
<p>
<font color=navy>
<%
for (int i = 1; i<=3; i++) {
%>
<h2>This is HTML in a Java loop! <%= i %> </h2>
<%
}
%>
</font>
</center>
</body>
</html>
Here is what the resulting page will look like after it is compiled:
Hello World Test
Java-generated Hello World
This is not Java!
Middle stuff on page
This is HTML in a Java loop! 1
This is HTML in a Java loop! 2
This is HTML in a Java loop! 3
|
Actions
Using JavaBeans in JSP
WebLogic JSP supports all of the functionality outlined in the JSP 1.0
specification with respect to the <jsp:useBean> tag. This allows you to instantiate Java
objects that comply with the JavaBean specification, and refer to them from
your JSP pages.
Complying with a JavaBean simply means that the objects should have:
- A public constructor that takes no arguments
- A setVariable() method for each variable field.
- A getVariable() method for each
variable field.
Instantiating the JavaBean object
The <jsp:useBean> tag will
attempt to retrieve an existing named Java object from an specific scope, and if not
found, may attempt to instantiate a new object and associate it with the name
given by the id attribute. The object
is stored in a location given by the scope attribute, which determines the availability of the
object. For example:
<jsp:useBean id="cart"
class="examples.jsp.ShoppingCart" scope="session"/>
will attempt to retrieve a Java object of type
examples.jsp.ShoppingCart
from the HTTP session under the
name cart. If it does not currently
exist, the JSP will attempt to create the new object, and store it in the HTTP
session under the name cart.
It is good practice to use an errorPage directive with the <jsp:useBean> tag since there are runtime exceptions that must
be caught. In this case, if the class cannot be created, an InstantiationException may be thrown.
You may use the type
attribute to cast the JavaBean type to another object or interface,
provided that it is a legal type cast operation within Java.
If you use the attribute without the class attribute, your JavaBean object must
already be present in the scope specified. If it is not legal, an InstantiationException will be thrown.
Doing setup work at JavaBean instantiation
The <jsp:useBean> tag syntax has
another format that allows you to define a body of JSP code that is executed when the
object is instantiated. The body is not executed if the names JavaBean
already exists in the specified scope.
This allows you to set up certain properties when the
object is first created such as:
<jsp:useBean id="cart" class="examples.jsp.ShoppingCart"
scope=session>
Creating the shopping cart now...
<jsp:setProperty name="cart"
property="cartName" value="music">
</jsp:useBean>
Note: If you use the type attribute without the class attribute, a JavaBean object is never instantiated, and
you should not attempt to use the tag format to include a body. Instead, you
should use the single tag format. In this instance, the JavaBean must exist in
the specified scope, or an InstantiationException is thrown. In this case, you must use an
errorPage directive to catch the
potential exception.
Using the JavaBean object
Once you have instantiated the JavaBean object, you can refer to it by its
id name in the JSP file as a
Java object. You can use it within scriplet tags and expression evaluator
tags, and you can invoke its setXxx()
or getXxx() methods using the
<jsp:setProperty> and
<jsp:getProperty> tags
respectively.
Defining the scope of a JavaBean object
Use the scope attribute to specify the
availability and life-span of the JavaBean object. The scope may be defined as
one of the following:
- page
- This is the default scope for a JavaBean, where the object is stored in
the javax.servlet.jsp.PageContext of
the current page. It is only available from the current invocation of this JSP
page. It is not available to included JSP pages, and shall be discarded upon
completion of this page request.
- request
- The object is stored in the current ServletRequest, and is available to other included JSP pages
that are passed the same request object. The object is discarded when the
current request is completed.
- session
- You use the session scope to store the JavaBean object in the HTTP
Session so that it may be tracked across several HTTP pages. The reference to
the JavaBean is stored in the page's HttpSession object. Your JSP pages must be able to participate
in a session to use this scope. That is, you must not have the page directive session set to false.
- application
- At the application scope level, your JavaBean object is stored in the
ServletContext. At present, this
implies that it is available to any other servlet or JSP page running in the
server. It is not available to other servers running in a WebLogic Cluster.
You will find more information on using JavaBeans in the JSP 1.0
specification.
Deploying applets from JSP
JSP provides a convenient way to generate HTML that contains the
appropriate client browser tag to include the Java Plugin in a web page.
The Java Plugin allows you to displace the JVM implementated by the client
web-browser with a JRE supplied by JavaSoft. This avoids incompatibility
problems between your applets and specific types of web-browsers.
The
syntax used by Internet Explorer and Netscape is different, but the servlet
code generated from the
<jsp:plugin> action
dynamically senses the type of browser client and sends the appropriate
<OBJECT> or
<EMBED> tags in the HTML page.
The <jsp:plugin> tag uses
many attributes similar to those of the <APPLET> tag, and some extra that configure which version
of the Java Plugin to use. If the applet communicates with the server, the JVM
running your applet code must be compatible with the JVM running the WebLogic
Server.
This example JSP syntax uses the plugin action to deploy the phonebook
applet, taken from the WebLogic examples.
<jsp:plugin type="applet" code="examples.applets.PhoneBook1"
codebase="/classes/" height="800" width="500"
jreversion="1.1"
nspluginurl="http://java.sun.com/products/plugin/1.1.3/\
plugin-install.html"
iepluginurl="http://java.sun.com/products/plugin/1.1.3/\
jinstall-113-win32.cab#Version=1,1,3,0" >
<params>
<param name="weblogic_url" value="t3://localhost:7001">
<param name="poolname" value="demoPool">
</params>
<fallback>
<font color=#FF0000>Sorry, cannot run java applet!!</font>
</fallback>
</jsp:plugin>
Note: We have broken two lines at the "\" character to fit on this page;
the lines ending with "\" should not have the "\" and are to be one line.
This JSP syntax instructs the browser to download the Java Plugin version
1.1.3 if necessary, and run the applet given by the code attribute from the location specified by codebase.
The jreversion attribute identifies the
spec version of the Java Plugin that the applet requires to operate. The
web-browser attempts to use this version of the Java Plugin. If not already
installed on the browser, the nspluginurl and
iepluginurl attributes specify URLs
where the Java Plugin can be downloaded from Sun's website. Once the plugin
is installed on the web-browser, it need not be downloaded again.
If you are running the WebLogic Server with the Java 1.2.x VM, and your
applet communicates with the server using RMI, JDBC, EJB, or JNDI, then you
must specify the Java Plugin version 1.2.x in the <jsp:plugin> tag. You would achieve this in the above
example by replacing the corresponding attribute values with:
jreversion="1.2"
nspluginurl="http://java.sun.com/products/plugin/1.2/\
plugin-install.html"
iepluginurl="http://java.sun.com/products/plugin/1.2/\
jinstall-12-win32.cab"
Note: We have broken two lines at the "\" character to fit on this page;
the lines ending with "\" should not have the "\" and are to be one line.
The other attributes of the plugin action correspond with those of the
<APPLET> tag. You specify applet
parameters within a pair of <params> tags, nested within the
<jsp:plugin> and
</jsp:plugin> tags.
The <fallback> tags allow
you to substitute HTML for browsers that are not supported by the
<jsp:plugin> action. The HTML
nested between the <fallback>
and </fallback> tags is sent
instead of the plugin syntax.
Using the WebLogic JSP compiler
Since the JSPServlet automatically calls the WebLogic JSP
compiler to process your JSP pages, you generally do not need to
use the compiler directly. However, there may be situations (such as
debugging) where accessing the compiler directly can be useful. This section
is provided as reference for the compiler.
The WebLogic JSP compiler parses your JSP file into a
.java file, then compiles the generated
.java file into a Java class using a
regular Java compiler.
Syntax
The JSP compiler works in much the same way that other WebLogic
compilers work (including the RMI and EJB compilers). Here is the
pattern:
$ java weblogic.jspc -options fileName
where fileName is the
name of the JSP file that you want to compile. The options may be before or
after the target filename. Here is an example that compiles "myFile.jsp" into the
destination directory (one of the options) "weblogic/classes".
$ java weblogic.jspc -d /weblogic/classes myFile.jsp
Options
You may use any combination of the following options:
- -classpath
- Add a semicolon-delimited list of directories that make
up the desired CLASSPATH. For example (to be entered on one line):
$ java weblogic.jspc \
-classpath java/classes.zip;/weblogic/classes.zip \
myFile.JSP
- -commentary
- Causes the JSP compiler to emit commentary.
- -compiler
- Sets the Java compiler used to compile the class file from the generated
Java source code. The default compiler used if javac. This should be in your
PATH
unless you specify the absolute path to the compiler explicitly.
- -d
- Sets the destination of the compiled output (the class file). Use this
as a shortcut to place the compiled classes in a directory that is already in
your CLASSPATH.
- -debug
- Compile with debugging on.
- -deprecation
- Warn about use of deprecated methods in the generated Java source file
when compiling it into a class file. This is compiler dependent. Note that the
Symantec compiler does not provide checking for deprecated methods.
- -encoding
- Valid args are "default" to use the default character encoding of JDK, or
named character encoding, like "8859_1". If the -encoding flag is not present,
an array of bytes is used.
- -g
- Instructs the Java compiler to include debugging information in the class file.
- -help
- Outputs a list of all the available flags.
- -J
- Use the -J option to add other options that your specific compiler
will parse.
- -keepgenerated
- Keeps the Java files that are created as an intermediary
step in the compilation process.
- -normi
- Passed through to Symantec's compiler (sj).
- -nowarn
- Turns off warning messages from the Java compiler.
- -nowrite
- Runs the compilation process without actually producing
a .class file. If you combine this with the
-keepgenerated flag,
the compiler will create only the intermediate
.java file.
This can be useful for debugging.
- -O
- Compiles the generated Java source file with optimization turned on. This
overrides the -g flag.
- -package
- Sets the package for the generated java HTTP servlet. This defaults to
"jsp_servlet".
- -superclass
- Sets the classname of the superclass which the generated servlet shall
extend. The names superclass must be a derivative of
HTTPServlet.
- -verbose
- Prints messages to the command line window when the
flag is present. Default is off.
- -version
- Prints out the version of the JSP compiler.
V. Troubleshooting guide
This section describes several techniques for debugging your JSP files.
Symptoms in the browser
Debugging information in the browser
The most useful feature for debugging your JSP pages is output to the browser
by default. This displays where the error occured in the
generated HTTP servlet Java file, a description of the error, and an
approximate location of the error code in the original JSP file. For example:
Compilation of 'C:\weblogic\myserver\classfiles\examples\jsp\_HelloWorld.java'
failed:
C:\weblogic\myserver\classfiles\examples\jsp\_HelloWorld.java:73: Undefined variable, class, or package name: foo
probably occurred due to an error in HelloWorld.jsp line 21:
foo.bar.baz();
Tue Sep 07 16:48:54 PDT 1999
|
To disable this feature, set the verbose flag to false in the JSPServlet registration in the
weblogic.properties file. For details,
see Register the JSPServlet.
Error 404--Not Found
Check that you have typed the URL of the JSP file correctly, and that it is
relative to the document root.
Error 500--Internal Server Error
Check the WebLogic Server log file for Page
compilation failed messages, and see the relevant section in the log file
symptoms section below.
Error 503--Service Unavailable
You will get this response if you have not set the compileCommand property in the
weblogic.properties file. Check the
initArgs property for the JSP
compiler. If this is correct, also check that the virtual name for the
initArgs pattern matches
the virtual name given to the JSPServlet (usually *.jsp).
JSP page content appears in the browser
If you have not registered the JSP Servlet correctly in the weblogic.properties file, it is probable
that the FileServlet will simply deliver the JSP page directly to the browser.
In Netscape, you will see the contents of the JSP page. In Internet Explorer,
you will see just the HTML parts of the JSP page.
Symptoms in the log file
This section describes things you should look for in the WebLogic log
file. The output is organized into the order you may encounter the messages in
the log file as the JSP request progresses.
Using the log file
As the WebLogic Server runs, verbose messages is saved into a log
file named weblogic/myserver/weblogic.log that you may view using a
text editor. Errors are usually denoted by
indented sections or Exception stack traces. As a general rule, you can search
for the word error or Exception.
Invoking the JSPServlet
- Couldn't find init param: compileCommand
- You must specify the compileCommand in the
weblogic.properties file. Check that this parameter is specified in the
initArgs property, and that the
virtual name or pattern specified for the initArgs matches that of the JSPServlet.
Page compilation failed
The following errors may occur if the JSP compiler fails to translate the JSP
page into a Java file, or can not compile the generated Java file. Look in the
log file for the following error messages:
- CreateProcess: ...
- This indicates that the Java compiler specified by
compileCommand
could not be found or was not a valid executable.
- Compiler failed:
- This indicates that the Java code generated from your JSP page could not
be compiled by the Java compiler you specified in the
weblogic.properties
file with compileCommand.
You can use the JSP Compiler independently to inspect
and debug the generated Java code in more detail.
- Undefined variable or classname:
- If you are using a custom variable, make sure it is defined before it is
used in a scriptlet, or it is defined in a declaration.
You may see this error if you are attempting to use an implicit object from a declaration.
Use of implicit objects in a declaration is not supported in JSP.
JSP Servlet Runtime Failure
You may encounter the following output if your JSP servlet has been
successfully generated, compiled and invoked, but fails at run time when
serving an HTTP request.
- ClassCastException
- A ClassCastException may be
thrown if you change your JSP page, causing it to reload when you are storing
custom classes in an HTTP session, and those classes are loaded from the
servlet classpath. Here is what is happening...
When your JSP needs to be recompiled, the WebLogic Server has to create
and use a new class-loader to ensure that the older classes are dropped, and
the newer classes are used instead. This is a workaround for a
'characteristic' of the Java class loader. If you define a custom class and
that class is loaded from the servlet classpath, it is also loaded by the same
class loader that loaded your generated JSP servlet. Of course, that
class loader is destroyed when the JSP is reloaded, and the custom class must
also be reloaded.
Now, when you attempt to retrieve the custom class from the HTTP session,
you get a ClassCastException since it
was loaded by a different class loader. Although the classes may be the same
logically, they have been loaded by different class-loaders, and are regarded
by the JVM as incompatible.
For more details on HTTP sessions and some suggested workarounds to this
dilemma, see the Developers Guide, "Using WebLogic HTTP servlets", under the
section
The dreaded ClassCastException!.
VI. Change history
- Release 4.5.0 -- 06/24/1999
- Introduced support for JSP 1.0 specification.
