Project

Profile

Help

How to connect?
Download (28.4 KB) Statistics
| Branch: | Revision:

he / src / userdoc / samples.xml @ 8ddaa514

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="samples" title="Sample Saxon Applications">
3
    <h1>Sample Saxon Applications</h1>
4

    
5
    <p>Saxonica provides an additional resources download which contains various sample XML
6
        resources, and several sample applications. The download file is named
7
            <code>saxon-resources-10.zip</code>, and is separate from the software download. It is
8
        available from <a href="http://www.saxonica.com/download/download_page.xml" class="bodylink"
9
            >Saxonica Downloads</a> or <a href="https://sourceforge.net/projects/saxon/files/"
10
            class="bodylink">SourceForge</a> (under the Saxon-HE project). Unzip the contents of
11
        this file into the same directory as the Saxon software. The sample applications are found
12
        in the directory <code>/samples</code>.</p>
13

    
14
    <p>The <code>saxon-resources</code> download contains various example XML files, stylesheets,
15
        queries, and schemas - in particular for the <a class="bodylink" href="books">Book List</a>,
16
            <a class="bodylink" href="tour">Knight's Tour</a>, <a class="bodylink"
17
            href="shakespeare">Shakespeare</a>, and <a class="bodylink" href="bible">Bible</a>
18
        examples. Also provided are a number of sample Java and .NET programs which demonstrate ways
19
        of using the Saxon APIs (see the <code>samples/java</code> and <code>samples/cs</code>
20
        directories). Many of the examples in the sample programs use the XML resources as sample
21
        data.</p>
22

    
23
    <p>The use of some of these sample applications is described in this section of the
24
        documentation:</p>
25
    <ul>
26
        <li>
27
            <a class="bodylink" href="shakespeare">Shakespeare XPath Sample Application</a>
28
        </li>
29
        <li>
30
            <a class="bodylink" href="s9api">S9API Examples</a>
31
        </li>
32
        <li>
33
            <a class="bodylink" href="jaxp">JAXP Transformation Examples</a>
34
        </li>
35
        <li>
36
            <a class="bodylink" href="jdom2">JDOM2 Example</a>
37
        </li>
38
        <li>
39
            <a class="bodylink" href="dotnetsamples">Example applications for .NET</a>
40
        </li>
41
        <li>
42
            <a class="bodylink" href="servlet">Saxon Servlet</a>
43
        </li>
44
    </ul>
45

    
46
    <p>Information about some of the other sample applications is documented elsewhere: </p>
47
    <ul>
48
        <li>see <a class="bodylink" href="/xpath-api/jaxp-xpath">JAXP XPath API</a> for details on
49
            the <code>ApplyXPathJAXP.java</code> sample (enhanced version of JAXP 1.3 sample)</li>
50
        <li>see <a class="bodylink" href="/using-xquery/api-query/xqj">Invoking XQuery using the XQJ
51
                API</a> for information on the <code>XQJExamples.java</code> sample</li>
52
        <li>see <a class="bodylink" href="/schema-processing/validation-api/schema-jaxp">Schema
53
                Processing using JAXP</a> for information on the <code>QuickValidator.java</code>,
54
                <code>SchemaValidatorExample.java</code>, and
55
                <code>SchemaValidatorHandlerExample.java</code> samples which demonstrate the use of
56
            JAXP validation APIs</li>
57
    </ul>
58

    
59
    <aside>Note: the example Java commands in this section are for the UNIX platform. Windows users
60
        may need to adapt the commands to use "\" instead of "/" in path names (this affects the
61
        command line only: the Java code itself should work on any platform). </aside>
62

    
63

    
64
    <section id="books" title="Book List Example">
65
        <h1>Book List Example</h1>
66

    
67
        <p>The XML file <code>books.xml</code> (derived from a file issued originally by Microsoft)
68
            is used for a number of demonstrations. This file, along with its DTD
69
                <code>books.dtd</code>, is found in the <code>samples/data</code> directory. </p>
70

    
71
        <h2 class="subtitle">Transform</h2>
72

    
73
        <p>The stylesheet <code>books.xsl</code> can be used to display the data, and is designed to
74
            illustrate several Saxon extensions. Run this as follows, with the samples directory as
75
            the current directory:</p>
76

    
77
        <p>
78
            <i>On the Java platform:</i>
79
        </p>
80
        <kbd> java net.sf.saxon.Transform -s:data/books.xml -xsl:styles/books.xsl
81
                -o:<i>output.html</i>
82
        </kbd>
83

    
84
        <p>
85
            <i>On the .NET platform:</i>
86
        </p>
87
        <kbd> Transform -s:data/books.xml -xsl:styles/books.xsl -o:<i>output.html</i>
88
        </kbd>
89

    
90
        <p>This produces an HTML page showing the data.</p>
91

    
92
        <p>The stylesheet takes a parameter named "top-author". This is the name of the "author of
93
            the week", and the default value is "Jasper Fforde". To run the stylesheet with a
94
            different top author, try adding to the end of the command line:</p>
95
        <kbd> ..... top-author='Thomas Hardy' </kbd>
96

    
97
        <h2 class="subtitle">Query</h2>
98

    
99
        <p>A query that runs with this data is also supplied. The command to use on the Java
100
            platform is:</p>
101
        <kbd> java net.sf.saxon.Query -s:data/books.xml -q:query/books.xq -o:<i>output.html</i>
102
        </kbd>
103

    
104
        <p>The equivalent on .NET is:</p>
105
        <kbd> Query -s:data/books.xml -q:query/books.xq -o:<i>output.html</i>
106
        </kbd>
107

    
108
        <h2 class="subtitle">Other demonstrations</h2>
109

    
110
        <p>Several other related XML resources are supplied. The schema for
111
                <code>data/books.xml</code> is <code>data/books.xsd</code>. Also supplied in the
112
            samples resources is the file <code>data/books-invalid.xml</code>, which (as the name
113
            suggests) is a version of the books file which is invalid against the schema, and
114
                <code>data/more-books.xml</code> which lists some different books. These resources
115
            may be used for instance with the sample applications <code>QuickValidator.java</code>,
116
                <code>SchemaValidatorExample.java</code>, and
117
                <code>SchemaValidatorHandlerExample.java</code>.</p>
118

    
119
        <p>There is another stylesheet, <code>styles/books-csv.xsl</code>, which converts the data
120
            in the file <code>data/books.xml</code> into a comma-separated-values file.</p>
121

    
122
        <p>The stylesheet <code>styles/total.xsl</code> is used by the <a class="bodylink"
123
                href="/samples/jdom2">JDOM2 Example</a> application, and the query
124
                <code>query/books-to-html.xq</code> is used by one of the examples in the
125
                <code>QueryAPIExamples.java</code> application.</p>
126

    
127
        <p>The sample program <code>XPathExampleSA.java</code> illustrates the use of the JAXP XPath
128
            API, extended by Saxon to allow schema-aware XPath 2.0 processing. The program is
129
            designed to run against the sample file <code>books.xml</code>. It produces a list of
130
            all books over 2cm thick that were published during the 6 years since the start of
131
            2000.</p>
132

    
133
        <p>Also see the <a class="bodylink" href="/sql-extension/instructions/example">SQL extension
134
                instructions example</a> for details on the sample stylesheet
135
                <code>styles/books-sql.xsl</code> which uses Saxon SQL extension instructions to
136
            load the contents of <code>books.xml</code> into a database table.</p>
137
    </section>
138

    
139
    <section id="tour" title="Knight's Tour">
140
        <h1>Knight's Tour</h1>
141

    
142
        <p>This program is available in two forms: as an XSLT stylesheet <code>tour.xsl</code> and
143
            as an XQuery <code>tour.xq</code>.</p>
144

    
145
        <p>This is a program whose output is a knight's tour of the chessboard (the knight can start
146
            on any square, and has to visit each square exactly once). The XSLT version was
147
            published as an example stylesheet in my book <i>XSLT 2.0 Programmers Reference</i> (<a
148
                href="http://www.wrox.com/" class="bodylink">Wrox Press</a>) but has been completely
149
            reworked so it now makes extensive use of features in XSLT 2.0, XPath 2.0 and XQuery
150
            (since Saxon 9.6, the query uses XQuery 3.0). It is worth studying the stylesheet and
151
            query as an introduction to the use of the new features in these languages. Comparing
152
            the two versions, it can be seen that they are very similar: the only differences are in
153
            the surface syntax of the two languages.</p>
154

    
155
        <p>The stylesheet can be found in the file <code>samples/styles/tour.xsl</code>, the query
156
            in <code>samples/query/tour.xq</code>. No source document is required.</p>
157

    
158
        <p>You can run this example with Saxon on the Java platform using a command of the form:</p>
159
        <kbd> java net.sf.saxon.Transform -it:main -xsl:samples/styles/tour.xsl -o:tour.html
160
            start=e5 </kbd>
161

    
162
        <p>or</p>
163
        <kbd> java net.sf.saxon.Query -q:samples/query/tour.xq -o:tour.html start=e5 </kbd>
164

    
165
        <p>On the .NET platform, the equivalent commands are:</p>
166
        <kbd> Transform -it:main -xsl:samples/styles/tour.xsl -o:tour.html start=e5 </kbd>
167

    
168
        <p>or</p>
169
        <kbd> Query -q:samples/query/tour.xq -o:tour.html start=e5 </kbd>
170

    
171
        <p>When you display the resulting HTML file in your browser it should look something like
172
            this:</p>
173
        <div align="center">
174

    
175
            <p>
176
                <b>
177
                    <big>Knight's tour starting at e5</big>
178
                </b>
179
            </p>
180
            <table border="1" cellpadding="4" size="64">
181
                <tr>
182
                    <td align="center" bgcolor="white">6</td>
183
                    <td align="center" bgcolor="xffff44">3</td>
184
                    <td align="center" bgcolor="white">8</td>
185
                    <td align="center" bgcolor="xffff44">21</td>
186
                    <td align="center" bgcolor="white">42</td>
187
                    <td align="center" bgcolor="xffff44">51</td>
188
                    <td align="center" bgcolor="white">18</td>
189
                    <td align="center" bgcolor="xffff44">39</td>
190
                </tr>
191
                <tr>
192
                    <td align="center" bgcolor="xffff44">9</td>
193
                    <td align="center" bgcolor="white">22</td>
194
                    <td align="center" bgcolor="xffff44">5</td>
195
                    <td align="center" bgcolor="white">2</td>
196
                    <td align="center" bgcolor="xffff44">19</td>
197
                    <td align="center" bgcolor="white">40</td>
198
                    <td align="center" bgcolor="xffff44">43</td>
199
                    <td align="center" bgcolor="white">50</td>
200
                </tr>
201
                <tr>
202
                    <td align="center" bgcolor="white">4</td>
203
                    <td align="center" bgcolor="xffff44">7</td>
204
                    <td align="center" bgcolor="white">20</td>
205
                    <td align="center" bgcolor="xffff44">41</td>
206
                    <td align="center" bgcolor="white">52</td>
207
                    <td align="center" bgcolor="xffff44">49</td>
208
                    <td align="center" bgcolor="white">38</td>
209
                    <td align="center" bgcolor="xffff44">17</td>
210
                </tr>
211
                <tr>
212
                    <td align="center" bgcolor="xffff44">23</td>
213
                    <td align="center" bgcolor="white">10</td>
214
                    <td align="center" bgcolor="xffff44">27</td>
215
                    <td align="center" bgcolor="white">48</td>
216
                    <td align="center" bgcolor="xffff44">1</td>
217
                    <td align="center" bgcolor="white">44</td>
218
                    <td align="center" bgcolor="xffff44">55</td>
219
                    <td align="center" bgcolor="white">60</td>
220
                </tr>
221
                <tr>
222
                    <td align="center" bgcolor="white">26</td>
223
                    <td align="center" bgcolor="xffff44">31</td>
224
                    <td align="center" bgcolor="white">24</td>
225
                    <td align="center" bgcolor="xffff44">53</td>
226
                    <td align="center" bgcolor="white">56</td>
227
                    <td align="center" bgcolor="xffff44">61</td>
228
                    <td align="center" bgcolor="white">16</td>
229
                    <td align="center" bgcolor="xffff44">37</td>
230
                </tr>
231
                <tr>
232
                    <td align="center" bgcolor="xffff44">11</td>
233
                    <td align="center" bgcolor="white">28</td>
234
                    <td align="center" bgcolor="xffff44">47</td>
235
                    <td align="center" bgcolor="white">34</td>
236
                    <td align="center" bgcolor="xffff44">45</td>
237
                    <td align="center" bgcolor="white">54</td>
238
                    <td align="center" bgcolor="xffff44">59</td>
239
                    <td align="center" bgcolor="white">64</td>
240
                </tr>
241
                <tr>
242
                    <td align="center" bgcolor="white">32</td>
243
                    <td align="center" bgcolor="xffff44">25</td>
244
                    <td align="center" bgcolor="white">30</td>
245
                    <td align="center" bgcolor="xffff44">13</td>
246
                    <td align="center" bgcolor="white">62</td>
247
                    <td align="center" bgcolor="xffff44">57</td>
248
                    <td align="center" bgcolor="white">36</td>
249
                    <td align="center" bgcolor="xffff44">15</td>
250
                </tr>
251
                <tr>
252
                    <td align="center" bgcolor="xffff44">29</td>
253
                    <td align="center" bgcolor="white">12</td>
254
                    <td align="center" bgcolor="xffff44">33</td>
255
                    <td align="center" bgcolor="white">46</td>
256
                    <td align="center" bgcolor="xffff44">35</td>
257
                    <td align="center" bgcolor="white">14</td>
258
                    <td align="center" bgcolor="xffff44">63</td>
259
                    <td align="center" bgcolor="white">58</td>
260
                </tr>
261
            </table>
262
        </div>
263
    </section>
264

    
265
    <section id="shakespeare" title="Shakespeare Example">
266
        <h1>Shakespeare Example</h1>
267

    
268
        <p>This example works on an input file containing a Shakespeare play. You can use any of the
269
            Shakespeare plays in Jon Bosak's distribution at <a
270
                href="http://www.ibiblio.org/bosak/xml/eg/shaks200.zip" class="bodylink"
271
                >http://www.ibiblio.org/bosak/xml/eg/shaks200.zip</a>, but for convenience one of
272
            them, <i>Othello</i>, is included in the <code>saxon-resources</code> download (in the
273
                <code>samples/data</code> directory).</p>
274

    
275
        <h2 class="subtitle">Shakespeare stylesheet</h2>
276

    
277
        <p>There is an XSLT stylesheet <code>play.xsl</code> which processes an input play in XML
278
            and generates a set of linked HTML files (one for the play and one for each scene) in an
279
            output directory. To run this on the Java platform, create a directory (say
280
                <code>playhtml</code>) and execute the following from the command line:</p>
281
        <kbd> cd samples<br/> java net.sf.saxon.Transform -s:data/othello.xml -xsl:styles/play.xsl
282
            dir=playhtml </kbd>
283

    
284
        <p>The equivalent on .NET is:</p>
285
        <kbd> cd samples<br/> Transform -s:data/othello.xml -xsl:styles/play.xsl dir=playhtml </kbd>
286

    
287
        <p>The last parameter sets the value of the constant <code>dir</code> to the value
288
                <code>playhtml</code>; this constant is referenced from the stylesheet when creating
289
            output files.</p>
290

    
291
        <h2 class="subtitle">Shakespeare XPath Sample Application</h2>
292
        
293
        <p>An example application called <code>XPathExample</code> is provided, with versions for
294
            Java and .NET (<code>samples/java/he/XPathExample.java</code> and
295
            <code>samples/cs/XPathExample.cs</code> respectively). This is designed to illustrate
296
            the use of Saxon's implementation of the JAXP 1.3 XPath API from a Java or C#
297
            application. It searches a Shakespeare play for all occurrences of a word entered from
298
            the console, displaying the lines containing that word, and the context where they
299
            appear.</p>
300
        
301
        <p>To run this example, first ensure that it is on your classpath, and find the location of
302
            the <code>othello.xml</code> file in the <code>samples/data</code> directory. Open a
303
            command-line console, and run the Java application using the command:</p>
304
        <kbd> cd samples<br/> java he/XPathExample data/othello.xml </kbd>
305
        
306
        <p>Or equivalently to run the .NET application:</p>
307
        <kbd> cs/bin/XPathExample data/othello.xml </kbd>
308

    
309
        <p>The application prompts for a word. Enter the word (try "castle" or "handkerchief"). The
310
            lines containing the chosen word are displayed on the console. Exit the application by
311
            entering ".".</p>
312

    
313
        <h2 class="subtitle">Other Sample Applications</h2>
314

    
315
        <p>Also see the related sample programs <code>XPathExampleDOM.java</code> - a variant of the
316
            XPathExample application written to use DOM interfaces, and
317
                <code>XPathExampleServlet.java</code> which illustrates the use of the JAXP XPath
318
            API within a Java servlet.</p>
319
    </section>
320

    
321
    <section id="bible" title="The Bible Example">
322
        <h1>The Bible Example</h1>
323

    
324
        <p>The stylesheet <code>styles/bible.xsl</code> takes as input an XML file containing the
325
            text of the Old or New Testament. These files are not included in the <code>saxon-resources</code> download
326
            for space reasons, but can be downloaded from <a
327
                href="http://www.ibiblio.org/bosak/xml/eg/rel200.zip" class="bodylink"
328
                >http://www.ibiblio.org/bosak/xml/eg/rel200.zip</a> or from various mirror sites.
329
            They were prepared by Jon Bosak.</p>
330

    
331
        <p>The output of the stylesheet is a set of 292 HTML files in a single directory, which
332
            together provide a frames-oriented rendition of the text. The application also works
333
            with the Old Testament text, but not with the other religious texts included in Jon
334
            Bosak's distribution.</p>
335

    
336
        <p>To run the stylesheet on the Java platform first create an output directory (say
337
                <code>htmldir</code>), then execute the following from the command line :</p>
338
        <kbd> java  net.sf.saxon.Transform  -s:data/nt.xml  -xsl:styles/bible.xsl  dir=htmldir </kbd>
339

    
340
        <p>The equivalent on .NET is:</p>
341
        <kbd> Transform  -s:data/nt.xml  -xsl:styles/bible.xsl  dir=htmldir </kbd>
342

    
343
        <p>The final parameter sets the value of the XSLT parameter <code>dir</code> to the value
344
                <code>htmldir</code>, which is referenced within the stylesheet to select a
345
            directory for output files.</p>
346
    </section>
347

    
348
    <section id="s9api" title="S9API Examples">
349
        <h1>S9API Examples</h1>
350

    
351
        <p>
352
            <i>This section applies to the Java platform only.</i>
353
        </p>
354

    
355
        <p>Saxon's s9api interface is a custom-designed interface for all XML processing. This API
356
            is useful when you want to write your own Java applications that invoke Saxon XSLT
357
            transforms, XQuery, and evaluate XPath expressions (for more information see <a
358
                class="bodylink" href="/using-xsl/embedding/s9api-transformation">Using s9api for
359
                Transformations</a>, <a class="bodylink" href="/using-xquery/api-query/s9api-query"
360
                >Using s9api for XQuery</a>, and <a class="bodylink" href="/xpath-api/s9api-xpath"
361
                >Evaluating XPath Expressions using s9api</a> respectively).</p>
362

    
363
        <p>A sample program that illustrates many features of the s9api interface is included in the
364
            <code>saxon-resources</code> download as <code>S9APIExamples.java</code>. To run the
365
            program, use the command:</p>
366
        <kbd> cd samples<br/> java he/S9APIExamples </kbd>
367

    
368
        <p>You can supply an argument to indicate which of the examples you want to run; see the
369
            source code for details. By default, they are all executed in turn.</p>
370
        
371
        <p>The additional sample program <code>S9APIExamplesOM.java</code> contains examples
372
            demonstrating XPath expressions evaluated against source documents supplied using
373
            different third-party object models: JDOM2, XOM, and DOM4J. To run the program, the
374
            classpath must include these third-party JAR files as well as Saxon. See <a
375
                class="bodylink" href="/about/installationjava/jarfiles">JAR files</a> for more
376
            information about running applications and the classpath, and <a class="bodylink"
377
                href="/sourcedocs/thirdparty">Third-party Object Models</a> for more information on
378
            the object models.</p>
379
    </section>
380

    
381
    <section id="jaxp" title="JAXP Transformation Examples">
382
        <h1>JAXP Transformation Examples</h1>
383

    
384
        <p>
385
            <i>This section applies to the Java platform only.</i>
386
        </p>
387

    
388
        <p>As an alternative to the s9api interface, Saxon supports the Java JAXP Transformation API
389
            (package javax.xml.transform), originally known as TrAX, for invoking the XSLT
390
            stylesheet processor (see <a class="bodylink"
391
                href="/using-xsl/embedding/jaxp-transformation">Using JAXP for Transformations</a>).
392
            This API is useful when you want to write your own Java applications that invoke Saxon
393
            XSLT transformations.</p>
394

    
395
        <p>A sample program that illustrates many features of the JAXP Transformation interface
396
            (including Saxon-specific extensions) is included in the <code>saxon-resources</code> download as
397
                <code>JAXPExamples.java</code>. Source XML and XSLT files for use with this program
398
            are included in the <code>data</code> and <code>style</code> directories. To run the
399
            program, use the command:</p>
400
        <kbd> cd samples<br/> java he/JAXPExamples </kbd>
401

    
402
        <p>You can supply an argument to indicate which of the examples you want to run; see the
403
            source code for details. By default, they are all executed in turn.</p>
404
    </section>
405

    
406
    <section id="jdom2" title="JDOM2 Example">
407
        <h1>JDOM2 Example</h1>
408

    
409
        <p>
410
            <i>This section applies to the Java platform only. Requires Saxon-PE or Saxon-EE</i>
411
        </p>
412

    
413
        <p>Saxon includes an adapter that allows the source tree to be a JDOM2 document. The sample
414
            application <code>JDOM2Example.java</code> illustrates how a JDOM2 tree can be used with
415
            Saxon. It combines two scenarios: running XPath expressions directly against a JDOM2
416
            tree, from the Java application; and invoking a transformation with the JDOM2 document
417
            supplied as the source object.</p>
418

    
419
        <p>The application is designed to take two arguments, the <code>books.xml</code> file in the
420
                <code>samples/data</code> directory, and the <code>total.xsl</code> file in the
421
                <code>samples/styles</code> directory. The application builds a JDOM2 tree, modifies
422
            it <i>in situ</i> to add extra attributes, and then references these attributes from the
423
            stylesheet.</p>
424
    </section>
425

    
426
    <section id="dotnetsamples" title="Example applications for .NET">
427
        <h1>Example applications for .NET</h1>
428

    
429
        <p>The <code>samples/cs</code> directory contains some sample applications written in C#,
430
            designed to illustrate use of the Saxon API available in the <code>Saxon.Api</code>
431
            namespace. In particular there are three programs <code>ExamplesHE.cs</code>,
432
                <code>ExamplesPE.cs</code>, and <code>ExamplesEE.cs</code> relevant to Saxon-HE,
433
            Saxon-PE, and Saxon-EE respectively; each shows various ways of invoking XSLT, XQuery,
434
            XPath, and schema validation where appropriate. The idea is that you should be able to
435
            cut and paste a suitable fragment of code into your own application as a quick way of
436
            getting started.</p>
437

    
438
        <p>The main value of these samples is in reading the source code rather than in actually
439
            running them; however, running them is also a good check that your installation has been
440
            set up correctly. A quick look at the comments in the source should enable you to see
441
            how they are executed. Note that they all require the environment variable
442
                <code>SAXON_HOME</code> to be set to the directory where Saxon is installed: this is
443
            used to find the sample data files.</p>
444
        
445
        <p>The example applications can be run from the command line (executables are found in the
446
            <code>samples/cs/bin</code> directory). They take the following arguments:</p>
447

    
448
        <ul>
449
            <li>
450
                <p><strong>-dir:<i>samples</i></strong> - provides the name of the samples directory
451
                    from the <code>saxon-resources</code> download. The default uses the SAXON_HOME environment
452
                    variable - but it's normally best to supply this parameter explicitly.</p>
453
            </li>
454
            <li>
455
                <p><strong>-ask:<i>yes|no</i></strong> - with ask:yes (the default), the application
456
                    prompts after each test to ask if you want to continue.</p>
457
            </li>
458
            <li>
459
                <p><strong>-test:<i>testname</i></strong> - supplies the name of the test you want
460
                    to run, or "all" (the default) to indicate all tests.</p>
461
            </li>
462
        </ul>
463
        
464
        <p>Also in the same directory is an application <code>TestRunner</code> which is a
465
            test harness for running the XSLT, XQuery, and XSD test suites published by W3C (in the
466
            case of XSLT, the test data is available to W3C members only); and an application
467
            <code>XPathExample</code> which illustrates the use of Saxon's JAXP XPath API from C#
468
            (see <a class="bodylink" href="../shakespeare">Shakespeare Example</a> for more
469
            information).</p>
470
    </section>
471

    
472
    <section id="servlet" title="Saxon Servlet">
473
        <h1>Saxon Servlet</h1>
474

    
475
        <p>
476
            <i>This section applies to the Java platform only.</i>
477
        </p>
478

    
479
        <p>The sample application <code>SaxonServlet.java</code> is a general-purpose servlet that
480
            takes the name of a source document and XSLT stylesheet as URL parameters, and uses the
481
            stylesheet to process the source document, creating a result document which is sent back
482
            to the browser for display. The result document may have any media type, though HTML and
483
            XML are the most likely.</p>
484

    
485
        <p>The servlet maintains a cache of prepared stylesheets; if the same stylesheet is used
486
            repeatedly, it is only parsed and validated once, which will often greatly improve
487
            performance. Prepared style sheets are thread-safe so they can be used to serve
488
            documents to several users concurrently.</p>
489

    
490
        <p>The URLs for the source document and the stylesheet document are supplied in the URL,
491
            which will typically take the form:</p>
492
        <kbd> http://server.com/servlets/SaxonServlet?source=doc.xml&amp;style=sheet.xsl </kbd>
493

    
494
        <p>
495
            <i>Note: Internet Explorer assumes that if the URL ends with ".xml" or ".xsl", as in the
496
                above example, then the returned file will be XML - even if the media type in the
497
                HTTP header is set to "text/html". You can prevent this behaviour by adding an extra
498
                dummy parameter, for example "&amp;x=y".</i>
499
        </p>
500

    
501
        <p>The source and style parameters identify the source document and stylesheet by URL. These
502
            are interpreted relative to the servlet context. This means that specifying say
503
            "style=/styles/styleone.xsl" in the URL will locate the stylesheet in this file relative
504
            to the root directory for the web server.</p>
505

    
506
        <p>The stylesheet is prepared the first time it is used, and held in memory in a cache. The
507
            cache may be cleared (for example, if a stylesheet has been changed) using a URL such
508
            as:</p>
509
        <kbd> http://server.com/servlets/SaxonServlet?clear-stylesheet-cache=yes </kbd>
510

    
511
        <p>This code is provided purely as a sample, in the expectation that you will customise it
512
            to your particular site requirements.</p>
513

    
514
        <p>Also see <code>SaxonSAServlet.java</code> for a schema-aware version of this servlet, and
515
                <code>XPathExampleServlet.java</code> which illustrates the use of the JAXP XPath
516
            API within a Java servlet.</p>
517
    </section>
518
</article>
(16-16/21)