1 /*-------------------------------------------------------------------------
2 Copyright 2006 Olivier Berlanger
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 -------------------------------------------------------------------------*/
16 package net.sf.xolite;
17
18
19 /**
20 * Interface of support object used to serialize XMLSerializable objects to XML. <br>
21 * The XMLSerializable tells what to generate to this XMLSerializer using events similar to SAX events. So, this interface is
22 * similar to the org.xml.sax.ContentHandler interface. It's simply because this interface does similar job as SAX
23 * ContentHandler but just in the other direction (serialize from java objects to a stream). Fortunately, using the event-based
24 * SAX model is very easy when you are on the provider part. So, interacting with this XMLSerializer is pretty straightforward.
25 * <p>
26 * You can also view this interface as a Visitor pattern specialized for XML. This object plays the "visitor" role while objects
27 * implementing the <code>XMLSerializable</code> interface play the role of "element" and the "accept" method is called
28 * <code>serialize</code>.
29 * </p>
30 */
31 public interface XMLSerializer {
32
33
34 /**
35 * Start an XML document.
36 */
37 public void startDocument() throws XMLSerializeException;
38
39
40 /**
41 * Define a prefix mapping. This method associate the given prefix to the given namespace. So when a node of the given
42 * namespace will be serialized, the given prefix will be used to denote the namespace (and the prefix declaration will be
43 * inserted when necessary).
44 * <p>
45 * This method should be called for each namespace URI before the first time they are used.
46 * </p>
47 * <p>
48 * If the given namespace is already associated to another prefix (or the same prefix), this method call is ignored (i.e.
49 * first association wins).
50 * </p>
51 * <p>
52 * If the given prefix is already associated to an other namespace, a new prefix is generated and mapped at the place of the
53 * given one.
54 * </p>
55 *
56 * @param prefix
57 * a prefix (can be "" for default prefix mapping)
58 * @param namespaceUri
59 * a namespace URI
60 * @throws XMLSerializeException
61 * if prefix or namespaceUri is null or if required action cannot be done (implementation dependent).
62 */
63 public void startPrefixMapping(String prefix, String namespaceUri) throws XMLSerializeException;
64
65
66 /**
67 * Start an XML element.
68 *
69 * @param namespaceUri
70 * The element namespace URI (can be null if namespace are not used)
71 * @param localName
72 * The element local name (a.k.a. NCName)
73 * @throws XMLSerializeException
74 * if required action cannot be done (implementation dependent).
75 */
76 public void startElement(String namespaceUri, String localName) throws XMLSerializeException;
77
78
79 /**
80 * Add an attribute to the element that was just started. All the call to this method must immediately follow a
81 * <code>startElement</code> call. attribute. This attribute use no namespace.
82 *
83 * @param localName
84 * The attribute local name (a.k.a. NCName)
85 * @param value
86 * the attribute value (null is treated as empty string).
87 * @throws XMLSerializeException
88 * if you don't call this method just after <code>startElement</code> or if required action cannot be done
89 * (implementation dependent).
90 */
91 public void attribute(String localName, String value) throws XMLSerializeException;
92
93
94 /**
95 * Add an attribute to the element that was just started. All the call to this method must immediately follow a
96 * <code>startElement</code> call. attribute
97 *
98 * @param namespaceUri
99 * The attribute namespace URI. This URI is usually null because most of the time, attributes don't use a
100 * namespace.
101 * @param localName
102 * The attribute local name (a.k.a. NCName)
103 * @param value
104 * the attribute value (null is treated as empty string).
105 * @throws XMLSerializeException
106 * if you don't call this method just after <code>startElement</code> or if required action cannot be done
107 * (implementation dependent).
108 */
109 public void attribute(String namespaceUri, String localName, String value) throws XMLSerializeException;
110
111
112 /**
113 * End an XML element.
114 *
115 * @param namespaceUri
116 * The element namespace URI (can be null if namespace are not used)
117 * @param localName
118 * The element local name (a.k.a. NCName)
119 * @throws XMLSerializeException
120 * if required action cannot be done (implementation dependent).
121 */
122 public void endElement(String namespaceUri, String localName) throws XMLSerializeException;
123
124
125 /**
126 * Add character content of an element. This method must be called between <code>startElement</code> (possibly followed by
127 * <code>attribute</code>) and <code>endElement</code>. If this method is called several times for the same element, the
128 * texts are concatenated.
129 *
130 * @param text
131 * text of the currently started element.
132 * @throws XMLSerializeException
133 * if you don't call this method just beteween <code>startElement</code> and <code>endElement</code> or if
134 * required action cannot be done (implementation dependent).
135 */
136 public void characters(String text) throws XMLSerializeException;
137
138
139 /**
140 * Same as characters but the text (supposed to be multi-line) is formatted to be an indented text block. <br>
141 * The result will look like:
142 *
143 * <pre>
144 * <tag>
145 * some text
146 * spanning multiple
147 * lines.
148 * </tag>
149 * </pre>
150 *
151 * While usual output would have given:
152 *
153 * <pre>
154 * <tag>some text
155 * spanning multiple
156 * lines.</tag>
157 * </pre>
158 *
159 * The original text can be retrieved (when parsing) with the <code>ElementText.getMultilineText(..)</code> method. This
160 * method will automatically remove the added space.
161 *
162 * @param text
163 * the text to serialize in XML
164 * @throws XMLSerializeException
165 * @see ElementText#getMultilineText(String, XMLEventParser)
166 */
167 public void charactersMultiLine(String text) throws XMLSerializeException;
168
169
170 /**
171 * This is a helper method useful to add a simpleType element in one call. It is strictly equivalent to the following
172 * sequence:
173 *
174 * <pre>
175 * startElement(namespaceUri, localName);
176 * characters(text);
177 * endElement(namespaceUri, localName);
178 * </pre>
179 *
180 * @param namespaceUri
181 * The element namespace URI (can be null if namespace are not used)
182 * @param localName
183 * The element local name (a.k.a. NCName)
184 * @param text
185 * text of the element.
186 * @throws XMLSerializeException
187 */
188 public void simpleElement(String namespaceUri, String localName, String text) throws XMLSerializeException;
189
190
191 /**
192 * End the current XML document.
193 */
194 public void endDocument() throws XMLSerializeException;
195
196
197 /**
198 * Put a custom object in an internal Map. <br>
199 * It can be retrieved later with <code>getCustomObject(key)</code> method.
200 *
201 * @param key
202 * key of the custom object.
203 * @param value
204 * custom object.
205 */
206 public void putCustomObject(Object key, Object value);
207
208
209 /**
210 * Get back any custom object that was put in with the <code>putCustomObject(key, value)</code> method.
211 *
212 * @param key
213 * key of the custom object.
214 * @return the custom object.
215 */
216 public Object getCustomObject(Object key);
217
218
219 }