1 package com.atlassian.vcache;
2
3
4 import com.atlassian.annotations.PublicSpi;
5 import com.atlassian.marshalling.api.MarshallingException;
6 import com.atlassian.marshalling.api.Unmarshaller;
7
8 /**
9 * Represents the ability to convert an object, of type <tt>T</tt>, to and from an array of {@code byte}s.
10 * <p>Notes:</p>
11 * <ul>
12 * <li>
13 * The {@link #unmarshall(byte[])} method should only ever be passed data that was generated by
14 * calling the {@link #marshall(Object)} method on an instance of {@link Marshaller} associated
15 * with a cache with the same <tt>name</tt>. However, the
16 * {@link #unmarshall(byte[])} should endeavour to be robust in the event of arbitrary data.
17 * </li>
18 * <li>
19 * Data versioning is the responsibility of the implementation.
20 * </li>
21 * <li>
22 * The instances returned by {@link #unmarshall(byte[])} for the same input byte array must match when
23 * compared using the {@link Object#equals(Object)} method.
24 * </li>
25 * <li>
26 * See the <i>Data Considerations</i> section in the {@link ExternalCache} documentation.
27 * </li>
28 * <li>
29 * The implementation must be multi-thread safe.
30 * </li>
31 * </ul>
32 *
33 * @param <T> the type that can be converted
34 * @since 1.0
35 * @deprecated since 1.5.0. Use the Atlassian Marshalling API and implementations instead.
36 */
37 @Deprecated
38 @PublicSpi
39 public interface Marshaller<T> extends com.atlassian.marshalling.api.Marshaller<T>, Unmarshaller<T> {
40 /**
41 * Responsible for converting a object into an array of bytes.
42 *
43 * @param obj the object to be converted.
44 * @return the array of bytes representing <tt>data</tt>
45 * @throws MarshallerException if unable to perform the conversion
46 */
47 byte[] marshall(T obj) throws MarshallerException;
48
49 /**
50 * Responsible for converting an array of bytes into an object. The instances returned for the same input byte
51 * array must match when compared using the {@link Object#equals(Object)} method.
52 *
53 * @param raw the array of bytes to be converted.
54 * @return the object represented by <tt>raw</tt>
55 * @throws MarshallerException if unable to perform the conversion
56 */
57 T unmarshall(byte[] raw) throws MarshallerException;
58
59 @Override
60 default byte[] marshallToBytes(T t) throws MarshallingException {
61 try {
62 return marshall(t);
63 } catch (MarshallerException e) {
64 throw new MarshallingException("Legacy marshall() failed", e);
65 }
66 }
67
68 @Override
69 default T unmarshallFrom(byte[] bytes) throws MarshallingException {
70 try {
71 return unmarshall(bytes);
72 } catch (MarshallerException e) {
73 throw new MarshallingException("Legacy unmarshall() failed", e);
74 }
75 }
76 }