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