package org.apache.commons.digester3;

/*
 * 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.
 */

/**
 * An interface that can be implemented in order to get notifications of objects being pushed onto a digester stack or
 * popped from one.
 * <p>
 * Because objects are pushed onto the main object stack when a rule has created a new object, this gives the ability to
 * intercept such operations and perform modifications on created objects.
 * <p>
 * One use expected for this interface is to store information about the xml line that a particular object was created
 * from. An implementation of this interface can detect whenever an object is pushed onto the digester object stack,
 * call Digester.getDocumentLocator() to get the location within the current xml file, and store this either on the
 * object on the stack (if it supports some user-specific interface for this purpose), or build a map of
 * (object->locationinfo) separately.
 * <p>
 * It is recommended that objects implementing this interface provide a method to set a "next" action, and invoke it
 * from the callback methods. This allows multiple actions to be "chained" together.
 * <p>
 * See also Digester.setStackAction.
 * 
 * @since 1.8
 */
public interface StackAction
{

    /**
     * Invoked just before an object is to be pushed onto a digester stack.
     *
     * @param <T> whatever type is accepted
     * @param d is the digester instance.
     * @param stackName is the name of the stack onto which the object has been pushed. Null is passed to indicate the
     *            default stack.
     * @param o is the object that has just been pushed. Calling peek on the specified stack will return
     *        the same object.
     * @return the object to be pushed. Normally, parameter o is returned but this method could return an alternate
     *         object to be pushed instead (eg a proxy for the provided object).
     */
    <T> T onPush( Digester d, String stackName, T o );

    /**
     * Invoked just after an object has been popped from a digester stack.
     *
     * @param <T> whatever type is accepted
     * @param d is the digester instance.
     * @param stackName is the name of the stack from which the object has been popped. Null is passed to indicate the
     *            default stack.
     * @param o is the object that has just been popped.
     * @return the object to be returned to the called. Normally, parameter o is returned but this method could return
     *         an alternate object.
     */
    <T> T onPop( Digester d, String stackName, T o );

}