001package org.apache.commons.digester3;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import static java.lang.String.format;
023
024import org.xml.sax.Attributes;
025
026/**
027 * <p>
028 * Rule implementation that saves a parameter for use by a surrounding <code>CallMethodRule<code>.
029 * </p>
030 * <p>
031 * This parameter may be:
032 * <ul>
033 * <li>an arbitrary Object defined programatically, assigned when the element pattern associated with the Rule is
034 * matched. See {@link #ObjectParamRule(int paramIndex, Object param)}.
035 * <li>an arbitrary Object defined programatically, assigned if the element pattern AND specified attribute name are
036 * matched. See {@link #ObjectParamRule(int paramIndex, String attributeName, Object param)}.
037 * </ul>
038 * </p>
039 * 
040 * @since 1.4
041 */
042public class ObjectParamRule
043    extends Rule
044{
045    // ----------------------------------------------------------- Constructors
046    /**
047     * Construct a "call parameter" rule that will save the given Object as the parameter value.
048     * 
049     * @param paramIndex The zero-relative parameter number
050     * @param param the parameter to pass along
051     */
052    public ObjectParamRule( int paramIndex, Object param )
053    {
054        this( paramIndex, null, param );
055    }
056
057    /**
058     * Construct a "call parameter" rule that will save the given Object as the parameter value, provided that the
059     * specified attribute exists.
060     * 
061     * @param paramIndex The zero-relative parameter number
062     * @param attributeName The name of the attribute to match
063     * @param param the parameter to pass along
064     */
065    public ObjectParamRule( int paramIndex, String attributeName, Object param )
066    {
067        this.paramIndex = paramIndex;
068        this.attributeName = attributeName;
069        this.param = param;
070    }
071
072    // ----------------------------------------------------- Instance Variables
073
074    /**
075     * The attribute which we are attempting to match
076     */
077    protected String attributeName = null;
078
079    /**
080     * The zero-relative index of the parameter we are saving.
081     */
082    protected int paramIndex = 0;
083
084    /**
085     * The parameter we wish to pass to the method call
086     */
087    protected Object param = null;
088
089    // --------------------------------------------------------- Public Methods
090
091    /**
092     * {@inheritDoc}
093     */
094    @Override
095    public void begin( String namespace, String name, Attributes attributes )
096        throws Exception
097    {
098        Object anAttribute = null;
099        Object parameters[] = getDigester().peekParams();
100
101        if ( attributeName != null )
102        {
103            anAttribute = attributes.getValue( attributeName );
104            if ( anAttribute != null )
105            {
106                parameters[paramIndex] = param;
107            }
108            // note -- if attributeName != null and anAttribute == null, this rule
109            // will pass null as its parameter!
110        }
111        else
112        {
113            parameters[paramIndex] = param;
114        }
115    }
116
117    /**
118     * {@inheritDoc}
119     */
120    @Override
121    public String toString()
122    {
123        return format( "ObjectParamRule[paramIndex=%s, attributeName=%s, param=%s]", paramIndex, attributeName, param );
124    }
125
126}