001/* $Id: StackAction.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
022/**
023 * An interface that can be implemented in order to get notifications of
024 * objects being pushed onto a digester stack or popped from one.
025 * <p>
026 * Because objects are pushed onto the main object stack when a rule
027 * has created a new object, this gives the ability to intercept such
028 * operations and perform modifications on created objects.
029 * <p>
030 * One use expected for this interface is to store information about the xml
031 * line that a particular object was created from. An implementation of this
032 * interface can detect whenever an object is pushed onto the digester object
033 * stack, call Digester.getDocumentLocator() to get the location within the
034 * current xml file, and store this either on the object on the stack (if it
035 * supports some user-specific interface for this purpose), or build a map of
036 * (object->locationinfo) separately.
037 * <p>
038 * It is recommended that objects implementing this interface provide
039 * a method to set a "next" action, and invoke it from the callback
040 * methods. This allows multiple actions to be "chained" together.
041 * <p>
042 * See also Digester.setStackAction.
043 * 
044 * @since 1.8
045 */
046public interface StackAction {
047    /**
048     * Invoked just before an object is to be pushed onto a digester stack.
049     * 
050     * @param d is the digester instance.
051     * 
052     * @param stackName is the name of the stack onto which the object
053     * has been pushed. Null is passed to indicate the default stack.
054     * 
055     * @param o is the object that has just been pushed. Calling peek on the
056     * specified stack will return the same object.
057     * 
058     * @return the object to be pushed. Normally, parameter o is returned
059     * but this method could return an alternate object to be pushed
060     * instead (eg a proxy for the provided object).
061     */
062    public Object onPush(Digester d, String stackName, Object o);
063
064    /**
065     * Invoked just after an object has been popped from a digester stack.
066     * 
067     * @param d is the digester instance.
068     * 
069     * @param stackName is the name of the stack from which the object
070     * has been popped. Null is passed to indicate the default stack.
071     * 
072     * @param o is the object that has just been popped.
073     * 
074     * @return the object to be returned to the called. Normally, parameter
075     * o is returned but this method could return an alternate object.
076     */
077    public Object onPop(Digester d, String stackName, Object o);
078}