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    
020    package org.apache.commons.digester;
021    
022    import 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    
042    public 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    }