01: /*
02: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
03: */
04: package javax.jcr;
05:
06: import java.io.InputStream;
07:
08: /**
09: * The <code>Binary</code> interface and its related methods in
10: * <code>Property</code>, <code>Value</code> and <code>ValueFactory</code>
11: * replace the deprecated {@link Value#getStream} and {@link Property#getStream}
12: * methods. The <code>Binary</code> interface allows repositories to provide
13: * implementations that handle JCR BINARY values in the most efficient manner,
14: * given the specifics of their internal handling of the binary data.
15: *
16: * @since JCR 2.0
17: */
18: public interface Binary {
19:
20: /**
21: * Returns an <code>InputStream</code> representation of this value.
22: *
23: * @return A stream representation of this value.
24: * @throws IllegalStateException if {@link #acquire} has not yet or
25: * {@link #release} has already been called on this
26: * <code>Binary</code> object instance.
27: * @throws RepositoryException if another error occurs.
28: */
29: InputStream getStream() throws IllegalStateException,
30: RepositoryException;
31:
32: /**
33: * Returns a byte array representation of this value.
34: *
35: * @return a byte array representation of this value.
36: * @throws IllegalStateException if {@link #acquire} has not yet or
37: * {@link #release} has already been called on this
38: * <code>Binary</code> object instance.
39: * @throws RepositoryException if another error occurs.
40: */
41: byte[] getBytes() throws IllegalStateException, RepositoryException;
42:
43: /**
44: * Returns the size of this value in bytes.
45: *
46: * @return the size of this value in bytes.
47: * @throws IllegalStateException if {@link #acquire} has not yet or
48: * {@link #release} has already been called on this
49: * <code>Binary</code> object instance.
50: * @throws RepositoryException if another error occurs.
51: */
52: long getSize() throws IllegalStateException, RepositoryException;
53:
54: /**
55: * Clients must call this method before using any of the other methods of
56: * this interface, other than {@link #release}.
57: * <p/>
58: * This method is used by the implementation to track the usage of
59: * <code>Binary</code> objects and perform any preparation that may be
60: * necessary for returning the binary data (through either {@link #getStream}
61: * or {@link #getBytes}) or reporting the size of the binary data (through
62: * {@link #getSize}). The details of any such preparation will be specific
63: * to the implementation.
64: *
65: * @throws IllegalStateException if {@link #release} has already been
66: * called on this <code>Binary</code> object instance.
67: * @throws RepositoryException if another error occurs.
68: */
69: void acquire() throws IllegalStateException, RepositoryException;
70:
71: /**
72: * Clients must call this method when they are finished with a
73: * <code>Binary</code> object instance in order to allow the implementation
74: * to release any resources used during the lifetime of the object. The
75: * details of any such clean-up will be specific to the implementation.
76: * <p/>
77: * It is legal for this method to be called even if {@link #acquire} has not
78: * yet been called, though in a typical implementation this will have no
79: * effect.
80: *
81: * @throws RepositoryException if an error occurs.
82: */
83: void release() throws RepositoryException;
84: }
|