Java tutorial
/* $Id: CallParamRule.java 992060 2010-09-02 19:09:47Z simonetripodi $ * * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.digester; import java.util.Stack; import org.xml.sax.Attributes; /** * <p>Rule implementation that saves a parameter for use by a surrounding * <code>CallMethodRule<code>.</p> * * <p>This parameter may be: * <ul> * <li>from an attribute of the current element * See {@link #CallParamRule(int paramIndex, String attributeName)} * <li>from current the element body * See {@link #CallParamRule(int paramIndex)} * <li>from the top object on the stack. * See {@link #CallParamRule(int paramIndex, boolean fromStack)} * <li>the current path being processed (separate <code>Rule</code>). * See {@link PathCallParamRule} * </ul> * </p> */ public class CallParamRule extends Rule { // ----------------------------------------------------------- Constructors /** * Construct a "call parameter" rule that will save the body text of this * element as the parameter value. * * <p>Note that if the element is empty the an <i>empty string</i> is * passed to the target method, not null. And if automatic type conversion * is being applied (ie if the target function takes something other than * a string as a parameter) then the conversion will fail if the converter * class does not accept an empty string as valid input.</p> * * @param digester The associated Digester * @param paramIndex The zero-relative parameter number * * @deprecated The digester instance is now set in the {@link Digester#addRule} method. * Use {@link #CallParamRule(int paramIndex)} instead. */ @Deprecated public CallParamRule(Digester digester, int paramIndex) { this(paramIndex); } /** * Construct a "call parameter" rule that will save the value of the * specified attribute as the parameter value. * * @param digester The associated Digester * @param paramIndex The zero-relative parameter number * @param attributeName The name of the attribute to save * * @deprecated The digester instance is now set in the {@link Digester#addRule} method. * Use {@link #CallParamRule(int paramIndex, String attributeName)} instead. */ @Deprecated public CallParamRule(Digester digester, int paramIndex, String attributeName) { this(paramIndex, attributeName); } /** * Construct a "call parameter" rule that will save the body text of this * element as the parameter value. * * <p>Note that if the element is empty the an <i>empty string</i> is * passed to the target method, not null. And if automatic type conversion * is being applied (ie if the target function takes something other than * a string as a parameter) then the conversion will fail if the converter * class does not accept an empty string as valid input.</p> * * @param paramIndex The zero-relative parameter number */ public CallParamRule(int paramIndex) { this(paramIndex, null); } /** * Construct a "call parameter" rule that will save the value of the * specified attribute as the parameter value. * * @param paramIndex The zero-relative parameter number * @param attributeName The name of the attribute to save */ public CallParamRule(int paramIndex, String attributeName) { this.paramIndex = paramIndex; this.attributeName = attributeName; } /** * Construct a "call parameter" rule. * * @param paramIndex The zero-relative parameter number * @param fromStack should this parameter be taken from the top of the stack? */ public CallParamRule(int paramIndex, boolean fromStack) { this.paramIndex = paramIndex; this.fromStack = fromStack; } /** * Constructs a "call parameter" rule which sets a parameter from the stack. * If the stack contains too few objects, then the parameter will be set to null. * * @param paramIndex The zero-relative parameter number * @param stackIndex the index of the object which will be passed as a parameter. * The zeroth object is the top of the stack, 1 is the next object down and so on. */ public CallParamRule(int paramIndex, int stackIndex) { this.paramIndex = paramIndex; this.fromStack = true; this.stackIndex = stackIndex; } // ----------------------------------------------------- Instance Variables /** * The attribute from which to save the parameter value */ protected String attributeName = null; /** * The zero-relative index of the parameter we are saving. */ protected int paramIndex = 0; /** * Is the parameter to be set from the stack? */ protected boolean fromStack = false; /** * The position of the object from the top of the stack */ protected int stackIndex = 0; /** * Stack is used to allow nested body text to be processed. * Lazy creation. */ protected Stack<String> bodyTextStack; // --------------------------------------------------------- Public Methods /** * Process the start of this element. * * @param attributes The attribute list for this element */ @Override public void begin(Attributes attributes) throws Exception { Object param = null; if (attributeName != null) { param = attributes.getValue(attributeName); } else if (fromStack) { param = digester.peek(stackIndex); } // Have to save the param object to the param stack frame here. // Can't wait until end(). Otherwise, the object will be lost. // We can't save the object as instance variables, as // the instance variables will be overwritten // if this CallParamRule is reused in subsequent nesting. if (param != null) { Object parameters[] = (Object[]) digester.peekParams(); parameters[paramIndex] = param; } } /** * Process the body text of this element. * * @param bodyText The body text of this element */ @Override public void body(String bodyText) throws Exception { if (attributeName == null && !fromStack) { // We must wait to set the parameter until end // so that we can make sure that the right set of parameters // is at the top of the stack if (bodyTextStack == null) { bodyTextStack = new Stack<String>(); } bodyTextStack.push(bodyText.trim()); } } /** * Process any body texts now. */ @Override public void end(String namespace, String name) { if (bodyTextStack != null && !bodyTextStack.empty()) { // what we do now is push one parameter onto the top set of parameters Object parameters[] = (Object[]) digester.peekParams(); parameters[paramIndex] = bodyTextStack.pop(); } } /** * Render a printable version of this Rule. */ @Override public String toString() { StringBuffer sb = new StringBuffer("CallParamRule["); sb.append("paramIndex="); sb.append(paramIndex); sb.append(", attributeName="); sb.append(attributeName); sb.append(", from stack="); sb.append(fromStack); sb.append("]"); return (sb.toString()); } }