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