package-summary.html

j2ee的API 1.4版本,j2ee的帮助文档

<p>The API allows a concrete
          <A HREF="../../../javax/xml/transform/TransformerFactory.html" title="class in javax.xml.transform"><CODE>TransformerFactory</CODE></A> object to be created from
          the static function
          <A HREF="../../../javax/xml/transform/TransformerFactory.html#newInstance()"><CODE>TransformerFactory.newInstance()</CODE></A>.
      
        
<h3>Specification of Inputs and Outputs</h3>
        
<p>This API defines two interface objects called
          <A HREF="../../../javax/xml/transform/Source.html" title="interface in javax.xml.transform"><CODE>Source</CODE></A> and
          <A HREF="../../../javax/xml/transform/Result.html" title="interface in javax.xml.transform"><CODE>Result</CODE></A>. In order to pass Source and Result
          objects to the interfaces, concrete classes must be used.
          Three concrete representations are defined for each of these
          objects:
          <A HREF="../../../javax/xml/transform/stream/StreamSource.html" title="class in javax.xml.transform.stream"><CODE>StreamSource</CODE></A> and
          <A HREF="../../../javax/xml/transform/stream/StreamResult.html" title="class in javax.xml.transform.stream"><CODE>StreamResult</CODE></A>,
          <A HREF="../../../javax/xml/transform/sax/SAXSource.html" title="class in javax.xml.transform.sax"><CODE>SAXSource</CODE></A> and
          <A HREF="../../../javax/xml/transform/sax/SAXResult.html" title="class in javax.xml.transform.sax"><CODE>SAXResult</CODE></A>, and
          <A HREF="../../../javax/xml/transform/dom/DOMSource.html" title="class in javax.xml.transform.dom"><CODE>DOMSource</CODE></A> and
          <A HREF="../../../javax/xml/transform/dom/DOMResult.html" title="class in javax.xml.transform.dom"><CODE>DOMResult</CODE></A>. Each of these objects defines
          a FEATURE string (which is i the form of a URL), which can be passed into
          <A HREF="../../../javax/xml/transform/TransformerFactory.html#getFeature(java.lang.String)"><CODE>TransformerFactory.getFeature(java.lang.String)</CODE></A> to see if the
          given type of Source or Result object is supported. For instance, to test if a
          DOMSource and a StreamResult is supported, you can apply the following
          test.</p>
        
<code>
<pre>    TransformerFactory tfactory = TransformerFactory.newInstance();

    if (tfactory.getFeature(DOMSource.FEATURE) &amp;&amp; tfactory.getFeature(StreamResult.FEATURE))
    {
       ...
    }</pre>
</code>
   
     
<h3>
<a name="qname-delimiter">Qualified Name Representation</a>
</h3>
     
<p>
<A href="http://www.w3.org/TR/REC-xml-names">Namespaces</A>
        present something of a problem area when dealing with XML objects. Qualified
        Names appear in XML markup as prefixed names. But the prefixes themselves do
        not hold identity. Rather, it is the URIs that they contextually map to that
        hold the identity. Therefore, when passing a Qualified Name like "xyz:foo"
        among Java programs, one must provide a means to map "xyz" to a namespace.
        </p>
     
<p>One solution has been to create a "QName" object that holds the
        namespace URI, as well as the prefix and local name, but this is not always an
        optimal solution, as when, for example, you want to use unique strings as keys
        in a dictionary object. Not having a string representation also makes it
        difficult to specify a namespaced identity outside the context of an XML
        document.</p>
     
<p>In order to pass namespaced values to transformations, for instance
        as a set of properties to the Serializer, this specification defines that a
        String "qname" object parameter be passed as two-part string, the namespace URI
        enclosed in curly braces ({}), followed by the local name. If the qname has a
        null URI, then the String object only contains the local name. An application
        can safely check for a non-null URI by testing to see if the first character of
        the name is a '{' character.</p>
     
<p>For example, if a URI and local name were obtained from an element
        defined with &lt;xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;,
        then the Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo".
        Note that the prefix is lost.</p>
   
     
<h3>Result Tree Serialization</h3>
     
<p>Serialization of the result tree to a stream can be controlled with
        the <A HREF="../../../javax/xml/transform/Transformer.html#setOutputProperties(java.util.Properties)"><CODE>Transformer.setOutputProperties(java.util.Properties)</CODE></A> and the
        <A HREF="../../../javax/xml/transform/Transformer.html#setOutputProperty(java.lang.String, java.lang.String)"><CODE>Transformer.setOutputProperty(java.lang.String, java.lang.String)</CODE></A> methods.
        Strings that match the <A href="http://www.w3.org/TR/xslt#output">XSLT
        specification for xsl:output attributes</A> can be referenced from the
        <A HREF="../../../javax/xml/transform/OutputKeys.html" title="class in javax.xml.transform"><CODE>OutputKeys</CODE></A> class. Other strings can be
        specified as well. If the transformer does not recognize an output key, a
        <A HREF="http://java.sun.com/j2se/1.4/docs/api/java/lang/IllegalArgumentException.html" title="class or interface in java.lang"><CODE>IllegalArgumentException</CODE></A> is thrown, unless the
        key name is <A href="#qname-delimiter">namespace qualified</A>. Output key names that are
        qualified by a namespace are ignored or passed on to the serializer
        mechanism.</p>
     
<p>If all that is desired is the simple identity transformation of a
        source to a result, then <A HREF="../../../javax/xml/transform/TransformerFactory.html" title="class in javax.xml.transform"><CODE>TransformerFactory</CODE></A>
        provides a
        <A HREF="../../../javax/xml/transform/TransformerFactory.html#newTransformer()"><CODE>TransformerFactory.newTransformer()</CODE></A> method
        with no arguments. This method creates a Transformer that effectively copies
        the source to the result. This method may be used to create a DOM from SAX
        events or to create an XML or HTML stream from a DOM or SAX events.  </p>
     
 
  
<h3>Exceptions and Error Reporting</h3>
  
<p>The transformation API throw three types of specialized exceptions. A
     <A HREF="../../../javax/xml/transform/TransformerFactoryConfigurationError.html" title="class in javax.xml.transform"><CODE>TransformerFactoryConfigurationError</CODE></A> is parallel to
     the <A HREF="../../../javax/xml/parsers/FactoryConfigurationError.html" title="class in javax.xml.parsers"><CODE>FactoryConfigurationError</CODE></A>, and is thrown
     when a configuration problem with the TransformerFactory exists. This error
     will typically be thrown when the transformation factory class specified with
     the "javax.xml.transform.TransformerFactory" system property cannot be found or
     instantiated.</p>
  
<p>A <A HREF="../../../javax/xml/transform/TransformerConfigurationException.html" title="class in javax.xml.transform"><CODE>TransformerConfigurationException</CODE></A>
     may be thrown if for any reason a Transformer can not be created. A
     TransformerConfigurationException may be thrown if there is a syntax error in
     the transformation instructions, for example when
     <A HREF="../../../javax/xml/transform/TransformerFactory.html#newTransformer(javax.xml.transform.Source)"><CODE>TransformerFactory.newTransformer(javax.xml.transform.Source)</CODE></A> is
     called.</p>
  
<p><A HREF="../../../javax/xml/transform/TransformerException.html" title="class in javax.xml.transform"><CODE>TransformerException</CODE></A> is a general
     exception that occurs during the course of a transformation. A transformer
     exception may wrap another exception, and if any of the
     <A HREF="../../../javax/xml/transform/TransformerException.html#printStackTrace()"><CODE>TransformerException.printStackTrace()</CODE></A>
     methods are called on it, it will produce a list of stack dumps, starting from
     the most recent. The transformer exception also provides a
     <A HREF="../../../javax/xml/transform/SourceLocator.html" title="interface in javax.xml.transform"><CODE>SourceLocator</CODE></A> object which indicates where
     in the source tree or transformation instructions the error occurred.
     <A HREF="../../../javax/xml/transform/TransformerException.html#getMessageAndLocation()"><CODE>TransformerException.getMessageAndLocation()</CODE></A>
     may be called to get an error message with location info, and
     <A HREF="../../../javax/xml/transform/TransformerException.html#getLocationAsString()"><CODE>TransformerException.getLocationAsString()</CODE></A>
     may be called to get just the location string.</p>
  
<p>Transformation warnings and errors are normally first sent to a
     <A HREF="../../../javax/xml/transform/ErrorListener.html" title="interface in javax.xml.transform"><CODE>ErrorListener</CODE></A>, at which point the
     implementor may decide to report the error or warning, and may decide to throw
     an exception for a non-fatal error. The error listener may be set via
     <A HREF="../../../javax/xml/transform/TransformerFactory.html#setErrorListener(javax.xml.transform.ErrorListener)"><CODE>TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener)</CODE></A> for
     reporting errors that have to do with syntax errors in the transformation
     instructions, or via
     <A HREF="../../../javax/xml/transform/Transformer.html#setErrorListener(javax.xml.transform.ErrorListener)"><CODE>Transformer.setErrorListener(javax.xml.transform.ErrorListener)</CODE></A> to report
     errors that occur during the transformation. The error listener on both objects
     should always be valid and non-null, whether set by the user or a default
     implementation provided by the processor.</p>
 
  
<h3>Resolution of URIs within a transformation</h3>
  
<p>The API provides a way for URIs referenced from within the stylesheet
     instructions or within the transformation to be resolved by the calling
     application. This can be done by creating a class that implements the
     <A HREF="../../../javax/xml/transform/URIResolver.html" title="interface in javax.xml.transform"><CODE>URIResolver</CODE></A> interface, with its one method,
     <A HREF="../../../javax/xml/transform/URIResolver.html#resolve(java.lang.String, java.lang.String)"><CODE>URIResolver.resolve(java.lang.String, java.lang.String)</CODE></A>, and use this class to
     set the URI resolution for the transformation instructions or transformation
     with <A HREF="../../../javax/xml/transform/TransformerFactory.html#setURIResolver(javax.xml.transform.URIResolver)"><CODE>TransformerFactory.setURIResolver(javax.xml.transform.URIResolver)</CODE></A> or
     <A HREF="../../../javax/xml/transform/Transformer.html#setURIResolver(javax.xml.transform.URIResolver)"><CODE>Transformer.setURIResolver(javax.xml.transform.URIResolver)</CODE></A>. The
     <code>URIResolver.resolve</code> method takes two String arguments, the URI found in the
     stylesheet instructions or built as part of the transformation process, and the
     base URI in effect when the URI passed as the first argument was encountered.
     The returned <A HREF="../../../javax/xml/transform/Source.html" title="interface in javax.xml.transform"><CODE>Source</CODE></A> object must be usable by
     the transformer, as specified in its implemented features.</p>
<P>

<P>
<HR>


<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<b>Java<sup><font size=-2>TM</font></sup> 2 Platform<br>Ent. Ed. v1.4</b></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../javax/xml/soap/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../../javax/xml/transform/dom/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../index.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>

</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->

<HR>
<font size="-1"><a href="http://java.sun.com/webapps/bugreport">Submit a bug or feature</a> <p>Copyright 2003 Sun Microsystems, Inc. All rights reserved.</font>
</BODY>
</HTML>