001    package org.apache.fulcrum.xslt;
002    
003    /*
004     * Licensed to the Apache Software Foundation (ASF) under one
005     * or more contributor license agreements.  See the NOTICE file
006     * distributed with this work for additional information
007     * regarding copyright ownership.  The ASF licenses this file
008     * to you under the Apache License, Version 2.0 (the
009     * "License"); you may not use this file except in compliance
010     * with the License.  You may obtain a copy of the License at
011     *
012     *   http://www.apache.org/licenses/LICENSE-2.0
013     *
014     * Unless required by applicable law or agreed to in writing,
015     * software distributed under the License is distributed on an
016     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017     * KIND, either express or implied.  See the License for the
018     * specific language governing permissions and limitations
019     * under the License.
020     */
021    
022    import java.io.Reader;
023    import java.io.Writer;
024    import java.util.Map;
025    
026    import org.w3c.dom.Node;
027    
028    /**
029     * The Turbine XSLT Service is used to transform xml with a xsl stylesheet.
030     * The service makes use of the Xalan xslt engine available from apache.
031     *
032     *
033     * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
034     * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
035     */
036    public interface XSLTService
037    {
038        String ROLE = XSLTService.class.getName();
039    
040        /**
041         * Uses an xsl file to transform xml input from a reader and writes the
042         * output to a writer.
043         *
044         * @param xslName The name of the file that contains the xsl stylesheet.
045         * @param in The reader that passes the xml to be transformed
046         * @param out The writer for the transformed output
047         * @throws Exception the transformation failed
048         */
049        void transform (String xslName, Reader in, Writer out) throws Exception;
050    
051        /**
052         * Uses an xsl file to transform xml input from a reader and returns a
053         * string containing the transformed output.
054         *
055         * @param xslName The name of the file that contains the xsl stylesheet.
056         * @param in The reader that passes the xml to be transformed
057         * @return the transformed output
058         * @throws Exception the transformation failed
059         */
060        String transform (String xslName, Reader in) throws Exception;
061    
062        /**
063         * Uses an xsl file to transform xml input from a DOM note and writes the
064         * output to a writer.
065         *
066         * @param xslName The name of the file that contains the xsl stylesheet.
067         * @param in The DOM Node to be transformed
068         * @param out The writer for the transformed output
069         * @throws Exception the transformation failed
070         */
071        void transform (String xslName, Node in, Writer out) throws Exception;
072    
073        /**
074         * Uses an xsl file to transform xml input from a DOM note and returns a
075         * string containing the transformed output.
076         *
077         * @param xslName The name of the file that contains the xsl stylesheet.
078         * @param in The DOM Node to be transformed
079         * @return the transformed output
080         * @throws Exception the transformation failed
081         */
082        String transform (String xslName, Node in) throws Exception;
083    
084        /**
085         * Uses an xsl file to transform xml input from a reader and writes the
086         * output to a writer.
087         *
088         * @param xslName The name of the file that contains the xsl stylesheet.
089         * @param in The reader that passes the xml to be transformed
090         * @param out The writer for the transformed output
091         * @param params A set of parameters that will be forwarded to the XSLT
092         * @throws Exception the transformation failed
093         */
094        void transform(String xslName, Reader in, Writer out, Map params) throws Exception;
095    
096        /**
097         * Uses an xsl file to transform xml input from a reader and returns a
098         * string containing the transformed output.
099         *
100         * @param xslName The name of the file that contains the xsl stylesheet.
101         * @param in The reader that passes the xml to be transformed
102         * @param params A set of parameters that will be forwarded to the XSLT
103         * @return the transformed output
104         * @throws Exception the transformation failed
105         */
106        String transform(String xslName, Reader in, Map params) throws Exception;
107    
108        /**
109         * Uses an xsl file to transform xml input from a DOM note and writes the
110         * output to a writer.
111         *
112         * @param xslName The name of the file that contains the xsl stylesheet.
113         * @param in The DOM Node to be transformed
114         * @param out The writer for the transformed output
115         * @param params A set of parameters that will be forwarded to the XSLT
116         * @throws Exception the transformation failed
117         */
118        void transform(String xslName, Node in, Writer out, Map params) throws Exception;
119    
120        /**
121         * Uses an xsl file to transform xml input from a DOM note and returns a
122         * string containing the transformed output.
123         *
124         * @param xslName The name of the file that contains the xsl stylesheet.
125         * @param in The DOM Node to be transformed
126         * @param params A set of parameters that will be forwarded to the XSLT
127         * @return the transformed output
128         * @throws Exception the transformation failed
129         */
130        String transform(String xslName, Node in, Map params) throws Exception;
131    
132        /**
133         * Uses an xsl file without any xml input.
134         *
135         * @param xslName The name of the file that contains the xsl stylesheet.
136         * @param params A set of parameters that will be forwarded to the XSLT
137         * @return the transformed output
138         * @throws Exception the transformation failed
139         */
140        String transform(String xslName, Map params) throws Exception;
141    
142        /**
143         * Uses an xsl file without any xml input.
144         *
145         * @param xslName The name of the file that contains the xsl stylesheet
146         * @param out The writer for the transformed output.
147         * @param params A set of parameters that will be forwarded to the XSLT
148         * @return the transformed output
149         * @throws Exception the transformation failed
150         */
151        void transform(String xslName, Writer out, Map params) throws Exception;
152    
153    }