Oracle XSQL- P24 ppt

An XSQL Error Template Developing an error handling template is just like developing any other template. Here you’ll develop a stylesheet that can be imported into other stylesheets so that you can use the same error handling routines throughout your application. Then you’ll look at ways to override the basic error handling stylesheet for specific cases. Here is the error handling stylesheet itself: <?xml version = ‘1.0’?> <xsl:stylesheet xmlns:xsl=”http://www.w3.org/1999/XSL/Transform” version=”1.0”> <xsl:template match=”xsql-error”> <xsl:param name=”error-mesg”>Error!</xsl:param> <p> <table border=”1”> <tr><td><h3><xsl:value-of select=”$error-mesg”/></h3></td></tr> <tr><td> <b>XSQL Action Handler:</b> <xsl:value-of select=”@action”/> </td></tr> <tr><td> <b>Code:</b> <xsl:value-of select=”@code”/> </td></tr> <xsl:apply-templates/> </table> </p> </xsl:template> <xsl:template match=”message”> <tr><td><b>Message: </b> <xsl:value-of select=”.”/> </td></tr> </xsl:template> <xsl:template match=”statement”> <tr><td><b>Statement: </b> <xsl:value-of select=”.”/> </td></tr> </xsl:template> </xsl:stylesheet> Now you just need to add the following xsl:import to all of your stylesheets: <xsl:import href=”xsql-error.xsl”/> Notice that you are doing an import this time, not an include. The reasoning is that you can override the default template on a page-by-page basis. For instance, if this error comes up in prod-search.xsl, you know that it was caused by a bad search string. You can put the following template in prod-search.xsl to handle the error: <xsl:template match=”xsql-error”> Fix your broken search string! <xsl:apply-imports/> </xsl:template> 440 Chapter 14 This will give the error and then invoke the template that resides in the xsql -error.xsl stylesheet. It is also possible to give more refined messages based on the error code that was returned. This one interprets the error based on the error code that was returned: <xsl:template match=”xsql-error[@code=911]”> Hey! Don’t use single quotes in your searches. They aren’t allowed. </xsl:template> Because you know what the error is, you don’t need to trouble the user with all of the error code stuff and Oracle messages. This is easily suppressed—just don’t use the xsl:apply-imports element. Ways to Handle Errors If you follow just the preceding instructions, then the error messages will appear wher- ever the query results were supposed to appear. This may be the behavior that you desire—or maybe not. This section looks at two other ways of handling errors. The first handles errors globally. If any error occurs, then an error page is shown detailing all of the errors instead of having error messages inside of the interface. The second method examines how to deal with errors at a more granular level. You can choose what to do with errors inside the templates that would otherwise handle the results. First, let’s look at how the errors are displayed by default. In Figure 14.17, the error message pops up exactly where the query should be. Figure 14.17 Default behavior with error handling template. Building XSQL Web Applications 441 What if you want only an error page if any error occurs? You can do that by using the following template that matches at the root of the stylesheet: <xsl:template match=”/”> <xsl:choose> <xsl:when test=”count(//xsql-error)>0”> <html> <head></head> <body> <xsl:apply-templates select=”//xsql-error”/> </body> </html> </xsl:when> <xsl:otherwise> <xsl:apply-templates select=”/prod-search”/> </xsl:otherwise> </xsl:choose> </xsl:template> In this previous example, the node-set //xsql-error was used to determine if there were any errors. You can use the same kind of technique inside your templates. You can use xsl:if and xsl:choose elements to determine if there are errors on a template-by-template basis. Then you can decide what should be done in those cases. All of these strategies have their own pluses and minuses, and a lot of it depends on what your application requires. Regardless, some kind of error handling is important. By using some of the techniques outlined here, you should be able to make error handling an easy (and error-free!) part of your application. Moving On This chapter brought together all of the concepts of the previous chapters. In addition to writing XSQL pages, you also developed XSLT code and used SQL, Oracle Text, and the Oracle XML functionality. You should be able to use this chapter as a basis for developing your own XSQL applications. The next chapters move beyond the core of XSQL, and show you how to use it in new ways and extend the framework. The next two chapters show you how to use XSQL from the command line and how to use XSQL with Web services. Then, for the last three chapters of the book, you’ll see how to use XSQL in conjunction with Java. 442 Chapter 14 443 The command line utility gives you the ability to access most of the functionality of XSQL from the command line. You pass the URL of an XSQL page and, optionally, an output file and its parameters to the command line utility. It gives you back the results of processing the XSQL page. Since it isn’t servlet-based, you can’t make use of session parameters or cookies, but you can pass request-level parameters if you’d like. The first section covers how to use the command line utility first. The next section provides two examples to demonstrate the command line utility. One example shows how to create a newsletter; the other, shows to send a newsletter with a simple shell script. Using the Command Line Utility The command line utility exists as the oracle.xml.xsql.XSQLCommandLine class. The syntax for the call is as follows: >java oracle.xml.xsql.XSQLCommandLine xsqlpage [out] [param1=val1 . . .] The xsqlpage argument is the URL for the XSQL page that you wish to process. You don’t have to have a Web server running to use the command line tool, though. You can use the file:/// protocol to use local files. The out argument is an optional argument for an output file. If you specify it, the output will be written to the file. Command Line Utility CHAPTER 15 The other arguments are parameters that you wish to pass to the XSQL page. These arguments will function just like request parameters passed in the query string of HTTP GETrequests. Action handlers that reference the servlet environment beyond simple request parameters won’t work properly. Oracle also provides a batch file so that you don’t have to type out the full class name. It resides in the bin directory of your XSQL distribution or the bin directory of your Oracle distribution if you installed it in conjunction with your Oracle server. You use it as follows: >xsql xsqlpage [out] [param1=val1 . . .] Before using the command line tool, you’ll need a XSQLConfig.xml file in the classpath that you are running from. The classpath exists as an environment variable, so just look at it to see where all it points to. You may also have to add the following jar files to the classpath before the command line utility will work. ■■ jlib/sax2.jar ■■ rdbms/jlib/xsu12.jar ■■ lib/xmlparserv2.jar ■■ lib/oraclexsql.jar ■■ jdbc/lib/classes12.jar You may be tempted to use the command line tool with XSQL pages that are part of an online application. You probably won’t have a lot of success calling them with the HTTP protocol, like this: >xsql http://localhost/xsql/momnpup/home.xsql By the time the response comes back, a stylesheet will have already been applied. What you get back isn’t the original XSQL page but an HTML page. The command line tool can’t make any sense out of it, so you get a weird error like this: Oracle XSQL Command Line Page Processor 9.0.1.1.0 (Prod) XSQL-005: XSQL page is not well-formed. XML parse error at line 5, char 10 End tag does not match start tag ‘link’. You won’t find any link tag on page 5 of your XSQL page. You need only call the XSQL page with a file URL, make a copy of the XSQL page without reference to the stylesheet, or set the xml-stylesheet parameter to none if this is allowed by your setup. So, what if you want the command line tool to apply a stylesheet to my results? You do this by passing it a xml-stylesheet parameter. The command line parameter has three such parameters, as described in Table 15.1. 444 Chapter 15 Table 15.1 Built-in Command Line Parameters PARAMETER MEANING xml-stylesheet The stylesheet’s URL or a URL relative to the XSQL page’s URL. If set to none, no stylesheet is applied. posted-xml Optional XML document to be posted to the request. Used in conjunction with the XML handlers to input data. useragent The user agent to pass to the page. Useful if you choose stylesheets based on the user agent string in your XSQL page. Text Example So far, you have been very focused on developing applications for the Web. The pur- pose of this chapter is, in part, to look beyond the Web and examine how else XSQL can be used. In this example, you’ll use XSQL to generate a plain-text file. Instead of mak- ing a Web page, you’ll make one of those goofy email newsletters that likes to refer to you by name. Here’s how you do it: <?xml version = ‘1.0’?> <xsl:stylesheet xmlns:xsl=”http://www.w3.org/1999/XSL/Transform” version=”1.0”> <xsl:output method=”text”/> <xsl:template match=”/ROWSET/ROW”> Hi <xsl:value-of select=”NAME”/>, It is your lucky day! Nothing could be better for you and everyone else there at <xsl:value-of select=”ORGANIZATION”/>. We’re talking deals. Good ones! Not like that stuff you see in all that spam. Oh, no! This is the real thing. Just between you and me, <xsl:value-of select=”NAME”/>, This could very well be the best thing that ever happened to you. So come on by, and we’ll figure it out, or your name isn’t <xsl:value-of select=”NAME”/>. Cheers! </xsl:template> </xsl:stylesheet> Command Line Utility 445 Now you need an XSQL page that will create the email for a particular email address. Here’s one: <?xml version=”1.0”?> <xsql:query connection=”momnpup” xmlns:xsql=”urn:oracle-xsql”> SELECT * FROM newsletter WHERE email=’{@email}’ </xsql:query> The following command line pulls the pieces together. It specifies that the newsletter.xsl stylesheet should be used and that the email parameter should be passed. >xsql file:///java/xsql/newsletter.xsql xml- stylesheet=file:///java/xsql/newsletter.xsl email=test2@momnpup.com In this example, the output writes to the console. If you would prefer to write it to a file, you need only specify that file as the second parameter: >xsql file:///java/xsql/newsletter.xsql newsletter.out xml- stylesheet=file:///java/xsql/newsletter.xsl email=test2@momnpup.com In the next section, you’ll use this code as part of a script. Script Writing By using the XSQL file from the preceding section, you can generate a newsletter itself. To actually send it, you just have to pass the newsletter to some kind of mail-handling program to get it out to the right recipients. In this example, you’ll write a simple script that can be used on Unix with the mail utility. It will send out a batch of newsletters based on a particular XSQL page. Of course, the scripts that you can write with XSQL are pretty unlimited. You can even write SQL scripts based on your XSQL output. This script is mainly intended to get your imagination going about the kind of scripts that are possible. The first step is to figure out how to send the newsletter to a single address. This is rather simple: >xsql file:///java/xsql/newsletter.xsql newsletter.out xml- stylesheet=file:///java/xsql/newsletter.xsl email=test2@momnpup.com | mail -t test2@momnpup.com To do the mailing, you need an XSQL page that captures all the addresses in the newsletter table. The following XSQL page will do the trick: <?xml version=”1.0”?> 446 Chapter 15 <xsql:query connection=”momnpup” xmlns:xsql=”urn:oracle-xsql”> SELECT email FROM newsletter </xsql:query> Now you need a stylesheet that creates one of the foregoing mailer commands for each of the email addresses, such as the following: <?xml version = ‘1.0’?> <xsl:stylesheet xmlns:xsl=”http://www.w3.org/1999/XSL/Transform” version=”1.0”> <xsl:output method=”text”/> <xsl:template match=”/”> #/bin/sh <xsl:apply-templates select=”ROWSET/ROW”/> </xsl:template> <xsl:template match=”ROW”> java oracle.xml.xsql.XSQLCommandLine file:///java/xsql/newsletter.xsql xml-stylesheet=file:///java/xsql/newsletter.xsl email=<xsl:value-of select=”EMAIL”/>|mail -t <xsl:value-of select=”EMAIL”/> -s “Newsletter” </xsl:template> </xsl:stylesheet> This stylesheet creates a separate command for each newsletter. When the script runs, a newsletter will be generated and then piped to the mail command. $xsql file:///java/xsql/mailer.xsql xml-stylesheet=mailer.xsl > mailer.sh After creation, the script will look something like this: #/bin/sh java oracle.xml.xsql.XSQLCommandLine file:///java/xsql/newsletter.xsql xml-stylesheet=file:///java/xsql/newsletter.xsl email=test1@momnpup.com | mail -t test1@momnpup.com -s “Newsletter” java oracle.xml.xsql.XSQLCommandLine file:///java/xsql/newsletter.xsql xml-stylesheet=file:///java/xsql/newsletter.xsl email=test2@momnpup.com | mail -t test2@momnpup.com -s “Newsletter” The command line tool gives you a simple but powerful means of creating all kinds of scripts. If you need data out of the database to be in your scripts, you can use XSQL to help create the scripts. A lot of the same lessons from the earlier JavaScript discus- sion apply. Most important, however, is not to get too fancy. If you find that you are using stylesheets to greatly modify the logic of the stylesheet, you may be creating a beast that no one can maintain. Command Line Utility 447 Creating Static Web Pages In the catalog application developed in the last chapter, a lot of the pages will come up the same each time. Pages containing product descriptions and category lists probably aren’t going to change much. Instead of querying the database each time that a user hits the site, you could generate all the static pages at midnight and then just link to the static pages. This approach won’t necessarily work for all the pages in an application; for example, it cannot be applied to the search results page in the product catalog application. In this example, you’ll see how to create all the product details pages using a script. Before going down this path, it’s important to note that the links in the application would have to change to use the product details page. Right now, XSLT statements like the following are used throughout the application: <a> <xsl:attribute name=”href”>prod-details.xsql?product_id=<xsl:value-of select=”PRODUCT_ID”/></xsl:attribute> <xsl:value-of select=”PRODUCT_NAME”/> </a> You don’t want to link to the XSQL page, because it will query the database. Instead, you want to link to a static page. The first step is to determine where you will keep the static pages and how you will name them. For this example, each details page will have a name like prod-details-1.html, where 1 is the id for the product. They’ll live in the /momnpup virtual directory. Thus, this particular link should look like the following: <a> <xsl:attribute name=”href”>/momnpup/prod-details-<xsl:value-of select=”PRODUCT_ID”/>.html</xsl:attribute> <xsl:value-of select=”PRODUCT_NAME”/> </a> The next step is to figure out how to create a single page. The following will create the HTML for a single page: prompt>xsql file:///java/xsql/momnpup/prod-details.xsql prod-details- 4.html product_id=4 Now you just use XSQL to generate a script for the entire site. Here is what the XSQL looks like: <?xml version=”1.0”?> <xsql:query connection=”momnpup” xmlns:xsql=”urn:oracle-xsql”> SELECT id FROM product </xsql:query> 448 Chapter 15 Next, you need a stylesheet that will actually create the script: <?xml version = ‘1.0’?> <xsl:stylesheet xmlns:xsl=”http://www.w3.org/1999/XSL/Transform” version=”1.0”> <xsl:output method=”text”/> <xsl:template match=”/”> <xsl:apply-templates select=”ROWSET/ROW”/> </xsl:template> <xsl:template match=”ROW”> java oracle.xml.xsql.XSQLCommandLine file:///java/xsql/momnpup/prod- details.xsql new/prod-details-<xsl:value-of select=”PRODUCT_ID”/> xml- stylesheet=file:///java/xsql/newsletter.xsl product_id=<xsl:value-of select=”PRODUCT_ID”/> </xsl:template> </xsl:stylesheet> You generate the script as follows. You only have to generate the script if new products have been inserted into or deleted from the database since the last time that you ran the script. If the set of products is the same, then you can use the last script that you created. >xsql file:///java/xsql/details-pages-script.xsql details-script.bat xml-stylesheet=file:///java/xsql/details-pages-script.xsl XSQL and XSLT are useful in a command line environment. The command line tool gives you an easy way to access the database and get data into the scripts. Moving On This chapter showed you how you can use XSQL as a command line tool. The XSQL command line utility is a good way for you to easily access the database. This is only one way that you can use XSQL beyond Web publishing. The next chapter shows how you can create Web services with XSQL; Chapter 17 shows you how to use XSQL from inside your Java applications. Command Line Utility 449 [...]... each other Toward this end, the SOAP standard provides transaction and data-type support If you are trying to create a true distributed application, SOAP would be a much better starting point than the XSQL-based Web services model that you will learn here 451 452 Chapter 16 N OT E XSQL uses DOM, which you’ll learn more about in the next chapter DOM requires that all the data be loaded into memory before... XSQL Request Figure 16.1 Basic Web services architecture Web Services with XSQL The Web services application probably isn’t going to want the XML data it receives to be in the canonical Oracle schema Likewise, it probably won’t want to post data in that same canonical schema This is where XSLT comes in to play You use separate XSLT stylesheets to transform data on the way into and on . match=”/”> <xsl:choose> <xsl:when test=”count(//xsql-error)>0”> <html> <head></head> <body> <xsl:apply-templates select=”//xsql-error”/> </body> </html> </xsl:when> <xsl:otherwise> <xsl:apply-templates. chapters. In addition to writing XSQL pages, you also developed XSLT code and used SQL, Oracle Text, and the Oracle XML functionality. You should be able to use this chapter as a basis for developing. Line Utility The command line utility exists as the oracle. xml.xsql.XSQLCommandLine class. The syntax for the call is as follows: >java oracle. xml.xsql.XSQLCommandLine xsqlpage [out] [param1=val1