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 }