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 * An encapsulation of the process of mapping XML ids to java objects.
30 * <p>
31 * Ids can occur in an XML document before or after the point at which they are
32 * referenced. An IdMapper keeps track of the currently available mappings so
33 * that handlers can fix up object graphs as objects are bound to ids.</p>
34 * <p>
35 * For example, given an xml document
36 * <pre>
37 * <?xml version="1.0" ?>
38 * <foo>
39 * <bar_ref id="0" />
40 *
41 * <bar id="0" />
42 * <bar id="1" />
43 *
44 * <bar_ref id="1" />
45 * <foo>
46 * </pre>
47 *
48 * You can handle normal elements (bar) and reference elements (bar_ref) with
49 * <pre>
50 * class FooHandler
51 * extends StAXContentHandlerBase
52 * {
53 * private List results = new ArrayList();
54 *
55 * public void startElement(..., StAXDelegationContext dctx)
56 * {
57 * if ("bar".equals(qName))
58 * {
59 * dctx.delegate(barHandler);
60 * }
61 * else if ("bar_ref".equals(qName))
62 * {
63 * dctx.delegate(barRefHandler);
64 * }
65 * }
66 *
67 * class BarHandler
68 * extends StAXContentHandlerBase
69 * {
70 * private Bar bar;
71 *
72 * public void startTree(StAXContext ctx) { bar = new Bar(); }
73 *
74 * public void startElement(..., StAXDelegationContext dctx)
75 * {
76 * if ("bar".equals(qName))
77 * {
78 * // ...
79 * IdMapper mapper = dctx.getIdMapper();
80 * mapper.registerItemForId(attrs.getValue("id"), bar);
81 * }
82 * }
83 *
84 * public void endElement(...)
85 * {
86 * if ("bar".equals(qName))
87 * results.add(bar);
88 * }
89 * }
90 *
91 * class BarRefHandler
92 * extends StAXContentHandlerBase
93 * {
94 * private Bar bar;
95 *
96 * public void startElement(..., StAXDelegationContext dctx)
97 * {
98 * if ("bar".equals(qName))
99 * {
100 * final String barRefId = attrs.getValue("id");
101 *
102 * IdMapper mapper = dctx.getIdMapper();
103 * mapper.addIdListener(new IdListener()
104 * {
105 * public void idRegistered(Object id, Object item)
106 * {
107 * if ((barRefId.equals(id)) && (item instanceof Bar))
108 * {
109 * bar = (Bar) item;
110 * results.add(bar);
111 * }
112 * }
113 * });
114 * }
115 * }
116 * }
117 * }
118 * </pre>
119 * </p>
120 *
121 * @author Matthew Pocock
122 * @author Michael Heuer
123 * @version $Revision: 1.2 $ $Date: 2006/01/02 20:37:34 $
124 */
125 public interface IdMapper
126 {
127
128 /***
129 * Bind an id to an item.
130 * <p>
131 * All listeners that have previously been registered for this id will be
132 * informed that the id is now bound. All future listeners will be informed
133 * that the id is bound before the stream stops parsing.</p>
134 *
135 * @param id the id of the bound object
136 * @param item the item to register for this id
137 * @throws SAXException if the id has previously been bound
138 */
139 void registerItemForId(Object id, Object item)
140 throws SAXException;
141
142 /***
143 * Add a listener for all ids.
144 * <p>
145 * The listener will be informed of all id events, past and future for the
146 * complete parse of the StAX stream. This may happen as each id is found, or
147 * all together after the whole StAX stream has been parsed.</p>
148 *
149 * @param listener the IdListener to add
150 * @throws SAXException if the id has previously been bound
151 */
152 void addIdListener(IdListener listener)
153 throws SAXException;
154
155 /***
156 * Remove a listener for all ids.
157 *
158 * @param listener the IdListener to remove
159 * @throws SAXException any SAX exception, possibly wrapping another exception
160 */
161 void removeIdListener(IdListener listener)
162 throws SAXException;
163
164 /***
165 * Add a listener for a specific id.
166 * <P>
167 * The listener will be informed exactly once of an item associated with this
168 * id. This may happen on registration, as the id is bound, or after the whole
169 * StAX stream has been parsed.
170 *
171 * @param listener the IdListener to register
172 * @param id the that the listener is interested in
173 * @throws SAXException any SAX exception, possibly wrapping another exception
174 */
175 void addIdListener(IdListener listener, Object id)
176 throws SAXException;
177
178 /***
179 * Remove a listener for a specific id.
180 *
181 * @param listener the IdListener to remove
182 * @param id the id that the listener was interested in
183 * @throws SAXException any SAX exception, possibly wrapping another exception
184 */
185 void removeIdListener(IdListener listener, Object id)
186 throws SAXException;
187 }