001    /* $Id: StackAction.java 476205 2006-11-17 16:43:10Z dennisl $
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    /**
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     */
046    public 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    }