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;
023import java.util.Stack;
024
025import org.xml.sax.Attributes;
026
027/**
028 * <p>
029 * Rule implementation that saves a parameter for use by a surrounding <code>CallMethodRule<code>.
030 * </p>
031 * <p>
032 * This parameter may be:
033 * <ul>
034 * <li>from an attribute of the current element See {@link #CallParamRule(int paramIndex, String attributeName)}
035 * <li>from current the element body See {@link #CallParamRule(int paramIndex)}
036 * <li>from the top object on the stack. See {@link #CallParamRule(int paramIndex, boolean fromStack)}
037 * <li>the current path being processed (separate <code>Rule</code>). See {@link PathCallParamRule}
038 * </ul>
039 * </p>
040 */
041public class CallParamRule
042    extends Rule
043{
044
045    // ----------------------------------------------------------- Constructors
046
047    /**
048     * Construct a "call parameter" rule that will save the body text of this element as the parameter value.
049     * <p>
050     * Note that if the element is empty the an <i>empty string</i> is passed to the target method, not null. And if
051     * automatic type conversion is being applied (ie if the target function takes something other than a string as a
052     * parameter) then the conversion will fail if the converter class does not accept an empty string as valid input.
053     * </p>
054     * 
055     * @param paramIndex The zero-relative parameter number
056     */
057    public CallParamRule( int paramIndex )
058    {
059        this( paramIndex, null );
060    }
061
062    /**
063     * Construct a "call parameter" rule that will save the value of the specified attribute as the parameter value.
064     * 
065     * @param paramIndex The zero-relative parameter number
066     * @param attributeName The name of the attribute to save
067     */
068    public CallParamRule( int paramIndex, String attributeName )
069    {
070        this.paramIndex = paramIndex;
071        this.attributeName = attributeName;
072    }
073
074    /**
075     * Construct a "call parameter" rule.
076     * 
077     * @param paramIndex The zero-relative parameter number
078     * @param fromStack should this parameter be taken from the top of the stack?
079     */
080    public CallParamRule( int paramIndex, boolean fromStack )
081    {
082        this.paramIndex = paramIndex;
083        this.fromStack = fromStack;
084    }
085
086    /**
087     * Constructs a "call parameter" rule which sets a parameter from the stack. If the stack contains too few objects,
088     * then the parameter will be set to null.
089     * 
090     * @param paramIndex The zero-relative parameter number
091     * @param stackIndex the index of the object which will be passed as a parameter. The zeroth object is the top of
092     *            the stack, 1 is the next object down and so on.
093     */
094    public CallParamRule( int paramIndex, int stackIndex )
095    {
096        this.paramIndex = paramIndex;
097        this.fromStack = true;
098        this.stackIndex = stackIndex;
099    }
100
101    // ----------------------------------------------------- Instance Variables
102
103    /**
104     * The attribute from which to save the parameter value
105     */
106    protected String attributeName = null;
107
108    /**
109     * The zero-relative index of the parameter we are saving.
110     */
111    protected int paramIndex = 0;
112
113    /**
114     * Is the parameter to be set from the stack?
115     */
116    protected boolean fromStack = false;
117
118    /**
119     * The position of the object from the top of the stack
120     */
121    protected int stackIndex = 0;
122
123    /**
124     * Stack is used to allow nested body text to be processed. Lazy creation.
125     */
126    protected Stack<String> bodyTextStack;
127
128    // --------------------------------------------------------- Public Methods
129
130    /**
131     * Set the attribute from which to save the parameter value.
132     *
133     * @param attributeName The attribute from which to save the parameter value
134     * @since 3.0
135     */
136    public void setAttributeName( String attributeName )
137    {
138        this.attributeName = attributeName;
139    }
140
141    /**
142     * {@inheritDoc}
143     */
144    @Override
145    public void begin( String namespace, String name, Attributes attributes )
146        throws Exception
147    {
148        Object param = null;
149
150        if ( attributeName != null )
151        {
152
153            param = attributes.getValue( attributeName );
154
155        }
156        else if ( fromStack )
157        {
158
159            param = getDigester().peek( stackIndex );
160
161            if ( getDigester().getLogger().isDebugEnabled() )
162            {
163                getDigester()
164                    .getLogger().debug( format( "[CallParamRule]{%s} Save from stack; from stack?%s; object=%s",
165                                                getDigester().getMatch(), fromStack, param ) );
166            }
167        }
168
169        // Have to save the param object to the param stack frame here.
170        // Can't wait until end(). Otherwise, the object will be lost.
171        // We can't save the object as instance variables, as
172        // the instance variables will be overwritten
173        // if this CallParamRule is reused in subsequent nesting.
174
175        if ( param != null )
176        {
177            Object parameters[] = getDigester().peekParams();
178            parameters[paramIndex] = param;
179        }
180    }
181
182    /**
183     * {@inheritDoc}
184     */
185    @Override
186    public void body( String namespace, String name, String text )
187        throws Exception
188    {
189        if ( attributeName == null && !fromStack )
190        {
191            // We must wait to set the parameter until end
192            // so that we can make sure that the right set of parameters
193            // is at the top of the stack
194            if ( bodyTextStack == null )
195            {
196                bodyTextStack = new Stack<String>();
197            }
198            bodyTextStack.push( text.trim() );
199        }
200    }
201
202    /**
203     * {@inheritDoc}
204     */
205    @Override
206    public void end( String namespace, String name )
207    {
208        if ( bodyTextStack != null && !bodyTextStack.empty() )
209        {
210            // what we do now is push one parameter onto the top set of parameters
211            Object parameters[] = getDigester().peekParams();
212            parameters[paramIndex] = bodyTextStack.pop();
213        }
214    }
215
216    /**
217     * {@inheritDoc}
218     */
219    @Override
220    public String toString()
221    {
222        return format( "CallParamRule[paramIndex=%s, attributeName=%s, from stack=%s]",
223                       paramIndex, attributeName, fromStack );
224    }
225
226}