View Javadoc

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  }