001package 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 */
042public 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}