01: /* $Id: Substitutor.java 471661 2006-11-06 08:09:25Z skitching $
02: *
03: * Licensed to the Apache Software Foundation (ASF) under one or more
04: * contributor license agreements. See the NOTICE file distributed with
05: * this work for additional information regarding copyright ownership.
06: * The ASF licenses this file to You under the Apache License, Version 2.0
07: * (the "License"); you may not use this file except in compliance with
08: * the License. You may obtain a copy of the License at
09: *
10: * http://www.apache.org/licenses/LICENSE-2.0
11: *
12: * Unless required by applicable law or agreed to in writing, software
13: * distributed under the License is distributed on an "AS IS" BASIS,
14: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15: * See the License for the specific language governing permissions and
16: * limitations under the License.
17: */
18:
19: package org.apache.commons.digester;
20:
21: import org.xml.sax.Attributes;
22:
23: /**
24: * <p>(Logical) Interface for substitution strategies.
25: * (It happens to be implemented as a Java abstract class to allow
26: * future additions to be made without breaking backwards compatibility.)
27: * </p>
28: * <p>
29: * Usage: When {@link Digester#setSubstitutor} is set, <code>Digester</code>
30: * calls the methods in this interface to create substitute values which will
31: * be passed into the Rule implementations.
32: * Of course, it is perfectly acceptable for implementations not to make
33: * substitutions and simply return the inputs.
34: * </p>
35: * <p>Different strategies are supported for attributes and body text.</p>
36: *
37: * @since 1.6
38: */
39: public abstract class Substitutor {
40:
41: /**
42: * <p>Substitutes the attributes (before they are passed to the
43: * <code>Rule</code> implementations's).</p>
44: *
45: * <p><code>Digester</code> will only call this method a second time
46: * once the original <code>Attributes</code> instance can be safely reused.
47: * The implementation is therefore free to reuse the same <code>Attributes</code> instance
48: * for all calls.</p>
49: *
50: * @param attributes the <code>Attributes</code> passed into <code>Digester</code> by the SAX parser,
51: * not null (but may be empty)
52: * @return <code>Attributes</code> to be passed to the <code>Rule</code> implementations.
53: * This method may pass back the Attributes passed in.
54: * Not null but possibly empty.
55: */
56: public abstract Attributes substitute(Attributes attributes);
57:
58: /**
59: * Substitutes for the body text.
60: * This method may substitute values into the body text of the
61: * elements that Digester parses.
62: *
63: * @param bodyText the body text (as passed to <code>Digester</code>)
64: * @return the body text to be passed to the <code>Rule</code> implementations
65: */
66: public abstract String substitute(String bodyText);
67: }
|