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 }