dleslie 02/01/30 06:23:52
Modified: java/xdocs/sources xalan-jlocal.xml xalan-jsite.xml
java/xdocs/sources/xalan commandline.xml extensionslib.xml
faq.xml usagepatterns.xml
Added: java/xdocs/sources/xalan features.xml
Log:
1. Added features.xml.
2. Updated faq on StackOverflow with recursion.
3. Added NodeInfo extension functions to extensionslib.xml
Revision Changes Path
1.20 +1 -0 xml-xalan/java/xdocs/sources/xalan-jlocal.xml
Index: xalan-jlocal.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan-jlocal.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- xalan-jlocal.xml 17 Jan 2002 20:07:30 -0000 1.19
+++ xalan-jlocal.xml 30 Jan 2002 14:23:52 -0000 1.20
@@ -73,6 +73,7 @@
<document id="commandline" label="Command Line"
source="xalan/commandline.xml"/>
<separator/>
<document id="usagepatterns" label="Usage Patterns"
source="xalan/usagepatterns.xml"/>
+ <hidden id="features" source="xalan/features.xml"/>
<separator/>
<document id="trax" label="TrAX" source="xalan/trax.xml"/>
<external href="apidocs/index.html" label="API (Javadoc)"/>
1.38 +1 -0 xml-xalan/java/xdocs/sources/xalan-jsite.xml
Index: xalan-jsite.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan-jsite.xml,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -r1.37 -r1.38
--- xalan-jsite.xml 25 Jan 2002 21:21:11 -0000 1.37
+++ xalan-jsite.xml 30 Jan 2002 14:23:52 -0000 1.38
@@ -76,6 +76,7 @@
<document id="commandline" label="Command Line"
source="xalan/commandline.xml"/>
<separator/>
<document id="usagepatterns" label="Usage Patterns"
source="xalan/usagepatterns.xml"/>
+ <hidden id="features" source="xalan/features.xml"/>
<separator/>
<document id="trax" label="TrAX" source="xalan/trax.xml"/>
<external href="apidocs/index.html" label="API (Javadoc)"/>
1.18 +1 -1 xml-xalan/java/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/commandline.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- commandline.xml 25 Jan 2002 22:22:53 -0000 1.17
+++ commandline.xml 30 Jan 2002 14:23:52 -0000 1.18
@@ -85,7 +85,7 @@
-V (Version info)
-QC (Quiet Pattern Conflicts Warnings)
--L (Use line numbers for source document)
+-L (Report line numbers for problems with source document)
-TT (Trace the templates as they are being called)
-TG (Trace each result tree generation event)
-TS (Trace each selection event)
1.20 +24 -0 xml-xalan/java/xdocs/sources/xalan/extensionslib.xml
Index: extensionslib.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/extensionslib.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- extensionslib.xml 27 Sep 2001 18:57:15 -0000 1.19
+++ extensionslib.xml 30 Jan 2002 14:23:52 -0000 1.20
@@ -66,6 +66,10 @@
<li><link anchor="difference">difference</link></li>
<li><link anchor="distinct">distinct</link></li>
<li><link anchor="hassamenodes">hasSameNodes</link></li>
+<li><link anchor="systemid">systemId</link></li>
+<li><link anchor="publicid">publicId</link></li>
+<li><link anchor="linenumber">lineNumber</link></li>
+<li><link anchor="columnnumber">columnNumber</link></li>
<li><link anchor="sql">SQL library</link></li>
<li><link anchor="pipedocument">PipeDocument</link></li>
<li><link anchor="evaluate">evaluate</link></li>
@@ -213,6 +217,26 @@
<s2 title= "hasSameNodes">
<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/Extensions.html">org.apache.xalan.lib.Extensions</jump>,<br/>
<code>hasSameNodes(node-set1, node-set2)</code> returns true if both
node-set1 and node-set2 contain exactly the same set of nodes.</p>
+</s2><anchor name="systemid"/><anchor name="nodeinfo"/>
+<s2 title="systemId">
+<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
+<code>systemId()</code> returns the system ID for the current node, and <br/>
+<code>systemId(node-set)</code> returns the system ID of the first node in
the node-set.</p>
+</s2><anchor name="publicid"/>
+<s2 title="publicId">
+<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
+<code>publicId()</code> returns the public ID for the current node, and<br/>
+<code>publicId(node-set)</code> returns the public ID of the first node in
the node-set.</p>
+</s2><anchor name="linenumber"/>
+<s2 title="lineNumber">
+<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
+<code>lineNumber()</code> returns the line number in the source document for
the current node, and<br/>
+<code>lineNumber(node-set)</code> returns the line number in the source
document for the first node in the node-set.</p>
+</s2><anchor name="columnnumber"/>
+<s2 title="columnNumber">
+<p>Implemented in <jump
href="apidocs/org/apache/xalan/lib/NodeInfo.html">org.apache.xalan.lib.NodeInfo</jump>,<br/>
+<code>columnNumber()</code> returns the column number in the source document
for the current node, and<br/>
+<code>columnNumber(node-set)</code> returns the column number in the source
document for the first node in the node-set.</p>
</s2><anchor name="sql"/>
<s2 title= "SQL library">
<note>For UML Diagrams of the SQL Library, see <jump
href="http://xml.apache.org/xalan-j/Xalan-SQL-Extension/DiagramIndex.html";>SQL
Library UML Diagrams</jump>.</note>
1.17 +9 -0 xml-xalan/java/xdocs/sources/xalan/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/faq.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- faq.xml 22 Jan 2002 17:25:36 -0000 1.16
+++ faq.xml 30 Jan 2002 14:23:52 -0000 1.17
@@ -287,6 +287,15 @@
<br/><br/>
A JAXP 1.1 TransformerException often wraps another exception. Two of the
TransformerException structures that are frequently used to construct contained
exceptions in JAXP 1.1 do not set the locator. The locator is not set because
we don't know the type of exception that the Throwable argument represents.
The solution is to chase up the contained exceptions to find the root cause,
which will usually have a location set for you. This can be somewhat tricky,
as not all the exceptions may be TransformerExceptions. A good sample is in
the DefaultHandler static printLocation() method, which the Xalan command-line
processor uses to report errors. You can also roll your own functions along the
lines of the getRootSourceLocator() example above.</note>
</a>
+</faq>
+<faq title="StackOverflowError with recursive stylesheet">
+<q>Xalan dies with a java.lang.StackOverflowError when I run a deeply
recursive stylesheet. The same stylesheet worked fine in the past (or on other
machines). What's happening?</q>
+<a>
+<p>That may not be our fault. As of JDK 1.3.x, many Java Virtual Machine
publishers reduced the default size of a thread's call stack from 1MB to 256MB.
This allows more threads to run simultaneously, but it means that each thread
is more limited in how deeply its function calls can be nested. </p>
+<p>Some JVMs may offer an option that allows you to raise this limit. For
example, in Sun JDK 1.3.1 you can start JVM with the -Xss1m option to allow
each thread to use a full megabyte. Other JVMs may set this in other ways, or
may not allow you to control it at all; check the documentation on your system
for details.</p>
+
+<p>Note too that on some platforms 1MB is an architectural upper limit on
the stack size, so setting -Xss2m (or equivalent) may not allow deeper recusion
than -Xss1m.</p>
+</a>
</faq>
</faqs>
1.48 +1 -0 xml-xalan/java/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/usagepatterns.xml,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- usagepatterns.xml 25 Jan 2002 22:22:53 -0000 1.47
+++ usagepatterns.xml 30 Jan 2002 14:23:52 -0000 1.48
@@ -76,6 +76,7 @@
<li><link anchor="multithreading">Multithreading</link></li>
<li><link anchor="debugging">Debugger interface</link></li>
</ul>
+<p>See also: <link idref="features">Tranformer Features</link>.</p>
<anchor name="basic"/>
<s2 title="Basic steps">
<ol>
1.1 xml-xalan/java/xdocs/sources/xalan/features.xml
Index: features.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<s1 title="Transform Features">
<p>Transform features include standard JAXP 1.1 behaviors that your
implementation may support (&xslt4j; supports all such behaviors), general
session-level &xslt4j;-defined behaviors that you can set, and &xslt4j;-defined
behaviors that you can set for an individual transformation. Transform features
are identified by URI Strings and fall into the following categories:</p>
<ul>
<li><link anchor="factoryfeature">Standard TransformationFactory
features</link></li>
<li><link anchor="factoryattribute">&xslt4j; TransformerFactory
attributes</link></li>
<li><link anchor="transformerproperty">&xslt4j; Transformer
properties</link></li>
</ul>
<anchor name="factoryfeature"/>
<s2 title="Standard TransformerFactory features">
<p>The JAXP 1.1 Transformation API for XML (<link idref="trax">TrAX</link>)
defines objects and methods for processing input and producing output in a
variety of formats, including character streams, SAX event streams, and DOM
Documents.</p>
<p>JAXP 1.1 defines the following feature URIs:</p>
<ul>
<li><link
anchor="streamsource">"http://xml.apache.org.stream.StreamSource/feature";</link></li>
<li><link
anchor="streamresult">"http://xml.apache.org.stream.StreamResult/feature";</link></li>
<li><link
anchor="domsource">"http://xml.apache.org.dom.DOMSource/feature";</link></li>
<li><link
anchor="domresult">"http://xml.apache.org.dom.DOMResult/feature";</link></li>
<li><link
anchor="saxsource">"http://xml.apache.org.dom.SAXSource/feature";</link></li>
<li><link
anchor="saxresult">"http://xml.apache.org.dom.SAXResult/feature";</link></li>
<li><link
anchor="saxtransformerfactory">"http://xml.apache.org.sax.SAXTransformerFactory/feature";</link></li>
<li><link
anchor="xmlfilter">"http://xml.apache.org.sax.SAXTransformerFactory/feature/xmlfilter";</link></li>
</ul>
<p>You can use the
<jump
href="apidocs/javax/xml/transform/TransformerFactory.html#getFeature(java.lang.String)">TransformerFactory.getFeature(String)</jump>
method to return a boolean indicating whether the implementation you are
using supports the use of one of these objects or methods. For the String
argument, provide the static String variable or literal URI String as detailed
below.</p>
<p>&xslt4j; supports <em>all</em> TransformerFactory features.</p>
<anchor name="streamsource"/>
<s3 title='"http://xml.apache.org.stream.StreamSource/feature";'>
<p>The implementation supports the processing of <jump
href="apidocs/javax/xml/transform/stream/StreamSource.html">StreamSource</jump>
input objects.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static StreamSource.FEATURE variable (equivalent to the
URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.stream.StreamSource;
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(StreamSource.FEATURE)){
// Can process a StreamSource.
..
}</source>
</s3><anchor name="streamresult"/>
<s3 title='"http://xml.apache.org.stream.StreamResult/feature";'>
<p>The implementation supports the production of transformation output in the
form of <jump
href="apidocs/javax/xml/transform/stream/StreamResult.html">StreamResult</jump>
objects.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static StreamResult.FEATURE variable (equivalent to the
URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.stream.StreamSource;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(StreamResult.FEATURE)){
// Can generate a StreamResult.
..
}</source>
</s3><anchor name="domsource"/>
<s3 title='"http://xml.apache.org.dom.DOMSource/feature";'>
<p>The implementation supports the processing of XML input in the form of
<jump href="apidocs/javax/xml/transform/dom/DOMSource.html">DOMSource</jump>
objects.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static DOMSource.FEATURE string variable (equivalent to
the URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.dom.DOMSource;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(DOMSource.FEATURE)){
// Can process DOM input
..
}</source>
</s3><anchor name="domresult"/>
<s3 title='"http://xml.apache.org.dom.DOMResult/feature";'>
<p>The implementation supports the production of transformation output in the
form of <jump
href="apidocs/javax/xml/transform/dom/DOMResult.html">DOMResult</jump>
objects.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static DOMResult.FEATURE variable (equivalent to the
URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.dom.DOMResult;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(DOMResult.FEATURE)){
// Can generate DOM output.
..
}</source>
</s3><anchor name="saxsource"/>
<s3 title='"http://xml.apache.org.dom.SAXSource/feature";'>
<p>The implementation supports the processing of XML input in the form of
<jump href="apidocs/javax/xml/transform/sax/SAXSource.html">SAXSource</jump>
objects.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static SAXSource.FEATURE string variable (equivalent to
the URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.sax.SAXSource;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(SAXSource.FEATURE)){
// Can process SAX events.
..
}</source>
</s3><anchor name="saxresult"/>
<s3 title='"http://xml.apache.org.dom.SAXResult/feature";'>
<p>The implementation supports the production of transformation output in the
form of <jump
href="apidocs/javax/xml/transform/sax/SAXResult.html">SAXResult</jump>
objects.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static SAXResult.FEATURE variable (equivalent to the
URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.sax.SAXResult;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(SAXResult.FEATURE)){
// Can output SAX events.
..
}</source>
</s3><anchor name="saxtransformerfactory"/>
<s3 title='"http://xml.apache.org.sax.SAXTransformerFactory/feature";'>
<p>The implementation provides a <jump
href="apidocs/javax/xml/transform/sax/SAXTransformerFactory.html">SAXTransformerFactory</jump>.
You may safely cast
the TransformerFactory returned by TransformerFactory.newInstance() to a
SAXTransformerFactory.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static SAXTransformerFactory.FEATURE variable
(equivalent to the URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.sax.SAXTransformerFactory;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(SAXTransformerFactory.FEATURE)){
SAXTransformerFactory saxTFact = (SAXTransformerFactory)tFact;
..
}</source>
</s3><anchor name="xmlfilter"/>
<s3
title='"http://xml.apache.org.sax.SAXTransformerFactory/feature/xmlfilter";'>
<p>The implementation supports the use of <jump
href="apidocs/org/xml/sax/XMLFilter.html">XMLFilter</jump> to use the output of
one transformation as input for another transformation. The
SAXTransformerFactory newXMLFilter(Source) and newXMLFilter(Templates) methods
are supported.</p>
<p>To determine whether your implementation supports this feature (&xslt4j;
does), you can use the static SAXTransformerFactory.FEATURE_XMLFilter variable
(equivalent to the URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.sax.SAXTransformerFactory;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact.getFeature(SAXTransformerFactory.FEATURE_XMLFILTER))){
// Can use SAXTransformerFactory to get XMLFilters.
..
}</source>
<p>For an example, see <link idref="samples"
anchor="usexmlfilters">UseXMLFilters</link>.</p>
</s3>
</s2><anchor name="factoryattribute"/>
<s2 title="&xslt4j; TransformerFactory attributes">
<p>A given implementation may provide TransformerFactory attributes that you
can set and get. &xslt4j; uses the <link idref="dtm">
DTM (Document Table Model)</link> to support two such attributes:</p>
<ul>
<li><link
anchor="optimize">"http://apache.org/xalan/features/optimize";</link></li>
<li><link
anchor="incremental">"http://apache.org/xalan/features/incremental";</link></li>
</ul>
<p>To get an attribute setting, use the
TransformerFactory.getAttribute(String) method, which returns an Object that
(for these two &xslt4j; attributes) you can cast to a boolean. To set an
attribute, use the TransformerFactory.setAttribute(String, Object) method. For
the String argument, provide the static String variable or literal URI String
as detailed below. For the Object argument, use Boolean.TRUE or
Boolean.FALSE.</p><anchor name="optimize"/>
<s3 title='"http://apache.org/xalan/features/optimize";'>
<p>Optimize stylesheet processing. By default, this attribute is on. You may
need to turn it off for tooling applications. For more information, see <link
idref="dtm" anchor="incremental">incremental transforms</link>.</p>
<p>To turn optimization off, you can use the
TransformerFactoryImpl.FEATURE_OPTIMIZE static variable (equivalent to the URI
String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import org.apache.xalan.processor.TransformerFactoryImpl;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact instanceof TransformerFactoryImpl) {
tFact.setAttribute(TransformerFactoryImpl.FEATURE_OPTIMIZE,
Boolean.FALSE);
}</source>
</s3><anchor name="incremental"/>
<s3 title='"http://apache.org/xalan/features/incremental";'>
<p>Produce output incrementally, rather than waiting to finish parsing the
input before generating any output. By default this attribute is off. You can
turn this attribute on to transform large documents where the stylesheet
structure is optimized to execute individual templates without having to parse
scattered sections of the document. For more information, see <link idref="dtm"
anchor="optimized">optimized transforms</link>.</p>
<p>To turn incremental transformations on, you can use the
TransformerFactoryImpl.FEATURE_INCREMENTAL static variable (equivalent to the
URI String above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import org.apache.xalan.processor.TransformerFactoryImpl;
..
TransformerFactory tFact = TransformerFactory.newInstance();
if (tFact instanceof TransformerFactoryImpl) {
tFact.setAttribute(TransformerFactoryImpl.FEATURE_INCREMENTAL,
Boolean.FALSE);
}</source>
</s3>
</s2><anchor name="transformerproperty"/>
<s2 title="&xslt4j; Transformer property">
<p>A Transformer implementation may provide runtime properties that you can
set. The JAXP Transformer API provides no method for getting and setting
Transformer properties, so you must use the implementation API. The &xslt4j;
org.apache.xalan.transformer.TransformerImpl supports one such property:</p>
<ul><li><link
anchor="source-location">"http://apache.org/xalan/properties/source-location";</link></li></ul>
<p>You can use the TransformerImpl getProperty(String) and
setProperty(String). The getProperty method returns a boolean. For the String
argument, use the static String variable or literal URI String as indicated
below.</p><anchor name="source-location"/>
<s3 title='"http://apache.org/xalan/properties/source-location";'>
<p>Provide a <jump
href="apidocs/javax/xml/transform/SourceLocator.html">SourceLocator</jump> that
can be used from within a stylesheet, programatically, or in the command-line
utility to obtain the location in a source document (system ID, public ID, line
number, and column number) of individual nodes. By default, this property is
off.</p>
<note>The <link idref="commandline">command-line utility</link> -L flag,
<link idref="usagepatterns" anchor="debugging">PrintTraceListener</link>, and
<link idref="extensionslib" anchor="nodeinfo">NodeInfo</link> extension set
this property to Boolean.TRUE.</note>
<p>To set the SourceLocation property, you can use the
XalanProperties.SOURCE_LOCATION static variable (equivalent to the URI String
above) as follows:</p>
<source>import javax.xml.transform.TransformerFactory;
import javax.xml.transform.Transformer;
import org.apache.xalan.transformer.TransformerImpl;
import org.apache.xalan.transformer.XalanProperties;
..
TransformerFactory tFact = TransformerFactory.newInstance();
Transformer transformer =
tFact.newTransformer(new StreamSource("foo.xsl"));
if (transformer instanceof TransformerImpl) {
TransformerFactoryImpl transImpl =
(TransformerFactoryImpl)transformer;
transImpl.setProperty(XalanProperties.SOURCE_LOCATION,
Boolean.TRUE);
..
}</source>
</s3>
</s2>
</s1>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
