Edit D:\app\Administrator\product\11.2.0\dbhome_1\xdk\doc\java\xsql\xsql

Edit D:\app\Administrator\product\11.2.0\dbhome_1\xdk\doc\java\xsql\xsql_userguide.html

<html>
 <head>
 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <link rel="stylesheet" type="text/css" href="readme.css">
 <style>
 .literal {font-family: monospace }
 </style>
 <title> Oracle XSQL Pages and the XSQL Servlet</title>
 </head>
 <body>
 <h1 style="color:#000088"><img src="images/line1.gif" width="600" height="15"> Oracle XSQL Pages and the XSQL Servlet</h1>
 <h3>Release Notes</h3> <h2 style="color:#000090"><img src="images/line3.gif" width="300" height="11"> 
Contents</h2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID55">Overview</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID138">What are XSQL Pages?</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID318">Release 10.0.0.0</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID329">New Features for Multi-Valued Parameters</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID983">Other New Features</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID1975">Bugs Fixed</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2041">Security Consideration for Production XSQL Pages Systems</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2165">Reference Information</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2172">Online Help</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2196">XSQL Action Handler Summary</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2588">Parameter Resolution</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2778">Known Issues</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2851">Installation</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID2859">Supported Configurations</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID3280">Prerequisites</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID3336">XSQL Software Included in the XDK Distribution</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID3386">Downloading and Installing the XSQL Servlet</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID5300">Additional Technical Tips</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID5307">Producing XML from SQL with Nested Structure</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID5775">Inserting XML Into Any Table You Require </a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID7116">Demos Included with This Release</a> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#ID7660">Closing Comments</a> 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
	 Before installing XSQL Pages on a production server, please read the
		section below on 
		<a href="#securityinfo">Security Considerations for Production XSQL
		 Pages System</a>
 
 </td>
 </tr>
 </table> <a name="intro"></a><a name="ID55">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Overview</h2>
 </a>
 As the Internet drives an explosive demand for flexible information
		exchange, more and more application developers need to put their business data
		to work over the Web. Developers require standards-based solutions to this
		problem and SQL, XML, and XSLT are the standards that can get the job done in
		practice.
 SQL is the standard you are already familiar with for accessing
		appropriate views of business information in your production systems. XML
		provides an industry-standard, platform-neutral format for representing the
		results of SQL queries as "datagrams" for exchange, and 
		<a href="http://www.w3.org/TR/xslt">XSLT</a> defines the
		industry-standard way to transform XML "datagrams" into target XML, HTML, or
		Text formats as needed. 
 By combining the power of SQL, XML, and XSLT in the server with the
		ubiquitously available HTTP protocol for the transport mechanism you
		can:
 <ul> 
		<li> 
		 Receive web-based information requests from any client device on
			 the Web, 
		</li> 
		<li> 
		 Query an appropriate logical "view" of business data needed by
			 the request, 
		</li> 
		<li> 
		 Return the "datagram" in XML over the web to the requester, or
			 optionally 
		</li> 
		<li> 
		 Transform the information flexibly into any XML, HTML, or text
			 format they require. 
		</li> 
	 </ul>
 Of course, Oracle 8i, the Oracle 
		<a href="http://otn.oracle.com/tech/xml">XML Developer's
		 Kit</a>, and the 
		<a href="http://otn.oracle.com/tech/xml/oracle_xsu/">XML SQL
		 Utility for Java</a> provide all of the core technology needed by
		developers to implement this solution. However it is Oracle XSQL
		Pages that bring this capability to the "rest of us" by automating
		the use of these underlying XML technology components to solve the most common
		cases without programming. <a name="ID138">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> What are XSQL Pages?</h3>
 </a>
 Oracle XSQL Pages are templates that allow anyone
		 familiar with SQL to declaratively:
 <ul> 
		 <li> 
			 Assemble dynamic XML "datapages" based on one or more
				parametrized SQL queries, and 
		 </li> 
		 <li> 
			 Transform the "datapage" to produce a final result in any
				desired XML, HTML, or Text-based format using an associated XSLT
				Transformation. 
		 </li> 
		</ul>
 The two key design goals of Oracle XSQL Pages are: 
		 <ul> 
			 <li> 
				Make simple things very simple and hard things
				 possible 
			 </li> 
			 <li> 
				Keep the "datapage" cleanly separate from the way that data
				 will be rendered to the requester. 
			 </li> 
		 </ul> 
 XSQL Pages are simple to build. Just use any text editor to create
		 an XML file that includes 
 &lt;xsql:query>
 tags wherever you want
		 to include XML-based SQL query results in the template. Associate an XSLT
		 stylesheet to the page by including one extra line at the top of the file: an
		 
 &lt;?xml-stylesheet?>
 instruction. Save the file and request it
		 through your browser to get immediate results. Since you can extend the set of
		 actions that can be performed to assemble the "datapage" using the
		 
 &lt;xsql:action>
 element, it's possible to cleverly extend the
		 basic simple model to handle harder jobs. Let's start by looking at a simple
		 example of an XSQL Page.
 For example, to serve a list of available flights today for any
		 desired destination city from your enterprise database in response to a URL
		 request like:
 
		 <pre>http://yourcompany.com/AvailableFlightsToday.xsql?City=NYC</pre>

you might write an XSQL Page like:
 <pre>&lt;?xml version="1.0"?&gt;
&lt;xsql:query connection="demo" bind-params="City" xmlns:xsql="urn:oracle-xsql"&gt;

SELECT Carrier, FlightNumber, Origin, TO_CHAR(ExpectedTime,'HH24:MI') Due
      FROM FlightSchedule
     WHERE TRUNC(ArrivalTime) = TRUNC(SYSDATE)
       AND Destination = ?
  ORDER BY ExpectedTime

&lt;/xsql:query&gt;</pre>
 To return the same information in HTML or some alternative XML
		 format that might comply with a particular DTD you've been given, just
		 associate an appropriate with 
 &lt;?xml-stylesheet?>
 like
		 this:
 <pre>&lt;?xml version="1.0"?&gt;
&lt;?xml-stylesheet type="text/xsl" href="FlightList.xsl"?&gt;
&lt;xsql:query connection="demo" bind-params="City" xmlns:xsql="urn:oracle-xsql"&gt;

SELECT Carrier, FlightNumber, Origin, TO_CHAR(ExpectedTime,'HH24:MI') Due
      FROM FlightSchedule
     WHERE TRUNC(ArrivalTime) = TRUNC(SYSDATE)
       AND Destination = ?
  ORDER BY ExpectedTime

&lt;/xsql:query&gt;</pre>
 Once you've built a set of XSQL Pages, you can "exercise" your
		 templates by:
 <ul> 
		 <li> 
			 Requesting the pages over the Web from browsers or client
				programs after installing the Oracle XSQL Servlet on your
				favorite Web Server, 
		 </li> 
		 <li> 
			 Using the Oracle XSQL Command Line Utility
				in batch programs, 
		 </li> 
		 <li> 
			 Calling the XSQLRequest.process() method
				from within any Java program 
		 </li> 
		 <li> 
			 
 &lt;jsp:include>
 ing an XSQL Page into your JSP
				page, or 
 &lt;jsp:forward>
 ing to 
		 </li> 
		</ul>
 These release notes explain in detail how to setup the Oracle XSQL
		 Servlet and how to make use of all the time-saving features supported by XSQL
		 Page templates. 
 Using XSQL Pages, the information you already have in your Oracle
		 database, and the power of SQL, XML, and XSLT, you'll quickly discover that a
		 powerful and flexible world of web data publishing is at your fingertips.
		 <a name="ID318">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Release 10.0.0.0</h2>
 </a>
 Release 10.0.0.0 adds several new features:<a name="ID329">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> New Features for Multi-Valued Parameters</h3>
 </a>
 Many users have requested an easy way to work with parameters whose
		 values are arrays of strings. The most common scenario
		 where multi-valued parameters occur is when a user submits an HTML form
		 containing multiple occurrences of input controls that share the same
		 name.
 <ul> 
		 <li> 
			 Working with Array-Valued
				Parameters
 
 
 
			 In addition to the existing support for simple-string values,
				now request parameters, session parameters, and page-private parameters may
				have values that are arrays of strings. To treat to the value of a parameter as
				an array, you add two empty square brackets to the end of its name. For
				example, if an HTML form is posted having four occurrences of a input control
				named productid, then to refer to the array-valued
				productid parameter you use the notation
				productid[]. 
			 If you refer to an array-valued parameter as a lexical
				substitution parameter -- either inside an action handler attribute value or
				inside the content of an action handler element -- its value will be converted
				to a comma-separated list of all non-null and non-empty strings in the array in
				the order that they appear in the array. For example, if you had a page
				like: 
			 <pre>&lt;page xmlns:xsql="urn:oracle-xsql"&gt;
 &lt;xsql:query&gt;
 select description
 from product
 where productid in ( {@productid[]} ) /* Using lexical parameter */
 &lt;/xsql:query&gt;
&lt;/page&gt;</pre>
			 and the request contains four values for the productid
				parameter, then the {@productid[]} lexical substitution
				expression will be replaced in the query by a string like
				111,222,333,444. 
			 If you refer to an array-valued parameter without using the
				array-brackets notation on the end of the name, then the value used will be the
				value of the first array entry. 
			 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				It is not supported to use a number
				 inside the array brackets. That is, you can refer to
				 productid or productid[], but
				 not productid[2]. Also, as described
				 above only the request parameters, page-private parameters, and session
				 parameters can use string arrays. The
				 
 &lt;xsql:set-stylesheet-param>
 and
				 
 &lt;xsql:set-cookie>
 only support working with parameters as
				 simple string values. 
			 </td>
 </tr>
 </table> 
		 </li> 
		 <li> 
			 Setting Array-Valued Page or Session Parameters From
				Strings
 
 
 
			 You can set the value of a page-private parameter or session
				parameter to a string-array value simply by using the array-brackets notation
				on the name like this: 
			 <pre>&lt;!-- Note, param name contains array brackets --&gt;
&lt;xsql:set-page-param name="names[]" value="Tom Jane Joe"/&gt;</pre>
			 or similarly for session parameters: 
			 <pre>&lt;!-- Note, param name contains array brackets --&gt;
&lt;xsql:set-session-param name="dates[]" value="12-APR-1962 15-JUL-1968"/&gt;</pre>
			 By default, when the name of the parameter being set is an name
				with array-brackets, the value will be treated as a space-or-comma-separated
				list and tokenized. The resulting string array value will contain these
				separate tokens. In the examples above, the names[]
				parameter would be the string array {"Tom", "Jane", "Joe"}
				and the dates[] parameter would be the string array
				{"12-APR-1962", "15-JUL-1968"}. 
			 In order to handle strings that contain spaces, the
				tokenization algorithm first checks the string being tokenized for the presence
				of any commas. If at least one comma is found in the string, then commas are
				used as the token delimiter. So, for example, the following action: 
			 <pre>&lt;!-- Note, param name contains array brackets --&gt;
&lt;xsql:set-page-param name="names[]" value="Tom Jones,Jane York"/&gt;</pre>
			 would set the value of the names[] parameter
				to the string array {"Tom Jones", "Jane York"}. 
			 By default, when you set a parameter whose name does
				not end with the array-brackets, then the
				string-tokenization does not occur. So, as in previous releases of XSQL Pages,
				the following action: 
			 <pre>&lt;!-- Note, param name does NOT contain array brackets --&gt;
&lt;xsql:set-page-param name="names" value="Tom Jones,Jane York"/&gt;</pre>
			 Sets a parameter named names to the literal
				string "Tom Jones,Jane York". For convenience, you can
				optionally force the string to be tokenized by including the new
				treat-list-as-array="yes" attribute on the
				
 &lt;xsql:set-page-param>
 or
				
 &lt;xsql:set-session-param>
 actions. The result will be to assign
				a comma-separated string of the tokenized values to the parameter. For example,
				the action: 
			 <pre>&lt;!-- Note, param name does NOT contain array brackets --&gt;
&lt;xsql:set-page-param name="names" value="Tom Jane Joe" treat-list-as-array="yes"/&gt;</pre>
			 sets the names parameter to the literal string
				"Tom,Jane,Joe". As a final new convenience, when you are
				setting the value of a simple string-valued parameter and you are tokenizing
				the value using treat-list-as-array="yes", you can include
				the new quote-array-values="yes" attribute to have the
				comma-separated values be surrounded by single-quotes. So, an action like
				this: 
			 <pre>&lt;!-- Note, param name does NOT contain array brackets --&gt;
&lt;xsql:set-page-param name="names" value="Tom Jones,Jane York,Jimmy"
 treat-list-as-array="yes" quote-array-values="yes"/&gt;</pre>
			 assigns the literal string value "'Tom Jones','Jane
				York','Jimmy'" to the names parameter.

</li> 
		 <li> 
			 Binding Array-Valued Parameters in SQL and PL/SQL
				Statements
 
 
 
			 Anywhere in XSQL Pages where string-valued scalar bind
				variables were supported previously, you may now bind array-valued parameters
				by simply using the array-parameter name in the list of parameter names that
				you supply for the bind-params attribute. 
			 This makes it very easy to process array-valued parameters in
				SQL statements and in PLSQL procedures. Array-valued parameters are bound as an
				nested table object type named XSQL_TABLE_OF_VARCHAR that
				you must create in your current schema using the DDL statement: 
			 <pre>CREATE TYPE xsql_table_of_varchar AS TABLE OF VARCHAR2(2000);</pre>
			 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				While the type must have this exact name,
				 XSQL_TABLE_OF_VARCHAR, you can change the dimension of the
				 VARCHAR2 string if desired. Of course, you should make it as long as any string
				 value you expect to handle in your array-valued string parameters. 
			 </td>
 </tr>
 </table> 
			 Consider the following PL/SQL stored procedure: 
			 <pre>FUNCTION testTableFunction(p_name XSQL_TABLE_OF_VARCHAR,
 p_value XSQL_TABLE_OF_VARCHAR) RETURN VARCHAR2 IS
 lv_ret VARCHAR2(4000);
 lv_numElts INTEGER;
BEGIN
 IF p_name IS NOT NULL THEN
 lv_numElts := p_name.COUNT;
 FOR j IN 1..lv_numElts LOOP
 IF (j &gt; 1) THEN
 lv_ret := lv_ret||':';
 END IF;
 lv_ret := lv_ret||p_name(j)||'='||p_value(j);
 END LOOP;
 END IF;
 RETURN lv_ret;
END;</pre>
			 The following page illustrates how to bind two array-valued
				parameters in a SQL statement that uses this PL/SQL function taking
				XSQL_TABLE_OF_VARCHAR-typed arguments. 
			 <pre>&lt;page xmlns:xsql="urn:oracle-xsql" connection="demo" someNames="aa,bb,cc" someValues="11,22,33"&gt;
 &lt;xsql:query bind-params="someNames[] someValues[]"&gt;
 select testTableFunction(?,?) as example from dual
 &lt;/xsql:query&gt;
&lt;/page&gt;</pre>
			 This produces a resulting XML data page of: 
			 <pre>&lt;page someNames="aa,bb,cc" someValues="11,22,33"&gt;
 &lt;ROWSET&gt;
 &lt;ROW num="1"&gt;
 &lt;EXAMPLE&gt;aa=11:bb=22:cc=33&lt;/EXAMPLE&gt;
 &lt;/ROW&gt;
 &lt;/ROWSET&gt;
&lt;/page&gt;</pre>
			 illustrating that the array-valued someNames[] and someValues[]
				parameters were bound as table collection types and the values were iterated
				over and concatenated together to produce the
				"aa=11:bb=22:cc=33" string value as the function
				return. 
			 You can mix any number of regular parameters and array-valued
				parameters in your bind-params string. Just use the array-bracket notation for
				the ones you want to be bound as arrays. 
			 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				If you try the example above and you have not created the
				 XSQL_TABLE_OF_VARCHAR type as illustrated above, you will receive an error like
				 this: 
				<pre>&lt;page someNames="aa,bb,cc" someValues="11,22,33"&gt;
 &lt;xsql-error code="17074" action="xsql:query"&gt;
 &lt;statement&gt;select testTableFunction(?,?) as example from dual&lt;/statement&gt;
 &lt;message&gt;invalid name pattern: SCOTT.XSQL_TABLE_OF_VARCHAR&lt;/message&gt;
 &lt;/xsql-error&gt;
&lt;/page&gt;</pre>

</td>
 </tr>
 </table> 
			 Since the array parameters are bound as nested table collection
				types, you can use the TABLE() operator in combination with
				the CAST() operator in SQL to treat the nested table bind
				variable value as a table of values to query against. This can be quite a
				powerful technique to use in subselect clauses of a SQL statement (but it's not
				limited to this). The following page illustrates using an array-valued
				parameter containing employee id's to restrict the rows queried from the
				familiar EMP table. 
			 <pre>&lt;page xmlns:xsql="urn:oracle-xsql" connection="demo"&gt;
 &lt;xsql:set-page-param name="someEmployees[]" value="7369,7839"/&gt;
 &lt;xsql:query bind-params="someEmployees[]"&gt;
 select ename, sal
 from emp
 where empno in (
 select * from TABLE(CAST( ? as xsql_table_of_varchar))
 )
 &lt;/xsql:query&gt;
&lt;/page&gt;</pre>
			 This produces a result like: 
			 <pre>&lt;page&gt;
 &lt;ROWSET&gt;
 &lt;ROW num="1"&gt;
 &lt;ENAME&gt;SMITH&lt;/ENAME&gt;
 &lt;SAL&gt;800&lt;/SAL&gt;
 &lt;/ROW&gt;
 &lt;ROW num="2"&gt;
 &lt;ENAME&gt;KING&lt;/ENAME&gt;
 &lt;SAL&gt;5000&lt;/SAL&gt;
 &lt;/ROW&gt;
 &lt;/ROWSET&gt;
&lt;/page&gt;</pre>
			 These examples have shown using bind-params
				with 
 &lt;xsql:query>
 , but these new features work for
				
 &lt;xsql:dml>
 , 
 &lt;xsql:include-owa>
 ,
				
 &lt;xsql:ref-cursor-function>
 , and any other actions that accept
				SQL statements as part of their functionality. 
			 Finally, some users might ask, "Why doesn't XSQL support using
				PL/SQL index-by tables instead of nested table collection types for binding
				string-array values?" The simple answer is that PL/SQL index-by-tables do not
				work with the JDBC Thin driver. They only work using the OCI8 JDBC driver. By
				using the nested table collection type XSQL_TABLE_OF_VARCHAR
				we can use the array-valued parameters with both the Thin driver and the OCI8
				driver, without losing any of the programming flexibility of working with the
				array of values in PL/SQL.

</li> 
		 <li> 
			 Supplying Multi-Valued Parameters on the Command
				Line
 
 
 
			 If you use the
				oracle.xml.xsql.XSQLCommandLine command-line utility to run
				XSQL pages, you can supply multi-valued parameters to the XSQL page processor
				by simply including the same parameter name on the command line multiple times
				like this: 
			 <pre>java oracle.xml.xsql.XSQLCommandLine SomePage.xsql user=Steve user=Paul user=Mary</pre>
			 This will result in having the user[]
				array-valued parameter set as part of the page processing request. 
		 </li> 
		 <li> 
			 Supplying Multi-Valued Parameters Programmatically
				with XSQLRequest
 
 
 
			 The XSQLRequest programmatic API to the XSQL
				Page engine already takes a java.util.Dictionary of named
				parameters. Typically users have used a Hashtable and called
				its put( 
				name, 
				value) method to add
				String-valued parameters to the request. To add multi-valued parameters, simply
				put a value of type String[] instead of type
				String. 
		 </li> 
		 <li> 
			 Using Multi-Valued Parameters in Custom XSQL
				Actions
 
 
 
			 The base class for custom XSQL actions,
				oracle.xml.xsql.XSQLActionHandlerImpl has been enhanced to
				support working with array-named lexical parameter substitution and array-named
				bind variables, so if your custom actions are using methods like
				getAttributeAllowingParam(),
				getActionElementContent(), or
				handleBindVariables() methods from this base class, you
				pickup this new functionality for free in your custom actions. 
			 A new method getParameterValues() is added
				to the XSQLPageRequest interface to explicitly get a parameter value as a
				String[], and the helper method
				variableValues() in XSQLActionHandlerImpl
				makes it easy to use this functionality from within a custom action handler if
				you need to do so programmatically. 
		 </li> 
		 <li> 
			 New Behavior of &lt;xsql:include-param&gt; for
				Multi-Valued Parameters
 
 
 
			 The 
 &lt;xsql:include-param>
 method is used to
				include the value of any parameter into the XML data page that your XSLT
				stylesheet will "see" for processing. When used with a simple string-valued
				parameter, an action like: 
			 <pre>&lt;xsql:include-param name="productid"/&gt;</pre>
			 includes a fragment of XML like this into your data
				page: 
			 <pre>&lt;productid&gt;1234&lt;/productid&gt;</pre>
			 If you use the new array-name syntax to indicate that you want
				to treat the parameter as an array-valued parameter,
				
 &lt;xsql:include-param>
 will add all array values to your data
				page using an XML fragment that looks like this: 
			 <pre>&lt;productid&gt;
 &lt;value&gt;1234&lt;/value&gt;
 &lt;value&gt;4567&lt;/value&gt;
 &lt;value&gt;890&lt;/value&gt; 
&lt;/productid&gt;</pre>
			 assuming the productid parameter was
				array-valued with values {"1234","4567","890"} and that you
				used the array-bracket notation in the action like this: 
			 <pre>&lt;xsql:include-param name="productid[]"/&gt;</pre>

</li> 
		</ul><a name="ID983">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Other New Features</h3>
 </a>
 <ul> 
		 <li> 
			 Conditionally Execute Actions or Include Content with
				xsql:if-param
 
 
 
			 The new 
 &lt;xsql:if-param>
 action allows you to
				conditionally include the elements and/or actions that are nested inside it if
				some condition is true. If the condition evaluates to true, then all nested XML
				content and actions are included in the page. If the condition evaluates to
				false, then none of the nested XML content or actions are included (and hence
				any nested actions are not executed). 
			 You specify which parameter value will be evaluated by
				supplying the required name attribute. Both simple parameter
				names as well as array-parameter names are supported. 
			 In addition to the name attribute, you must
				also pick exactly one of the following five attributes to
				indicate how the parameter value (or values, in the array case) should be
				tested: 
			 <ol> 
				<li> 
				 
 exists="yes" or
					 exists="no"
 
				 This tests whether the named parameter exists and has a
					 non-empty value. For an array-valued parameter, it tests whether the
					 array-parameter exists, and has at least one non-empty element. 
				</li> 
				<li> 
				 
 equals=" 
					 stringValue"
 
				 This tests whether the named parameter equals the string
					 value provided. By default the comparison is an exact string match. If you want
					 a case-insensitive match, supply the additional ignore-case="yes" attribute as
					 well. For an array-valued parameter, it tests whether any element in the array
					 has the indicated value. 
				</li> 
				<li> 
				 
 not-equals="stringValue"
 
				 
				 This tests whether the named parameter does not equal the
					 string value provided. For an array-valued parameter, it tests whether no
					 element in the array has the indicated value. 
				</li> 
				<li> 
				 
 in-list="comma-or-space-separated-list"
 
				 
				 This tests whether the named parameter matches any of the
					 strings in the provided list. The value of the in-list
					 parameter is tokenized into an array using commas as the delimiter if any
					 commas are detected in the string, otherwise using space as the delimiter. For
					 an array-valued parameter, it tests whether any element in
					 the array matches some element in the list. 
				</li> 
				<li> 
				 
 not-in-list=" 
					 comma-or-space-separated-list"
 
				 
				 This tests whether the named parameter does not match any
					 of the strings in the provided list. The value of the
					 not-in-list parameter is tokenized into an array using
					 commas as the delimiter if any commas are detected in the string, otherwise
					 using space as the delimiter. For an array-valued parameter, it tests whether
					 none of the elements in the array matches any element in
					 the list. 
				</li> 
			 </ol> 
			 For the equals,
				not-equals, in-list, and
				not-in-list tests, by default the comparison is an exact
				string match. If you want a case-insensitive match, supply the additional
				ignore-case="yes" attribute as well. 
			 All of the attributes of the 
 &lt;xsql:if-param>
 
				action can contain lexical substitution parameter expressions (e.g. {@
				
				paramName}) if needed. 
			 Any XML content or XSQL action element can be nested inside an
				
 &lt;xsql:if-param>
 , including other
				
 &lt;xsql:if-param>
 elements if needed. 
			 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				If the parameter being tested does not exist, the test
				 evaluates to false. 
			 </td>
 </tr>
 </table> 
		 </li> 
		 <li> 
			 New Commit="No" Flag on Actions That Performed an
				Implicit Commit
 
 
 
			 The 
 &lt;xsql:delete-request>
 ,
				
 &lt;xsql:insert-request>
 , 
 &lt;xsql:insert-request>
 ,
				and 
 &lt;xsql:insert-parameter>
 action elements each takes a new
				optional commit attribute to control whether the action does an implicit commit
				or not. For backward compatibility, if not specified, these actions perform an
				implicit commit. To avoid performing this implicit commit, you may now specify
				commit="no" on any of these actions. 
		 </li> 
		 <li> 
			 Optionally Set an Error Param on Any Built-in
				Action
 
 
 
			 It is often convenient to know whether an action encountered a
				non-fatal error during its execution. For example, an attempt to insert a row
				or call a stored procedure could fail with a database exception. Now you can
				optionally have any built-in XSQL action set a page-private parameter of your
				choice when that action reports a non-fatal error by using the
				error-param attribute on your action. 
			 For example, to have the parameter named
				dml-error set if the statement inside the
				
 &lt;xsql:dml>
 action encounters a database error, use an action
				like this: 
			 <pre>&lt;xsql:dml error-param="dml-error" bind-params="val"&gt;
 insert into yourtable(somecol) values(?)
&lt;/xsql:dml&gt;</pre>
			 If the execution of this action encounters an error, then the
				page-private parameter named dml-error will be set to the string
				"Error". 
			 If the execution of the action is
				successful, the error parameter is not assigned any value.
				In the example above, this would mean that if the page-private parameter
				dml-error already exists, it will retain its current value.
				If it does not exist, it will continue to not exist. 
			 By using this new error parameter in combination with
				
 &lt;xsql:if-param>
 you can achieve conditional behavior in your
				XSQL page tempate, depending on the success or failure of certain actions. For
				example, assuming your connection definition sets the
				autocommit flag to false on the
				connection named "demo" in
				XSQLConfig.xml, then the following page illustrates how you
				might rollback the changes made by a previous action if a subsequent action
				encounters an error. 
			 <pre>&lt;!-- NOTE: Connection "demo" must not set to autocommit! --&gt;
&lt;page connection="demo" xmlns:xsql="urn:oracle-xsql"&gt;
 &lt;xsql:dml error-param="dml-error" bind-params="val"&gt;
 insert into yourtable(somecol) values(?)
 &lt;/xsql:dml&gt;
 &lt;!-- This second statement will commit if it succeeds --&gt;
 &lt;xsql:dml commit="yes" error-param="dml-error" bind-params="val2"&gt;
 insert into anothertable(anothercol) values(?)
 &lt;/xsql:dml&gt;
 &lt;xsql:if-param name="dml-error" exists="yes"&gt;
 &lt;xsql:dml&gt;rollback&lt;/xsql:dml&gt;
 &lt;/xsql:if-param&gt;
&lt;/page&gt;</pre>
			 If you've written any custom action handlers andyour custom
				actions call reportMissingAttribute(),
				reportError(), or
				reportErrorIncludingStatement() to report non-fatal action
				errors, then they will automatically pickup this new feature as well.

</li> 
		 <li> 
			 Use Your Servlet Container's DataSource
				Implementation
 
 
 
			 As an alternative to defining your named
				connections in the XSQLConfig.xml file, you may now
				alternatively use the datasources available through your servlet container's
				implementation of JDBC datasources. 
			 Two new XSQLConnectionManager
				implementations are provided: 
			 <ol> 
				<li> 
				 
 oracle.xml.xsql.XSQLDatasourceConnectionManager
 
				 
				 Consider using this alternative connection manager
					 implementation if your servlet container's datasource implementation does
					 not use the Oracle JDBC driver under the covers. Certain
					 features of the XSQL Pages system will not be available when you are not using
					 an Oracle JDBC driver, like 
 &lt;xsql:ref-cursor-function>
 and
					 
 &lt;xsql:include-owa>
 . 
				</li> 
				<li> 
				 
 oracle.xml.xsql.XSQLOracleDatasourceConnectionManager
 
				 
				 Consider using this alternative connection manager
					 implementation when you know that your datasource implementation returns JDBC
					 PreparedStatement and CallableStatement
					 objects that implement the oracle.jdbc.PreparedStatement and
					 oracle.jdbc.CallableStatement interfaces respectively. The
					 Oracle9iAS application server has a datasource
					 implementation that does this. 
				</li> 
			 </ol> 
			 When using either of these alternative connection manager
				implementations, the value of the connection attribute in
				your XSQL page should be the JNDI name used to lookup your desired datasource.
				For example, the value of the connection attribute might look something like:
				"jdbc/scottDS". 
		 </li> 
		 <li> 
			 Provide Custom XSQLErrorHandler
				Implementation
 
 
 
			 Many customers have asked for a programmatic way to control how
				errors are reported to be able to customize the treatment of how page processor
				errors (like a connection's being unavailable) are reported to users. A new
				interface is introduced in this release
				oracle.xml.xsql.XSQLErrorHandler that allows developers to
				achieve this. The interface contains the single method: 
			 <pre>public interface XSQLErrorHandler {
 public void handleError( XSQLError err, XSQLPageRequest env);
}</pre>
			 You can provide a class that implements the
				XSQLErrorHandler interface to customize how the XSQL Page
				Processor writes out any page processor error messages. The new
				XSQLError object encapsulates the error information and
				provides access to the error code, formatted error message, etc. 
			 For example, here is a sample implementation of
				XSQLErrorHandler: 
			 <pre>package test;
import oracle.xml.xsql.*;
import java.io.*;
/**
 * Example of a custom XSQLErrorHandler implementation
 */
public class MyErrorHandler implements XSQLErrorHandler {
 public void logError( XSQLError err, XSQLPageRequest env) {
 // Must set the content type before writing anything out
 env.setContentType("text/html");
 PrintWriter pw = env.getErrorWriter();
 pw.println("&lt;H1&gt;ERROR&lt;/H1&gt;&lt;hr&gt;"+err.getMessage()); 
 }
}</pre>
			 You can control which custom
				XSQLErrorHandler implementation gets used in two distinct
				ways: 
			 <ol> 
				<li> 
				 You can define the name of a custom
					 XSQLErrorHandler implementation class in the
					 XSQLConfig.xml file by providing the fully-qualified
					 classname of your error writer class as the value of the
					 XSQLConfig.xml file entry
					 /XSQLConfig/processor/error-handler/class. 
				 If the Page Processor can load this class and it correctly
					 implements the XSQLErrorHandler interface, then this class
					 is used as a singleton and replaces the default implementation globally,
					 wherever page processor errors are reported. 
				</li> 
				<li> 
				 You can override the error writer on a per-page basis using
					 the new, optional errorHandler (or
					 xsql:errorHandler) attribute on the document element of your
					 page. 
				 The value of this attribute is the fully-qualified class
					 name of a class that implements the XSQLErrorHandler
					 interface. This class will be used to report the errors for just this page and
					 the class is instantiated on each page request by the page engine. 
				 Or you can use a combination of both approaches. 
				</li> 
			 </ol>

</li> 
		 <li> 
			 Provide Custom XSQLLogger
				Implementation
 
 
 
			 Customers have asked for a way to log XSQL page requests. Two
				new interfaces are introduced in this release
				oracle.xml.xsql.XSQLLoggerFactory and
				oracle.xml.xsql.XSQLLogger that allow developers to achieve
				this. 
			 The XSQLLoggerFactory interface contains the
				single method: 
			 <pre>public interface XSQLLoggerFactory {
 public XSQLLogger create( XSQLPageRequest env);
}</pre>
			 You can provide a class that implements the
				XSQLLoggerFactory interface to decide how
				XSQLLogger objects should be created (or reused) for
				logging. The XSQL Page processor holds a reference to the XSQLLogger object
				returned by the factory for the duration of a page request and using it to log
				the start and end of each page request by invoking the
				logRequestStart() and logRequestEnd()
				methods on it. 
			 Here is the interface for XSQLLogger:
			 
			 <pre>public interface XSQLLogger {
 public void logRequestStart(XSQLPageRequest env) ;
 public void logRequestEnd(XSQLPageRequest env);
}</pre>
			 The following two classes illustrate a trivial implementation
				of a custom logger. First is the XSQLLogger implementation
				which notes the time the page request started and then logs the page request
				end by printing the name of the page request and the elapsed time to
				System.out: 
			 <pre>package example;
import oracle.xml.xsql.*;
public class SampleCustomLogger implements XSQLLogger {
 long start = 0;
 public void logRequestStart(XSQLPageRequest env) {
 start = System.currentTimeMillis();
 }
 public void logRequestEnd(XSQLPageRequest env) {
 long secs = System.currentTimeMillis() - start;
 System.out.println("Request for " + env.getSourceDocumentURI() + " took "+ secs + "ms");
 }
}</pre>
			 Next, the factory implementation: 
			 <pre>package example;
import oracle.xml.xsql.*;
public class SampleCustomLoggerFactory implements XSQLLoggerFactory {
 public XSQLLogger create(XSQLPageRequest env) {
 return new SampleCustomLogger();
 }
}</pre>
			 To register a custom logger factory, edit the XSQLConfig.xml
				file and provide the name of your custom logger factory class as the conent to
				the /XSQLConfig/processor/logger/factory element like
				this: 
			 <pre>&lt;XSQLConfig&gt;
 :
 &lt;processor&gt;
 :
 &lt;logger&gt;
 &lt;factory&gt;test.SampleCustomLoggerFactory&lt;/factory&gt;
 &lt;/logger&gt;
 :
 &lt;/processor&gt;
&lt;/XSQLConfig&gt;</pre>
			 By default, this 
 &lt;logger>
 section is commented
				out. There is no default logger.

</li> 
		 <li> 
			 Override the Default Name of of the XSQLConfig.xml
				file
 
 
 
			 Customers have requested a way to override the default
				XSQLConfig.xml file name so that they can easily provide
				different configuration files for test and production environments, for
				example. This releases introduces two ways to override the name. 
			 <ol> 
				<li> 
				 By setting the Java System property
					 xsql.config
 
				 The simplest way to accomplish this is to specify a Java VM
					 command-line flag like -Dxsql.config= 
					 MyConfigFile.xml
 
 
				</li> 
				<li> 
				 By defining a servlet initialization parameter
					 xsql.config
 
				 This is accomplished by adding an
					 
 &lt;init-param>
 element to your web.xml file
					 as part of the 
 &lt;servlet>
 tag that defines the XSQL Servlet as
					 follows: 
				 <pre> :
 &lt;servlet&gt;
 &lt;servlet-name&gt;XSQL&lt;/servlet-name&gt;
 &lt;servlet-class&gt;oracle.xml.xsql.XSQLServlet&lt;/servlet-class&gt;
 &lt;init-param&gt;
 &lt;param-name&gt;xsql.config&lt;/param-name&gt;
 &lt;param-value&gt;MyConfigFile.xml&lt;/param-value&gt;
 &lt;description&gt;Please Use MyConfigFile.xml instead of XSQLConfig.xml&lt;/description&gt;
 &lt;/init-param&gt;
 &lt;/servlet&gt;
 :</pre>

</li> 
			 </ol> 
			 Of course, the servlet initialization parameter is only
				applicable to the servlet-based use of the XSQL Pages engine. When using the
				XSQLCommandLine or XSQLRequest
				programmatic interfaces, use the System parameter instead. 
			 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				The config file is always read from the CLASSPATH. For
				 example, if you specify a custom configuration parameter file named
				 MyConfigFile.xml, then the XSQL page processor will attempt
				 to read the XML file as a resource from the CLASSPATH. In a J2EE-style servlet
				 environment, that means you should put your MyConfigFile.xml into the
				 .\WEB-INF\classes directory (or some other top-level
				 directory that will be found on the CLASSPATH). If both
				 the servlet initialization parameter and the System parameter are provided, the
				 servlet initialization parameter value is used. 
			 </td>
 </tr>
 </table> 
		 </li> 
		 <li> 
			 Support for Apache FOP 0.20.3
 
 
 
			 If you need to render PDF output from XSQL pages, this release
				supports working with the 0.20.3 release candidate of Apache FOP. The source
				code for the FOP Serializer in this release looks like this: 
			 <pre>package oracle.xml.xsql.serializers;
import org.w3c.dom.Document;
import org.apache.log.Logger;
import org.apache.log.Hierarchy;
import org.apache.fop.messaging.MessageHandler;
import org.apache.log.LogTarget;
import oracle.xml.xsql.XSQLPageRequest;
import oracle.xml.xsql.XSQLDocumentSerializer;
import org.apache.fop.apps.Driver;
import org.apache.log.output.NullOutputLogTarget;
/**
 * Tested with the FOP 0.20.3RC release from 19-Jan-2002
 */
public class XSQLFOPSerializer implements XSQLDocumentSerializer {
 private static final String PDFMIME = "application/pdf";
 public void serialize(Document doc, XSQLPageRequest env) throws Throwable {
 try {

// First make sure we can load the driver
      Driver FOPDriver = new Driver();

// Tell FOP not to spit out any messages by default.
      // You can modify this code to create your own FOP Serializer
      // that logs the output to one of many different logger targets
      // using the Apache LogKit API
      Logger logger = Hierarchy.getDefaultHierarchy().getLoggerFor("XSQLServlet");
      logger.setLogTargets(new LogTarget[]{new NullOutputLogTarget()});
      FOPDriver.setLogger(logger);
      // Some of FOP's messages appear to still use MessageHandler.
      MessageHandler.setOutputMethod(MessageHandler.NONE);

// Then set the content type before getting the reader/
 env.setContentType(PDFMIME);
 
 FOPDriver.setOutputStream(env.getOutputStream());
 FOPDriver.setRenderer(FOPDriver.RENDER_PDF);
 FOPDriver.render(doc);
 }
 catch (Exception e) {
 // Cannot write PDF output for the error anyway.
 // So maybe this stack trace will be useful info
 e.printStackTrace(System.err);
 }
 }
}</pre>
			 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				Using Apache FOP requires adding the following additional JAR
				 files to your XSQL Pages runtime CLASSPATH to function correctly: 
				<ul> 
				 <li> 
					 
 fop.jar (Apache FOP Rendering
						Engine) 
				 </li> 
				 <li> 
					 
 avalon-framework-4.0.jar (Base Apache
						Avalon Framework API's) 
				 </li> 
				 <li> 
					 
 logkit-1.0.jar (Apache Avalon
						Framework's LogKit subcomponent) 
				 </li> 
				 <li> 
					 
 batik.jar (Apache Batik SVG Rendering
						Engine) 
				 </li> 
				</ul> 
			 </td>
 </tr>
 </table> 
		 </li> 
		 <li> 
			 Set Preserve Whitespace Config
				Option
 
 
 
			 It is now possible to control whether or not the XSQL Page
				Processor uses the Oracle XML Parser to parse XSQL page templates and XSLT
				stylesheets with whitespace preserving mode. The default has always been to
				preserve whitespace, but it can be slightly faster to parse these documents
				with whitespace-preserving mode off. For backward compatibility, the default is
				to preserve whitespace, but to turn off whitespace-preserving mode set the new
				XSQLConfig.xml file entry
				/XSQLConfig/processor/xml-parsing/preserve-whitespace to the
				value false. 
		 </li> 
		</ul><a name="ID1975">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Bugs Fixed</h3>
 </a>
 <ul> 
		 <li> 
			 Tags present in stylesheet name are not quoted in the
				error message
 
 
 
			 A potential security issue was reported whereby a malicious
				user could execute JavaScript in the browser by passing in a value like
				&lt;script&gt;alert('Bingo.');&lt;/script&gt; for the value
				of the xml-stylesheet parameter. When the XSQL Servlet
				renders the error page to complain that a stylesheet named
				"&lt;script&gt;alert('Bingo.');&lt;/script&gt;" could not be
				found, it was not quoting the tags so the &lt;script&gt; tag
				would be interpreted by the browser. Now any tag maliciously introduced this
				way are quoted so that they appear as literal text in the error page instead of
				as an executable script tag. The security issue was minimal since users could
				always disable client styling on any or all pages to completely ignore the
				value of the xml-stylesheet parameter, but with this fix,
				even a page that allows client styling is no longer a victim to this
				vulnerability. 
		 </li> 
		 <li> 
			 &lt;xsql:include-xml&gt; Only Works with Clobs using
				the Oracle JDBC Driver
 
 
 
			 Now any JDBC driver that supports java.sql.Clob can be used to
				select a Clob-valued XML document for inclusion in the page. 
		 </li> 
		</ul><a name="securityinfo"></a><a name="ID2041">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Security Consideration for Production XSQL Pages Systems</h2>
 </a>
 As with any software running on a server, care must be taken to avoid
		risks of exposing sensitive information to malicious users. This section
		describes best practice security techniques for using the Oracle XSQL
		Servlet.
 <ul> 
		<li> 
		 Install Your XSQLConfig.xml File in a Safe
			 Directory
 
 
 
		 The XSQLConfig.xml configuration file contains
			 sensitive database username/password information that must be kept secure on
			 the server. This file should not reside in any directory that is mapped to a
			 virtual path of your Web server, nor in any subdirectory thereof. Its read
			 permissions need only be granted such that the Unix account that owns the
			 servlet engine can read it. 
		 Failure to follow this recommendation could mean that a user of
			 your site could accidentally (or intentionally) browse the contents of your
			 configuration file. 
		</li> 
		<li> 
		 Disable Default Client Stylesheet Overrideability When
			 Your Pages Go Production
 
 
 
		 By default, the XSQL Page Processor allows the user to supply a
			 stylesheet in the request by passing a value for the special
			 xml-stylesheet parameter. If you want the stylesheet that is
			 referenced inside if your server-side XSQL page to be the only stylesheet that
			 is used, then you can include the allow-client-style="no"
			 attribute on the document element of your page. You also can
			 globally change the default setting to disallow client
			 stylesheet overrides by changing a setting in your
			 XSQLConfig.xml file. If you do this, then only pages that
			 will allow client stylesheet overrides are ones that include the
			 allow-client-style="yes" attribute on their document
			 element. 
		</li> 
		<li> 
		 Be Alert of the Use of Subsitution
			 Parameters
 
 
 
		 With power comes responsibility. Any product, like Oracle Reports
			 and XSQL Pages among others, that supports the use of lexical substitution
			 variables in a SQL query can give a developer enough rope to hang himself. Any
			 time you deploy an XSQL page that allows important parts of a SQL statement (or
			 at the extreme, the entire SQL statement) to be substituted by a lexical
			 parameter, you should make sure that you have taken appropriate precautions
			 against misuse. 
		 For example, one of the demonstrations that comes with XSQL Pages
			 is the "adhoc query demo". It illustrates how the entire SQL statement of an
			 
 &lt;xsql:query>
 action handler can be supplied as a parameter.
			 This is a powerful capability when in the right users hands, but be aware if
			 you deploy a similar kind of page to your product system that the user can
			 execute any query that the database security privileges for the connection
			 associated with the page allows. The demo is setup to use a connection that
			 maps to the SCOTT account, so a user of the "adhoc query demo" can query any
			 data that SCOTT would be allowed to query from the SQL*Plus command line.
			 
		 Techniques that can be used to make sure your pages are not
			 abused include: 
		 <ul> 
			 <li> 
				Making sure the database user account associated with the
				 page has only the privileges for reading the tables/views you want your users
				 to see. 
			 </li> 
			 <li> 
				Using true bind variables instead of lexical bind variables
				 when substituting single values in a SELECT statement. If you need to make
				 syntactic parts of your SQL statement parameterized, then lexical parameters
				 are the only game in town. Otherwise, true bind variabled are recommended so
				 that any attempt to pass an invalid value will generate an error instead of
				 producing an unexpected result. 
			 </li> 
		 </ul> 
		</li> 
	 </ul><a name="ID2165">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Reference Information</h2>
 </a><a name="ID2172">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Online Help</h3>
 </a>
 This release includes an on-line Help System (built using XSQL
		 Pages, of course) giving helpful information about the syntax and options for
		 each XSQL Action Element. In additional helpful examples are provided
		 illustrating each action. To access the help system, after successfully
		 installing the XSQL Servlet, browse the URL:
 
		 <pre>http://yourmachine/xsql/index.html</pre>

<table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/helpsystem.gif">
 </td>
 </tr>
 </table><a name="ID2196">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> XSQL Action Handler Summary</h3>
 </a>
 A number of new built-in XSQL Action Elements have been added in
		 this release. The following table documents the new arrivals...
 <table border="0" cellpadding="3" cellspacing="0"> 
			 <tr class="tableheader">
 <td> Action Element </td>
 <td> Description </td>
 </tr> 
			 <tr class="ro">
 <td> 
 &lt;xsql:set-stylesheet-param>
 </td>
 <td> 
					 Set the value of a top-level XSLT stylesheet parameter.
						 </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:set-page-param>
 </td>
 <td> 
					 Set a page-level (local) parameter that can be referred
						to in subsequent SQL statements in the page. </td>
 </tr>
 <tr class="ro">
 <td> 
 &lt;xsql:set-session-param>
 </td>
 <td> 
					 Set an HTTP-Session level parameter. </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:set-cookie>
 </td>
 <td> 
					 Set an HTTP Cookie. </td>
 </tr>
 <tr class="ro">
 <td> 
 &lt;xsql:query>
 </td>
 <td> 
					 Execute an arbitrary SQL statement and include its
						result set in canonical XML format. </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:ref-cursor-function>
 </td>
 <td> 
					 Includes the canonical XML representation of the result
						set of a cursor returned by a PL/SQL stored function. </td>
 </tr>
 <tr class="ro">
 <td> 
 &lt;xsql:include-param>
 </td>
 <td> 
					 Include a parameter and its value as an element in your
						XSQL page. </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:include-request-params>
 </td>
 <td> 
					 Include all request parameters as XML elements in your
						XSQL page. </td>
 </tr>
 <tr class="ro">
 <td> 
 &lt;xsql:include-xml>
 </td>
 <td> 
					 Include arbitrary XML resources at any point in your
						page by relative or absolute URL. </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:include-owa>
 </td>
 <td> 
					 Include the results of executing a stored procedure that
						makes use of the Oracle Web Agent (OWA) packages inside the database to
						generate XML. </td>
 </tr>
 <tr class="ro">
 <td>
 &lt;xsql:if-param>
 
 </td>
 <td> 
					 Includes nested actions and/or literal XML content if
						some condition based on a parameter value is true. 
 </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:include-xsql>
 </td>
 <td> 
					 Include the results of one XSQL page at any point inside
						another. </td>
 </tr>
 <tr class="ro">
 <td> 
 &lt;xsql:insert-request>
 </td>
 <td> 
					 Insert the XML document (or HTML form) posted in the
						request into a database table or view. </td>
 </tr>
 <tr class="re">
 <td>
 &lt;xsql:update-request>
 
 </td>
 <td> 
					 Update an existing row in the database based on the
						posted XML document supplied in the request.
 </td>
 </tr>
 <tr class="ro">
 <td>
 &lt;xsql:delete-request>
 
 </td>
 <td> 
					 Delete an existing row in the database based on the
						posted XML document supplied in the request.
 </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:insert-param>
 </td>
 <td> 
					 Inserts the XML document contained in the value of a
						single parameter. </td>
 </tr>
 <tr class="ro">
 <td> 
 &lt;xsql:dml>
 </td>
 <td> 
					 Execute a SQL DML statement or PL/SQL anonymous block.
						 </td>
 </tr>
 <tr class="re">
 <td> 
 &lt;xsql:action>
 </td>
 <td> 
					 Invoke a user-defined action handler, implemented in
						Java, for executing custom logic and including custom XML information into your
						XSQL page. </td>
 </tr> 
		 </table><a name="ID2588">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Parameter Resolution</h3>
 </a>
 XSQL provides a single way to refer to values that can be specified
		 as:
 <ul> 
		 <li> 
			 HTTP Request Parameters 
		 </li> 
		 <li> 
			 HTTP Cookies 
		 </li> 
		 <li> 
			 HTTP Session Variables 
		 </li> 
		 <li> 
			 Local XSQL Page Parameters 
		 </li> 
		</ul>
 When you reference an parameter like myParam
		 inside the content of an XSQL Action Element, like:
 <pre>&lt;xsql:query&gt;
 select name from users where userid = {@myParam}
&lt;/xsql:query&gt;</pre>
 or in the attribute value of an XSQL Action Element, like:
 <pre>&lt;xsql:query max-rows="{@myParam}"&gt;
 :
&lt;/xsql:query&gt;</pre>
 the XSQL Page Processor determines the value of the parameter by
		 using the following logic.
 If the request is being processed by the XSQL
		 Servlet, then check in the following order if
		 myParam is the name of...
 <ol> 
		 <li> 
			 An XSQL local page parameter 
		 </li> 
		 <li> 
			 An HTTP Cookie 
		 </li> 
		 <li> 
			 An HTTP Session Variable 
		 </li> 
		 <li> 
			 An HTTP Request Parameter 
		 </li> 
		</ol>
 If the request is being processed by a non-Servlet request method
		 using XSQLCommandLine or the XSQLRequest
		 class, then check in the following order if myParam is the
		 name of...
 <ol> 
		 <li> 
			 An XSQL local page parameter 
		 </li> 
		 <li> 
			 An XSQL Request parameter 
			 Provided on the command-line or passed into the
				XSQLRequest.process() method. 
		 </li> 
		</ol>
 In either case, if none of the attempts produces a matching
		 parameter value, the XSQL Page Processor looks for a "fallback" (a.k.a
		 "default") value for myParam by searching the current Action
		 Element and its ancestor elements in order to find an XML attribute of the same
		 name as the parameter. If such an attribute is found, it's value is used as the
		 value of myParam. <a name="ID2778">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Known Issues</h3>
 </a>
 This release contains the following known issues: 
		 <ul> 
			 <li> 
				HTTP parameters with multibyte names (e.g. a parameter whose
				 name is in Kanji) are properly handled when they are inserted into your XSQL
				 page using 
 &lt;xsql:include-request-params>
 , but an attempt to
				 refer to a parameter with a multibyte name inside the query statement of an
				 
 &lt;xsql:query>
 tag will return an empty string for the
				 parameter's value. The workaround is to use a non-multibyte parameter name. The
				 parameter can still properly have a multibyte value which
				 will be handled correctly. 
			 </li> 
			 <li> 
				Using the CURSOR() function in SQL
				 statements can cause an "Exhausted ResultSet" error if
				 CURSOR() statements are nested and outer CURSOR()
				 functions evaluate to an empty rowset. 
			 </li> 
			 <li> 
				When using the Apache JServ servlet engine, the use of
				 relative stylesheet and XSQL page references may not produce the results you
				 expect if you have an elaborate virtual path mapping. Since the Apache JServ
				 engine does not properly implement the Servlet API method
				 getRealPath() that the XSQL Servlet uses to resolve a path
				 relative to the web server's virtual file system, a workaround is implemented
				 for JServ to make relative path references work for the most common
				 cases. 
			 </li> 
		 </ul> <a name="installation"></a><a name="ID2851">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Installation</h2>
 </a><a name="ID2859">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Supported Configurations</h3>
 </a>
 The XSQL Servlet is designed to run on any
		 Java VM, using any JDBC driver, against any database. In practice, we are able
		 to test it against only the most popular configurations of these. In this
		 section we document the supported configurations that have been tested in the
		 Oracle labs.<a name="ID2874">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Supported Java JDK Versions</h4>
 </a>
 The XSQL Pages and XSQL Servlet have been tested using:
 <ul> 
			 <li> 
				JDK 1.1.8 
			 </li> 
			 <li> 
				JDK 1.2.2 
			 </li> 
			 <li> 
				JDK 1.3 
			 </li> 
		 </ul>
 These are the only three JDK versions that we
			 know work correctly. 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
			 Numerous users have reported problems using XSQL Pages and the
				XSQL Servlet with JDK 1.1.7 which suffers problems in its character set
				conversion routines for UTF-8 that make it unusable for processing XSQL
				Pages. 
		 </td>
 </tr>
 </table> <a name="ID2930">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Supported Servlet Engines</h4>
 </a>
 This XSQL Servlet has been tested with the following servlet
			 engines: 
 <ul> 
			 <li> 
				Oracle9iAS Apache/JServ Servlet Engine 
			 </li> 
			 <li> 
				Oracle9iAS OC4J Servlet Engine 
			 </li> 
			 <li> 
				Allaire JRun 2.3.3 and 3.0.0 
			 </li> 
			 <li> 
				Apache 1.3.9 with JServ 1.0 and 1.1 
			 </li> 
			 <li> 
				Apache 1.3.9 with Tomcat 3.1 or 3.2 Servlet Engine 
			 </li> 
			 <li> 
				Apache Tomcat 3.1 or 3.2 Web Server + Servlet Engine 
			 </li> 
			 <li> 
				Caucho Resin 1.1 
			 </li> 
			 <li> 
				Java Web Server 2.0 
			 </li> 
			 <li> 
				Weblogic 5.1 Web Server 
			 </li> 
			 <li> 
				NewAtlanta ServletExec 2.2 and 3.0 for IIS/PWS 4.0 
			 </li> 
			 <li> 
				Oracle8i Lite Web-to-Go Server 
			 </li> 
			 <li> 
				Oracle8i 8.1.7 Oracle Servlet
				 Engine 
			 </li> 
			 <li> 
				Sun JavaServer Web Development Kit (JSWDK) 1.0.1 Web
				 Server 
			 </li> 
		 </ul><a name="ID3058">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Supported JSP Implementations</h4>
 </a>
 JavaServer Pages can use 
 &lt;jsp:forward>
 and/or
			 
 &lt;jsp:include>
 to collaborate with XSQL Pages as part of an
			 application. The following JSP platforms have been tested:
 <ul> 
			 <li> 
				Oracle9iAS Apache/JServ Servlet Engine 
			 </li> 
			 <li> 
				Oracle9iAS OC4J Servlet Engine 
			 </li> 
			 <li> 
				Apache 1.3.9 with Tomcat 3.1 or 3.2 Servlet Engine 
			 </li> 
			 <li> 
				Apache Tomcat 3.1 or 3.2 Web Server + Tomcat 3.1 or 3.2
				 Servlet Engine 
			 </li> 
			 <li> 
				Caucho Resin 1.1 (Built-in JSP 1.0 Support) 
			 </li> 
			 <li> 
				NewAtlanta ServletExec 2.2 and 3.0 for IIS/PWS 4.0 (Built-in
				 JSP 1.0 Support) 
			 </li> 
			 <li> 
				Oracle8i Lite Web-to-Go Server with
				 Oracle JSP 1.0 
			 </li> 
			 <li> 
				Oracle8i 8.1.7 Oracle Servlet
				 Engine 
			 </li> 
			 <li> 
				Any Servlet Engine with Servlet API 2.1+ and Oracle JSP
				 1.0 
			 </li> 
		 </ul>
 In general, it should work with any servlet engine supporting the
			 Servlet 2.1 Specification or higher, and the Oracle JSP 1.0 reference
			 implementation or functional equivalent from another vendor.<a name="ID3166">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> JDBC Drivers and Databases</h4>
 </a>
 The Oracle XSQL Page processor has been designed to exploit the
			 maximum set of features against the Oracle JDBC drivers,
			 but gracefully degrade to work against any database with a reasonable JDBC
			 driver. While numerous users have reported successfully using XSQL Pages with
			 many other JDBC drivers, the ones that we have tested in-house are:
 <ul> 
			 <li> 
				Oracle8i 8.1.5 Driver for JDBC 1. 
				 x
 
			 </li> 
			 <li> 
				Oracle8i 8.1.6 Driver for JDBC 1. 
				 x
 
			 </li> 
			 <li> 
				Oracle8i 8.1.7 Driver for JDBC 1. 
				 x
 
			 </li> 
			 <li> 
				Oracle8i Lite 4.0 Driver for JDBC
				 1.x 
			 </li> 
			 <li> 
				Oracle8i 8.1.6 Driver for JDBC
				 2.0 
			 </li> 
			 <li> 
				Oracle8i 8.1.7 Driver for JDBC
				 2.0 
			 </li> 
			 <li> 
				Oracle9i 9.0.1 Driver for JDBC
				 2.0 
			 </li> 
		 </ul><a name="ID3280">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Prerequisites</h3>
 </a>
 Oracle XSQL Pages 10.0.0.0 depends on: 
 <ul> 
		 <li> 
			 Oracle XML Parser V2, version 9.0.1 or higher 
		 </li> 
		 <li> 
			 Oracle XML SQL Utilities for Java, version 2.0.1 or higher 
		 </li> 
		 <li> 
			 A Web Server that supports Java Servlets 
		 </li> 
		 <li> 
			 A JDBC driver, like Oracle JDBC or
				Oracle8i Lite JDBC 
		 </li> 
		</ul>
 For your convenience, all of these dependent libraries are
		 included with the XSQL Servlet distribution when you download it.<a name="ID3336">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> XSQL Software Included in the XDK Distribution</h3>
 </a>
 In addition to the Oracle XSQL Servlet archive itself in
		 .\lib\oraclexsql.jar, and the optional
		 .\lib\xsqlserializers.jar archive for FOP/PDF integration,
		 the Oracle Technet (OTN) distribution of the XDK includes the following Oracle
		 XDK components on which Oracle XSQL Pages depends:
 <ul> 
		 <li> 
			 Oracle XML Parser V2,
				.\lib\xmlparserv2.jar
 
		 </li> 
		 <li> 
			 Oracle XML SQL Utility,
				.\lib\xsu12.jar
 
		 </li> 
		</ul><a name="ID3386">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Downloading and Installing the XSQL Servlet</h3>
 </a>
 <a name="ID3397">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Obtaining the XSQL Servlet Software from Oracle Technet</h4>
 </a>
 You can download the XSQL Servlet as part of the Oracle XDK for
			 Java download by:
 <ol> 
			 <li> 
				Visiting 
				 <a href="http://otn.oracle.com/tech/xml">http://otn.oracle.com/tech/xml</a>
 
				
			 </li> 
			 <li> 
				Clicking on the 'Software' icon at the top of the page: 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/software_download.gif">
 </td>
 </tr>
 </table> 
			 </li> 
			 <li> 
				Logging in with your OTN username and password (registration
				 is free if you do not already have an account). 
			 </li> 
			 <li> 
				Selecting whether you want the NT or Unix download (both
				 contain the same files) 
			 </li> 
			 <li> 
				Acknowledging the licensing agreement and download
				 survey 
			 </li> 
			 <li> 
				Clicking on appropriate *.tar.gz or
				 *.zip file. 
			 </li> 
		 </ol><a name="ID3481">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Extracting the Files in the Distribution</h4>
 </a>
 To extract the contents of the XDK distribution, do the
			 following:
 <ol> 
			 <li> 
				 Choose a directory under which you would like the
				 .\xdk directory and subdirectories to go. (e.g.
				 C:\) 
			 </li> 
			 <li> 
				 Change directory to C:\, then extract the
				 XSQL downloaded archive file there. For example: 
				<pre>tar xvfz xdk_xxx.tar.gz</pre>
				on Unix, or on Windows: 
				<pre>pkzip25 -extract -directories xdk_xxx.zip</pre>
				 using the 
				 <a href="http://www.pkware.com/shareware/pkzip_cli.html">pkzip25</a>
				 command-line tool or the 
				 <a href="http://www.winzip.com">WinZip</a> visual archive
				 extraction tool.

</li> 
		 </ol><a name="ID3558">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Setting Up the Database Connection Definitions for Your
			 Environment</h4>
 </a>
 The demos are set up to use the SCOTT schema
			 on a database on your local machine (i.e. the machine where the web server is
			 running). If you are running a local database and have a
			 SCOTT account whose password is TIGER,
			 then you are all set. Otherwise, you need to edit the
			 .\xdk\admin\XSQLConfig.xml file to correspond to your
			 appropriate values for username,
			 password, dburl, and
			 driver values for the connection named
			 "demo".
 <pre>&lt;?xml version="1.0" ?&gt;
&lt;XSQLConfig&gt;
 :
 &lt;connectiondefs&gt;
 &lt;connection name="demo"&gt;
 &lt;username&gt;scott&lt;/username&gt;
 &lt;password&gt;tiger&lt;/password&gt;
 &lt;dburl&gt;jdbc:oracle:thin:@localhost:1521:ORCL&lt;/dburl&gt;
 &lt;driver&gt;oracle.jdbc.OracleDriver&lt;/driver&gt;
 &lt;/connection&gt;
 &lt;connection name="lite"&gt;
 &lt;username&gt;system&lt;/username&gt;
 &lt;password&gt;manager&lt;/password&gt;
 &lt;dburl&gt;jdbc:Polite:POlite&lt;/dburl&gt;
 &lt;driver&gt;oracle.lite.poljdbc.POLJDBCDriver&lt;/driver&gt;
 &lt;/connection&gt;
 &lt;/connectiondefs&gt;
 :
&lt;/XSQLConfig&gt;</pre><a name="ID3620">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Setting Up Your Servlet Engine to Run XSQL Pages</h4>
 </a>
 Unix users and any user wanting to install the XSQL Servlet on
			 other web servers should continue with the instructions below depending on the
			 web server you're trying to use. In every case, there are 3 basic steps:
 <ol> 
			 <li> 
				Include the list of XSQL Java archives: 
				<ul> 
				 <li> 
					 
 xsu12.jar- Oracle XML SQL
						Utility 
				 </li> 
				 <li> 
					 
 xmlparserv2.jar- Oracle XML Parser for
						Java V2 
				 </li> 
				 <li> 
					 
 oraclexsql.jar- Oracle XSQL
						Pages 
				 </li> 
				 <li> 
					 
 xsqlserializers.jar- Oracle XSQL
						Serializers for FOP/PDF Integration 
				 </li> 
				 <li> 
					 
 ojdbc5.jar- Oracle JDBC
						Driver 
					 or the JAR file for the JDBC driver you will be
						using instead
 
				 </li> 
				</ul> 
				 as well as the directory where
				 XSQLConfig.xml resides (by default
				 ./xdk/admin) in the server CLASSPATH. 
				 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				 In a production system, make sure your
					 XSQLConfig.xml file does not reside under a directory that
					 is broweable from your web server. See 
					 <a href="#securityinfo">Security Considerations for
						Production XSQL Pages System</a> for more information. 
				</td>
 </tr>
 </table> 
			 </li> 
			 <li> 
				Map the .xsql file extension to the
				 oracle.xml.xsql.XSQLServlet servlet class 
			 </li> 
			 <li> 
				Map a virtual directory /xsql to the
				 directory where you extracted the XSQL files (to access the on-line help and
				 demos) 
			 </li> 
		 </ol><a name="oc4j_install"></a><a name="ID3778">
 <h5 style="color:#000044"><img src="images/line4.gif" width="100" height="7"> Oracle 9iAS 2.0 Oracle Containers for J2EE (OC4J) Servlet
				Container</h5>
 </a>
 You can install the XSQL Servlet in one of two ways:
 <ul> 
				<li> 
				 You can deploy the xsqldemos.ear file to
					 the OC4J server, or 
				</li> 
				<li> 
				 You can install the XSQL Servlet as a global application to
					 handle *.xsql files globally, similar to how
					 *.jsp files are globally recognized and handled by the
					 JSP-Runner servlet. 
				</li> 
			 </ul>
 To install xsqldemos.ear...
 <ul> 
				<li> 
				 Change directory to the ./j2ee/home
					 directory. 
				</li> 
				<li> 
				 Deploy the ear file with the command (all on one line,
					 replacing 
					 admin and 
					 welcome with your username and
					 password for OC4J administration): 
				 <pre>java -jar admin.jar ormi://yourserver/ admin welcome
 -deploy -file XDKHome/xdk/demo/java/xsql/xsqldemos.ear -deploymentName xsqldemos</pre>

</li> 
				<li> 
				 Bind the web application with the command (all on one line,
					 replace 
					 admin and 
					 welcome as above, using
					 default-web-site or http-web-site as
					 appropriate): 
				 <pre>java -jar admin.jar ormi://yourserver/ admin welcome
 -bindWebApp xsqldemos xsqldemos http-web-site /xsql</pre>

</li> 
			 </ul>
 The demos can then be run by browsing:
 
 http:// 
				yourserver: 
				port/xsql/index.html
 
 To install XSQL Servlet in the Oracle9iAS OC4J servlet
				container as a global application, do the following instead. Assuming your OC4J
				installation home is C:\j2ee\home, and that you've extracted
				the XDK distribution into the C:\xdk902 directory, here are
				the setup steps:
 <ol> 
				<li> 
				 Verify that the following jar files are already in your
					 C:\j2ee\home\lib directory (they should come
					 preinstalled): 
				 <ul> 
					 <li> 
						
 xmlparserv2.jar- Oracle XML Parser
						 for Java V2 
					 </li> 
					 <li> 
						
 ojdbc5.jar- Oracle JDBC
						 Driver 
					 </li> 
				 </ul> 
				</li> 
				<li> 
				 Copy the following additional jar files from
					 C:\xdk902\lib to
					 C:\j2ee\home\lib... 
				 <ul> 
					 <li> 
						
 xsu12.jar- Oracle XML SQL
						 Utility 
					 </li> 
					 <li> 
						
 oraclexsql.jar- Oracle XSQL
						 Pages 
					 </li> 
					 <li> 
						
 xsqlserializers.jar- Oracle XSQL
						 Serializers for FOP/PDF Integration 
					 </li> 
				 </ul> 
				</li> 
				<li> 
				 Copy the C:\xdk\admin\XSQLConfig.xml
					 configuration file to the
					 C:\j2ee\home\default-web-app\WEB-INF\classes
					 directory. 
				</li> 
				<li> 
				 Edit the
					 C:\j2ee\home\config\global-web-application.xml server
					 configuration file to add a 
 &lt;servlet>
 and
					 
 &lt;servlet-mapping>
 entry as child elements of the
					 
 &lt;web-app>
 element as follows: 
				 <pre>&lt;orion-web-app ...etc... &gt;
 :
 etc
 :
 &lt;web-app&gt;
 &lt;servlet&gt;
 &lt;servlet-name&gt;xsql&lt;/servlet-name&gt;
 &lt;servlet-class&gt;oracle.xml.xsql.XSQLServlet&lt;/servlet-class&gt;
 &lt;/servlet&gt;
 &lt;servlet-mapping&gt;
 &lt;servlet-name&gt;xsql&lt;/servlet-name&gt;
 &lt;url-pattern&gt;/*.xsql&lt;/url-pattern&gt;
 &lt;/servlet-mapping&gt;
 :
 etc
 :
 &lt;/web-app&gt;
&lt;/web-app&gt;</pre>

</li> 
				<li> 
				 At this point, you can refer to any XSQL page in
					 any virtual path and it will be processed by the XSQL
					 Servlet. If you want to try the XSQL built-in samples, demos, and online help
					 then you need to perform the following additional step to map a virtual path of
					 /xsql/ to the C:\xdk\demo\java\xsql
					 directory. 
				 Edit the
					 c:\j2ee\home\application-deployments\default\defaultWebApp\orion-web.xml
					 file to add the following 
 &lt;virtual-directory>
 entry: 
				 <pre>&lt;orion-web-app ...etc...&gt;
 :
 etc
 :
 &lt;virtual-directory
 virtual-path="/xsql"
 real-path="/c:/xdk/xdk/demo/java/xsql/" /&gt;
 :
 etc
 :
&lt;/orion-web-app&gt;
</pre>

</li> 
			 </ol>
 Then, you can browse the demos using the URL
				http://yoursever:yourport/xsql/index.html
 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				In a production system, make sure your
				 XSQLConfig.xml file does not reside under a directory that
				 is broweable from your web server. See 
				 <a href="#securityinfo">Security Considerations for
					 Production XSQL Pages System</a> for more information. 
			 </td>
 </tr>
 </table> <a name="ID4176">
 <h5 style="color:#000044"><img src="images/line4.gif" width="100" height="7"> Oracle Internet Application Server</h5>
 </a>
 Oracle IAS release 1.0 and beyond comes pre-configured to run
				XSQL Servlet. By default it's Apache JServ servlet engine contains all of the
				wrapper.classpath entries in jserv.conf
				to include the necessary Java archives to run XSQL. The
				XSQLConfig.xml file lives in the
				./xdk/admin subdirectory of the IAS installation
				home. 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				In a production system, make sure your
				 XSQLConfig.xml file does not reside under a directory that
				 is broweable from your web server. See 
				 <a href="#securityinfo">Security Considerations for
					 Production XSQL Pages System</a> for more information. 
			 </td>
 </tr>
 </table> <a name="ID4226">
 <h5 style="color:#000044"><img src="images/line4.gif" width="100" height="7"> Allaire JRun 2.3.3</h5>
 </a>
 <ol> 
				<li> 
				 Setup the Server CLASSPATH Correctly for the XSQL
					 Servlet
 
 
 
				 This is done by starting the JRun Administrator, clicking
					 on the General tab, and clicking on the
					 Java subtab as shown below. 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/jrun-step1.gif">
 </td>
 </tr>
 </table> 
				 Append the list of JAR files and directory that need to be
					 in the server CLASSPATH for the XSQL Servlet to the existing value in the Java
					 Classpath field. Assuming you installed into C:\, this list
					 looks like: 
				 <ul> 
					 <li> 
						To use the Oracle JDBC 1.x Driver, the list looks
						 like: 
						<pre>C:\xsql\lib\xsu111.jar;
C:\xsql\lib\xmlparserv2.jar;
directory_where_JDBC_Driver_resides\classes111.zip;
C:\xsql\lib\oraclexsql.jar;
directory_where_XSQLConfig.xml_resides
 </pre>
						To use Apache FOP for PDF Generation, you need to
						 add: 
						<pre>C:\xsql\lib\xsqlserializers.jar;
FOPHOME/build/fop.jar;
FOPHOME/lib/batik.jar;
FOPHOME/lib/logkit-1.0.jar;
FOPHOME/lib/avalon-framework-4.0.jar</pre>

</li> 
					 <li> 
						To use the Oracle JDBC 2.0 Driver, the list looks
						 like: 
						<pre>C:\xdk902\lib\xsu12.jar;
C:\xdk902\lib\xmlparserv2.jar;
directory_where_JDBC_Driver_resides\ojdbc5.jar;
C:\xdk902\lib\oraclexsql.jar;
directory_where_XSQLConfig.xml_resides
 </pre>

</li> 
				 </ul> 
				</li> 
				<li> 
				 Map the .xsql file extension
					 to the XSQL Servlet
 
 
 
				 To do this, select the Services tab in
					 the JRun Administrator and select the appropriate "JRun Servlet Engine for XXX"
					 entry for the Servlet Engine that corresponds to the web server that you are
					 using. In the example below, we'll show configuring the Servlet Engine for the
					 (built-in) JRun Web Server (JWS). 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/jrun-step2-1.gif">
 </td>
 </tr>
 </table> 
				 Then click the Service Config
					 button... 
				 On the Service Config screen, select the
					 Mappings tab. 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/jrun-step2-2.gif">
 </td>
 </tr>
 </table> 
				 Click the Add button and make an entry for the
					 *.xsql extension, indicating the name of the servlet to
					 invoke of oracle.xml.xsql.XSQLServlet as shown above. Then
					 click Save to save the changes, and
					 Close to dismiss the dialog. 
				</li> 
				<li> 
				 Map an /xsql/ virtual
					 directory
 
 
 
				 In this step, we want to map the virtual path
					 /xsql/ to C:\xdk902\xdk\demo\java\xsql\
					 (or wherever you installed the XSQL Servlet files). 
				 If you are using JRun together with another web server like
					 Apache, IIS, or others, the virtual directory mapping needs to be done using
					 the web server configuration file/utility. If you are using the JRun Web
					 Server, then you can configure this virtual path mapping from the JRun
					 Adminstrator. To do this, select the "jws" service and click on
					 Service Config. 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/jrun-step2-3.gif">
 </td>
 </tr>
 </table> 
				 Click on the Path Settings tab on the
					 Service Config dialog, and click the Add button as show
					 below.
 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/jrun-step2-4.gif">
 </td>
 </tr>
 </table> 
				 Make an entry for a virtual path of
					 /xsql/ (trailing slash important!) that maps to a Real Path
					 of C:\xdk902\xdk\demo\java\xsql\ (trailing slash
					 important!), or the appropriate directory into which you installed the XSQL
					 Servlet files. Click Save to save the changes, then
					 Close to dismiss the dialog. 
				</li> 
			 </ol>
 Restart the JRun server and browse the URL:
 <pre>http://localhost:8000/xsql/index.html</pre><a name="ID4500">
 <h5 style="color:#000044"><img src="images/line4.gif" width="100" height="7"> Apache JServ 1.0 or 1.1</h5>
 </a>
 <ol> 
				<li> 
				 Setup the Server CLASSPATH Correctly for the XSQL
					 Servlet
 
 
 
				 This is done by editing the JServ configuration file named
					 jserv.properties. Assuming you installed the XSQL Servlet
					 files into C:\, you need to add the following
					 entries: 
				 <ul> 
					 <li> 
						To use the Oracle JDBC 1.x Driver, the entries look
						 like: 
						<pre>
# Oracle XML SQL Utility (XSU)
wrapper.classpath=C:\xdk902\lib\xsu111.jar
# Oracle XSQL Servlet
wrapper.classpath=C:\xdk902\lib\oraclexsql.jar
# Oracle JDBC (8.1.6) -- JDBC 1.x driver
wrapper.classpath=directory_where_JDBC_Driver_resides\classes111.zip
# Oracle XML Parser V2 (with XSLT Engine)
wrapper.classpath=C:\xdk902\lib\xmlparserv2.jar
# XSQLConfig.xml File location
wrapper.classpath=directory_where_XSQLConfig.xml_resides
# FOR Apache FOP Generation, Add
# wrapper.classpath=C:\xdk902\lib\xsqlserializers.jar
# wrapper.classpath=FOPHOME/build/fop.jar
# wrapper.classpath=FOPHOME/lib/batik.jar
# wrapper.classpath=FOPHOME/lib/logkit-1.0.jar
# wrapper.classpath=FOPHOME/lib/avalon-framework-4.0.jar</pre>

</li> 
					 <li> 
						To use the Oracle JDBC 2.0 Driver, the list looks
						 like: 
						<pre>
# Oracle XML SQL Utility (XSU)
wrapper.classpath=C:\xdk902\lib\xsu12.jar
# Oracle XSQL Servlet
wrapper.classpath=C:\xdk902\lib\oraclexsql.jar
# Oracle JDBC (8.1.6) -- JDBC 2.0 driver
wrapper.classpath=directory_where_JDBC_Driver_resides\ojdbc5.jar
# Oracle XML Parser V2 (with XSLT Engine)
wrapper.classpath=C:\xdk902\lib\xmlparserv2.jar
# XSQLConfig.xml File location
wrapper.classpath=directory_where_XSQLConfig.xml_resides
# FOR Apache FOP Generation, Add
# wrapper.classpath=C:\xdk902\lib\xsqlserializers.jar
# wrapper.classpath=FOPHOME/build/fop.jar
# wrapper.classpath=FOPHOME/lib/batik.jar
# wrapper.classpath=FOPHOME/lib/logkit-1.0.jar
# wrapper.classpath=FOPHOME/lib/avalon-framework-4.0.jar
</pre>

</li> 
				 </ul> 
				</li> 
				<li> 
				 Map the .xsql file extension
					 to the XSQL Servlet
 
 
 
				 To do this, you need to edit the JServ configuration file
					 named jserv.conf (in JServ 1.0 this was named
					 mod_jserv.conf on some platforms). Add the following
					 line: 
				 <pre># Executes a servlet passing filename with proper extension in PATH_TRANSLATED 
# property of servlet request.
# Syntax: ApJServAction [extension] [servlet-uri]
# Defaults: NONE

ApJServAction .xsql /servlets/oracle.xml.xsql.XSQLServlet</pre>

</li> 
				<li> 
				 Map an /xsql/ virtual
					 directory
 
 
 
				 In this step, we want to map the virtual path
					 /xsql/ to C:\xdk902\xdk\demo\java\xsql\
					 (or wherever you installed the XSQL Servlet files). To do this, you need to
					 edit the Apache configuration file named httpd.conf and add
					 the following line: 
				 <pre>Alias /xsql/ "C:\xdk902\xdk\demo\java\xsql\"</pre>

</li> 
			 </ol>
 Restart the Apache server and browse the URL:
 <pre>http://localhost/xsql/index.html</pre><a name="ID4698">
 <h5 style="color:#000044"><img src="images/line4.gif" width="100" height="7"> Jakarta Tomcat 3.1 or 3.2</h5>
 </a>
 <ol> 
				<li> 
				 Setup the Server CLASSPATH Correctly for the XSQL
					 Servlet
 
 
 
				 This is done by editing the Tomcat startup script named
					 tomcat.bat in ./jakarta-tomcat/bin and
					 adding five lines to append the appropriate entries onto the system CLASSPATH
					 before the Tomcat server is started as shown below: 
				 <ul> 
					 <li> 
						To use the Oracle JDBC 1.x Driver, the entries look
						 like: 
						<pre>
rem Set up the CLASSPATH that we need

set cp=%CLASSPATH%

set CLASSPATH=.
set CLASSPATH=%TOMCAT_HOME%\classes
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\webserver.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\jasper.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xml.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\servlet.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\lib\tools.jar

REM Added for Oracle XSQL Servlet
REM -----------------------------
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsu111.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\oraclexsql.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xmlparserv2.jar
set CLASSPATH=%CLASSPATH%;directory_where_JDBC_Driver_resides\classes111.zip
set CLASSPATH=%CLASSPATH%;directory_where_XSQLConfig.xml_resides
REM FOR Apache FOP Generation, Add
REM set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsqlserializers.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/fop.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/lib/batik.jar</pre>

</li> 
					 <li> 
						To use the Oracle JDBC 2.0 Driver, the list looks
						 like: 
						<pre>
rem Set up the CLASSPATH that we need

set cp=%CLASSPATH%

REM Added for Oracle XSQL Servlet
REM -----------------------------
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsu12.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\oraclexsql.jar
set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xmlparserv2.jar
set CLASSPATH=%CLASSPATH%;directory_where_JDBC_Driver_resides\ojdbc5.jar
set CLASSPATH=%CLASSPATH%;directory_where_XSQLConfig.xml_resides
REM FOR Apache FOP Generation, Add
REM set CLASSPATH=%CLASSPATH%;C:\xdk902\lib\xsqlserializers.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/build/fop.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/lib/batik.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/lib/logkit-1.0.jar
REM set CLASSPATH=%CLASSPATH%;FOPHOME/lib/avalon-framework-4.0.jar</pre>

</li> 
				 </ul> 
				</li> 
				<li> 
				 Map the .xsql file extension
					 to the XSQL Servlet
 
 
 
				 Tomcat supports creating any number of configuration
					 "contexts" to better organize the web applications your site needs to support.
					 Each context is mapped to a virtual directory path, and has its own separate
					 servlet configuration information. XSQL Servlet comes with a pre-configured
					 context file to make XSQL Servlet setup easier. 
				 By default, Tomcat 3.1 and 3.2 come pre-configured with the
					 following contexts (defined by 
 &lt;Context>
 entries in the
					 ./jakarta-tomcat/conf/server.xml file)... 
				 <ul> 
					 <li> 
						The root context 
					 </li> 
					 <li> 
						
 /examples
 
					 </li> 
					 <li> 
						
 /test
 
					 </li> 
					 <li> 
						
 /admin
 
					 </li> 
				 </ul> 
				 We could install XSQL Servlet into one of these, but for
					 simplicity we'll create a new context just for the XSQL Servlet that maps to
					 the directory where you installed the XSQL Servlet distribution. 
				 Edit the
					 ./jakarta-tomcat/conf/server.xml file to add the following
					 
 &lt;Context>
 entry with a
					 path="/xsql"... 
				 <pre>&lt;Context path="/test" docBase="webapps/test" debug="0" reloadable="true" /&gt;

&lt;!--
 | Define a Servlet context for the XSQL Servlet 
 | 
 | The XSQL Servlet ships with a .\WEB-INF directory
 | with its web.xml file pre-configured for C:\xdk902\xdk\demo\java\xsql
 | installation.
 +--&gt;
&lt;Context path="/xsql" docBase="C:\xdk902\xdk\demo\java\xsql"/&gt;
</pre>
				 Note that the docBase="C:/xsql" points
					 to the physical directory where you installed the XSQL Servlet distribution.
					 You then need to create a WEB-INF subdirectory directory in
					 the C:\xdk902\xdk\demo\java\xsql and save into it the
					 following ./WEB-INF/web.xml file: 
				 <pre>&lt;?xml version = '1.0' encoding = 'UTF-8'?&gt;
&lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
 "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"&gt;
&lt;web-app&gt;
 &lt;servlet&gt;
 &lt;servlet-name&gt;oracle-xsql-servlet&lt;/servlet-name&gt;
 &lt;servlet-class&gt;oracle.xml.xsql.XSQLServlet&lt;/servlet-class&gt;
 &lt;/servlet&gt;
 &lt;servlet-mapping&gt;
 &lt;servlet-name&gt;oracle-xsql-servlet&lt;/servlet-name&gt;
 &lt;url-pattern&gt; *.xsql &lt;/url-pattern&gt;
 &lt;/servlet-mapping&gt;
&lt;/web-app&gt;</pre>
				 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
					 To add the XSQL Servlet to an existing context, add the
						servlet and servlet-mapping entries that you find in web.xml
						file above into the web.xml file for the context in
						question. 
				 </td>
 </tr>
 </table>

</li> 
				<li> 
				 Map an /xsql/ virtual
					 directory
 
 
 
				 This is already achieved by creating the
					 /xsql context above. 
				</li> 
			 </ol>
 Restart the Tomcat server and browse the URL:
 <pre>http://localhost:8080/xsql/index.html</pre> 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				If you use Tomcat with an XML Parser (like the Sun Crimson
				 Parser) that only supports DOM Leve 1 interfaces, then you must edit tomcat.bat
				 to insure that the Oracle XML Parser's archive xmlparser.jar comes before the
				 DOM Level 1 parser's archive in the classpath. For example, you could edit
				 tomcat.bat to add the following line: 
				<pre>REM NEED TO PUT xmlparserv2.jar FIRST before parser.jar
set CP=C:\xdk902\lib\xmlparserv2.jar;%CP%
</pre>
				just before the line: 
				<pre>echo Using CLASSPATH: %CP%
echo.
set CLASSPATH=%CP%</pre>

</td>
 </tr>
 </table> <a name="ID5016">
 <h5 style="color:#000044"><img src="images/line4.gif" width="100" height="7"> ServletExec 2.2</h5>
 </a>
 <ol> 
				<li> 
				 Setup the Server CLASSPATH Correctly for the XSQL
					 Servlet
 
 
 
				 This is done by browsing the url
					 http://localhost/servlet/admin after starting the IIS Server, and clicking the
					 VM Settings link under "Advanced" in the sidebar. 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/servletexec-step1.gif">
 </td>
 </tr>
 </table> 
				 Add the four archives and one directory as shown above, by
					 adding them one at a time and clicking the Submit button
					 after each new entry. 
				</li> 
				<li> 
				 Map the .xsql file extension
					 to the XSQL Servlet
 
 
 
				 Click on Configure under the
					 "Servlets" heading in the sidebar to browse the form where you register
					 servlets. Enter a Servlet Name of oraclexsql and a Servlet
					 Class of oracle.xml.xsql.XSQLServlet into the blank form at
					 the top and click Submit. It should then look like the picture below: 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/servletexec-step2.gif">
 </td>
 </tr>
 </table> 
				 Then, click on Aliases under
					 "Servlets" in the sidebar. 
				 Add an entry as shown below mapping
					 *.xsql to the servlet "nickname" of
					 oraclexsql you defined above. 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/servletexec-step3.gif">
 </td>
 </tr>
 </table> 
				 
				</li> 
				<li> 
				 Map an /xsql/ virtual
					 directory
 
 
 
				 Use the IIS Admin console to create an
					 /xsql virtual directory and map it to
					 C:\xdk902\xdk\demo\java\xsql as shown here: 
				 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/servletexec-step4.gif">
 </td>
 </tr>
 </table> 
				</li> 
			 </ol>
 Restart the IIS server and browse the URL:
 <pre>http://localhost/xsql/index.html</pre><a name="ID5165">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Setting Up the Demo Data</h4>
 </a>
 To setup the data for the demos do the following:
 <ol> 
			 <li> 
				 Change directory to the .\xsql\demo
				 directory on your machine. 
			 </li> 
			 <li> 
				 In this directory, run SQLPLUS. Connect to your database as
				 CTXSYS/CTXSYS (the schema owner for Intermedia Text
				 packages) and issue the command 
				<pre>GRANT EXECUTE ON CTX_DDL TO SCOTT;</pre>

</li> 
			 <li> 
				 Connect to your database as
				 SYSTEM/MANAGER and issue the command: 
				<pre>GRANT QUERY REWRITE TO SCOTT;</pre>
				This allows SCOTT to create a functional index that one of
				 the demos uses to perform case-insensitive queries on descriptions of
				 airports. 
			 </li> 
			 <li> 
				 Connect to your database as SCOTT/TIGER.
				 
			 </li> 
			 <li> 
				 Run the script install.sql in the
				 ./xsql/demo directory. This script will, in turn, run all
				 the SQL scripts for all the demos. 
			 </li> 
			 <li> 
				 Change directory to the doyouxml
				 subdirectory, and run the command imp scott/tiger
				 file=doyouxml.dmp to import some sample data for the "Do You XML?
				 Site" demo. 
			 </li> 
		 </ol> 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
			 To properly experience the Scalable Vector Graphics
				demonstration, you need to install an SVG plugin into your browser like the 
				<a href="http://beta1.adobe.com/svgpreview_alpha/SVG/download/download.html">Adobe
				 SVG Plugin</a>. 
		 </td>
 </tr>
 </table> <a name="ID5300">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Additional Technical Tips</h2>
 </a><a name="ID5307">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Producing XML from SQL with Nested Structure</h3>
 </a>
 In addition to "flat" database query results, using the techniques
		 described in this section you can easily produce XML from database query with
		 nested structure by selecting information from structured
		 columns in your XSQL page. Structured columns can be one of three types:
 <ol> 
		 <li> 
			 Strongly Typed, User-Defined Object 
		 </li> 
		 <li> 
			 Strongly Typed, User-Defined Collection 
		 </li> 
		 <li> 
			 Untyped Collection based on a SQL statement 
		 </li> 
		</ol>
 Since the underlying Oracle XML SQL Utility for Java natively
		 supports all of these combinations for producing richly structure XML from SQL
		 statements that make use of these features, your Oracle XSQL Pages gain this
		 capability for "free". We'll look at two simple examples...<a name="ID5356">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Using User-Defined Object Types</h4>
 </a>
 If you have used the object/relational capabilities of
			 Oracle8i to create a user-defined object type called
			 POINT using the command:
 <pre>CREATE TYPE POINT AS OBJECT (X NUMBER, Y NUMBER);</pre>
 and have used your new POINT type as the
			 datatype of the ORIGIN column in your
			 LOCATION table with the DDL statement:
 <pre>CREATE TABLE LOCATION (
 NAME VARCHAR2(80),
 ORIGIN POINT
);</pre>
 and have inserted a row into this LOCATION
			 table using an INSERT statement with the
			 POINT() constructor like...
 <pre>INSERT INTO LOCATION VALUES ( 'Someplace', POINT(11,17) );
COMMIT;</pre>
 Then, an XSQL page like point.xsql below that
			 does a query over the LOCATION table like...
 <pre>&lt;xsql:query connection="demo" xmlns:xsql="urn:oracle-xsql"&gt;
 SELECT name, origin
 FROM location loc
 WHERE loc.origin.x = {@x-coord}
&lt;/xsql:query&gt; </pre>
 ...when requested using a URL like:
 <pre>http://yourmachine.com/xsql/demo/point.xsql?x-coord=11</pre>
 produces the output:
 <pre>&lt;ROWSET&gt;
 &lt;ROW num="1"&gt;
 &lt;NAME&gt;Someplace&lt;/NAME&gt;
 &lt;ORIGIN&gt;
 &lt;X&gt;11&lt;/X&gt;
 &lt;Y&gt;17&lt;/Y&gt;
 &lt;/ORIGIN&gt;
 &lt;/ROW&gt;
&lt;/ROWSET&gt;</pre>
 This demonstrates how the nested X and
			 Y attributes in the POINT datatype
			 structure of the ORIGIN column appear automatically as
			 nested 
 &lt;X>
 and 
 &lt;Y>
 elements in the XML
			 output. This is about the simplest possible example of using a user-defined
			 type to get more richly structured XML output from your object/relational
			 database. See the included Insurance Claim Demo for a much
			 more detailed example combining both object types and object views. Take a look
			 at the the associated SQL script in
			 ./xsql/demo/insclaim/insclaim.sql to see the SQL syntax for
			 creating the object types and object views used by the demo. 
			 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
				See the supplied
				 ./xsql/demo/point/point.sql script to create the example
				 type and table above on your database. Also in the
				 ./xsql/demo directory, see the
				 ./empdept/empdeptobjs.sql,
				 ./classerr/invalidclasses.sql, and
				 ./insclaim/insclaim.sql files for additional object view
				 examples. 
			 </td>
 </tr>
 </table> 
 <a name="ID5540">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Using the CURSOR Operator for Nested Rowsets</h4>
 </a>
 If you have not created object types that contain a
			 pre-defined structure, you can still introduce nested
			 structure into your SQL queries using the CURSOR operator
			 allows you to select a nested rowset as a column in the
			 SELECT list of a query. While almost
			 any nested query is legal to include inside the
			 CURSOR operator in the SELECT list, the
			 most useful is a query that selects a nested set of detail
			 rows for the current "master" row.
 Taking the familar DEPT and
			 EMP tables as an example, the following XSQL Page contains a
			 query that selects the DNAME column from the
			 DEPT table, and for each row returned a nested rowset of the
			 EMPLOYEES from the EMP table who work in that
			 department:
 <pre>&lt;xsql:query connection="demo" xmlns:xsql="urn:oracle-xsql"&gt;
 SELECT dname,
 CURSOR( SELECT ename,sal
 FROM emp
 WHERE emp.deptno = dept.deptno) as employees /* Column Alias */
 FROM dept
 WHERE deptno = {@department}
&lt;/xsql:query&gt;
</pre>
 Requesting this 
 <pre>http://yourserver.com/xsql/demo/empdept.xsql?department=10</pre>
 produces the resulting XML "datapage":
 <pre>&lt;ROWSET&gt;
 &lt;ROW num="1"&gt;
 &lt;DNAME&gt;ACCOUNTING&lt;/DNAME&gt;
 &lt;EMPLOYEES&gt;
 &lt;EMPLOYEES_ROW num="1"&gt;
 &lt;ENAME&gt;CLARK&lt;/ENAME&gt;
 &lt;SAL&gt;2450&lt;/SAL&gt;
 &lt;/EMPLOYEES_ROW&gt;
 &lt;EMPLOYEES_ROW num="2"&gt;
 &lt;ENAME&gt;KING&lt;/ENAME&gt;
 &lt;SAL&gt;5000&lt;/SAL&gt;
 &lt;/EMPLOYEES_ROW&gt;
 &lt;EMPLOYEES_ROW num="3"&gt;
 &lt;ENAME&gt;MILLER&lt;/ENAME&gt;
 &lt;SAL&gt;1300&lt;/SAL&gt;
 &lt;/EMPLOYEES_ROW&gt;
 &lt;/EMPLOYEES&gt;
 &lt;/ROW&gt;
&lt;/ROWSET&gt;</pre>
 Note that the second column in the SELECT
			 statement is the expression using the CURSOR() operator to
			 select the details. Since it is a column like any other, it can be aliased to
			 the column name EMPLOYEES by using the AS 
			 COLUMNALIAS
 syntax as shown
			 above.
 Since the EMPLOYEES column is a nested rowset,
			 it appears as a set of 
 &lt;ROW>
 elements nested within its parent
			 
 &lt;ROW>
 . Given the facts that:
 <ul> 
			 <li> 
				One or more CURSOR operators can be used
				 in the SELECT list of any SQL statement, 
			 </li> 
			 <li> 
				One or more CURSOR operators can be used
				 in the SELECT list of SQL statements that appear
				 inside any CURSOR operator (to any
				 level of nesting), 
			 </li> 
			 <li> 
				The SQL statement that may appear within the
				 CURSOR operator can be virtually any valid SQL statment
				 (including GROUP BY and ORDER BY, etc), and that 
			 </li> 
			 <li> 
				Any SQL statement can be included in an
				 
 &lt;xsql:query>
 tag in an XSQL Page 
			 </li> 
		 </ul>
 you can quickly see how powerful, structured information can be
			 created on the fly to get almost any structure you are looking for. This allows
			 the processing speed of the database to be exploited for sorting and grouping
			 instead of having to rely on slower techniques that would attempt these
			 operations on flat data from within the XSLT
			 stylesheet.
 Of course, by using these query techniques in the
			 
 &lt;xsql:query>
 tags of an XSQL Page, you can combine rich
			 master/detail XML "datapages" with powerful database sorting and grouping
			 applied to them by the SQL engine before subsequently
			 applying an XSLT Transformation to the resulting datapage as we learned above
			 to transform the resulting datapage into any "presentation" format you
			 need.<a name="ID5775">
 <h3 style="color:#000066"><img src="images/line4.gif" width="200" height="9"> Inserting XML Into Any Table You Require </h3>
 </a>
 Oracle provides all the ingredients necessary to accomplish this
		 task. The approach you take depends on whether you need to accomplish the
		 insert from within your own Java program, or whether you want a simple,
		 declarative way of inserting the target document.<a name="ID5786">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Overview</h4>
 </a>
 The Oracle XML SQL Utility for Java contains the
			 OracleXMLQuery class that we used above to get SQL query
			 results out of the database. It also contains a companion class called
			 OracleXMLSave that performs the
			 opposite job of putting XML information back
			 into Oracle tables or views.
 The OracleXMLSave class understands how to
			 insert any information which
			 OracleXMLQuery knows how to produce.
			 Said another way, the canonical structure of the output
			 from OracleXMLQuery defines the kinds of structures for
			 input which OracleXMLSave can automatically insert for
			 us.
 The fact that OracleXMLSave can only insert
			 XML documents that look like XML documents produced by
			 OracleXMLQuery may at first sound like a drastic limitation.
			 However, this is not the case by any stretch of the imaginition. By taking
			 advantage of an appropriate XSL transformation, virtually any XML document can
			 be transformed to have the canonical format required by
			 OracleXMLSave. This means that given:
 <ul> 
			 <li> 
				An arbitrary XML document X, and 
			 </li> 
			 <li> 
				A database table T where you want to
				 insert it 
			 </li> 
		 </ul>
 You can create an XSL Transformation that transforms the
			 source document X into a
			 target document X2 having precisely the
			 structure needed for automatic insertion into table
			 T.
 Let's say that the source document is an XML news feed like what
			 you'll see if you browse the following URL from 
			 <a href="http://www.moreover.com">www.moreover.com</a>
			 ...
 <pre><a href="http://www.moreover.com/cgi-local/page?index_xml+xml">http://www.moreover.com/cgi-local/page?index_xml+xml</a>
 </pre>
 A shortened version of such a resulting XML document looks like
			 this: 
 
			 <pre>&lt;?xml version="1.0"?&gt;
 &lt;!DOCTYPE moreovernews SYSTEM "http://www.moreover.com/xml/moreovernews.dtd"&gt;
 &lt;moreovernews&gt;
 &lt;article id="4227581"&gt;
 &lt;url&gt;http://d.moreover.com/click/here.pl?x4227575&lt;/url&gt;
 &lt;headline_text&gt;Austin: webMethods gets deal with Dell&lt;/headline_text&gt;
 &lt;source&gt;dbusiness.com&lt;/source&gt;
 &lt;media_type&gt;text&lt;/media_type&gt;
 &lt;cluster&gt;XML and metadata news&lt;/cluster&gt;
 &lt;tagline&gt;Austin&lt;/tagline&gt;
 &lt;document_url&gt;http://washington.dbusiness.com/&lt;/document_url&gt;
 &lt;harvest_time&gt;Oct 30 1999 7:08AM&lt;/harvest_time&gt;
 &lt;access_registration&gt; &lt;/access_registration&gt;
 &lt;access_status&gt; &lt;/access_status&gt;
 &lt;/article&gt;
 &lt;article id="4212701"&gt;
 &lt;url&gt;http://d.moreover.com/click/here.pl?x4212698&lt;/url&gt;
 &lt;headline_text&gt;Microsoft continues XML push with resource kit&lt;/headline_text&gt;
 &lt;source&gt;InfoWorld&lt;/source&gt;
 &lt;media_type&gt;text&lt;/media_type&gt;
 &lt;cluster&gt;XML and metadata news&lt;/cluster&gt;
 &lt;tagline&gt;&lt;/tagline&gt;
 &lt;document_url&gt;http://www.infoworld.com/&lt;/document_url&gt;
 &lt;harvest_time&gt;Oct 29 1999 7:27AM&lt;/harvest_time&gt;
 &lt;access_registration&gt; &lt;/access_registration&gt;
 &lt;access_status&gt; &lt;/access_status&gt;
 &lt;/article&gt;
 &lt;article id="4202251"&gt;
 &lt;url&gt;http://d.moreover.com/click/here.pl?x4202247&lt;/url&gt;
 &lt;headline_text&gt;IBM Brings XML To MQSeries&lt;/headline_text&gt;
 &lt;source&gt;Internet Week&lt;/source&gt;
 &lt;media_type&gt;text&lt;/media_type&gt;
 &lt;cluster&gt;XML and metadata news&lt;/cluster&gt;
 &lt;tagline&gt;&lt;/tagline&gt;
 &lt;document_url&gt;http://www.internetwk.com/&lt;/document_url&gt;
 &lt;harvest_time&gt;Oct 28 1999 4:28PM&lt;/harvest_time&gt;
 &lt;access_registration&gt; &lt;/access_registration&gt;
 &lt;access_status&gt; &lt;/access_status&gt;
 &lt;/article&gt;
 &lt;article id="4082434"&gt;
 &lt;url&gt;http://d.moreover.com/click/here.pl?x4082432&lt;/url&gt;
 &lt;headline_text&gt;XML leader OnDisplay's travel clients praised&lt;/headline_text&gt;
 &lt;source&gt;Web Travel News&lt;/source&gt;
 &lt;media_type&gt;text&lt;/media_type&gt;
 &lt;cluster&gt;XML and metadata news&lt;/cluster&gt;
 &lt;tagline&gt;&lt;/tagline&gt;
 &lt;document_url&gt;http://www.webtravelnews.com/&lt;/document_url&gt;
 &lt;harvest_time&gt;Oct 20 1999 7:34AM&lt;/harvest_time&gt;
 &lt;access_registration&gt; &lt;/access_registration&gt;
 &lt;access_status&gt; &lt;/access_status&gt;
 &lt;/article&gt;
 &lt;/moreovernews&gt;
</pre>
			 Next, let's say that you have a table called
			 newsstory that you created with the following DDL statement.
			 
		 
 <pre>CREATE TABLE newsstory(
 id NUMBER PRIMARY KEY,
 title VARCHAR2(200),
 url VARCHAR2(200),
 source VARCHAR2(200)
);</pre>
 And further, let's suppose that you want to insert information
			 from the XML news feed from Moreover.com into this table.
 So, we need to produce an XSL transformation that transforms the
			 information in the XML news feed from Moreover.com into the canonical format
			 that OracleXMLSave knows how to insert into the
			 newsstory table.
 We start by using an XSQL page to quickly produce one row of
			 canonical query results from the newstory table. We can
			 produce this with the XSQL Page:
 <pre>&lt;?xml version="1.0"?&gt;
&lt;query connection="demo" max-rows="1"&gt;

SELECT *
   FROM NEWSTORY

&lt;/query&gt;</pre>
 We can either request this page through the webserver, or more
			 conveninently for this job, use the XSQL Command Line Utility to quickly put
			 the XSQL Page's output into a file:
 <pre>xsql newstory.xsql newsstory.xml</pre>
 This command processes the newsstory.xsql page
			 above and writes the output to the file named newsstory.xml.
			 The contents of the newsstory.xml file will look like:
 <pre>&lt;?xml version = '1.0'?&gt;
&lt;ROWSET&gt;
 &lt;ROW num="1"&gt;
 &lt;ID&gt;1911&lt;/ID&gt;
 &lt;TITLE&gt;Some Title&lt;/TITLE&gt;
 &lt;URL&gt;http://somemachine/somepage.html&lt;/URL&gt;
 &lt;SOURCE&gt;SomeSource&lt;/SOURCE&gt;
 &lt;/ROW&gt;
&lt;/ROWSET&gt;</pre>
 We can take this one row of canonical output from a
			 "SELECT *" query over the newsstory table
			 and immediately turn it into our "insert transformation" by doing the following
			 steps:
 <ol> 
			 <li> 
				Add an xsl namespace declaration to the
				 document element, 
			 </li> 
			 <li> 
				Remove the num="1" attribute from the
				 
 &lt;ROW>
 element, 
			 </li> 
			 <li> 
				Remove any elements corresponding to columns whose values
				 will be assigned by database triggers, like the ID column will be in this
				 example, 
			 </li> 
			 <li> 
				Surround the 
 &lt;ROW>
 element with an
				 
 &lt;xsl:for-each>
 that loops over the 
 &lt;article>
 
				 elements in the source document from Moreover.com,
				 and 
			 </li> 
			 <li> 
				Replace the literal text between the
				 
 &lt;TITLE>
 , 
 &lt;URL>
 , and 
 &lt;SOURCE>
 
				 elements with an appropriate 
 &lt;xsl:value-of>
 element to plug-in
				 the appropriate information from the current
				 
 &lt;article>
 we're looping over in the enclosing
				 
 &lt;xsl:for-each>
 loop. 
			 </li> 
		 </ol>
 The result of applying the changes outlined in the three steps
			 above to the sample output of the:
 
 SELECT * FROM NEWSSTORY
 
 query produces the following XSL Transformation:
 <pre>&lt;?xml version = '1.0'?&gt;
&lt;ROWSET xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
 &lt;xsl:for-each select="moreovernews/article"&gt;
 &lt;ROW&gt;
 &lt;TITLE&gt;&lt;xsl:value-of select="headline_text"/&gt;&lt;/TITLE&gt;
 &lt;URL&gt;&lt;xsl:value-of select="url"/&gt;&lt;/URL&gt;
 &lt;SOURCE&gt;Moreover.com&lt;/SOURCE&gt;
 &lt;/ROW&gt;
 &lt;/xsl:for-each&gt;
&lt;/ROWSET&gt;</pre>
 Which illustrates that we have:
 <ul> 
			 <li> 
				Added the xsl namespace declaration to the
				 
 &lt;ROWSET>
 element: 
				<pre>&lt;ROWSET xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;</pre>

</li> 
			 <li> 
				Added the 
 &lt;xsl:for-each>
 element to loop
				 over each 
 &lt;article>
 element that is a child of the
				 
 &lt;moreovernews>
 element in the source document: 
				<pre>&lt;xsl:for-each select="moreovernews/article"&gt;</pre>
				so that for each 
 &lt;article>
 we find in the
				 source, we create a 
 &lt;ROW>
 in the
				 target. 
			 </li> 
			 <li> 
				Removed the 
 &lt;ID>
 element since its value
				 will be assigned by our database trigger that assign new story id's from a
				 database sequence. 
			 </li> 
			 <li> 
				Changed the: 
				<pre>&lt;TITLE&gt;Some Title&lt;/TITLE&gt;
&lt;URL&gt;http://somemachine/somepage.html&lt;/URL&gt;</pre>
				tags to: 
				<pre>&lt;TITLE&gt;&lt;xsl:value-of select="headline_text"/&gt;&lt;/TITLE&gt;
&lt;URL&gt;&lt;xsl:value-of select="url"/&gt;&lt;/URL&gt;</pre>
				to plug-in the value of the current
				 
 &lt;headline_text>
 and 
 &lt;url>
 for the current
				 
 &lt;article>
 .

</li> 
			 <li> 
				Hard-coded the value of the 
 &lt;SOURCE>
 element
				 to Moreover.com to indicate where this news feed came from. 
			 </li> 
		 </ul>
 If we rename the now-edited newsstory.xml file
			 to moreover-to-newsstory.xsl, we can use the command-line
			 oraxsl utility to test our transformation: 
 <pre>java oracle.xml.parser.v2.oraxsl moreover.xml moreover-to-newsstory.xsl out.xml</pre> 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
			 Since the moreover.xml file includes
				the: 
			 <pre>&lt;!DOCTYPE moreovernews 
 SYSTEM "http://www.moreover.com/xml/moreovernews.dtd"&gt;</pre>
			 declaration with an http:// reference to the
				MoreoverNews DTD that is outside of Oracle's firewall, you need to provide the
				following three extra Java VM parameters to allow the Oracle XML Parser to
				properly find and parse the DTD through our Proxy server: 
			 <pre>java -DproxySet=true 
 -DproxyHost=proxyServerName 
 -DproxyPort=80 oracle.xml.parser.v2.oraxsl ...</pre>

</td>
 </tr>
 </table> 
 If we use Internet Explorer to browse the resulting
			 out.xml file, we can see the results of the
			 transformation:
 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/outdotxml.gif">
 </td>
 </tr>
 </table>
 If we pass this resulting target document to the
			 OracleXMLSave class, as we'll do below, it will effortlessly
			 insert all of the Moreover.com data into our newsstory
			 table.
 The last step before showing how to tie it all together using
			 Java or XSQL Pages is to create the database trigger to automatically assign
			 the value of the ID column on insert. Assuming we have a sequence named
			 newsstory_id_seq lying around, the code looks like:
 
			 <pre>CREATE TRIGGER newsstory_autoid
BEFORE INSERT ON newsstory FOR EACH ROW
BEGIN
 SELECT newsstory_id_seq.nextval
 INTO :new.id
 FROM dual;
END;</pre>

<a name="ID6405">
 <h4 style="color:#000044"><img src="images/line4.gif" width="150" height="7"> Inserting Posted XML into the Database</h4>
 </a>
 The general steps for inserting XML into the database are:
 <ol> 
			 <li> 
				Choose the table or view you want to use for inserting the
				 XML information, 
			 </li> 
			 <li> 
				Create an XSL Transformation that transforms the inbound
				 document into the canonical format for this table or view, 
				We saw a "cookbook" approach above for how to do this easily
				 based on a SELECT * query against the target table or
				 view, 
			 </li> 
			 <li> 
				Transform the inbound document into the canonical format for
				 the table or view into which you want to insert it, and 
			 </li> 
			 <li> 
				Let OracleXMLSave insert the transformed
				 document into your table or view. 
			 </li> 
		 </ol>
 Oracle XSQL Pages support a simple 
 &lt;xsql:insert-request>
 
			 tag that automates these four steps for you when you need to post XML documents
			 to be inserted into the database to your webserver over HTTP. Given the name of
			 the table or view to use as the insert target and the name of the XSL
			 transformation to use to transform the inbound document into the canonical
			 format for this table or view, you can add the tag:
 <pre>&lt;xsql:insert-request 
 table="tableorviewname"
 transform="transformname.xsl"/&gt;</pre>
 to the top of your XSQL page to perform the four steps above
			 automatically. So, for example, the following XSQL Page would accept
			 information posted through HTTP in the Moreover.com moreovernews format, and
			 insert it into the newsstory table:
 <pre>&lt;?xml version="1.0?&gt;
&lt;xsql:insert-request xmlns:xsql="urn:oracle-xsql" 
 connection="demo" 
 table="newsstory"
 transform="moreover-to-newsstory.xsl"/&gt;</pre>
 Running this program retrieves the newsstories and inserts them
			 into our NEWSSTORY table.
 Due to the nature of this news feed, news stories stay in the
			 feed for a few days. If we want to avoid inserting the same story over and over
			 again, we can easily do that by making sure we don't insert a story unless its
			 Title and URL are a unique combination in our NEWSSTORY
			 table.
 Let's implement this behavior using a database INSTEAD
			 OF INSERT trigger. Creating an INSTEAD OF INSERT
			 trigger allows us to write code which will be executed in the database whenever
			 an INSERT of any kind is performed. In the code of the INSTEAD OF
			 INSERT trigger, we can check for uniqueness of the newsstory and only
			 really insert it if it is
			 unique.
 Since INSTEAD OF triggers can only be defined
			 on database views in Oracle8i, we
			 simply need to create the newstoryview as follows:
 
			 <pre>CREATE VIEW newsstoryview AS
SELECT *
 FROM newsstory</pre>

Then we can create the INSTEAD OF INSERT
			 trigger from the SQL*Plus command line using code like:
 <pre>CREATE OR REPLACE TRIGGER insteadOfIns_newsstoryview
INSTEAD OF INSERT ON newsstoryview FOR EACH ROW
DECLARE
 notThere BOOLEAN := TRUE;
 tmp VARCHAR2(1);
 CURSOR chk IS SELECT 'x'
 FROM newsstory
 WHERE title = :new.title
 AND url = :new.url;
BEGIN
 OPEN chk;
 FETCH chk INTO tmp;
 notThere := chk%NOTFOUND;
 CLOSE chk;
 IF notThere THEN
 INSERT INTO newsstory(title,url,source)
 VALUES (:new.title,:new.url,:new.source);
 END IF;
END;</pre>
 Here we are assuming that "uniqueness" of a story is defined by
			 the combination of its TITLE and its URL
			 columns. To make the check fast, we can create a unique index on the
			 (TITLE,URL) combination with the command:
 
			 <pre>CREATE UNIQUE INDEX newsstory_unique_title_url on newsstory(title,url);</pre>

We've written the body of the trigger in PL/SQL to demonstrate
			 that you can mix and match PL/SQL and Java in this solution, but in Oracle8i we
			 could have also written the INSTEAD OF trigger to call a Java Stored Procedures
			 as well to perform the uniqueness check. 
 Finally, the only thing left to do is to change the
			 xsql:insert-request action element above to use the
			 NEWSSTORYVIEW instead of the NEWSTORY
			 table by changing the line:
 <pre>&lt;?xml version="1.0?&gt;
&lt;xsql:insert-request xmlns:xsql="urn:oracle-xsql" 
 connection="demo" 
 table="newsstoryview"
 transform="moreover-to-newsstory.xsl"/&gt;</pre>
 Now, only unique newstories from the
			 Moreover XML news feed will be inserted. 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
			 Using the same INSTEAD OF INSERT trigger
				technique above, it would be quite straightforward to support automatically
				updating XML information in the database as well. While
				OracleXMLSave can only perform insert
				operations, the INSTEAD OF INSERT trigger on your view could
				check for existience of a primary key, and if it exists, actually perform an
				UPDATE instead of an
				INSERT. 
		 </td>
 </tr>
 </table> 
 The 
 &lt;xsql:insert-request>
 tag can be combined
			 with 
 &lt;xsql:query>
 tags in your XSQL page to
			 first insert any posted XML document (if there is any),
			 then return some data from queries. For example:
 <pre>&lt;?xml version="1.0"?&gt;
&lt;page connection="demo" xmlns:xsql="urn:oracle-xsql"&gt;
 &lt;xsql:insert-request table="newsstoryview" transform="moreover-to-newsstory.xsl"/&gt;
 &lt;lateststories&gt;
 &lt;xsql:query tag-case="lower" max-rows="5" rowset-element="" row-element="story" &gt;
 select * 
 from newsstory
 order by id desc
 &lt;/xsql:query&gt;
 &lt;/lateststories&gt;
&lt;/page&gt;</pre>
 The XSQL page above inserts any posted XML document containing
			 moreovernews/article elements (as we did programmatically
			 above), and then returns the XML datagram to the requester that looks like this
			 viewed "raw" in the Internet Explorer 5.0 browser:
 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/afterinsert.gif">
 </td>
 </tr>
 </table>
 When XML is posted to a web server through HTTP, it's ContentType
			 is text/xml by convention. Sometimes, it's convenient to
			 accept posted information as a set of HTML 
 &lt;FORM>
 parameters.
			 When an HTML form is posted, the server receives it with a ContentType of
			 application/x-www-form-urlencoded. When the XSQL Servlet
			 receives an HTTP request with method="POST" from such a
			 form, it internally converts the form parameters into an XML document that
			 looks like:
 <pre>&lt;request&gt;
 &lt;parameters&gt;
 &lt;firstparamname>firstparamvalue&lt;/firstparamname>
 :
 &lt;lastparamname>lastparamvalue&lt;/lastparamname>
 &lt;/parameters&gt;
 &lt;session&gt;
 &lt;firstparamname>firstsessionparamvalue&lt;/firstparamname>
 :
 &lt;lastparamname>lastsessionparamvalue&lt;/lastparamname>
 &lt;/session&gt;
 &lt;cookies&gt;
 &lt;firstcookie>firstcookievalue&lt;/firstcookiename>
 :
 &lt;lastcookie>firstcookievalue&lt;/lastcookiename>
 &lt;/cookies&gt;
&lt;/request&gt;</pre>
 and then allows an 
 &lt;xsql:insert-request>
 tag to
			 treat this document as the posted input document. 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
			 If multiple parameters are posted with the same name, then they
				will automatically be "row-ified" to make subsequent processing easier. This
				means, for example, that a request which posts or includes the following
				parameters: 
			 <ul> 
				<li> 
				 
 id=101
 
				</li> 
				<li> 
				 
 name=Steve
 
				</li> 
				<li> 
				 
 id=102
 
				</li> 
				<li> 
				 
 name=Sita
 
				</li> 
				<li> 
				 
 operation=update
 
				</li> 
			 </ul> 
			 Will create a "row-ified" set of parameters like: 
			 <pre>&lt;request&gt;
 &lt;parameters&gt;
 &lt;row>
 &lt;id&gt;101&lt;/id&gt;
 &lt;name&gt;Steve&lt;/name&gt;
 &lt;/row>
 &lt;row>
 &lt;id&gt;102&lt;/id&gt;
 &lt;name&gt;Sita&lt;/name&gt;
 &lt;/row>
 &lt;operation&gt;update&lt;/operation&gt;
 &lt;/parameters&gt;
 :
&lt;/request&gt;</pre>

</td>
 </tr>
 </table> 
 Using an 
 &lt;xsql:insert-request>
 tag like:
 <pre>&lt;xsql:insert-request 
 table="newsstoryview" 
 transform="request-to-newsstoryview.xsl"/</pre>
 and by referencing the name of the
			 request-to-newsstoryview.xsl transform that looks
			 like:
 
			 <pre>&lt;?xml version = '1.0'?&gt;
&lt;ROWSET xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xsl:version="1.0"&gt;
 &lt;xsl:for-each select="request/parameters"&gt;
 &lt;ROW&gt;
 &lt;TITLE&gt;&lt;xsl:value-of select="title_field"/&gt;&lt;/TITLE&gt;
 &lt;URL&gt;&lt;xsl:value-of select="url_field"/&gt;&lt;/URL&gt;
 &lt;SOURCE&gt;User-Submitted&lt;/SOURCE&gt;
 &lt;/ROW&gt;
 &lt;/xsl:for-each&gt;
&lt;/ROWSET&gt;</pre>

If the above XSQL page were saved as
			 insertnewsform.xsql, it can be used as the target of an HTML
			 
 &lt;FORM>
 element that includes fields named
			 title_field and url_field by simply
			 setting the forms's ACTION="insertnewsform.xsql" attribute.
			 The following newsform.html file demonstrate this:
 <pre>&lt;html&gt;
&lt;body&gt;
 Insert a new news story...
 &lt;form action="insertnewsform.xsql" method="post"&gt;
 &lt;b&gt;Title&lt;/b&gt;&lt;input type="text" name="title_field" size="30"&gt;&lt;br&gt;
 &lt;b&gt;URL&lt;/b&gt;&lt;input type="text" name="url_field" size="30"&gt;&lt;br&gt;
 &lt;br&gt;
 &lt;input type="submit"&gt;
 &lt;/form&gt;
&lt;body&gt;
&lt;/html&gt;</pre>
 If we let a user fill-out and post the form as-is, they will get
			 raw XML as a response from the insertnewform.xsql page,
			 listing the five most recent news stories entered as show above. However, we
			 can easily improve on that for better usability.
 Using the mechanism we learned in the previous section for
			 associating XSL Stylesheets with XSQL Pages, we can include an
			 
 &lt;?xml-stylesheet?>
 processing instruction at the top of the
			 insertnewsform.xsql that refers to the
			 lateststories.xsl XSL Stylesheet below:
 <pre>&lt;html xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
 &lt;head&gt;
 &lt;title&gt;Latest Stories&lt;/title&gt;
 &lt;/head&gt;
 &lt;body&gt;
 &lt;h2&gt;Thanks for your Story!&lt;/h2&gt;
 Here's a list of the latest stories we've received...
 &lt;table border="0" cellspacing="0"&gt;
 &lt;xsl:for-each select="page/lateststories/story"&gt;
 &lt;tr&gt;
 &lt;td&gt;&lt;a href="{url}"&gt;&lt;xsl:value-of select="title"/&gt;&lt;/a&gt;&lt;/td&gt;
 &lt;/tr&gt;
 &lt;/xsl:for-each&gt;
 &lt;/table&gt;
 &lt;/body&gt;
&lt;/html&gt;</pre>
 This means the insertnewsform.xsql now will
			 look like:
 <pre>&lt;?xml version="1.0"?&gt;
&lt;?xml-stylesheet type="text/xsl" href="lateststories.xsl"?&gt;
&lt;page connection="demo" xmlns:xsql="urn:oracle-xsql"&gt;
 &lt;xsql:insert-request table="newsstoryview" transform="request-to-newsstory.xsl"/&gt;
 &lt;lateststories&gt;
 &lt;xsql:query tag-case="lower" max-rows="5" rowset-element="" row-element="story" &gt;
 select * 
 from newsstory
 order by id desc
 &lt;/xsql:query&gt;
 &lt;/lateststories&gt;
&lt;/page&gt;</pre>
 Now when the user browses the newsform.html
			 page and enters her story...
 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/insertyourstory.gif">
 </td>
 </tr>
 </table>
 ...then rather than seeing the raw XML datagram returned by the
			 insertnewsform.xsql page, this will be transformed using the
			 lateststories.xsl stylesheet so that it shows up in her
			 browser like:
 <table border="0" cellspacing="0" cellpadding="0">
 <tr>
 <td><img src="images/thanksforyourstory.gif">
 </td>
 </tr>
 </table>
 as an HTML page instead of as raw XML.
 So in addition to being possible for developers by using Java
			 programs that leverage the Oracle XML SQL Utility directly, we've seen that
			 it's easy to insert XML-based information into Oracle database tables or views
			 without programming using XSQL Pages and XSLT Transformations. 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
			 Here we've used simple examples with simple tables, however
				OracleXMLQuery and OracleXMLSave work
				well with any kind of richly structured object and with all supported
				datatypes. This means that, while not shown here, the same techniques described
				in this paper can be applied used to: 
			 <ul> 
				<li> 
				 Insert richly strutured information into an Object View
					 with nested types and nested collections 
				</li> 
				<li> 
				 Insert "fragments" or "chunks" of XML elements and their
					 content (from an entire document to any desired granularity of sub-structure)
					 into a CLOB column or an object type with a CLOB attribute. 
				</li> 
			 </ul> 
			 The ./xsql/demo/empdeptobjs.sql script shows
				a working example of an a "department" object view ( based over the familiar
				EMP and DEPT tables) and an accompanying
				INSTEAD OF INSERT trigger on the object view to allow
				structured inserting of multiple departments and nested employees. 
		 </td>
 </tr>
 </table> <a name="demos"></a><a name="ID7116">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Demos Included with This Release</h2>
 </a>
 The following demo files are part of this release. Instructions for
		installing the demos are included in the Installation section of these release
		notes. 
		<table border="0" cellpadding="3" cellspacing="0">
 <tr>
 <td class="tabletitle" colspan="2" align="center"> Description of Demonstrations
 <hr>
 </td>
 </tr> 
		 <tr class="tableheader">
 <td nowrap=""> Demonstration Name
				 (directory)</td>
 <td> Comments </td>
 </tr> 
		 <tr class="ro">
 <td nowrap="">Hello World
				 (helloworld)</td>
 <td>Simplest possible XSQL page. </td>
 </tr>
 <tr class="re">
 <td nowrap="">Do You XML Site
				 (doyouxml)</td>
 <td> 
				 XSQL page which shows how a simple, data-driven web site
					 can be built using an XSQL page which makes clever use of SQL,
					 XSQL-substitution variables in the queries, and XSLT for formatting the site.
					 
				 Demonstrates using substitution parameters in both the body
					 of SQL query statements within 
 &lt;xsql:query>
 tags, as well as
					 withing the attributes to 
 &lt;xsql:query>
 tags to control things
					 like how many records to display and to skip (for "paging" through query
					 results in a stateless way).
 </td>
 </tr>
 <tr class="ro">
 <td nowrap=""> Employee Page (emp)</td>
 <td> 
				 XSQL page showing XML data from the EMP table, using XSQL
					 page parameters to control what employees are returned and what column(s) to
					 use for the database sort. Uses an associated XSLT Stylesheet for format the
					 results as an HTML Form containing the emp.xsql page as the form
					 action so the user can refine their search
					 criteria.
 </td>
 </tr>
 <tr class="re">
 <td nowrap=""> Insurance Claim Page (insclaim)</td>
 <td> 
				 Demonstrates a number of sample queries over the
					 richly-structured, Insurance Claim object view. The
					 insclaim.sql sets up the
					 INSURANCE_CLAIM_VIEW object view and populates some sample
					 data. 
 </td>
 </tr>
 <tr class="ro">
 <td nowrap="">Invalid Classes Page (classerr)</td>
 <td> 
				 XSQL Page which uses invalidclasses.xsl
					 to format a "live" list of current Java class compilation errors in your
					 schema. The accompanying .sql script sets up the
					 XSQLJavaClassesView object view used by the demo. The
					 master/detail information from the object view is formatted into HTML by the
					 invalidclasses.xsl stylesheet in the server.
 </td>
 </tr>
 <tr class="re">
 <td nowrap="">Airport Code Validation (airport)</td>
 <td> 
				 XSQL page which returns a "datagram" of information about
					 airports based on their three-letter code. Demonstrates using the
					 
 &lt;xsql:no-rows-query>
 to attempt alternative queries when
					 initial queries return no rows. In this case, after attempting an exact match
					 on the airport code passed in, the page tries a fuzzy match on the airport
					 description. 
				 The airport.htm page demonstrates how to
					 use the XML results of the airport.xsql page
					 programmatically from within a web page using JavaScript to exploit the
					 built-in XML Document Object Model functionality in the Internet Explorer 5.0
					 browser. 
				 When you type in a three-leter airport code into this web
					 page, some JavaScript under the covers fetches the XML datagram from the XSQL
					 Servlet over the web corresponding to information for the airport code you
					 typed in. If the return indicates that there was no exact match, the builds up
					 a dynamic "picklist" of possible matches based on the information returned in
					 the XML "datagram" from the XSQL Servlet.
 </td>
 </tr>
 <tr class="ro">
 <td nowrap="">Airport Code Display (airport)</td>
 <td> 
				 Demonstrates using the same XSQL page as the previous
					 example but supplying an XSLT Stylesheet name in the request. This causes the
					 airport information to be formatted as an HTML form instead of being returned
					 as raw XML. 
 </td>
 </tr>
 <tr class="re">
 <td nowrap="">Airport Code Display (airport)</td>
 <td> 
				 Demonstrates returning Airport information as a SOAP
					 Service.
 </td>
 </tr>
 <tr class="ro">
 <td nowrap="">Emp/Dept Object View Demo
				 (empdept)</td>
 <td>Demonstrates using an object view to group
				 master/detail information from two existing "flat" tables like EMP and DEPT.
				 The empdeptobjs.sql script creates the object view (along
				 with INSTEAD OF INSERT triggers allowing the master/detail
				 view to be used as an insert target of xsql:insert-request). 
				 The empdept.xsl stylesheet illustrates
					 an example of the "simple form" of an XSLT stylesheet that can look just like
					 an HTML page without the extra xsl:stylesheet or xsl:transform at the top. This
					 is part of the XSLT 1.0 specification called using a 
					 <a href="http://www.w3.org/TR/xslt#result-element-stylesheet">Literal Result
						Element as Stylesheet</a>. It also demonstrates how to generate an HTML
					 page that includes the 
 &lt;link rel="stylesheet">
 to allow the
					 generated HTML to fully leverage CSS for centralized HTML style information,
					 found in the coolcolors.css file.
 </td>
 </tr>
 <tr class="re">
 <td nowrap="">Adhoc Query Visualization
				 (adhocsql)</td>
 <td>Demonstrates passing the entire SQL query and
				 XSLT Stylesheet to use as parameters to the server.</td>
 </tr>
 <tr class="ro">
 <td nowrap="">XML Document Demo (document)</td>
 <td>Demonstrates inserting XML documents into
				 relational tables. The docdemo.sql script creates a
				 user-defined type called XMLDOCFRAG containing an attribute of type CLOB. 
				 Try inserting the text of the document in
					 ./xsql/demo/xml99.xml and providing the name
					 xml99.xsl as the stylesheet, as well as
					 ./xsql/demo/JDevRelNotes.xml with the stylesheet
					 relnotes.xsl. 
				 The docstyle.xsql page illustrates an
					 example of the 
 &lt;xsql:include-xsql>
 action element to include
					 the output of the doc.xsql page into its own page before
					 transforming the final output using a client-supplied stylesheet name. 
				 The demo uses the client-side XML features of Internet
					 Explorer 5.0 to check the document for well-formedness before allowing it to be
					 posted to the server. </td>
 </tr>
 <tr class="re">
 <td nowrap="">XML Insert Request Demo
				 (insertxml)</td>
 <td>Demonstrates posting XML from a client to an
				 XSQL Page that handles inserting the posted XML information into a database
				 table using the 
 &lt;xsql:insert-request>
 action element. The demo
				 is setup to accept XML documents in the 
				 <a href="http://www.moreover.com/site/products/xml/">moreover.com</a> XML-based
				 news format. 
				 In this case, the program doing the posting of the XML is a
					 client-side web page using Internet Explorer 5.0 and the <a href="http://msdn.microsoft.com/xml/reference/scriptref/XMLHttpRequest_object.asp">XMLHttpRequest</a>
 
					 object from JavaScript. If you look at the source for the insertnewsstory.xsql
					 page, you'll see it's specifying a table name and an XSLT Transform name. The
					 moreover-to-newsstory.xsl stylesheet transforms the incoming
					 XML information into the canonical format that the OracleXMLSave utility knows
					 how to insert. 
				 Try copying and pasting the example
					 
 &lt;article>
 element several times within the
					 
 &lt;moreovernews>
 element to insert several new articles in one
					 shot. 
				 The newsstory.sql script shows how
					 INSTEAD OF triggers can be used on the database views into which you ask XSQL
					 Pages to insert to the data to customize how incoming data is handled, default
					 primary key values, etc.
 </td>
 </tr>
 <tr class="ro">
 <td nowrap="">SVG Demo (svg)</td>
 <td>The deptlist.xsql page
				 displays a simple list of departments with hyperlinks to the
				 SalChart.xsql page. The SalChart.xsql
				 page queries employees for a given department passed in as a parameter and uses
				 the associated SalChart.xsql stylesheet to format the result
				 into a Scalable Vector Graphics drawing, a bar chart comparing salaries of the
				 employees in that department.</td>
 </tr> 
		</table> Then, browse the URL 
		<a href="http://localhost/xsql/index.xsql">http://localhost/xsql/index.html</a>
		to see a list of all the demos. <a name="colophon"></a><a name="ID7660">
 <h2 style="color:#000088"><img src="images/line3.gif" width="300" height="11"> Closing Comments</h2>
 </a>
 Once you've understood what the XSQL Page Processor running inside the XSQL Servlet
		does, you'll realize that Oracle XSQL Pages is really just a very thin layer of
		convenience functionality allowing you to leverage the tremendous flexibility
		and power of SQL, XML, and XSLT to really do the "heavy lifting". 
 <table border="1" cellspacing="0" cellpadding="4">
 <tr>
 <td valign="top" align="right" bgcolor="yellow"><img src="images/point.gif">
 </td>
 <td valign="top">Note
 : 
		Some of the material included in this document is excerpted from 
		 <a href="http://www.oreilly.com/catalog/orxmlapp">Building Oracle
			 XML Applications</a> by permission of 
		 <a href="http://www.oreilly.com">O'Reilly and Associates</a>.
		 
	 </td>
 </tr>
 </table> 
 </body>
</html>

Ms-Dos/Windows Unix Write backup

jsp File Browser version 1.2 by www.vonloesch.de