doc
[nikiroo-utils.git] / Exporter.java
... / ...
CommitLineData
1package be.nikiroo.utils.serial;
2
3import java.io.IOException;
4import java.io.NotSerializableException;
5import java.util.HashMap;
6import java.util.Map;
7
8import be.nikiroo.utils.StringUtils;
9
10/**
11 * A simple class to serialise objects to {@link String}.
12 * <p>
13 * This class does not support inner classes (it does support nested classes,
14 * though).
15 *
16 * @author niki
17 */
18public class Exporter {
19 private Map<Integer, Object> map;
20 private StringBuilder builder;
21
22 /**
23 * Create a new {@link Exporter}.
24 */
25 public Exporter() {
26 map = new HashMap<Integer, Object>();
27 builder = new StringBuilder();
28 }
29
30 /**
31 * Serialise the given object and add it to the list.
32 * <p>
33 * <b>Important: </b>If the operation fails (with a
34 * {@link NotSerializableException}), the {@link Exporter} will be corrupted
35 * (will contain bad, most probably not importable data).
36 *
37 * @param o
38 * the object to serialise
39 * @return this (for easier appending of multiple values)
40 *
41 * @throws NotSerializableException
42 * if the object cannot be serialised (in this case, the
43 * {@link Exporter} can contain bad, most probably not
44 * importable data)
45 */
46 public Exporter append(Object o) throws NotSerializableException {
47 SerialUtils.append(builder, o, map);
48 return this;
49 }
50
51 /**
52 * Clear the current content.
53 */
54 public void clear() {
55 builder.setLength(0);
56 map.clear();
57 }
58
59 /**
60 * Append the exported items in a serialised form into the given
61 * {@link StringBuilder}.
62 *
63 * @param toBuilder
64 * the {@link StringBuilder}
65 * @param b64
66 * TRUE to have BASE64-coded content, FALSE to have raw content,
67 * NULL to let the system decide
68 * @param zip
69 * TRUE to zip the BASE64 output if the output is indeed in
70 * BASE64 format, FALSE not to
71 */
72 public void appendTo(StringBuilder toBuilder, Boolean b64, boolean zip) {
73 if (b64 == null && builder.length() < 128) {
74 b64 = false;
75 }
76
77 if (b64 == null || b64) {
78 try {
79 String zipped = StringUtils.base64(builder.toString(), zip);
80 if (b64 != null || zipped.length() < builder.length() - 4) {
81 toBuilder.append(zip ? "ZIP:" : "B64:");
82 toBuilder.append(zipped);
83 return;
84 }
85 } catch (IOException e) {
86 throw new RuntimeException(
87 "Base64 conversion of data failed, maybe not enough memory?",
88 e);
89 }
90 }
91
92 toBuilder.append(builder);
93 }
94
95 /**
96 * The exported items in a serialised form.
97 *
98 * @deprecated use {@link Exporter#toString(Boolean, boolean)} instead
99 *
100 * @param zip
101 * TRUE to have zipped (and BASE64-coded) content, FALSE to have
102 * raw content, NULL to let the system decide
103 *
104 * @return the items currently in this {@link Exporter}
105 */
106 @Deprecated
107 public String toString(Boolean zip) {
108 return toString(zip, zip == null || zip);
109 }
110
111 /**
112 * The exported items in a serialised form.
113 *
114 * @param b64
115 * TRUE to have BASE64-coded content, FALSE to have raw content,
116 * NULL to let the system decide
117 * @param zip
118 * TRUE to zip the BASE64 output if the output is indeed in
119 * BASE64 format, FALSE not to
120 *
121 * @return the items currently in this {@link Exporter}
122 */
123 public String toString(Boolean b64, boolean zip) {
124 StringBuilder toBuilder = new StringBuilder();
125 appendTo(toBuilder, b64, zip);
126 return toBuilder.toString();
127 }
128
129 /**
130 * The exported items in a serialised form (possibly BASE64-coded, possibly
131 * zipped).
132 *
133 * @return the items currently in this {@link Exporter}
134 */
135 @Override
136 public String toString() {
137 return toString(null, true);
138 }
139}