com.ocpsoft.shade.org.apache.commons.digester.StackAction Maven / Gradle / Ivy
/* $Id: StackAction.java 476205 2006-11-17 16:43:10Z dennisl $
*
* 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.
*/
package org.apache.commons.digester;
/**
* 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
*/
public interface StackAction {
/**
* Invoked just before an object is to be pushed onto a digester stack.
*
* @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).
*/
public Object onPush(Digester d, String stackName, Object o);
/**
* Invoked just after an object has been popped from a digester stack.
*
* @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.
*/
public Object onPop(Digester d, String stackName, Object o);
}