001/* $Id: ObjectParamRule.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
020package org.apache.commons.digester;
021
022import org.xml.sax.Attributes;
023
024/**
025 * <p>Rule implementation that saves a parameter for use by a surrounding
026 * <code>CallMethodRule<code>.</p>
027 *
028 * <p>This parameter may be:
029 * <ul>
030 * <li>an arbitrary Object defined programatically, assigned when the element 
031 *  pattern associated with the Rule is matched. See 
032 * {@link #ObjectParamRule(int paramIndex, Object param)}.
033 * <li>an arbitrary Object defined programatically, assigned if the element 
034 * pattern AND specified attribute name are matched. See 
035 * {@link #ObjectParamRule(int paramIndex, String attributeName, Object param)}.
036 * </ul>
037 * </p>
038 *
039 * @since 1.4
040 */
041
042public class ObjectParamRule extends Rule {
043    // ----------------------------------------------------------- Constructors
044    /**
045     * Construct a "call parameter" rule that will save the given Object as
046     * the parameter value.
047     *
048     * @param paramIndex The zero-relative parameter number
049     * @param param the parameter to pass along
050     */
051    public ObjectParamRule(int paramIndex, Object param) {
052        this(paramIndex, null, param);
053    }
054
055
056    /**
057     * Construct a "call parameter" rule that will save the given Object as
058     * the parameter value, provided that the specified attribute exists.
059     *
060     * @param paramIndex The zero-relative parameter number
061     * @param attributeName The name of the attribute to match
062     * @param param the parameter to pass along
063     */
064    public ObjectParamRule(int paramIndex, String attributeName, Object param) {
065        this.paramIndex = paramIndex;
066        this.attributeName = attributeName;
067        this.param = param;
068    }
069
070
071    // ----------------------------------------------------- Instance Variables
072
073    /**
074     * The attribute which we are attempting to match
075     */
076    protected String attributeName = null;
077
078    /**
079     * The zero-relative index of the parameter we are saving.
080     */
081    protected int paramIndex = 0;
082
083    /**
084     * The parameter we wish to pass to the method call
085     */
086    protected Object param = null;
087
088
089    // --------------------------------------------------------- Public Methods
090
091    /**
092     * Process the start of this element.
093     *
094     * @param attributes The attribute list for this element
095     */
096    public void begin(String namespace, String name,
097                      Attributes attributes) throws Exception {
098        Object anAttribute = null;
099        Object parameters[] = (Object[]) digester.peekParams();
100
101        if (attributeName != null) {
102            anAttribute = attributes.getValue(attributeName);
103            if(anAttribute != null) {
104                parameters[paramIndex] = param;
105            }
106            // note -- if attributeName != null and anAttribute == null, this rule
107            // will pass null as its parameter!
108        }else{
109            parameters[paramIndex] = param;
110        }
111    }
112
113    /**
114     * Render a printable version of this Rule.
115     */
116    public String toString() {
117        StringBuffer sb = new StringBuffer("ObjectParamRule[");
118        sb.append("paramIndex=");
119        sb.append(paramIndex);
120        sb.append(", attributeName=");
121        sb.append(attributeName);
122        sb.append(", param=");
123        sb.append(param);
124        sb.append("]");
125        return (sb.toString());
126    }
127}