1 package org.apache.commons.digester3; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 /** 23 * An interface that can be implemented in order to get notifications of objects being pushed onto a digester stack or 24 * popped from one. 25 * <p> 26 * Because objects are pushed onto the main object stack when a rule has created a new object, this gives the ability to 27 * intercept such operations and perform modifications on created objects. 28 * <p> 29 * One use expected for this interface is to store information about the xml line that a particular object was created 30 * from. An implementation of this interface can detect whenever an object is pushed onto the digester object stack, 31 * call Digester.getDocumentLocator() to get the location within the current xml file, and store this either on the 32 * object on the stack (if it supports some user-specific interface for this purpose), or build a map of 33 * (object->locationinfo) separately. 34 * <p> 35 * It is recommended that objects implementing this interface provide a method to set a "next" action, and invoke it 36 * from the callback methods. This allows multiple actions to be "chained" together. 37 * <p> 38 * See also Digester.setStackAction. 39 * 40 * @since 1.8 41 */ 42 public interface StackAction 43 { 44 45 /** 46 * Invoked just before an object is to be pushed onto a digester stack. 47 * 48 * @param <T> whatever type is accepted 49 * @param d is the digester instance. 50 * @param stackName is the name of the stack onto which the object has been pushed. Null is passed to indicate the 51 * default stack. 52 * @param o is the object that has just been pushed. Calling peek on the specified stack will return 53 * the same object. 54 * @return the object to be pushed. Normally, parameter o is returned but this method could return an alternate 55 * object to be pushed instead (eg a proxy for the provided object). 56 */ 57 <T> T onPush( Digester d, String stackName, T o ); 58 59 /** 60 * Invoked just after an object has been popped from a digester stack. 61 * 62 * @param <T> whatever type is accepted 63 * @param d is the digester instance. 64 * @param stackName is the name of the stack from which the object has been popped. Null is passed to indicate the 65 * default stack. 66 * @param o is the object that has just been popped. 67 * @return the object to be returned to the called. Normally, parameter o is returned but this method could return 68 * an alternate object. 69 */ 70 <T> T onPop( Digester d, String stackName, T o ); 71 72 }