001    /* $Id: Substitutor.java 471661 2006-11-06 08:09:25Z skitching $
002     *
003     * Licensed to the Apache Software Foundation (ASF) under one or more
004     * contributor license agreements.  See the NOTICE file distributed with
005     * this work for additional information regarding copyright ownership.
006     * The ASF licenses this file to You under the Apache License, Version 2.0
007     * (the "License"); you may not use this file except in compliance with
008     * the License.  You may obtain a copy of the License at
009     * 
010     *      http://www.apache.org/licenses/LICENSE-2.0
011     * 
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */ 
018    
019    package org.apache.commons.digester;
020    
021    import org.xml.sax.Attributes;
022    
023    /**
024     * <p>(Logical) Interface for substitution strategies.
025     * (It happens to be implemented as a Java abstract class to allow
026     * future additions to be made without breaking backwards compatibility.)
027     * </p>
028     * <p>
029     * Usage: When {@link Digester#setSubstitutor} is set, <code>Digester</code>
030     * calls the methods in this interface to create substitute values which will
031     * be passed into the Rule implementations.
032     * Of course, it is perfectly acceptable for implementations not to make 
033     * substitutions and simply return the inputs.
034     * </p>
035     * <p>Different strategies are supported for attributes and body text.</p>
036     *
037     * @since 1.6 
038     */
039    public abstract class Substitutor {
040        
041        /**
042         * <p>Substitutes the attributes (before they are passed to the 
043         * <code>Rule</code> implementations's).</p>
044         *
045         * <p><code>Digester</code> will only call this method a second time 
046         * once the original <code>Attributes</code> instance can be safely reused. 
047         * The implementation is therefore free to reuse the same <code>Attributes</code> instance
048         * for all calls.</p>
049         *
050         * @param attributes the <code>Attributes</code> passed into <code>Digester</code> by the SAX parser, 
051         * not null (but may be empty)
052         * @return <code>Attributes</code> to be passed to the <code>Rule</code> implementations. 
053         * This method may pass back the Attributes passed in.
054         * Not null but possibly empty.
055         */
056        public abstract Attributes substitute(Attributes attributes);
057        
058        /**
059         * Substitutes for the body text.
060         * This method may substitute values into the body text of the
061         * elements that Digester parses.
062         *
063         * @param bodyText the body text (as passed to <code>Digester</code>)
064         * @return the body text to be passed to the <code>Rule</code> implementations
065         */
066        public abstract String substitute(String bodyText);
067    }