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]
