View Javadoc
1   /*
2    * Copyright 2008 Joachim Grueneis
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  package org.castor.xml;
15  
16  import org.exolab.castor.xml.Unmarshaller;
17  
18  /**
19   * An interface to allow external "listening" to objects when they are being unmarshalled for
20   * various tracking purposes and potential modification. An implementation of this interface may be
21   * registered with the Unmarshaller.<br/>
22   * This is already a new version of this interface with enhanced callback methods. The orginial
23   * implementation still exists but is deprecated {@link org.exolab.castor.xml.UnmarshalListener}.
24   * <p/>
25   * The UnmarshalListener interface does <em>not</em> report on native data types that are
26   * unmarshalled.
27   * <p/>
28   * The first definition of this interface was by <a href="mailto:paul@priorartisans.com">Paul
29   * Christmann</a>, <a href="mailto:kvsico@intalio.com">Keith Visco</a> and
30   * <a href="mailto:blandin@intalio.com">Arnaud Blandin</a>.
31   * 
32   * @author Joachim Grueneis, jgrueneis AT codehaus DOT org
33   * @version $Revision$
34   * @since 1.2
35   */
36  public interface UnmarshalListener {
37  
38    /**
39     * This method is called when an object has just been initialized by the {@link Unmarshaller}.
40     *
41     * @param target the Object that was initialized.
42     * @param parent the parent of the target that was initialized
43     */
44    void initialized(final Object target, final Object parent);
45  
46    /**
47     * This method is called once the attributes have been processed. It indicates that the the fields
48     * of the given object corresponding to attributes in the XML document have been set.
49     *
50     * @param target the Object the object being unmarshalled.
51     * @param parent the parent of the target being unmarshalled
52     */
53    void attributesProcessed(final Object target, final Object parent);
54  
55    /**
56     * This method is called after a child object has been added during the unmarshalling. This method
57     * will be called after {@link #unmarshalled(Object)} has been called for the child.
58     *
59     * @param fieldName The Name of the field the child is being added to.
60     * @param parent The Object being unmarshalled.
61     * @param child The Object that was just added.
62     */
63    void fieldAdded(String fieldName, Object parent, Object child);
64  
65    /**
66     * This method is called after an object has been completely unmarshalled, including all of its
67     * children (if any).
68     *
69     * @param target the Object that was unmarshalled.
70     * @param parent the parent of the target that was unmarshalled
71     */
72    void unmarshalled(final Object target, final Object parent);
73  }