PageRenderTime 57ms CodeModel.GetById 23ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/contribs/saxon6_5_5/doc/samples.html

https://bitbucket.org/haris_peco/debrief
HTML | 367 lines | 207 code | 77 blank | 83 comment | 0 complexity | 5cebc7cb1103ca53eeedb523a5427c58 MD5 | raw file
    

  1. <html>

    2. 

  2. 

    3. 

  3. <head>

    4. 

  4. <title>Sample SAXON Applications</title>

    5. 

  5. 

    6. 

  6. </head>

    7. 

  7. 

    8. 

  8. <body leftmargin="150" bgcolor="#ddeeff"><font face="Arial, Helvetica, sans-serif">

    9. 

  9. <div align=right><a href="index.html">SAXON home page</a></div>

    10. 

  10. 

    11. 

  11. 

    12. 

  12. <h1><font color="#FF0080"><big>Sample SAXON Applications</big></font></h1>

    13. 

  13. 

    14. 

  14. <p>Several sample applications are included in the SAXON distribution.</p>

    15. 

  15. 

    16. 

  16. <div><font face="Arial, Helvetica, sans-serif">

    17. 

  17. <table width="100%">

    18. 

  18.   <tr>

    19. 

  19.     <td bgcolor="#0000FF"><font color="#FFFFFF"><big><b>Contents</b></big></font></td>

    20. 

  20.   </tr>

    21. 

  21. 

    22. 

  22.   <tr>

    23. 

  23.     <td VALIGN="top"  bgcolor="#00FFFF">

    24. 

  24.     <a href="#trax">TrAX Examples</a><br>

    25. 

  25.     <a href="#servlet">Sample Servlet</a><br>

    26. 

  26.     <a href="#books">The Book List Stylesheet</a><br>

    27. 

  27.     <a href="#sql">SQL Extensions</a><br>

    28. 

  28.     <a href="#shakespeare">Shakespeare Example</a><br>

    29. 

  29.     <a href="#bible">Bible Example</a><br>

    30. 

  30.     <!--<a href="#applet">Applet Examples</a><br>-->

    31. 

  31.     <a href="#jdom">JDOM Example</a><br>

    32. 

  32.     </td>

    33. 

  33.   </tr>

    34. 

  34. </table>

    35. 

  35. </font></div>

    36. 

  36. 

    37. 

  37. 

    38. 

  38. 

    39. 

  39. <hr>

    40. 

  40. 

    41. 

  41. 

    42. 

  42. <h2><a name="trax">JAXP examples</a></h2>

    43. 

  43. 

    44. 

  44. <p>Saxon supports the JAXP Java API (package javax.xml.transform), originally known as TrAX,

    45. 

  45.  for invoking the stylesheet processor.

    46. 

  46. This API is useful when you want to write your own applications that invoke Saxon.</p>

    47. 

  47. 

    48. 

  48. <p>A sample program that illustrates many features of the JAXP transformation interface is included in

    49. 

  49. the distribution as <b>TraxExamples.java</b>. Source XML and XSL files for use with this

    50. 

  50. program are included in the <b>trax</b> directory. To run the program, use the command:

    51. 

  51. 

    52. 

  52. <p><code><strong><font color="#FF0080">

    53. 

  53. cd $saxonhome/samples/trax

    54. 

  54. java TraxExamples <br>

    55. 

  55. </font></strong></code></p>

    56. 

  56. 

    57. 

  57. 

    58. 

  58. <p>One of the examples shows how to use TrAX to process input from a third-party (non-Saxon)

    59. 

  59. DOM document, and how to

    60. 

  60. send output to a third-party DOM document. This example tests to see if either Crimson or

    61. 

  61. Xerces is present on the classpath; if not, it should fail cleanly. You will need to change the

    62. 

  62. source code and recompile if you want to

    63. 

  63. use it with a different DOM implementation.</p>

    64. 

  64. 

    65. 

  65. 

    66. 

  66. <hr>

    67. 

  67. 

    68. 

  68. <h2><a name="servlet">SaxonServlet</a></h2>

    69. 

  69. 

    70. 

  70. <p>This is a general-purpose servlet that takes the name of a source document and stylesheet

    71. 

  71. as URL parameters, and processes the stylesheet to create a result document which is sent back

    72. 

  72. to the browser for display. The result document may have any media type, though HTML and XML are

    73. 

  73. the most likely.</p>

    74. 

  74. 

    75. 

  75. <p>The servlet maintains a cache of prepared stylesheets; if the same stylesheet is used repeatedly,

    76. 

  76. it is only parsed and validated once, which will often greatly improve performance. Prepared style

    77. 

  77. sheets are thread-safe so they can be used to serve documents to several users concurrently.</p>

    78. 

  78. 

    79. 

  79. <p>The URLs for the source document and the stylesheet document are supplied in the URL,

    80. 

  80. which will typically take the form:</p>

    81. 

  81. 

    82. 

  82. <p><code><strong><font color="#FF0080">

    83. 

  83. http://server.com/servlets/SaxonServlet?source=doc.xml&style=sheet.xsl

    84. 

  84. </font></strong></code></p>

    85. 

  85. 

    86. 

  86. <p><i>Note: Internet Explorer may assume that if the URL ends with ".xml" or ".xsl", as in

    87. 

  87. the above example, then the returned file will be XML - even if the media type in the HTTP header

    88. 

  88. is set to "text/html". You can prevent this behaviour by adding an extra dummy parameter, for example

    89. 

  89. "&amp;x=y".</i></p>

    90. 

  90. 

    91. 

  91. <p>The source and style parameters identify the source document and stylesheet by URL.

    92. 

  92. These are interpreted relative to the servlet context. This means that specifying

    93. 

  93. say "style=/styles/styleone.xsl" in the URL will locate the stylesheet in this file relative to the

    94. 

  94. root directory for the web server.</p>

    95. 

  95. 

    96. 

  96. <p>The stylesheet is prepared the first time it is used, and held in memory in a cache. The cache may

    97. 

  97. be cleared (for example, if a stylesheet has been changed) using a URL such as:</p>

    98. 

  98. 

    99. 

  99. <p><code><strong><font color="#FF0080">

    100. 

  100. http://server.com/servlets/SaxonServlet?clear-stylesheet-cache=yes

    101. 

  101. </font></strong></code></p>

    102. 

  102. 

    103. 

  103. <p>This code is provided purely as a sample, in the expectation that you will customise it to your

    104. 

  104. particular site requirements.</p>

    105. 

  105. 

    106. 

  106. <p><b>Security warning: if you implement a servlet that is prepared to execute untrusted stylesheets,

    107. 

  107. be sure to disable the use of extension functions. Otherwise users will be able to submit stylesheets for execution

    108. 

  108. that call arbitrary Java methods on your server, and these will typically have permissions to access private resources 

    109. 

  109. on the server machine.</b></p>

    110. 

  110. 

    111. 

  111. <h2><a name="books">The Book List Stylesheet</h2>

    112. 

  112. 

    113. 

  113. <p>This is a very simple sample stylesheet to illustrate several SAXON extensions.

    114. 

  114. It uses the XML file <b>books.xml</b> (derived from a file issued originally by Microsoft).

    115. 

  115. You will find this in the samples/data directory. The DTD is in <b>books.dtd</b></p>

    116. 

  116. 

    117. 

  117. <p> There is a style sheet <b>books.xsl</b> that can be used to display the data: run this as

    118. 

  118. follows, with the samples directory as the current directory:<p>

    119. 

  119. 

    120. 

  120. <p><code><strong><font color="#FF0080">

    121. 

  121. java com.icl.saxon.StyleSheet data/books.xml styles/books.xsl ><i>output.html</i><br>

    122. 

  122. </font></strong></code></p>

    123. 

  123. 

    124. 

  124. <p>This produces an HTML page showing the data. (The output isn't very pretty, if you have

    125. 

  125. time to write an improved version, please send it in).</p>

    126. 

  126. 

    127. 

  127. <p>The stylesheet takes a parameter named "top-author". This is the name of the "author of the week",

    128. 

  128. and the default value is "Bonner". To run the stylesheet with a different top author, try:</p>

    129. 

  129. 

    130. 

  130. <p><code><strong><font color="#FF0080">

    131. 

  131. java com.icl.saxon.StyleSheet data/books.xml styles/books.xsl top-author=Danzig ><i>output.html</i><br>

    132. 

  132. </font></strong></code></p>

    133. 

  133. 

    134. 

  134. <p>It is possible (under those operating systems I know of) to write the author's name in quotes if

    135. 

  135. it contains spaces, e.g. top-author="A. A. Milne".

    136. 

  136. 

    137. 

  137. <p>There is another style sheet, books-csv.xsl, which

    138. 

  138. converts the data into a comma-separated-values file.</p>

    139. 

  139. 

    140. 

  140. <p>There is also a Java program ShowBooks.java (in the samples/java directory) to process the books.xml

    141. 

  141.  file without using XSL. 

    142. 

  142. This can be run directly from the command line. It produces on the standard output an

    143. 

  143. HTML page showing the book list.</p>

    144. 

  144. 

    145. 

  145. 

    146. 

  146. <p>To run the application, first make sure the compiled program (ShowBooks.class) is on

    147. 

  147. the classpath, then execute</p>

    148. 

  148. 

    149. 

  149. <p><code><strong><font color="#FF0080">

    150. 

  150. java&nbsp; ShowBooks&nbsp; samples/data/books.xml&nbsp; &gt;test1.html<br>

    151. 

  151. </font></strong></code></p>

    152. 

  152. 

    153. 

  153. <h2><a name="sql">An SQL style sheet</a></h2>

    154. 

  154. 

    155. 

  155. <p>SAXON implements the <i>element extensibility</i> feature of the XSLT standard, allowing

    156. 

  156. you to extend the XSLT language by implementing your own stylesheet elements.

    157. 

  157. A specimen extension has been written to illustrate this feature: it

    158. 

  158. allows you to create stylesheets to load data into a relational database.</p>

    159. 

  159. 

    160. 

  160. <p>To use the SQL extension elements in a stylesheet, you need to define a namespace prefix

    161. 

  161. (for example "sql") in the extension-element-prefixes attribute of the xsl:stylesheet element,

    162. 

  162. and to map this prefix to namespace URI that ends in "/com.icl.saxon.sql.SQLElementFactory".</p>

    163. 

  163. 

    164. 

  164. <p>This extension defines four new stylesheet elements: <b>sql:connect</b>, <b>sql:insert</b>, 

    165. 

  165. <b>sql:column</b>, and <b>sql:close</b>: <ul>

    166. 

  166. <li>sql:connect creates a database connection. It has attributes "driver", "database", "user", and "password",

    167. 

  167. all of which are attribute value templates (so the values can be passed in as parameters).

    168. 

  168. the driver attribute names the JDBC driver class to be used. The

    169. 

  169. database name must be name that JDBC can associate with an actual database, and in the sample

    170. 

  170. stylesheet this database must contain a a table "Book" with three character columns,

    171. 

  171. "Title", "Author", and "Category".</li>

    172. 

  172. <li>sql:insert performs an SQL INSERT statement. This causes a row to be added to the table identified

    173. 

  173. by the "table" attribute.

    174. 

  174. <li>sql:column is used as a child element of sql:insert, and identifies the name and value of a column

    175. 

  175. to be included in the INSERT statement. The name of the column is identified by the "name" attribute,

    176. 

  176. the value may be indicated either by evaluating the expression contained in the "select" attribute, or

    177. 

  177. as the expanded contents of the sql:column element. The value is always interpreted as a String.

    178. 

  178. (Remember this is purely a demonstration of extensibility, in a real system there would be a need to

    179. 

  179. cater for SQL columns of other data types).</li>

    180. 

  180. <li>sql:close closes the database connection.</ul>

    181. 

  181. 

    182. 

  182. <p>A specimen stylesheet that uses these XSL extension is <b>books-sql.xsl</b>. This loads the contents

    183. 

  183. of the books.xml file into a database table.<p>

    184. 

  184. 

    185. 

  185. <p>To run this stylesheet you will need to do the following:</p>

    186. 

  186. 

    187. 

  187. <ul>

    188. 

  188. <li>Create a database (e.g. Microsoft Access) containing a table "Book" with three character columns,

    189. 

  189. "Title", "Author", and "Category".</li>

    190. 

  190. <li>Register this database as a JDBC data source. (If you use Microsoft Access, register it as an

    191. 

  191. ODBC data source called, say, Books, and then it will automatically be available under JDBC as

    192. 

  192. "jdbc:odbc:Books".</li>

    193. 

  193. <li>Modify the &lt;sql:connect&gt; element in the stylesheet to specify the correct JDBC connection

    194. 

  194. name for the database, and if necessary to supply a username and password. Alternatively you can

    195. 

  195. supply the driver class, database name, username, and password as parameters on the command line.</li>

    196. 

  196. <li>Execute the stylesheet from the command line, as follows:

    197. 

  197. </ul>

    198. 

  198. 

    199. 

  199. <p><code><strong><font color="#FF0080">

    200. 

  200. java com.icl.saxon.StyleSheet data/books.xml styles/books-sql.xsl <br>

    201. 

  201. </font></strong></code></p>

    202. 

  202. 

    203. 

  203. <p>The database will be populated with data from the books.xml document.</p>

    204. 

  204. <hr>

    205. 

  205. 

    206. 

  206. 

    207. 

  207. 

    208. 

  208. <h2><a name="shakespeare">Shakespeare Example</a></h2>

    209. 

  209. 

    210. 

  210. <p>This example works on an input file

    211. 

  211. containing a Shakespeare play. You can use any of the Shakespeare plays in Jon Bosak's

    212. 

  212. distribution at <a href="http://metalab.unc.edu/bosak/xml/eg/shaks200.zip">

    213. 

  213. http://metalab.unc.edu/bosak/xml/eg/shaks200.zip</a>,

    214. 

  214. but for convenience one of them, <em>Othello</em>, is included in the SAXON distribution

    215. 

  215. (in the samples\data directory).</p>

    216. 

  216. 

    217. 

  217. <h3>Shakespeare stylesheet</h3>

    218. 

  218. 

    219. 

  219. <p>There is an XSL stylesheet, play.xsl, which processes an input play in XML and

    220. 

  220. generates a set of linked HTML files (one for the play and one for each scene) in an

    221. 

  221. output directory. To run this, create a directory (say playhtml) and execute the following

    222. 

  222. from the command line:</p>

    223. 

  223. 

    224. 

  224. <p><strong><font color="#FF0080"><code>

    225. 

  225. cd samples<br>

    226. 

  226. java com.icl.saxon.StyleSheet data/othello.xml styles/play.xsl dir=playhtml</code></font></strong></p>

    227. 

  227. 

    228. 

  228. <p>The last parameter sets the value of the constant <strong>dir</strong> to the value <strong>playhtml</strong>;

    229. 

  229. this constant is referenced from the style sheet when creating output files.</p>

    230. 

  230. 

    231. 

  231. <!--

    232. 

  232. <h4>Shakespeare play splitter</h4>

    233. 

  233. 

    234. 

  234. <p>The Java application <strong>Loadplay.java</strong> splits a large XML document into

    235. 

  235. several smaller linked XML documents.</p>

    236. 

  236. 

    237. 

  237. <p>LoadPlay is a free-standing Java application which you can run from the command line.

    238. 

  238. It takes as input a full Shakespeare play (for example <b>othello.xml</b> which is

    239. 

  239. included in the distribution) and splits it into a number of separate XML files, one for

    240. 

  240. the &quot;front material&quot; of the play, and one for each scene in the play.</p>

    241. 

  241. 

    242. 

  242. <p>To run the program:</p>

    243. 

  243. 

    244. 

  244. <ul>

    245. 

  245.   <li>Ensure it is on your CLASSPATH </li>

    246. 

  246.   <li>Ensure you have installed a SAX parser and registered it in the <code>ParserManager.properties</code>

    247. 

  247.     file </li>

    248. 

  248.   <li>Change directory to the <code>samples/data</code> directory containing the file <code>othello.xml</code>

    249. 

  249.   </li>

    250. 

  250.   <li>Enter the command line:<br>

    251. 

  251.     <font color="#FF0080"><code>java LoadPlay othello</code></font> </li>

    252. 

  252. </ul>

    253. 

  253. 

    254. 

  254. <p>A directory called &quot;othello&quot; is created and the play and scene files are

    255. 

  255. generated within it. The program creates an output directory with the same name (othello)

    256. 

  256. as the input file (othello.xml). The parameter should therefore be the name of the play

    257. 

  257. file without its &quot;.xml&quot; suffix.</p>

    258. 

  258. 

    259. 

  259. <h4>Shakespeare servlets</h4>

    260. 

  260. 

    261. 

  261. <p>There are two programs (ShowPlay and ShowScene) for displaying the generated plays and scenes at a web browser.

    262. 

  262. They are written as Java servlets, and can be run in any web server that supports the

    263. 

  263. servlet interface.</p>

    264. 

  264. 

    265. 

  265. <p>To run them, follow the following steps:</p>

    266. 

  266. 

    267. 

  267. <ol>

    268. 

  268.   <li>Ensure your web server is properly configured to run servlets</li>

    269. 

  269.   <li>Copy the two files <strong>ShowPlay.class</strong> and <strong>ShowScene.class</strong>

    270. 

  270.     into the relevant servlets directory, which depends on which web server you are using. It

    271. 

  271.     may well be a directory called <strong>servlets</strong>.</li>

    272. 

  272.   <li>Create an HTML page which references the <strong>ShowPlay</strong> servlet. It should

    273. 

  273.     contain a hyperlink such as:<br>

    274. 

  274.     <strong><small><font color="#FF0080">&lt;a

    275. 

  275.     href=servlets/ShowPlay?dir=plays&amp;play=othello&gt;Othello, the Moor of Venice&lt;/a&gt;</font></small></strong><br>

    276. 

  276.     Here the <strong>dir</strong> parameter is a directory containing all the Shakespeare

    277. 

  277.     plays, and the <strong>play</strong> parameter is a subdirectory containing the various

    278. 

  278.     XML files constituting the text of <em>Othello</em>, which you prevoiusly created using

    279. 

  279.     the <strong>LoadPlay</strong> program.</li>

    280. 

  280.   <li>Select this HTML page from your browser and click on the link to <em>Othello</em>. You

    281. 

  281.     should be able to view the front page of the play, and browse through its individual

    282. 

  282.     scenes.</li>

    283. 

  283. </ol>

    284. 

  284. 

    285. 

  285. <p>If you have problems getting this to work, and there seem to be no useful diagnostics

    286. 

  286. visible at the web browser, check in the web server log files. Also, try getting any

    287. 

  287. sample servlets supplied with the web server to work first: this will ensure that the

    288. 

  288. environment is OK. The most likely cause of problems is that the code you need (servlets,

    289. 

  289. SAXON, the XML parser) is not all on the class path used by the web server: this is not

    290. 

  290. necessarily the same class path as you use from the command line.<code><br>

    291. 

  291. </code></p>

    292. 

  292. -->

    293. 

  293. <hr>

    294. 

  294. 

    295. 

  295. <h2 align="left"><a name="bible">The Bible</a></h2>

    296. 

  296. 

    297. 

  297. <p align="left">The stylesheet <b>bible.xsl</b> takes as input an XML file containing the text of the Old

    298. 

  298. or New Testament. These files are not included in the SAXON distribution for space

    299. 

  299. reasons, but can be downloaded from

    300. 

  300.  <a href="http://sunsite.unc.edu/pub/sun-info/standards/xml/eg/rel200.zip">

    301. 

  301.  http://sunsite.unc.edu/pub/sun-info/standards/xml/eg/rel200.zip</a>

    302. 

  302. or from various mirror sites. They were prepared by Jon Bosak.</p>

    303. 

  303. 

    304. 

  304. <p align="left">The output of the stylesheet is a set of 292 HTML files in a single

    305. 

  305. directory, which together provide a frames-oriented rendition of the text. 

    306. 

  306. The application also works with the Old Testament text, but not with the other religious

    307. 

  307. texts included in Jon Bosak's distribution.</p>

    308. 

  308. 

    309. 

  309. <p align="left">To run the stylesheet first create an output

    310. 

  310. directory (say htmldir), then execute the following from the command line:</p>

    311. 

  311. 

    312. 

  312. <p align="left"><strong><small><font color="#FF0080">java&nbsp; com.icl.saxon.StyleSheet

    313. 

  313. &nbsp; data\nt.xml&nbsp; styles\bible.xsl&nbsp; dir=htmldir</font></small></strong></p>

    314. 

  314. 

    315. 

  315. <p align="left">The final parameter sets the value of the XSLT parameter &quot;dir&quot; to

    316. 

  316. the value &quot;htmldir&quot;, which is referenced within the stylesheet to select a

    317. 

  317. directory for output files.</p>

    318. 

  318. 

    319. 

  319. <!--<h2><a name="applet">Applet Examples</a></h2>

    320. 

  320. 

    321. 

  321. <p>The directory samples/applet contains two demonstrations showing how to use

    322. 

  322. Saxon from an applet embedded in an HTML page.</p>

    323. 

  323. 

    324. 

  324. <p>The subdirectory /demo contains a demonstration taken straight from the Xalan

    325. 

  325. sample application, showing a window with three frames, containing the source document,

    326. 

  326. stylesheet, and result. Click on "index.html" to open this in the browser, then click on the

    327. 

  327. "Transform" button to run a transformation. Note that the HTML page is written in such

    328. 

  328. a way that expects the saxon.jar file to be located in the place where it will be 

    329. 

  329. unpacked when you unzip the Saxon distribution .zip file; if you move any files, you

    330. 

  330. will need to change the URL.</p>

    331. 

  331. 

    332. 

  332. <p>The subdirectory /family-tree contains a demonstration showing some members of

    333. 

  333. the Kennedy family; open the HTML file to view the data. This demonstration is adapted

    334. 

  334. from the one in my book <i>XSLT Programmer's Reference</i>. It illustrates how repeated

    335. 

  335. transformations using the same source document and the same stylesheet can be used to

    336. 

  336. browse around a data-set, without making repeated visits to the server.</p>

    337. 

  337. 

    338. 

  338. <hr>-->

    339. 

  339. 

    340. 

  340. <h2><a name="jdom">JDOM Example</a></h2>

    341. 

  341. 

    342. 

  342. <p>Saxon includes an adapter that allows the source tree to be a JDOM document.</p>

    343. 

  343. 

    344. 

  344. <p>To use this facility:</p>

    345. 

  345. 

    346. 

  346. <ul>

    347. 

  347. <li>The JAR file saxon-jdom.jar must be on the classpath</li>

    348. 

  348. <li>JDOM 1.0 must be installed and on the classpath</li>

    349. 

  349. </ul>

    350. 

  350. 

    351. 

  351. <p>The sample application JDOMExample.java illustrates how a JDOM tree can be used

    352. 

  352. with Saxon. It combines two scenarios: running XPath expressions directly against a

    353. 

  353. JDOM tree, from the Java application; and invoking a transformation with the JDOM document

    354. 

  354. supplied as the Source object.</p>

    355. 

  355. 

    356. 

  356. <p>The application is designed to take two arguments, the <code>books.xml</code> file

    357. 

  357. in the samples/data directory, and the <code>total.xsl</code> file in the samples/styles

    358. 

  358. directory. The application builds a JDOM tree, modifies it <i>in situ</i> to add extra

    359. 

  359. attributes, and then references these attributes from the stylesheet.</p>

    360. 

  360. 

    361. 

  361. <hr />

    362. 

  362. 

    363. 

  363. <p align="center">Michael H. Kay<br>

    364. 

  364. <a href="http://www.saxonica.com/">Saxonica Limited</a><br>

    365. 

  365. 22 June 2005</p>

    366. 

  366. </body>

    367. 

  367. </html>

    368. 

  368.