1 package org.apache.fulcrum.json;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.text.DateFormat;
23 import java.util.Collection;
24
25 /**
26 * This class defines custom methods needed to serialize and deserialize and
27 * helper methods if needed.
28 *
29 * Some methods expect a class parameter.
30 *
31 * If you want to call these methods from an environment, where you could only
32 * provide strings (e.g. velocity context), just wrap the method and call
33 * <code>Class clazz = Class.forName(className);</code> for the parameter.
34 *
35 *
36 * @author <a href="mailto:gk@apache.org">Georg Kallidis</a>
37 * @version $Id$
38 */
39 public interface JsonService {
40 /** Avalon Identifier **/
41 String ROLE = JsonService.class.getName();
42
43 String SERVICE_NAME = ROLE;
44
45 /**
46 * Serializes a Java object
47 *
48 * @param src the java object to be serialized, not null.
49 *
50 * @return JSON string
51 *
52 * @throws Exception if JSON serialization fails
53 */
54 String ser(Object src) throws Exception;
55
56 /**
57 * @param src the java object to be serialized, not null.
58 * @param cleanCache a boolean value, not null. If <code>true</code>, try to
59 * refresh cache after serialization
60 * @return serialized object
61 * @throws Exception generic exception
62 */
63 String ser(Object src, Boolean cleanCache) throws Exception;
64
65 /**
66 * Serializes a Java object
67 *
68 * @param src The Java object to be serialized
69 * @param type the Java Type, which should be used for the provided object
70 * @param <T> The class type
71 * @return JSON string
72 * @throws Exception If JSON serialization fails
73 */
74 <T> String ser(Object src, Class<T> type) throws Exception;
75
76 /**
77 * Serialize an object
78 *
79 * @param src The source object
80 * @param type The class type of the object
81 * @param <T> class type of the object
82 * @param cleanCache If <code>true</code>, try to clean cache after
83 * serialization
84 *
85 * For other attributes @see {@link #ser(Object, Class)}
86 *
87 * @return the serialized class
88 *
89 * @throws Exception if the JSON serialization fails
90 */
91 <T> String ser(Object src, Class<T> type, Boolean cleanCache) throws Exception;
92
93 /**
94 * Deserializing a JSON string
95 *
96 * @param src the JSON string to be deserialized
97 * @param type the Java Type to be used as a class
98 * @param <T> class type of the object
99 * @return the Java Object
100 *
101 * @throws Exception if JSON deserialization fails
102 */
103 <T> T deSer(String src, Class<T> type) throws Exception;
104
105 /**
106 * This is to deserialize collections. Depending on the implementation either
107 * both collectiontype and elementType is needed or the elementType will be
108 * derived from the typed collectiontype.
109 *
110 * @param json The JSON string to be deserialized
111 * @param collectionType It could be just the collection or the typed
112 * collection. It may then be used to get the type for
113 * element type too. Cft. implementation tests for more
114 * details (GSON).
115 * @param elementType The element type. This is need in any case to assure
116 * the generic checking.
117 * @param <T> class type of the object
118 * @return the generated Java Collection.
119 * @throws Exception if serialize collection fails
120 */
121 <T> Collection<T> deSerCollection(String json, Object collectionType, Class<T> elementType) throws Exception;
122
123 /**
124 * Custom method without caching. Caching is set to <code>false</code> for this
125 * method call.
126 *
127 * @see #serializeOnlyFilter(Object, Class, Boolean, String...)
128 *
129 * <code>refreshFilter</code> is set to <code>true</code> for this method
130 * call.
131 *
132 * @param src the source object
133 * @param filterAttr filter attributes
134 * @return JSON string
135 * @throws Exception if fails
136 */
137 public String serializeOnlyFilter(Object src, String... filterAttr) throws Exception;
138
139 /**
140 * Custom method. Caching key is derived from param src object class.
141 *
142 * @see #serializeOnlyFilter(Object, Class, Boolean, String...)
143 *
144 * @param src The Java object to serialize
145 * @param cleanFilter The Boolean value, not null. If it is <code>true</code>,
146 * cleans cache and the custom filter after serialization.
147 *
148 * <code>refreshFilter</code> is set to <code>true</code> for
149 * this method call.
150 *
151 * @param filterAttr filter attributes
152 * @return JSON string
153 * @throws Exception if fails
154 */
155 public String serializeOnlyFilter(Object src, Boolean cleanFilter, String... filterAttr) throws Exception;
156
157 /**
158 * @see #serializeOnlyFilter(Object, Class, Boolean, String...)
159 * Caching is set to <code>false</code> for this method call.
160 *
161 * @param src The Java object to serialize
162 * @param filterClass The filter class
163 * @param <T> class type of the object
164 * @param filterAttr filter attributes
165 * @return JSON string
166 * @throws Exception if fails
167 */
168 public <T> String serializeOnlyFilter(Object src, Class<T> filterClass, String... filterAttr) throws Exception;
169
170 /**
171 * Serialize only object properties where filter attributes are provided. If no
172 * filter is set, no attributes should be returned.
173 *
174 * @param src The Java object to serialize
175 * @param filterClass By default filterClass is a) the class to be filtered
176 * (required for filtering list elements) b) the key in the
177 * filter object cached.
178 * @param <T> class type of the object
179 * @param cleanFilter The Boolean value, not null. If it is <code>true</code>,
180 * cleans cache and the custom filter after serialization.
181 *
182 * @param filterAttr The class bean attributes which should be serialized
183 *
184 * @return JSON string
185 *
186 * @throws Exception If JSON serialization or filter registration fails
187 */
188 public <T> String serializeOnlyFilter(Object src, Class<T> filterClass, Boolean cleanFilter, String... filterAttr)
189 throws Exception;
190
191 /**
192 * Serialize all object properties excluding provided filters attributes. If no
193 * filter is set, all attributes should be returned.
194 *
195 * @param src The Java object to serialize. By default the filtering is
196 * applied for this class. By default the class of the src
197 * object is the key for the filter object cached.
198 * @param filterClass The class, which should be filtered out, if found as a
199 * property type.
200 * @param <T> class type of the object
201 * @param cleanFilter If <code>true </code> cleans filter (clean cache and
202 * custom filter for this filterClass) after serialization.
203 * @param filterAttr The bean attributes which should not be serialized
204 *
205 * @return JSON string
206 *
207 * @throws Exception If JSON serialization or filter registration fails
208 */
209 public <T> String serializeAllExceptFilter(Object src, Class<T> filterClass, Boolean cleanFilter,
210 String... filterAttr) throws Exception;
211
212 /**
213 * Class Filter is derived from param src object class.
214 * <code>refreshFilter</code> is set to <code>false</code> for this method call.
215 *
216 * @see #serializeAllExceptFilter(Object, Class, Boolean, String...)
217 *
218 * <code>refreshFilter</code> is <code>false</code>.
219 *
220 * @param src The Java object to serialize. By default the filtering is
221 * applied for this class. By default the class of the src
222 * object is the key for the filter object cached.
223 * @param <T> class type of the object
224 * @param filterClass The class, which should be filtered out, if found as a
225 * property type.
226 *
227 * @param filterAttr The bean attributes which should not be serialized
228 * @return JSON string
229 * @throws Exception If JSON serialization or filter registration fails
230 */
231 public <T> String serializeAllExceptFilter(Object src, Class<T> filterClass, String... filterAttr) throws Exception;
232
233 /**
234 * Class Filter is derived from param src object class.
235 *
236 * @see #serializeAllExceptFilter(Object, Class, Boolean, String...)
237 *
238 * @param src The Java object to serialize. By default the filtering is
239 * applied for this class. By default the class of the src
240 * object is the key for the filter object cached.
241 *
242 * @param cleanFilter If <code>true </code> cleans filter (clean cache and
243 * custom filter for this filterClass) after serialization.
244 *
245 * @param filterAttr The bean attributes which should not be serialized
246 * @return JSON string
247 * @throws Exception If JSON serialization or filter registration fails
248 */
249 public String serializeAllExceptFilter(Object src, Boolean cleanFilter, String... filterAttr) throws Exception;
250
251 /**
252 * @see #serializeAllExceptFilter(Object, Class, Boolean, String...)
253 * @param src The Java object to serialize. By default the filtering is
254 * applied for this class. By default the class of the src
255 * object is the key for the filter object cached.
256 *
257 * @param filterAttr The bean attributes which should not be serialized
258 * @return JSON string
259 * @throws Exception If JSON serialization or filter registration fails
260 */
261 public String serializeAllExceptFilter(Object src, String... filterAttr) throws Exception;
262
263 /**
264 * Adds an adapter (mixin, serializer,..) for the target class depending on the
265 * JsonService implementation. Cft. to
266 * {@link #addAdapter(String, Class, Object)}
267 *
268 * @param name The name of the adapter
269 * @param target The target class for this adapter
270 * @param mixin The adapter/mixin for the target class
271 *
272 * @return the JsonService instance
273 *
274 * @throws Exception If adapter registration fails
275 */
276 public JsonService addAdapter(String name, Class target, Class mixin) throws Exception;
277
278 /**
279 * Add an adapter (mixin, serializer,..) for the target class depending on the
280 * JsonService implementation. Adapters could by default not deregistered. If
281 * you want to get rid of them, you may try to reinit the service (or overwrite
282 * with the same target type, depending on implementation)
283 *
284 * @param name The name of the adapter
285 * @param target The target class for this adapter
286 * @param mixin The adapter/mixin for the target object
287 * (module/serializer/deserializer)
288 *
289 * @return A JsonService instance
290 *
291 * @throws Exception if adapter registration fails
292 */
293 public JsonService addAdapter(String name, Class target, Object mixin) throws Exception;
294
295 /**
296 * @param df The {@link DateFormat} to be used by the JsonService, not null.
297 * It could be provided by component configuration too.
298 *
299 */
300 public void setDateFormat(final DateFormat df);
301
302 }