1 package com.atlassian.vcache;
2
3
4 import javax.annotation.Nonnull;
5
6 import com.atlassian.annotations.PublicSpi;
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
11 * <p>Notes:</p>
12 * <ul>
13 * <li>
14 * The {@link #unmarshall(byte[])} method should only ever be passed data that was generated by
15 * calling the {@link #marshall(Object)} method on an instance of {@link Marshaller} associated
16 * with a cache with the same <tt>name</tt>. However, the
17 * {@link #unmarshall(byte[])} should endeavour to be robust in the event of arbitrary data.
18 * </li>
19 * <li>
20 * Data versioning is the responsibility of the implementation.
21 * </li>
22 * <li>
23 * The instances returned by {@link #unmarshall(byte[])} for the same input byte array must match when
24 * compared using the {@link Object#equals(Object)} method.
25 * </li>
26 * <li>
27 * See the <i>Data Considerations</i> section in the {@link ExternalCache} documentation.
28 * </li>
29 * <li>
30 * The implementation must be multi-thread safe.
31 * </li>
32 * </ul>
33 * @param <T> the type that can be converted
34 *
35 * @since 1.0
36 */
37 @PublicSpi
38 public interface Marshaller<T>
39 {
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 @Nonnull
48 byte[] marshall(T obj) throws MarshallerException;
49
50 /**
51 * Responsible for converting an array of bytes into an object. The instances returned for the same input byte
52 * array must match when compared using the {@link Object#equals(Object)} method.
53 *
54 * @param raw the array of bytes to be converted.
55 * @return the object represented by <tt>raw</tt>
56 * @throws MarshallerException if unable to perform the conversion
57 */
58 @Nonnull
59 T unmarshall(byte[] raw) throws MarshallerException;
60 }