001/* $Id: ObjectParamRule.java 992060 2010-09-02 19:09:47Z simonetripodi $
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    @Override
097    public void begin(String namespace, String name,
098                      Attributes attributes) throws Exception {
099        Object anAttribute = null;
100        Object parameters[] = (Object[]) digester.peekParams();
101
102        if (attributeName != null) {
103            anAttribute = attributes.getValue(attributeName);
104            if(anAttribute != null) {
105                parameters[paramIndex] = param;
106            }
107            // note -- if attributeName != null and anAttribute == null, this rule
108            // will pass null as its parameter!
109        }else{
110            parameters[paramIndex] = param;
111        }
112    }
113
114    /**
115     * Render a printable version of this Rule.
116     */
117    @Override
118    public String toString() {
119        StringBuffer sb = new StringBuffer("ObjectParamRule[");
120        sb.append("paramIndex=");
121        sb.append(paramIndex);
122        sb.append(", attributeName=");
123        sb.append(attributeName);
124        sb.append(", param=");
125        sb.append(param);
126        sb.append("]");
127        return (sb.toString());
128    }
129}