View Javadoc

1   /*
2   
3       stax  Stack API for XML.
4       Copyright (c) 2001-2006 held jointly by the individual authors.
5   
6       This library is free software; you can redistribute it and/or modify it
7       under the terms of the GNU Lesser General Public License as published
8       by the Free Software Foundation; either version 2.1 of the License, or (at
9       your option) any later version.
10  
11      This library is distributed in the hope that it will be useful, but WITHOUT
12      ANY WARRANTY; with out even the implied warranty of MERCHANTABILITY or
13      FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
14      License for more details.
15  
16      You should have received a copy of the GNU Lesser General Public License
17      along with this library;  if not, write to the Free Software Foundation,
18      Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA.
19  
20      > http://www.gnu.org/copyleft/lesser.html
21      > http://www.opensource.org/licenses/lgpl-license.php
22  
23  */
24  package net.sf.stax;
25  
26  import org.xml.sax.SAXException;
27  
28  /***
29   * The callback interface for those interested in ids.
30   * <p>
31   * An IdMapper may have any number of IdListeners registered. As ids become
32   * associated with objects during parsing, the IdMapper will call <code>idRegistered(Object,
33   * Object)</code> on all listeners interested in the id.</p>
34   * <p>
35   * There is no reason to believe that the IdListener will be informed at the
36   * earliest possible time that the id is known, but it will always be informed
37   * before the StAX stream has been fully processed.</p>
38   * <p>
39   * For example, given an xml document
40   * <pre>
41   * &lt;?xml version=&quot;1.0&quot; ?&gt;
42   * &lt;foo&gt;
43   *   &lt;bar_ref id=&quot;0&quot; /&gt;
44   *
45   *   &lt;bar id=&quot;0&quot; /&gt;
46   *   &lt;bar id=&quot;1&quot; /&gt;
47   *
48   *   &lt;bar_ref id=&quot;1&quot; /&gt;
49   * &lt;foo&gt;
50   * </pre>
51   *
52   * You can handle normal elements (bar) and reference elements (bar_ref) with
53   * <pre>
54   * class FooHandler
55   *     extends StAXContentHandlerBase
56   * {
57   *     private List results = new ArrayList();
58   *
59   *     public void startElement(..., StAXDelegationContext dctx)
60   *     {
61   *         if ("bar".equals(qName))
62   *         {
63   *             dctx.delegate(barHandler);
64   *         }
65   *         else if ("bar_ref".equals(qName))
66   *         {
67   *             dctx.delegate(barRefHandler);
68   *         }
69   *     }
70   *
71   *     class BarHandler
72   *         extends StAXContentHandlerBase
73   *     {
74   *         private Bar bar;
75   *
76   *         public void startTree(StAXContext ctx) { bar = new Bar(); }
77   *
78   *         public void startElement(..., StAXDelegationContext dctx)
79   *         {
80   *             if ("bar".equals(qName))
81   *             {
82   *                 // ...
83   *                 IdMapper mapper = dctx.getIdMapper();
84   *                 mapper.registerItemForId(attrs.getValue("id"), bar);
85   *             }
86   *         }
87   *
88   *         public void endElement(...)
89   *         {
90   *             if ("bar".equals(qName))
91   *                 results.add(bar);
92   *         }
93   *     }
94   *
95   *     class BarRefHandler
96   *         extends StAXContentHandlerBase
97   *     {
98   *         private Bar bar;
99   *
100  *         public void startElement(..., StAXDelegationContext dctx)
101  *         {
102  *             if ("bar".equals(qName))
103  *             {
104  *                 final String barRefId = attrs.getValue("id");
105  *
106  *                 IdMapper mapper = dctx.getIdMapper();
107  *                 mapper.addIdListener(new IdListener()
108  *                     {
109  *                         public void idRegistered(Object id, Object item)
110  *                         {
111  *                             if ((barRefId.equals(id)) && (item instanceof Bar))
112  *                             {
113  *                                 bar = (Bar) item;
114  *                                 results.add(bar);
115  *                             }
116  *                         }
117  *                     });
118  *             }
119  *         }
120  *     }
121  * }
122  * </pre>
123  * </p>
124  *
125  * @author  Matthew Pocock
126  * @author  Michael Heuer
127  * @version $Revision: 1.2 $ $Date: 2006/01/02 20:37:34 $
128  */
129 public interface IdListener
130 {
131 
132     /***
133      * Notify this listener that the specified id has been
134      * associated with the specified item.
135      *
136      * @param id the id of the bound object
137      * @param item the item that has been registered for this id
138      * @throws SAXException any SAX exception, possibly wrapping another exception
139      */
140     void idRegistered(Object id, Object item)
141         throws SAXException;
142 }
143 
144