1 /*
2 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25 package java.beans;
26
27 import java.io;
28 import java.util;
29 import java.lang.reflect;
30 import java.nio.charset.Charset;
31 import java.nio.charset.CharsetEncoder;
32 import java.nio.charset.IllegalCharsetNameException;
33 import java.nio.charset.UnsupportedCharsetException;
34
35 /**
36 * The <code>XMLEncoder</code> class is a complementary alternative to
37 * the <code>ObjectOutputStream</code> and can used to generate
38 * a textual representation of a <em>JavaBean</em> in the same
39 * way that the <code>ObjectOutputStream</code> can
40 * be used to create binary representation of <code>Serializable</code>
41 * objects. For example, the following fragment can be used to create
42 * a textual representation the supplied <em>JavaBean</em>
43 * and all its properties:
44 * <pre>
45 * XMLEncoder e = new XMLEncoder(
46 * new BufferedOutputStream(
47 * new FileOutputStream("Test.xml")));
48 * e.writeObject(new JButton("Hello, world"));
49 * e.close();
50 * </pre>
51 * Despite the similarity of their APIs, the <code>XMLEncoder</code>
52 * class is exclusively designed for the purpose of archiving graphs
53 * of <em>JavaBean</em>s as textual representations of their public
54 * properties. Like Java source files, documents written this way
55 * have a natural immunity to changes in the implementations of the classes
56 * involved. The <code>ObjectOutputStream</code> continues to be recommended
57 * for interprocess communication and general purpose serialization.
58 * <p>
59 * The <code>XMLEncoder</code> class provides a default denotation for
60 * <em>JavaBean</em>s in which they are represented as XML documents
61 * complying with version 1.0 of the XML specification and the
62 * UTF-8 character encoding of the Unicode/ISO 10646 character set.
63 * The XML documents produced by the <code>XMLEncoder</code> class are:
64 * <ul>
65 * <li>
66 * <em>Portable and version resilient</em>: they have no dependencies
67 * on the private implementation of any class and so, like Java source
68 * files, they may be exchanged between environments which may have
69 * different versions of some of the classes and between VMs from
70 * different vendors.
71 * <li>
72 * <em>Structurally compact</em>: The <code>XMLEncoder</code> class
73 * uses a <em>redundancy elimination</em> algorithm internally so that the
74 * default values of a Bean's properties are not written to the stream.
75 * <li>
76 * <em>Fault tolerant</em>: Non-structural errors in the file,
77 * caused either by damage to the file or by API changes
78 * made to classes in an archive remain localized
79 * so that a reader can report the error and continue to load the parts
80 * of the document which were not affected by the error.
81 * </ul>
82 * <p>
83 * Below is an example of an XML archive containing
84 * some user interface components from the <em>swing</em> toolkit:
85 * <pre>
86 * <?xml version="1.0" encoding="UTF-8"?>
87 * <java version="1.0" class="java.beans.XMLDecoder">
88 * <object class="javax.swing.JFrame">
89 * <void property="name">
90 * <string>frame1</string>
91 * </void>
92 * <void property="bounds">
93 * <object class="java.awt.Rectangle">
94 * <int>0</int>
95 * <int>0</int>
96 * <int>200</int>
97 * <int>200</int>
98 * </object>
99 * </void>
100 * <void property="contentPane">
101 * <void method="add">
102 * <object class="javax.swing.JButton">
103 * <void property="label">
104 * <string>Hello</string>
105 * </void>
106 * </object>
107 * </void>
108 * </void>
109 * <void property="visible">
110 * <boolean>true</boolean>
111 * </void>
112 * </object>
113 * </java>
114 * </pre>
115 * The XML syntax uses the following conventions:
116 * <ul>
117 * <li>
118 * Each element represents a method call.
119 * <li>
120 * The "object" tag denotes an <em>expression</em> whose value is
121 * to be used as the argument to the enclosing element.
122 * <li>
123 * The "void" tag denotes a <em>statement</em> which will
124 * be executed, but whose result will not be used as an
125 * argument to the enclosing method.
126 * <li>
127 * Elements which contain elements use those elements as arguments,
128 * unless they have the tag: "void".
129 * <li>
130 * The name of the method is denoted by the "method" attribute.
131 * <li>
132 * XML's standard "id" and "idref" attributes are used to make
133 * references to previous expressions - so as to deal with
134 * circularities in the object graph.
135 * <li>
136 * The "class" attribute is used to specify the target of a static
137 * method or constructor explicitly; its value being the fully
138 * qualified name of the class.
139 * <li>
140 * Elements with the "void" tag are executed using
141 * the outer context as the target if no target is defined
142 * by a "class" attribute.
143 * <li>
144 * Java's String class is treated specially and is
145 * written <string>Hello, world</string> where
146 * the characters of the string are converted to bytes
147 * using the UTF-8 character encoding.
148 * </ul>
149 * <p>
150 * Although all object graphs may be written using just these three
151 * tags, the following definitions are included so that common
152 * data structures can be expressed more concisely:
153 * <p>
154 * <ul>
155 * <li>
156 * The default method name is "new".
157 * <li>
158 * A reference to a java class is written in the form
159 * <class>javax.swing.JButton</class>.
160 * <li>
161 * Instances of the wrapper classes for Java's primitive types are written
162 * using the name of the primitive type as the tag. For example, an
163 * instance of the <code>Integer</code> class could be written:
164 * <int>123</int>. Note that the <code>XMLEncoder</code> class
165 * uses Java's reflection package in which the conversion between
166 * Java's primitive types and their associated "wrapper classes"
167 * is handled internally. The API for the <code>XMLEncoder</code> class
168 * itself deals only with <code>Object</code>s.
169 * <li>
170 * In an element representing a nullary method whose name
171 * starts with "get", the "method" attribute is replaced
172 * with a "property" attribute whose value is given by removing
173 * the "get" prefix and decapitalizing the result.
174 * <li>
175 * In an element representing a monadic method whose name
176 * starts with "set", the "method" attribute is replaced
177 * with a "property" attribute whose value is given by removing
178 * the "set" prefix and decapitalizing the result.
179 * <li>
180 * In an element representing a method named "get" taking one
181 * integer argument, the "method" attribute is replaced
182 * with an "index" attribute whose value the value of the
183 * first argument.
184 * <li>
185 * In an element representing a method named "set" taking two arguments,
186 * the first of which is an integer, the "method" attribute is replaced
187 * with an "index" attribute whose value the value of the
188 * first argument.
189 * <li>
190 * A reference to an array is written using the "array"
191 * tag. The "class" and "length" attributes specify the
192 * sub-type of the array and its length respectively.
193 * </ul>
194 *
195 *<p>
196 * For more information you might also want to check out
197 * <a
198 href="http://java.sun.com/products/jfc/tsc/articles/persistence4">Using XMLEncoder</a>,
199 * an article in <em>The Swing Connection.</em>
200 * @see XMLDecoder
201 * @see java.io.ObjectOutputStream
202 *
203 * @since 1.4
204 *
205 * @author Philip Milne
206 */
207 public class XMLEncoder extends Encoder {
208
209 private final CharsetEncoder encoder;
210 private final String charset;
211 private final boolean declaration;
212
213 private OutputStreamWriter out;
214 private Object owner;
215 private int indentation = 0;
216 private boolean internal = false;
217 private Map valueToExpression;
218 private Map targetToStatementList;
219 private boolean preambleWritten = false;
220 private NameGenerator nameGenerator;
221
222 private class ValueData {
223 public int refs = 0;
224 public boolean marked = false; // Marked -> refs > 0 unless ref was a target.
225 public String name = null;
226 public Expression exp = null;
227 }
228
229 /**
230 * Creates a new XML encoder to write out <em>JavaBeans</em>
231 * to the stream <code>out</code> using an XML encoding.
232 *
233 * @param out the stream to which the XML representation of
234 * the objects will be written
235 *
236 * @throws IllegalArgumentException
237 * if <code>out</code> is <code>null</code>
238 *
239 * @see XMLDecoder#XMLDecoder(InputStream)
240 */
241 public XMLEncoder(OutputStream out) {
242 this(out, "UTF-8", true, 0);
243 }
244
245 /**
246 * Creates a new XML encoder to write out <em>JavaBeans</em>
247 * to the stream <code>out</code> using the given <code>charset</code>
248 * starting from the given <code>indentation</code>.
249 *
250 * @param out the stream to which the XML representation of
251 * the objects will be written
252 * @param charset the name of the requested charset;
253 * may be either a canonical name or an alias
254 * @param declaration whether the XML declaration should be generated;
255 * set this to <code>false</code>
256 * when embedding the contents in another XML document
257 * @param indentation the number of space characters to indent the entire XML document by
258 *
259 * @throws IllegalArgumentException
260 * if <code>out</code> or <code>charset</code> is <code>null</code>,
261 * or if <code>indentation</code> is less than 0
262 *
263 * @throws IllegalCharsetNameException
264 * if <code>charset</code> name is illegal
265 *
266 * @throws UnsupportedCharsetException
267 * if no support for the named charset is available
268 * in this instance of the Java virtual machine
269 *
270 * @throws UnsupportedOperationException
271 * if loaded charset does not support encoding
272 *
273 * @see Charset#forName(String)
274 *
275 * @since 1.7
276 */
277 public XMLEncoder(OutputStream out, String charset, boolean declaration, int indentation) {
278 if (out == null) {
279 throw new IllegalArgumentException("the output stream cannot be null");
280 }
281 if (indentation < 0) {
282 throw new IllegalArgumentException("the indentation must be >= 0");
283 }
284 Charset cs = Charset.forName(charset);
285 this.encoder = cs.newEncoder();
286 this.charset = charset;
287 this.declaration = declaration;
288 this.indentation = indentation;
289 this.out = new OutputStreamWriter(out, cs.newEncoder());
290 valueToExpression = new IdentityHashMap();
291 targetToStatementList = new IdentityHashMap();
292 nameGenerator = new NameGenerator();
293 }
294
295 /**
296 * Sets the owner of this encoder to <code>owner</code>.
297 *
298 * @param owner The owner of this encoder.
299 *
300 * @see #getOwner
301 */
302 public void setOwner(Object owner) {
303 this.owner = owner;
304 writeExpression(new Expression(this, "getOwner", new Object[0]));
305 }
306
307 /**
308 * Gets the owner of this encoder.
309 *
310 * @return The owner of this encoder.
311 *
312 * @see #setOwner
313 */
314 public Object getOwner() {
315 return owner;
316 }
317
318 /**
319 * Write an XML representation of the specified object to the output.
320 *
321 * @param o The object to be written to the stream.
322 *
323 * @see XMLDecoder#readObject
324 */
325 public void writeObject(Object o) {
326 if (internal) {
327 super.writeObject(o);
328 }
329 else {
330 writeStatement(new Statement(this, "writeObject", new Object[]{o}));
331 }
332 }
333
334 private Vector statementList(Object target) {
335 Vector list = (Vector)targetToStatementList.get(target);
336 if (list != null) {
337 return list;
338 }
339 list = new Vector();
340 targetToStatementList.put(target, list);
341 return list;
342 }
343
344
345 private void mark(Object o, boolean isArgument) {
346 if (o == null || o == this) {
347 return;
348 }
349 ValueData d = getValueData(o);
350 Expression exp = d.exp;
351 // Do not mark liternal strings. Other strings, which might,
352 // for example, come from resource bundles should still be marked.
353 if (o.getClass() == String.class && exp == null) {
354 return;
355 }
356
357 // Bump the reference counts of all arguments
358 if (isArgument) {
359 d.refs++;
360 }
361 if (d.marked) {
362 return;
363 }
364 d.marked = true;
365 Object target = exp.getTarget();
366 if (!(target instanceof Class)) {
367 statementList(target).add(exp);
368 // Pending: Why does the reference count need to
369 // be incremented here?
370 d.refs++;
371 }
372 mark(exp);
373 }
374
375 private void mark(Statement stm) {
376 Object[] args = stm.getArguments();
377 for (int i = 0; i < args.length; i++) {
378 Object arg = args[i];
379 mark(arg, true);
380 }
381 mark(stm.getTarget(), false);
382 }
383
384
385 /**
386 * Records the Statement so that the Encoder will
387 * produce the actual output when the stream is flushed.
388 * <P>
389 * This method should only be invoked within the context
390 * of initializing a persistence delegate.
391 *
392 * @param oldStm The statement that will be written
393 * to the stream.
394 * @see java.beans.PersistenceDelegate#initialize
395 */
396 public void writeStatement(Statement oldStm) {
397 // System.out.println("XMLEncoder::writeStatement: " + oldStm);
398 boolean internal = this.internal;
399 this.internal = true;
400 try {
401 super.writeStatement(oldStm);
402 /*
403 Note we must do the mark first as we may
404 require the results of previous values in
405 this context for this statement.
406 Test case is:
407 os.setOwner(this);
408 os.writeObject(this);
409 */
410 mark(oldStm);
411 statementList(oldStm.getTarget()).add(oldStm);
412 }
413 catch (Exception e) {
414 getExceptionListener().exceptionThrown(new Exception("XMLEncoder: discarding statement " + oldStm, e));
415 }
416 this.internal = internal;
417 }
418
419
420 /**
421 * Records the Expression so that the Encoder will
422 * produce the actual output when the stream is flushed.
423 * <P>
424 * This method should only be invoked within the context of
425 * initializing a persistence delegate or setting up an encoder to
426 * read from a resource bundle.
427 * <P>
428 * For more information about using resource bundles with the
429 * XMLEncoder, see
430 * http://java.sun.com/products/jfc/tsc/articles/persistence4/#i18n
431 *
432 * @param oldExp The expression that will be written
433 * to the stream.
434 * @see java.beans.PersistenceDelegate#initialize
435 */
436 public void writeExpression(Expression oldExp) {
437 boolean internal = this.internal;
438 this.internal = true;
439 Object oldValue = getValue(oldExp);
440 if (get(oldValue) == null || (oldValue instanceof String && !internal)) {
441 getValueData(oldValue).exp = oldExp;
442 super.writeExpression(oldExp);
443 }
444 this.internal = internal;
445 }
446
447 /**
448 * This method writes out the preamble associated with the
449 * XML encoding if it has not been written already and
450 * then writes out all of the values that been
451 * written to the stream since the last time <code>flush</code>
452 * was called. After flushing, all internal references to the
453 * values that were written to this stream are cleared.
454 */
455 public void flush() {
456 if (!preambleWritten) { // Don't do this in constructor - it throws ... pending.
457 if (this.declaration) {
458 writeln("<?xml version=" + quote("1.0") +
459 " encoding=" + quote(this.charset) + "?>");
460 }
461 writeln("<java version=" + quote(System.getProperty("java.version")) +
462 " class=" + quote(XMLDecoder.class.getName()) + ">");
463 preambleWritten = true;
464 }
465 indentation++;
466 Vector roots = statementList(this);
467 for(int i = 0; i < roots.size(); i++) {
468 Statement s = (Statement)roots.get(i);
469 if ("writeObject".equals(s.getMethodName())) {
470 outputValue(s.getArguments()[0], this, true);
471 }
472 else {
473 outputStatement(s, this, false);
474 }
475 }
476 indentation--;
477
478 try {
479 out.flush();
480 }
481 catch (IOException e) {
482 getExceptionListener().exceptionThrown(e);
483 }
484 clear();
485 }
486
487 void clear() {
488 super.clear();
489 nameGenerator.clear();
490 valueToExpression.clear();
491 targetToStatementList.clear();
492 }
493
494
495 /**
496 * This method calls <code>flush</code>, writes the closing
497 * postamble and then closes the output stream associated
498 * with this stream.
499 */
500 public void close() {
501 flush();
502 writeln("</java>");
503 try {
504 out.close();
505 }
506 catch (IOException e) {
507 getExceptionListener().exceptionThrown(e);
508 }
509 }
510
511 private String quote(String s) {
512 return "\"" + s + "\"";
513 }
514
515 private ValueData getValueData(Object o) {
516 ValueData d = (ValueData)valueToExpression.get(o);
517 if (d == null) {
518 d = new ValueData();
519 valueToExpression.put(o, d);
520 }
521 return d;
522 }
523
524 /**
525 * Returns <code>true</code> if the argument,
526 * a Unicode code point, is valid in XML documents.
527 * Unicode characters fit into the low sixteen bits of a Unicode code point,
528 * and pairs of Unicode <em>surrogate characters</em> can be combined
529 * to encode Unicode code point in documents containing only Unicode.
530 * (The <code>char</code> datatype in the Java Programming Language
531 * represents Unicode characters, including unpaired surrogates.)
532 * <par>
533 * [2] Char ::= #x0009 | #x000A | #x000D
534 * | [#x0020-#xD7FF]
535 * | [#xE000-#xFFFD]
536 * | [#x10000-#x10ffff]
537 * </par>
538 *
539 * @param code the 32-bit Unicode code point being tested
540 * @return <code>true</code> if the Unicode code point is valid,
541 * <code>false</code> otherwise
542 */
543 private static boolean isValidCharCode(int code) {
544 return (0x0020 <= code && code <= 0xD7FF)
545 || (0x000A == code)
546 || (0x0009 == code)
547 || (0x000D == code)
548 || (0xE000 <= code && code <= 0xFFFD)
549 || (0x10000 <= code && code <= 0x10ffff);
550 }
551
552 private void writeln(String exp) {
553 try {
554 StringBuilder sb = new StringBuilder();
555 for(int i = 0; i < indentation; i++) {
556 sb.append(' ');
557 }
558 sb.append(exp);
559 sb.append('\n');
560 this.out.write(sb.toString());
561 }
562 catch (IOException e) {
563 getExceptionListener().exceptionThrown(e);
564 }
565 }
566
567 private void outputValue(Object value, Object outer, boolean isArgument) {
568 if (value == null) {
569 writeln("<null/>");
570 return;
571 }
572
573 if (value instanceof Class) {
574 writeln("<class>" + ((Class)value).getName() + "</class>");
575 return;
576 }
577
578 ValueData d = getValueData(value);
579 if (d.exp != null) {
580 Object target = d.exp.getTarget();
581 String methodName = d.exp.getMethodName();
582
583 if (target == null || methodName == null) {
584 throw new NullPointerException((target == null ? "target" :
585 "methodName") + " should not be null");
586 }
587
588 if (target instanceof Field && methodName.equals("get")) {
589 Field f = (Field)target;
590 writeln("<object class=" + quote(f.getDeclaringClass().getName()) +
591 " field=" + quote(f.getName()) + "/>");
592 return;
593 }
594
595 Class primitiveType = ReflectionUtils.primitiveTypeFor(value.getClass());
596 if (primitiveType != null && target == value.getClass() &&
597 methodName.equals("new")) {
598 String primitiveTypeName = primitiveType.getName();
599 // Make sure that character types are quoted correctly.
600 if (primitiveType == Character.TYPE) {
601 char code = ((Character) value).charValue();
602 if (!isValidCharCode(code)) {
603 writeln(createString(code));
604 return;
605 }
606 value = quoteCharCode(code);
607 if (value == null) {
608 value = Character.valueOf(code);
609 }
610 }
611 writeln("<" + primitiveTypeName + ">" + value + "</" +
612 primitiveTypeName + ">");
613 return;
614 }
615
616 } else if (value instanceof String) {
617 writeln(createString((String) value));
618 return;
619 }
620
621 if (d.name != null) {
622 writeln("<object idref=" + quote(d.name) + "/>");
623 return;
624 }
625
626 outputStatement(d.exp, outer, isArgument);
627 }
628
629 private static String quoteCharCode(int code) {
630 switch(code) {
631 case '&': return "&";
632 case '<': return "<";
633 case '>': return ">";
634 case '"': return """;
635 case '\'': return "'";
636 case '\r': return " ";
637 default: return null;
638 }
639 }
640
641 private static String createString(int code) {
642 return "<char code=\"#" + Integer.toString(code, 16) + "\"/>";
643 }
644
645 private String createString(String string) {
646 StringBuilder sb = new StringBuilder();
647 sb.append("<string>");
648 int index = 0;
649 while (index < string.length()) {
650 int point = string.codePointAt(index);
651 int count = Character.charCount(point);
652
653 if (isValidCharCode(point) && this.encoder.canEncode(string.substring(index, index + count))) {
654 String value = quoteCharCode(point);
655 if (value != null) {
656 sb.append(value);
657 } else {
658 sb.appendCodePoint(point);
659 }
660 index += count;
661 } else {
662 sb.append(createString(string.charAt(index)));
663 index++;
664 }
665 }
666 sb.append("</string>");
667 return sb.toString();
668 }
669
670 private void outputStatement(Statement exp, Object outer, boolean isArgument) {
671 Object target = exp.getTarget();
672 String methodName = exp.getMethodName();
673
674 if (target == null || methodName == null) {
675 throw new NullPointerException((target == null ? "target" :
676 "methodName") + " should not be null");
677 }
678
679 Object[] args = exp.getArguments();
680 boolean expression = exp.getClass() == Expression.class;
681 Object value = (expression) ? getValue((Expression)exp) : null;
682
683 String tag = (expression && isArgument) ? "object" : "void";
684 String attributes = "";
685 ValueData d = getValueData(value);
686 if (expression) {
687 if (d.refs > 1) {
688 String instanceName = nameGenerator.instanceName(value);
689 d.name = instanceName;
690 attributes = attributes + " id=" + quote(instanceName);
691 }
692 }
693
694 // Special cases for targets.
695 if (target == outer) {
696 }
697 else if (target == Array.class && methodName.equals("newInstance")) {
698 tag = "array";
699 attributes = attributes + " class=" + quote(((Class)args[0]).getName());
700 attributes = attributes + " length=" + quote(args[1].toString());
701 args = new Object[]{};
702 }
703 else if (target.getClass() == Class.class) {
704 attributes = attributes + " class=" + quote(((Class)target).getName());
705 }
706 else {
707 d.refs = 2;
708 getValueData(target).refs++;
709 outputValue(target, outer, false);
710 if (isArgument) {
711 outputValue(value, outer, false);
712 }
713 return;
714 }
715
716
717 // Special cases for methods.
718 if ((!expression && methodName.equals("set") && args.length == 2 &&
719 args[0] instanceof Integer) ||
720 (expression && methodName.equals("get") && args.length == 1 &&
721 args[0] instanceof Integer)) {
722 attributes = attributes + " index=" + quote(args[0].toString());
723 args = (args.length == 1) ? new Object[]{} : new Object[]{args[1]};
724 }
725 else if ((!expression && methodName.startsWith("set") && args.length == 1) ||
726 (expression && methodName.startsWith("get") && args.length == 0)) {
727 attributes = attributes + " property=" +
728 quote(Introspector.decapitalize(methodName.substring(3)));
729 }
730 else if (!methodName.equals("new") && !methodName.equals("newInstance")) {
731 attributes = attributes + " method=" + quote(methodName);
732 }
733
734 Vector statements = statementList(value);
735 // Use XML's short form when there is no body.
736 if (args.length == 0 && statements.size() == 0) {
737 writeln("<" + tag + attributes + "/>");
738 return;
739 }
740
741 writeln("<" + tag + attributes + ">");
742 indentation++;
743
744 for(int i = 0; i < args.length; i++) {
745 outputValue(args[i], null, true);
746 }
747
748 for(int i = 0; i < statements.size(); i++) {
749 Statement s = (Statement)statements.get(i);
750 outputStatement(s, value, false);
751 }
752
753 indentation--;
754 writeln("</" + tag + ">");
755 }
756 }
Save This Page