001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.components.xslt;
018:
019: import org.apache.avalon.framework.component.Component;
020: import org.apache.avalon.framework.parameters.Parameters;
021: import org.apache.cocoon.ProcessingException;
022: import org.apache.cocoon.environment.Source;
023: import org.apache.cocoon.environment.SourceResolver;
024: import org.xml.sax.XMLFilter;
025:
026: import javax.xml.transform.Result;
027: import javax.xml.transform.sax.TransformerHandler;
028:
029: /**
030: * This is the interface of the XSLT processor in Cocoon.
031: *
032: * @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
033: * @version CVS $Id: XSLTProcessor.java 433543 2006-08-22 06:22:54Z crossley $
034: * @version 1.0
035: * @since July 11, 2001
036: */
037: public interface XSLTProcessor extends Component {
038: /**
039: * The role implemented by an <code>XSLTProcessor</code>.
040: */
041: String ROLE = XSLTProcessor.class.getName();
042:
043: /**
044: * The default factory identifier. (simply used as a pointer, the actual
045: * content is not meaningful)
046: */
047: String DEFAULT_FACTORY = "default";
048:
049: /**
050: * Set the {@link org.apache.cocoon.environment.SourceResolver} for
051: * this instance. The <code>resolver</code> is invoked to return a
052: * <code>Source</code> object, given an HREF.
053: *
054: * @deprecated The processor can now simply lookup the source resolver.
055: * @param resolver a <code>SourceResolver</code> value
056: */
057: void setSourceResolver(SourceResolver resolver);
058:
059: /**
060: * Set the TransformerFactory for this instance.
061: * The <code>factory</code> is invoked to return a
062: * <code>TransformerHandler</code> to perform the transformation.
063: *
064: * @param classname the name of the class implementing
065: * <code>TransformerFactory</code> value. If an error is found
066: * or the indicated class doesn't implement the required interface
067: * the original factory of the component is maintained.
068: */
069: void setTransformerFactory(String classname);
070:
071: /**
072: * <p>Return a <code>TransformerHandler</code> for a given
073: * stylesheet <code>Source</code>. This can be used in a pipeline to
074: * handle the transformation of a stream of SAX events. See {@link
075: * org.apache.cocoon.transformation.TraxTransformer#setConsumer(org.apache.cocoon.xml.XMLConsumer)}
076: * for an example of how to use this method.
077: *
078: * <p>The additional <code>filter</code> argument, if it's not
079: * <code>null</code>, is inserted in the chain SAX events as an XML
080: * filter during the parsing or the source document.
081: *
082: * <p>This method caches the Source object and performs a reparsing
083: * only if this changes.
084: *
085: * @param stylesheet a <code>Source</code> value
086: * @param filter a <code>XMLFilter</code> value
087: * @return a <code>TransformerHandler</code> value
088: * @exception ProcessingException if an error occurs
089: */
090: TransformerHandler getTransformerHandler(Source stylesheet,
091: XMLFilter filter) throws ProcessingException;
092:
093: /**
094: * Same as {@link #getTransformerHandler(Source,XMLFilter)}, with
095: * <code>filter</code> set to <code>null</code> and <code>factory</code>
096: * set to <code>null</code>.
097: *
098: * @param stylesheet a <code>Source</code> value
099: * @return a <code>TransformerHandler</code> value
100: * @exception ProcessingException if an error occurs
101: * @see org.apache.cocoon.transformation.TraxTransformer#setConsumer(org.apache.cocoon.xml.XMLConsumer)
102: */
103: TransformerHandler getTransformerHandler(Source stylesheet)
104: throws ProcessingException;
105:
106: /**
107: * Applies an XSLT stylesheet to an XML document. The source and
108: * stylesheet documents are specified as <code>Source</code>
109: * objects. The result of the transformation is placed in
110: * <code>result</code>, which should be properly initialized before
111: * invoking this method. Any additional parameters passed in
112: * <code>params</code> will become arguments to the stylesheet.
113: *
114: * @param source a <code>Source</code> value
115: * @param stylesheet a <code>Source</code> value
116: * @param params a <code>Parameters</code> value
117: * @param result a <code>Result</code> value
118: * @exception ProcessingException if an error occurs
119: */
120: void transform(Source source, Source stylesheet, Parameters params,
121: Result result) throws ProcessingException;
122: }
|