    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    }