http://commons.apache.org/digester/: The Apache Commons Digester package lets you configure an XML to Java object mapping module which triggers certain actions called rules whenever a particular pattern of nested XML elements is recognized. (The Apache Software Foundation)
  • Bradley M. Handy
  • Christopher Lenz
  • Ted Husted
  • David H. Martin
  • Henri Chen
  • Janek Bogucki
  • Mark Huisman
  • Paul Jack
  • Anton Maslovsky
  • Matt Cleveland
  • Gabriele Carcassi
  • Wendy Smoak
  • Kevin Ross
  • Daniele Testa
  • Craig McClanahan
  • Robert Burrell Donkin
  • Scott Sanders
  • James Strachan
  • Jason van Zyl
  • Tim OBrien
  • Jean-Francois Arcand
  • Simon Kitching
  • Rahul Akolkar
  • Simone Tripodi
  • Matt Benson 
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.


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.


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.


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.


See also Digester.setStackAction.

Since:1.8
/**
 * 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.

Params:
  • d – is the digester instance.
  • stackName – is the name of the stack onto which the object has been pushed. Null is passed to indicate the
           default stack.
  • o – is the object that has just been pushed. Calling peek on the specified stack will return
       the same object.
Type parameters:
  • <T> – whatever type is accepted
Returns: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).
/**
     * 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.

Params:
  • d – is the digester instance.
  • stackName – is the name of the stack from which the object has been popped. Null is passed to indicate the
           default stack.
  • o – is the object that has just been popped.
Type parameters:
  • <T> – whatever type is accepted
Returns:the object to be returned to the called. Normally, parameter o is returned but this method could return
        an alternate object.
/**
     * 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 );

}