1 <?xml version="1.0"?> 2 <!-- $Id: package.html 226183 2005-04-08 10:39:14Z neeraj $ --> 3 4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 5 <html xmlns="http://www.w3.org/1999/xhtml"> 6 <head> 7 <title>javax.xml.transform</title> 8 </head> 9 10 <body> 11 <p>This package defines the generic APIs for processing transformation 12 instructions, and performing a transformation from source to result. These 13 interfaces have no dependencies on SAX or the DOM standard, and try to make as 14 few assumptions as possible about the details of the source and result of a 15 transformation. It achieves this by defining 16 {@link javax.xml.transform.Source} and 17 {@link javax.xml.transform.Result} interfaces. 18 </p> 19 20 <p>To define concrete classes for the user, the API defines specializations 21 of the interfaces found at the root level. These interfaces are found in 22 {@link javax.xml.transform.sax}, {@link javax.xml.transform.dom}, 23 and {@link javax.xml.transform.stream}. 24 </p> 25 26 27 <h3>Creating Objects</h3> 28 29 <p>The API allows a concrete 30 {@link javax.xml.transform.TransformerFactory} object to be created from 31 the static function 32 {@link javax.xml.transform.TransformerFactory#newInstance}. 33 </p> 34 35 36 <h3>Specification of Inputs and Outputs</h3> 37 38 <p>This API defines two interface objects called 39 {@link javax.xml.transform.Source} and 40 {@link javax.xml.transform.Result}. In order to pass Source and Result 41 objects to the interfaces, concrete classes must be used. 42 Three concrete representations are defined for each of these 43 objects: 44 {@link javax.xml.transform.stream.StreamSource} and 45 {@link javax.xml.transform.stream.StreamResult}, 46 {@link javax.xml.transform.sax.SAXSource} and 47 {@link javax.xml.transform.sax.SAXResult}, and 48 {@link javax.xml.transform.dom.DOMSource} and 49 {@link javax.xml.transform.dom.DOMResult}. Each of these objects defines 50 a FEATURE string (which is i the form of a URL), which can be passed into 51 {@link javax.xml.transform.TransformerFactory#getFeature} to see if the 52 given type of Source or Result object is supported. For instance, to test if a 53 DOMSource and a StreamResult is supported, you can apply the following 54 test. 55 </p> 56 57 <pre> 58 <code> 59 TransformerFactory tfactory = TransformerFactory.newInstance(); 60 if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) { 61 ... 62 } 63 </code> 64 </pre> 65 66 67 <h3> 68 <a name="qname-delimiter">Qualified Name Representation</a> 69 </h3> 70 71 <p><a href="http://www.w3.org/TR/REC-xml-names">Namespaces</a> 72 present something of a problem area when dealing with XML objects. Qualified 73 Names appear in XML markup as prefixed names. But the prefixes themselves do 74 not hold identity. Rather, it is the URIs that they contextually map to that 75 hold the identity. Therefore, when passing a Qualified Name like "xyz:foo" 76 among Java programs, one must provide a means to map "xyz" to a namespace. 77 </p> 78 79 <p>One solution has been to create a "QName" object that holds the 80 namespace URI, as well as the prefix and local name, but this is not always an 81 optimal solution, as when, for example, you want to use unique strings as keys 82 in a dictionary object. Not having a string representation also makes it 83 difficult to specify a namespaced identity outside the context of an XML 84 document. 85 </p> 86 87 <p>In order to pass namespaced values to transformations, 88 for 89 instance when setting a property or a parameter on a 90 {@link javax.xml.transform.Transformer} object, 91 this specification defines that a 92 String "qname" object parameter be passed as two-part string, the namespace URI 93 enclosed in curly braces ({}), followed by the local name. If the qname has a 94 null URI, then the String object only contains the local name. An application 95 can safely check for a non-null URI by testing to see if the first character of 96 the name is a '{' character. 97 </p> 98 99 <p>For example, if a URI and local name were obtained from an element 100 defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, 101 then the Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo". 102 Note that the prefix is lost. 103 </p> 104 105 106 <h3>Result Tree Serialization</h3> 107 108 <p>Serialization of the result tree to a stream can be controlled with 109 the {@link javax.xml.transform.Transformer#setOutputProperties} and the 110 {@link javax.xml.transform.Transformer#setOutputProperty} methods. 111 These properties only apply to stream results, they have no effect when 112 the result is a DOM tree or SAX event stream.</p> 113 114 <p>Strings that match the <a href="http://www.w3.org/TR/xslt#output">XSLT 115 specification for xsl:output attributes</a> can be referenced from the 116 {@link javax.xml.transform.OutputKeys} class. Other strings can be 117 specified as well. 118 If the transformer does not recognize an output key, a 119 {@link java.lang.IllegalArgumentException} is thrown, unless the 120 key name is <a href="#qname-delimiter">namespace qualified</a>. Output key names 121 that are namespace qualified are always allowed, although they may be 122 ignored by some implementations.</p> 123 124 <p>If all that is desired is the simple identity transformation of a 125 source to a result, then {@link javax.xml.transform.TransformerFactory} 126 provides a 127 {@link javax.xml.transform.TransformerFactory#newTransformer()} method 128 with no arguments. This method creates a Transformer that effectively copies 129 the source to the result. This method may be used to create a DOM from SAX 130 events or to create an XML or HTML stream from a DOM or SAX events. </p> 131 132 <h3>Exceptions and Error Reporting</h3> 133 134 <p>The transformation API throw three types of specialized exceptions. A 135 {@link javax.xml.transform.TransformerFactoryConfigurationError} is parallel to 136 the {@link javax.xml.parsers.FactoryConfigurationError}, and is thrown 137 when a configuration problem with the TransformerFactory exists. This error 138 will typically be thrown when the transformation factory class specified with 139 the "javax.xml.transform.TransformerFactory" system property cannot be found or 140 instantiated.</p> 141 142 <p>A {@link javax.xml.transform.TransformerConfigurationException} 143 may be thrown if for any reason a Transformer can not be created. A 144 TransformerConfigurationException may be thrown if there is a syntax error in 145 the transformation instructions, for example when 146 {@link javax.xml.transform.TransformerFactory#newTransformer} is 147 called.</p> 148 149 <p>{@link javax.xml.transform.TransformerException} is a general 150 exception that occurs during the course of a transformation. A transformer 151 exception may wrap another exception, and if any of the 152 {@link javax.xml.transform.TransformerException#printStackTrace()} 153 methods are called on it, it will produce a list of stack dumps, starting from 154 the most recent. The transformer exception also provides a 155 {@link javax.xml.transform.SourceLocator} object which indicates where 156 in the source tree or transformation instructions the error occurred. 157 {@link javax.xml.transform.TransformerException#getMessageAndLocation()} 158 may be called to get an error message with location info, and 159 {@link javax.xml.transform.TransformerException#getLocationAsString()} 160 may be called to get just the location string.</p> 161 162 <p>Transformation warnings and errors are sent to an 163 {@link javax.xml.transform.ErrorListener}, at which point the 164 application may decide to report the error or warning, and may decide to throw 165 an <code>Exception</code> for a non-fatal error. The <code>ErrorListener</code> may be set via 166 {@link javax.xml.transform.TransformerFactory#setErrorListener} for 167 reporting errors that have to do with syntax errors in the transformation 168 instructions, or via 169 {@link javax.xml.transform.Transformer#setErrorListener} to report 170 errors that occur during the transformation. The <code>ErrorListener</code> on both objects 171 will always be valid and non-<code>null</code>, whether set by the application or a default 172 implementation provided by the processor. 173 The default implementation provided by the processor will report all warnings and errors to <code>System.err</code> 174 and does not throw any <code>Exception</code>s. 175 Applications are <em>strongly</em> encouraged to register and use 176 <code>ErrorListener</code>s that insure proper behavior for warnings and 177 errors. 178 </p> 179 180 181 <h3>Resolution of URIs within a transformation</h3> 182 183 <p>The API provides a way for URIs referenced from within the stylesheet 184 instructions or within the transformation to be resolved by the calling 185 application. This can be done by creating a class that implements the 186 {@link javax.xml.transform.URIResolver} interface, with its one method, 187 {@link javax.xml.transform.URIResolver#resolve}, and use this class to 188 set the URI resolution for the transformation instructions or transformation 189 with {@link javax.xml.transform.TransformerFactory#setURIResolver} or 190 {@link javax.xml.transform.Transformer#setURIResolver}. The 191 <code>URIResolver.resolve</code> method takes two String arguments, the URI found in the 192 stylesheet instructions or built as part of the transformation process, and the 193 base URI 194 against which the first argument will be made absolute if the 195 absolute URI is required. 196 The returned {@link javax.xml.transform.Source} object must be usable by 197 the transformer, as specified in its implemented features.</p> 198 199 200 </body> 201 </html> 202
