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 }