Oracle XSQL- P5 pps

Figure 4.3 XSQL programmatic invocation architecture. XSQL Servlet XSQL servlet invokes the XSQL page processor. You will have a lot of interaction with the XSQL servlet. As described in the previous chapter, you must register the XSQL servlet with the servlet engine. There are also two servlet-specific configuration ele- ments: output-buffer-size and suppress-mime-types. Though XSQL servlet is the Web interface to all XSQL functionality, it itself does lit- tle. It receives a request and passes it to the XSQL page processor. The XSQL page processor does the heavy lifting and hands back a result. If you have buffering turned on, the XSQL servlet will buffer the output for you. If the XSQL servlet is configured appropriately, it will suppress the sending of character-encoding information. And that’s about it. It’s time to move on to the real player—the XSQL page processor! XSQL Page Processor The XSQL page processor, as the name applies, is responsible for processing the XSQL pages. It is the magician of the system. It takes a simple XSQL and a XSLT file, connects .xsl .xsql Database JDBC XML SQL XSQLRequest YourJavaClass Java Virtual Machine XSLT Processor XSQL Page Processor XML Parser 60 Chapter 4 to the database, and gives you back something presentable. At the highest level, it per- forms this function as described in Figure 4.4. This invoker is the XSQL servlet, the XSQL command line, or the XSQL request. At the time of invocation, it is possible to know how the XSQL page processor was invoked. For this discussion, you’ll learn how the XSQL page processor behaves regardless of how it is invoked. The XSQL page processor is already loaded into memory at the time of invocation except when you call it from the command line or make the first call for the instance of the JVM. When the XSQL page processor loads, it reads its XSQLConfig.xml file. At about a 5,000-ft level, the XSQL page processor does the following when invoked: 1. Parses the request from the invoker 2. Selects the XSQL page 3. Processes the actions described in the XSQL page (most of the time by going to the database) 4. Applies an XSLT stylesheet, if one is specified, to the resulting XML datagram 5. Passes the result back to the invoker But alas, it couldn’t possibly be that simple! The engineers at Oracle have always been known to put some brilliant, elegant machinery under the covers. You’ve already had a glance at some of these widgets. In the previous chapter, you read about all the configuration parameters in the XSQLConfig.xml file. In that discussion, you learned about the XSQL page cache, the stylesheet cache, and the database connection pool. Each of these are modules in the XSQL page processor. They ensure that the XSQL page processor can drive your application with high efficiency. Figure 4.5 gives a detailed view. You’ll learn about the two caches here; in the next section, you’ll learn about the database connection pool. Figure 4.4 High-level diagram of the XSQL page processor. .xsl .xsql Database JDBC XML SQL Invoker Java Virtual Machine XSLT Processor XSQL Page Processor XML Parser XSQL Architecture 61 Figure 4.5 The XSQL page processor. We begin with the XSQL page cache. This is a simple least recently used (LRU) cache. When the cache is full and a page not in the cache gets called, the page in the LRU cache is expelled. The algorithm, an LRU algorithm, is used to determine this action. So, if one page gets hammered a lot, it would probably stay in the cache all the time. The frequently used pages stand at alert, ready to be processed. This saves the XSQL page processor the trouble of loading into memory the most active XSQL pages each time they are called. By using a process described in the previous chapter, you can configure how many pages you want the XSQL page cache to hold. In small sites, you can expect all the XSQL pages to be easily loaded into the cache. If you have perfor- mance problems, you may want to bump up the size of the cache. The trade-off is that you will have less memory available for other tasks. Database .xsl files .xsql files XSQL Page XSQL Page XSQL Page XSQL Page XSQL Page XSQL Page Cache xsl xsl xsl xsl xsl xsl xsl xsl xsl xsl xsl xsl xsl xsl xsl xsl XSLT Stylesheet Cache XML SQL XSLT Processor XSQL Page Processor Java Virtual Machine Invoker JDBC JDBC JDBC JDBC Connection Pool XML Parser 62 Chapter 4 In concept, the stylesheet cache is similar to the XSQL page cache. It caches stylesheets so that the XSQL page processor doesn’t have to fetch them from the file sys- tem every time. Like the XSQL page cache, it uses an LRU algorithm to determine which stylesheets most greatly need to be in the cache. However, it works quite a bit differently than the XSQL page cache. It is optimized for multithreaded servlet engines. Why would the two need to work differently? The acts of XSQL page processing and stylesheet processing are quite different. Once an XSQL page is loaded, it can be repre- sented statically in memory. The XSQL page processor can respond to requests by accessing instantiated objects; that is, the XSQL page itself doesn’t need to be reparsed in any way on each request. XSLT is more complex. An XSL stylesheet is merged with the resulting XML in a way described by the stylesheet. As you will see in Chapter 5, the XSLT language isn’t trivial. Since the XML is expected to change from one query to the next, there is a lot of processing work that must occur at the time of invocation. On a multithreaded servlet engine, multi- ple threads could easily process the same XSLT stylesheet at the same time. For caching to be effective, it makes sense that there should be multiple instances of the cached stylesheet. Thus, the stylesheet cache uses an LRU cache in conjunction with pooling. The LRU cache is a cache of pools. The pool is designed to grow when multiple threads demand the same stylesheet and to contract when activity is slower. When there is a set amount of inactivity (the time-out seconds parameter in the XSQLConfig.xml file), a particular stylesheet instance will drop out of the pool. In a busy servlet engine, the individual pools can grow for popular stylesheets so that all threads can have their own instance. The pooling is one side of the equation; the cache itself is the other side. The LRU cache works essentially the same as the XSQL page cache. Think of it like this: If you configured the stylesheet pool so that it could have, at a maximum, only one stylesheet instance, the XSQL page cache and the stylesheet cache would work exactly the same. As you can see, the actual processing of XSQL is quite complex. This complexity, however, is hidden from the user. Programmers could work with XSQL for years and never have any reason to know about the details discussed here, but if they encounter performance problems, an understanding of the underlying XSQL architecture would be very useful. Oracle XML Modules XSQL is built on top of other XML modules from Oracle. In this section, we look at the different underlying pieces and how they provide the necessary functionality. First, you’ll learn more about the Oracle XML parser; then, you’ll learn about XML SQL, which transforms SQL results into XML; finally, you’ll learn about the XSLT processor, which handles XSLT transformations. XML Parser In any XML-based system, sooner or later you are going to run into an XML parser. There is no exception to this rule here. The XSQL page processor makes use of the XSQL Architecture 63 Oracle XML parser in a couple of key ways. XSQL pages and XSLT stylesheets are all XML documents, so they need to be parsed. As an XSQL developer, you may never need to use the XML parser. However, if you wish to extend the functionality of XSQL, you may find reason to use the parser directly. You’ll learn more about programming with the XML parser in later chapters; here, you’ll learn about the architecture of the Oracle XML parser. XSQL uses the Document Object Model (DOM) functionality of the Oracle XML parser. Like all DOM XML parsers, the Oracle XML parser takes a stream—which may be a file, a string generated internally by an application, or data received over the network—and creates an in-memory representation of the XML. The representation, called a document, looks like a tree and can be traversed and queried to get data out of it. The document can also be added to and otherwise modified. Usually, at some point it is passed along to some other component. It might be written to the file system, sent over the network, or just handed as an argument to another component. XML SQL The Oracle XML SQL utility is used by the XSQL page processor in its interaction with the database. This is a stand-alone utility that you can use as part of the Oracle XDK. The use of the utility in conjunction with XSQL pages is transparent. You can be an effective XSQL developer without knowing anything about XML SQL, but for a solid understanding of the overall architecture, it’s important that you know how XML SQL fits in. On queries, XML SQL is used to translate the result set into XML. It produces a canonical XML representation, covered in detail later in this chapter. This representa- tion is based on a standard schema that works for all SQL queries. When working with the output of XSQL, you can assume that the results will come back in this schema. XSQL replaces the query call with these results that XML SQL provides. XML SQL is also used by XSQL when pushing data to the database by using the xsql:insert-request, xsql:update-request, xsql:delete-request, and xsql:insert-param actions. The canonical schema is used for these cases, also. In these situations, the burden is on you to ensure that your data is in the correct format. Doing so is easily accomplished with XSLT stylesheets, as you’ll see. Much of XSQL is based on XML SQL. If you find yourself wanting to get under the hood of XSQL, you’ll want to explore the Oracle XML SQL utility. As you’ll see in Chapter 18, it is easy to exploit the power of XML SQL from your own custom action handlers. XSLT Processor The XSLT processor performs the XSLT transformations. Without the XSLT processor, XSQL is pretty boring, for all you have is an easy way to execute commands against the database and produce XML from SQL statements. The XSLT processor takes the result of the XSQL page processor and transforms it into something usable by the requesting agent. 64 Chapter 4 As an XSQL developer, you have very little direct interaction with the XSLT proces- sor. You tell it what to do with the stylesheet processing instruction that is documented completely later in this chapter. The most significant part of this instruction is the loca- tion of the stylesheet. The XSLT processor finds the stylesheet and performs the trans- formation. The transformation itself is dictated by the stylesheet, which is written in the XSLT language. This language allows you to describe how you want the source XML to merge with the text in the stylesheet. Usually, the stylesheet contains HTML markup that describes how nodes in your XML should be output. You can, however, output whatever you want. The XSLT engine is compliant with the World Wide Web Consortium (W3C) XSLT 1.0 Recommendation released in 1999 and, for the moment, acting as the driving stan- dard behind XSLT. You might run across an old stylesheet based on an earlier standard. The processing instruction of the stylesheet should enable you to determine whether that stylesheet is old. Core XSQL Components So far in this chapter, you’ve learned a lot about the technologies that XSQL leverages and the ways to access XSQL functionality. What you haven’t learned are the compo- nents that XSQL developers work with daily. These components are discussed in this section and revisited throughout the remainder of the book. The first component is the XSQL page, which is the key component of XSQL. XSQL Pages These are XML documents that describe what the XSQL page processor should do. We’ve already described several XSQL pages used for executing SQL queries, as well as those for linking to a stylesheet that transforms the resulting XML. First, it’s important to note that an XSQL page doesn’t have to be a file. When in Chapter 17 you learn about embedding the XSQL page processor into your Java code, you’ll see that you can construct your XSQL page at runtime. You can also create an XSQL page with another XSQL page, dynamically. To do so, the XSQL page proces- sor requires only that the XSQL page be a valid, well-formed XML document. When XSQL is used programmatically, there is a lot of flexibility in how an XSQL page may originate. When the XSQL servlet is used, however, your XSQL page needs to exist as a file. An XSQL page itself can contain several different entities. Any nontrivial XSQL page contains one or more actions, which are discussed in the next chapter. The actions tell the XSQL page processor what it should do. You can also link an XSQL page to an XSLT stylesheet. Doing so tells the XSQL page processor to use the specified stylesheet to transform the results. The XSQL page can also specify a serializer, which is discussed in more detail later in this section. You can use a serializer to specify exactly how the data are written to the output. XSQL Architecture 65 Actions XSQL is built around the concept of actions, an XML element that defines what you want to do. You have already seen the xsql:query action. This action is, by far, the most popular, but there are others. The XSQL page processor executes the actions. It takes the resulting XML datagram for a particular query and replaces the original action element with the XML datagram. More than one action can be included in the same page. In the case of multiple actions in a page, you must have a top-level element that contains all the action elements on the page. This is an XML requirement, so if you don’t follow this requirement, the doc- ument will not be valid XML. The following code is the first XSQL page that you saw in Chapter 1. It contains one action, the xsql:query action. This action is simply an XML element that belongs to the XSQL namespace. <?xml version=”1.0”?> <?xml-stylesheet type=”text/xsl” href=”emp-intro.xsl”?> <page xmlns:xsql=”urn:oracle-xsql” connection=”demo”> <xsql:query> SELECT ename, job, sal FROM emp WHERE deptno=20 ORDER BY sal </xsql:query> </page> In Chapter 5, you’ll learn more about built-in actions. In Chapter 18, you’ll see how you can define your own actions. Action Handlers Action handlers handle XSQL actions. In the case of the built-in actions, XSQL implic- itly relates a given action to an action handler. When the built-in actions don’t provide you with the functionality that you desire, you can create your own custom action handlers. The architecture of action handlers is diagrammed in Figure 4.6. The XSQL page processor knows about the built-in action handlers; for the custom action han- dlers, you either specify the name of the class in the XSQL page or cite it by a nickname given in the XSQLConfig.xml file. In Figure 4.6, the some-page.xsql has three actions, including the xsql:query action that you’ve seen used in the code examples so far. The XSQL page processor handles that action with the built-in action handler called the XSQL query handler. There is a built-in action handler for each action discussed in the next chapter. The two custom action handler classes handle the two custom actions and are loaded into the JVM. A custom action handler can do whatever you want. In Chapter 18 you’ll learn more about programming custom action handlers. 66 Chapter 4 Figure 4.6 Architecture of action handlers. Serializers Serialization is the process of writing the end XML document. In our earliest examples in the last chapter, the default serializer wrote XML out to a network stream only, and our browser displayed it. The serializer’s job isn’t hard: It just takes what the XSQL page processor assembles in memory and writes it to output. Figure 4.7 shows how the serializer fits in. The architecture of serializers is simpler than that of action handlers. Although you can—and often will—use multiple action handlers in your XSQL page, you can specify only one serializer per XSQL page. In most cases, you won’t need to specify a serializer at all. Figure 4.7 The serializer. Java Virtual Machine XSQL Page Processor some-page.xsql Some Serializer Some Serializer Java Virtual Machine Built-in Actions XSQL Page Processor Query Action Handler Custom Action2 Custom Action1 xsql:query built-in action custom action 1 custom action 2 some-page.xsql XSQL Architecture 67 There are several built-in action handlers, but the only built-in serializer is the default one. Like action handlers, you can create your own custom serializers, a process you’ll learn more about in Chapter 19. Why would you want to? In most cases, you won’t need to; the default serializer will do just fine. The primary reason to specify a serializer is to output binary data, such as a PDF or image. Oracle provides a serial- izer that allows you to use Apache FOP to create dynamic PDFs. Moving On This chapter focused on the high-level architecture of XSQL. Chapter 5 discusses XSQL coding; Chapters 6 and 7 show you the ins and outs of how XSQL works. You’ll exam- ine the technologies associated with XSQL—first, SQL and other Oracle database tech- nologies, then XSLT. You can use much of the material in Chapters 5 through 7 for building upon, implicitly, the knowledge you’ve gained from this chapter. By having a good understanding of XSQL architecture, you’ll find developing good XSQL-based systems easy. 68 Chapter 4 69 In the previous chapter, you learned about the architecture of XSQL. You looked at a lot of diagrams, but you did not write any code. In this chapter, you start coding. The first step is to flesh out your knowledge of the xsql:query action, which you used in previous examples. This is the action used to retrieve data from the database using SQL statements. This is only one of the built-in actions, though. All of them are covered in this chapter. But before going in to the rest of the actions, you will learn about the canonical XSQL schema and date formatting. These two areas apply generally to several of the built-in actions, including xsql:query. The chapter ends by describing how to link to XSLT stylesheets. This chapter provides all of the raw information for using the built-in XSQL actions. A couple of the areas, however, are explored in more detail in later chapters. Passing parameters between pages is very important, and is covered in Chapter 6. The actions that allow you to put information into the database are covered here, but an in-depth discussion of how to modify your database is presented in Chapter 7. You will learn how to create your own custom actions in Chapter 18. Querying the Database The xsql:query action is used to retrieve information from the database. You have already used it several times. At its simplest, you simply put a SQL statement between Writing XSQL Pages CHAPTER 5 [...]... statement If you try to insert a statement that would modify data or administer data objects, the XSQL page processor will reject it SELECT * from emp As you have observed earlier, the result set from the query is turned into an XML fragment that replaces the xsql:query element in the output The names of... ename as “employee name” so that the XML is returned with employee_name elements instead of ename elements, as in the following example SELECT ename as “employee_name” from emp Figure 5.1 Simple xsql:query example Writing XSQL Pages In some cases, you have to alias the field name Let’s say that, in addition... parentheses, which are illegal characters for an XML tag name, so you need to alias the field to something else Here’s how you do it: SELECT ename as “employee_name”, to_char(hiredate,’YYYY-MON’) AS “hiredate” FROM emp This XSQL page will produce the result shown in Figure 5.2 You will remember from the previous... row and rowset element names You do this by setting the row-element and rowset-element attributes of xsql:query Here’s how it works: SELECT * FROM emp This will yield the result shown in Figure 5.3 As you can see, you have a lot of control over the format... they have to be contained by a root node This goes back to the earlier discussion about XML There must be one root node for each document select dname from dept where deptno=10 select ename from emp where deptno=10 When you look at this example, you should see something... hard to distinguish where one query ended and the other began Instead, you should enclose each query inside a distinct element, as follows: select dname from dept where deptno=10 select ename from emp where deptno=10 ... already with the xsql:query action, and you’ll see the XML-to-SQL conversion later in this chapter In both of these cases, data that is usually arranged in a table has to be represented in a tree format Oracle solves this problem with a canonical schema This schema is used by xsql:query when result sets are presented as XML and is required by the XSQL actions that insert XML documents into database tables... representation into HTML When pushing data to the database, you use a stylesheet to transform the data from its original format into the canonical form The canonical form can be used to represent all of the Oracle datatypes, including cursors, objects, and collections But first, say that you have a simple table in the database, which includes the values in Table 5.4 77 78 Chapter 5 Table 5.4 Simple Database . about the architecture of the Oracle XML parser. XSQL uses the Document Object Model (DOM) functionality of the Oracle XML parser. Like all DOM XML parsers, the Oracle XML parser takes a stream—which. understanding of the underlying XSQL architecture would be very useful. Oracle XML Modules XSQL is built on top of other XML modules from Oracle. In this section, we look at the different underlying pieces. component. XML SQL The Oracle XML SQL utility is used by the XSQL page processor in its interaction with the database. This is a stand-alone utility that you can use as part of the Oracle XDK. The use