XSLTProcessor


1   /* 
2    * Copyright 2002-2004 The Apache Software Foundation
3    * Licensed  under the  Apache License,  Version 2.0  (the "License");
4    * you may not use  this file  except in  compliance with the License.
5    * You may obtain a copy of the License at 
6    * 
7    *   http://www.apache.org/licenses/LICENSE-2.0
8    * 
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed  under the  License is distributed on an "AS IS" BASIS,
11   * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
12   * implied.
13   * 
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.excalibur.xml.xslt;
18  
19  import javax.xml.transform.Result  ;
20  import javax.xml.transform.sax.TransformerHandler  ;
21  
22  import org.apache.avalon.framework.component.Component;
23  import org.apache.avalon.framework.parameters.Parameters;
24  import org.apache.excalibur.source.Source;
25  import org.apache.excalibur.source.SourceValidity;
26  import org.xml.sax.XMLFilter  ;
27  
28  /**
29   * This is the interface of the XSLT processor.
30   *
31   * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
32   * @version CVS $Id: XSLTProcessor.java,v 1.4 2004/02/28 11:47:16 cziegeler Exp $
33   * @version 1.0
34   * @since   July 11, 2001
35   */
36  public interface XSLTProcessor
37      extends Component
38  {
39      /**
40       * The role implemented by an <code>XSLTProcessor</code>.
41       */
42      String   ROLE = XSLTProcessor.class.getName();
43  
44      public static class TransformerHandlerAndValidity
45      {
46          private final TransformerHandler   transformerHandler;
47          private final SourceValidity transformerValidity;
48  
49          protected TransformerHandlerAndValidity( final TransformerHandler   transformerHandler,
50                                                   final SourceValidity transformerValidity )
51          {
52              this.transformerHandler = transformerHandler;
53              this.transformerValidity = transformerValidity;
54          }
55  
56          public TransformerHandler   getTransfomerHandler()
57          {
58              return transformerHandler;
59          }
60  
61          public SourceValidity getTransfomerValidity()
62          {
63              return transformerValidity;
64          }
65      }
66  
67      /**
68       * Set the TransformerFactory for this instance.
69       * The <code>factory</code> is invoked to return a
70       * <code>TransformerHandler</code> to perform the transformation.
71       *
72       * @param classname the name of the class implementing
73       * <code>TransformerFactory</code> value. If an error is found
74       * or the indicated class doesn't implement the required interface
75       * the original factory of the component is maintained.
76       */
77      void setTransformerFactory( String   classname );
78  
79      /**
80       * <p>Return a <code>TransformerHandler</code> for a given
81       * stylesheet {@link Source}. This can be used in a pipeline to
82       * handle the transformation of a stream of SAX events. See {@link
83       * org.apache.cocoon.transformation.TraxTransformer#setConsumer} for
84       * an example of how to use this method.
85       *
86       * <p>The additional <code>filter</code> argument, if it's not
87       * <code>null</code>, is inserted in the chain SAX events as an XML
88       * filter during the parsing or the source document.
89       *
90       * <p>This method caches the Templates object with meta information
91       * (modification time and list of included stylesheets) and performs
92       * a reparsing only if this changes.
93       *
94       * @param stylesheet a {@link Source} value
95       * @param filter a {@link XMLFilter} value
96       * @return a {@link TransformerHandler} value
97       * @exception XSLTProcessorException if an error occurs
98       */
99      TransformerHandler   getTransformerHandler( Source stylesheet, XMLFilter   filter )
100         throws XSLTProcessorException;
101 
102     /**
103      * <p>Return a {@link TransformerHandler} and
104      * <code>SourceValidity</code> for a given stylesheet
105      * {@link Source}. This can be used in a pipeline to
106      * handle the transformation of a stream of SAX events. See {@link
107      * org.apache.cocoon.transformation.TraxTransformer#setConsumer} for
108      * an example of how to use this method.
109      *
110      * <p>The additional <code>filter</code> argument, if it's not
111      * <code>null</code>, is inserted in the chain SAX events as an XML
112      * filter during the parsing or the source document.
113      *
114      * <p>This method caches the Templates object with meta information
115      * (modification time and list of included stylesheets) and performs
116      * a reparsing only if this changes.
117      *
118      * @param stylesheet a {@link Source} value
119      * @param filter a {@link XMLFilter} value
120      * @return a <code>TransformerHandlerAndValidity</code> value
121      * @exception XSLTProcessorException if an error occurs
122      */
123     TransformerHandlerAndValidity getTransformerHandlerAndValidity( Source stylesheet, XMLFilter   filter )
124         throws XSLTProcessorException;
125 
126     /**
127      * Same as {@link #getTransformerHandler(Source,XMLFilter)}, with
128      * <code>filter</code> set to <code>null</code>.
129      *
130      * @param stylesheet a {@link Source} value
131      * @return a {@link TransformerHandler} value
132      * @exception XSLTProcessorException if an error occurs
133      */
134     TransformerHandler   getTransformerHandler( Source stylesheet )
135         throws XSLTProcessorException;
136 
137     /**
138      * Same as {@link #getTransformerHandlerAndValidity(Source,XMLFilter)}, with
139      * <code>filter</code> set to <code>null</code>.
140      *
141      * @param stylesheet a {@link Source} value
142      * @return a {@link TransformerHandlerAndValidity} value
143      * @exception XSLTProcessorException if an error occurs
144      */
145     TransformerHandlerAndValidity getTransformerHandlerAndValidity( Source stylesheet )
146         throws XSLTProcessorException;
147 
148     /**
149      * Applies an XSLT stylesheet to an XML document. The source and
150      * stylesheet documents are specified as {@link Source}
151      * objects. The result of the transformation is placed in
152      * {@link Result}, which should be properly initialized before
153      * invoking this method. Any additional parameters passed in
154      * {@link Parameters params} will become arguments to the stylesheet.
155      *
156      * @param source a {@link Source} value
157      * @param stylesheet a {@link Source} value
158      * @param params a <code>Parameters</code> value
159      * @param result a <code>Result</code> value
160      * @exception XSLTProcessorException if an error occurs
161      */
162     void transform( Source source, Source stylesheet, Parameters params, Result   result )
163         throws XSLTProcessorException;
164 }
165
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags