Programmer's Guide
JRun and XML

Writing JSPs in XML

You can write JSPs in the core JSP syntax or in JSP XML syntax. JSP XML syntax defines a format for writing JSPs in well-formed XML. Traditional JSP syntax allows you to mix HTML markup with JavaScript and JSP directives, scriptlets, actions, and expressions. While JSP XML syntax allows you to use all of these elements, you must comply with the rules of XML on the page.

This section describes the benefits of coding JSPs in the JSP XML syntax and provides some examples on how to do this.

Understanding the XML view

The core JSP syntax is made up of scriptlets, actions, directives, expressions and declarations defined by the JSP specification. Web browsers do not understand JSP syntax as they do HTML. For the browser to display the contents of a JSP page, JRun must first compile the JSP source as a servlet which JRun then uses to generate the response. The response is HTML or whatever markup language is requested. However, the JSP-to-servlet compilation process is not a direct one. The JSP must first be transformed into XML.

The following steps occur when a JSP is requested for the first time:

1. A client requests a JSP for the first time.
2. JRun converts the JSP into a temporary XML representation called the XML view.
3. JRun validates the XML view of the JSP page.
4. JRun transforms the XML view into a .java class file that extends jrun.jsp.runtime.HttpJSPServlet and implements jrun.jsp.runtime.JRunJspPage. You can view the servlet's source code as described in "Viewing servlet source code".
5. JRun compiles the new class into a servlet.
6. The servlet generates the output based on the client request.

The following image shows the lifecycle of a JSP page when it is first requested by a client and finally compiled into a servlet. The servlet then returns the request to the client.

Viewing servlet source code

You can view the source code of the servlet representation of the JSP page. You cannot view the XML view of the JSP page because it is only maintained in memory temporarily while JRun constructs the servlet.

JRun does not keep servlets generated from JSP source code by default. This section shows you how to configure JRun to keep the Java files and where to view them.

To keep generated JSPs:

1. In the jrun_root/servers/jrun_server/SERVER-INF/default-web.xml file, set the JSPServlet's keepGenerated initialization parameter to true, as shown in the following example:

   <servlet>
   ��<servlet-name>JSPServlet</servlet-name>
   ��<servlet-class>jrun.jsp.JSPServlet</servlet-class>
   ��<init-param>
   ����<param-name>keepGenerated</param-name>
   ����<param-value>true</param-value>
   ��</init-param>
   </servlet>
   

2. Delete the JSP class files in the web application's /WEB-INF/jsp directory.

   Doing this removes the already-generated servlet class files. JRun checks for the existence of the class file before recompiling a JSP. If the class files were still available, JRun would not recompile the JSP. JRun also checks the data/time stamp of the JSP, so you can change the JSP source code and save the JSP file to cause JRun to regenerate the Java source code and recompile the class.

3. Restart the JRun server.
4. Request the JSP.
5. Open the JSP's generated Java class file (*.java) in the web application's /WEB-INF/jsp directory. JRun names the source code files starting with "jrun__" and appends version information to the name.

Understanding JSP XML

The Java 1.2 JSP specification introduced the ability for you to write JSP pages directly in XML, rather than write them in the JSP syntax. The JSP XML syntax uses similar markup as traditional JSP syntax to represent a page, but it conforms to XML standards and includes several tags unique to the JSP document type description (DTD).

You can take advantage of the following benefits of JSP XML syntax support for JSP pages:

• JRun compiles the JSP page faster, because the JSP-to-XML view transformation is not necessary.
• You can use XML tools to work with the JSP.
• JRun validates JSPs against the Sun JSP 1.2 DTD, to make sure the XML file is well-formed and valid.
• The compiler produces more meaningful debugging messages for XML syntax.

For a description of the JSP XML syntax schema, see http://java.sun.com/dtd/jspxml.xsd.

For a description of the JSP XML DTD, see http://java.sun.com/dtd/jspxml.dtd.

Simple JSP XML example

The following example shows a JSP page in the traditional JSP syntax, and then shows it in JSP XML syntax:

Traditional JSP syntax:

<%-- Traditional JSP syntax -->
<%@ taglib uri=/WEB-INF/doclib.tld prefix="docs" %>
<HTML>
�<BODY>
��<docs:format><P>This is a simple page.</docs>
��A <I>very</I> simple page.
�</BODY>
</HTML>

JSP XML syntax:

<jsp:root xmlns:jsp="http://java.sun.com/jsp_1_2" 
�xmlns:docs="/WEB-INF/doclib.tld" 
�version="1.2">
�<jsp:text>
��<!-- XML JSP syntax -->
��<![CDATA[ <HTML><BODY> ]]>
�</jsp:text>
�<docs:format>This is a simple page.
�A <![CDATA[<I>very</I>]]> simple page.</docs>
�<jsp:text>
��<![CDATA[ </HTML></BODY> ]]>
�</jsp:text>
</jsp:root>

To see a sample JSP page in XML, start the samples JRun server and open a browser to http://localhost:8200/techniques.

Differences between JSP and JSP XML syntax

As shown in the previous example, the JSP XML syntax is more verbose than traditional JSP syntax, but it also provides a more structured representation of the page.

The differences between JSP and JSP XML syntax shown in the previous example include the following:

• The root element jsp:root wraps the entire page. JRun recognizes this tag as the start of a JSP XML page.
• The jsp:root element defines the XML namespaces and the version attribute. Namespace attributes define the prefixes and URIs for custom tag libraries used in the page.
• The jsp:text element wraps template data. Template data is any data that does not use JSP syntax elements, such as the body of the page, HTML tags, or JavaScript code.
• The CDATA elements wrap template data that should not be interpreted by the XML parser, such as HTML tags. This data confuses an XML parser. The parser ignores any data in the CDATA element.
• The JSP XML tags cannot be nested inside one another.

The following table shows the basic syntactic differences between traditional JSP and JSP XML syntax:

Type	Traditional JSP syntax	JSP XML syntax
page directive	<% page ... %>	<jsp:directive.page ... />
include directive	<%@ include ... %>	<jsp:directive.include ... />
taglib directive	<%@ taglib ... %>	<jsp:root xmlns:prefix="taglibURI"> ... </jsp:root>
Declarations	<%! declaration %>	<jsp:declaration> declaration </jsp:declaration>
Expressions	<%= expression %>	<jsp:expression> expression </jsp:expression>
Scriptlets	<% scriptlet_code %>	<jsp:scriptlet> scriptlet_code </jsp:scriptlet>
Actions	<jsp:include> ... </jsp:include> <jsp:forward> ... </jsp:forward> <jsp:plugin> ... </jsp:plugin> <jsp:useBean> ... </jsp:useBean> <jsp:setProperty> ... </jsp:setProperty> <jsp:getProperty> ... </jsp:getProperty>	Previous versions of the JSP specification required that standard actions use XML syntax. Therefore, the syntax for actions in JSP XML is not different. Files included with the jsp:include action can be in either JSP or JSP XML syntax, but cannot use both types of syntax in the same file.
Template data	template_data	<jsp:text> template_data </jsp:text>
Comments	<%-- comment -->	<!-- comment -->

New JSP XML tags

The following table describes new elements that were not part of traditional JSP syntax, but are used by the JSP XML syntax:

Element syntax	Description
<jsp:root>	The jsp:root element is the top-level element in the JSP XML syntax. It defines the version, namespaces, and tag libraries for the JSP. Syntax: <jsp:root �xmlns:jsp="http://java.sun.com/jsp_1_2" �xmlns:tag_prefix="tag_library_URI" �version="1.2"> �Contents_of_JSP </jsp:root> The JSP XML namespace is required and must be set to http://java.sun.com/jsp_1_2. Other xmlns attributes are optional and define custom tag library prefixes and URIs for the JSP page. The version attribute is required and must be set to 1.2 (the version of the JSP specification). Example: <jsp:root xmlns:jsp="http://java.sun.com/jsp_1_2" �xmlns:test="/WEB-INF/DocSamples.tld" �version="1.2"> </jsp:root>
<jsp:text>	The jsp:text element wraps template data in the JSP. The XML parser validates the template data in the jsp:text element. As a result, you must treat special characters, such as quotes, or brackets, carefully in your template data. For more information, see "Representing special characters in JSP XML".
<![CDATA[template_data]]>	Within other JSP XML elements, the CDATA element wraps template data. The XML parser completely ignores data wrapped by a CDATA element. The CDATA element is commonly used to wrap HTML blocks or JSP scriptlets and declarations, because they use many special characters. Syntax: <jsp_XML_element_tag> <![CDATA[ template_data ]]> </jsp_XML_element_tag> Example: <jsp:text> �This is a <![CDATA[<I>very</I>]]> simple example. </jsp:text>

JSP XML syntax details

The following sections provide additional details about JSP XML element syntax.

Using expressions and declarations in JSP XML

To avoid confusing the XML parser with special characters, such as braces or quotation marks, wrap declarations and expressions inside CDATA elements. The following example shows a JSP XML declaration using CDATA tags to wrap the entire declaration:

<jsp:declaration><![CDATA[

�public int incrementCounter(int x) {
��x = x + 1;
��return x;
�} ]]>
</jsp:declaration>

Do not wrap the jsp:expression and jsp:declaration elements in the jsp:text element. However, these elements can contain the CDATA element.

You can also use Unicode sequences the replace special characters in expressions and declarations. The following example shows a JSP XML expression using the Unicode sequence \u0022 to represent quotation marks:

<jsp:expression>request.getParameter(\u0022backgroundcolor\u0022)</jsp:expression>

For information on using Unicode sequences in JSP XML, see "Representing special characters in JSP XML".

Using scriptlets

Scriptlets work similarly in JSP XML syntax to how they work in JSP syntax. However, special characters (such as quotation marks, brackets, and braces) confuse the XML parser and must be encoded in a special way. Use the following when using special characters in scriptlets:

• Unicode sequences
• HTML entities

For information on using Unicode sequences and HTML entities in JSP XML, see "Representing special characters in JSP XML".

Do not wrap jsp:scriptlet elements in jsp:text elements. The jsp:scriptlet element cannot contain the CDATA element.

Using actions

JSP actions conform to XML standards in both traditional JSP syntax and JSP XML syntax, so you do not have to change the way you access actions in your code. However, to access request-time expressions, you must use a slightly different syntax; you remove the brackets, as the following example shows:

Traditional JSP syntax:

<jsp:include page="<%= filename %>" />

JSP XML syntax:

<jsp:include page="%= filename %" />

Do not wrap JSP action elements in jsp:text elements. The JSP action elements cannot contain the CDATA element.

JSP XML examples

The following example code shows a JSP page written in JSP XML syntax:

<jsp:root xmlns:jsp="http://java.sun.com/jsp_1_2">

�<jsp:scriptlet> 
��String backgroundcolor=request.getParameter(\u0022backgroundcolor\u0022);
��String textcolor=request.getParameter(\u0022textcolor\u0022);
�</jsp:scriptlet>

�<jsp:text>

��<![CDATA[ <HTML> ]]>

��<![CDATA[ <BODY bgcolor="]]></jsp:text><jsp:expression>backgroundcolor</jsp:expression>

�<jsp:text><![CDATA[">]]>

��<![CDATA[ <FONT FACE="arial, helvetica" COLOR="]]></jsp:text><jsp:expression>textcolor</jsp:expression>

�<jsp:text><![CDATA[">]]>
�</jsp:text> 

�<jsp:text>   

��<![CDATA[<P>]]>
���The color of the text is: 
 </jsp:text>
 <jsp:expression>textcolor</jsp:expression>

�<jsp:text> 

��<![CDATA[<P>]]>
���The color of the background is:
�</jsp:text>
�<jsp:expression>backgroundcolor</jsp:expression>

�<jsp:text>

��<![CDATA[ </FONT></BODY></HTML>]]>
�</jsp:text>
</jsp:root>

To see this page use the variable settings, you must set the font color and background color using the request parameters as the following example URL shows:

http://localhost:8100/testxml.jsp?textcolor=orange&backgroundcolor=black

The following code shows how the rendered HTML looks:

   <HTML> 

   <BODY bgcolor="black">
   <FONT FACE="arial, helvetica" COLOR="orange">
   The color of the text is:
     orange   
  <P>
  The color of the background is:
     black   
   </FONT></BODY></HTML>

To see a sample JSP page in JSP XML syntax, start the samples JRun server and open a browser to http://localhost:8200/techniques.

When building HTML tags, such as the FONT tag, keep the request-time variable expressions on the same line as the rest of the tag. Otherwise, the browser might misinterpret the tag and produce unexpected results.

Use the CDATA element whenever you include HTML tags in the JSP page because the XML parser tries to validate the contents of the jsp:text elements and misinterprets special characters.

In some cases, you can use HTML entities or Unicode sequences to represent special characters. For more information, see "Representing special characters in JSP XML".

Representing special characters in JSP XML

To represent special characters that might confuse the XML parser, use Unicode escape sequences or HTML entities. Using these character code schemes is a more succinct alternative to putting all special characters inside CDATA elements.

In some cases, you can use apostrophes in place of quotation marks in JSP XML elements. The JRun XML parser accepts this alternative. However, some compilers do not.

The following sections describe how to use HTML entities and Unicode sequences in JSP XML.

Using HTML entity references

HTML entity references use symbolic names to represent characters. They conform to the following syntax:

& + entity_name + ;

For example, the following is the HTML entity reference for the greater-than symbol (>):

>

For a list of HTML entities, see http://www.ramsch.org/martin/uni/fmi-hp/iso8859-1.html.

The XML parser converts HTML entities to their character representations when writing a JSP response to the output. The following table describes where you can use HTML entities in JSP XML elements:

Element	Example
jsp:text	The following example shows HTML entities used in place of less-than and greater-than symbols in the jsp:text element: <jsp:text> �&lt;HR&gt; </jsp:text>
jsp:declaration	The following example shows HTML entities used in place of quotation marks in the jsp:declaration element: <jsp:declaration> public String returnColor() { String color=&quot;black&quot;; return color; } </jsp:declaration>
jsp:expression	The following example shows HTML entities used in place of quotation marks in the jsp:expression element: <jsp:expression> �request.getParameter(&quot;backgroundcolor&quot;) </jsp:expression>
jsp:scriptlet	The following example shows HTML entities used in place of quotation marks in the jsp:scriptlet element: <jsp:scriptlet> �String power=request.getParameter(&quot;power& quot;); </jsp:scriptlet>
CDATA	You cannot use HTML entities in CDATA elements.
JSP actions	You cannot use HTML entities in action elements.

Using Unicode sequences

Unicode provides a unique number for every character and is supported by most platforms. Unicode sequences consist of a four-character sequence that maps to the symbol. The following is the Unicode sequence for the greater-than symbol (>):

003E

In your Java code, you must escape the sequence with \u, as shown in the following example:

\u003E

For a list of Unicode sequence characters, see http://www.unicode.org.

The XML parser converts Unicode sequences to their character representations when writing a JSP response to the output. The following table describes where you can use Unicode sequences in JSP XML elements:

Element	Example
jsp:text	You cannot use Unicode sequences in jsp:text elements.
jsp:declaration	The following example shows Unicode sequences used in place of quotation marks in the jsp:declaration element: <jsp:declaration> public String returnCheese() { String cheese=\u0022cheese\u0022; return cheese; } </jsp:declaration>
jsp:expression	The following example shows Unicode sequences used in place of quotation marks in the jsp:expression element: <jsp:expression>request.getParameter(\u0022power\u0022)</jsp:expression>
jsp:scriptlet	The following example shows Unicode sequences used in place of quotation marks in the jsp:scriptlet element: <jsp:scriptlet> �String power=request.getParameter(\u0022power\u0022); �out.println("\u003CH1\u003EBehold the power of " + power); </jsp:scriptlet>
CDATA	The following example shows Unicode sequences used in place of quotation marks in the CDATA element: <jsp:declaration><![CDATA[ public String returnCheese() { String cheese=\u0022cheese\u0022; return cheese; } ]]> </jsp:declaration>
JSP actions	You cannot use Unicode sequences in action elements.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/jrun/4/Programmers_Guide/servletxml5.htm

Add Comment