1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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 * <?xml version="1.0" ?>
42 * <foo>
43 * <bar_ref id="0" />
44 *
45 * <bar id="0" />
46 * <bar id="1" />
47 *
48 * <bar_ref id="1" />
49 * <foo>
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