001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr;
005:
006: import java.io.InputStream;
007: import java.util.Calendar;
008: import java.math.BigDecimal;
009:
010: /**
011: * A generic holder for the value of a property. A <code>Value</code> object can be used without knowing the actual
012: * property type (<code>STRING</code>, <code>DOUBLE</code>, <code>BINARY</code> etc.).
013: * <p>
014: * Any implementation of this interface must adhere to the following behavior:
015: * <ul>
016: * <li>
017: * A <code>Value</code> object can be read using type-specific
018: * <code>get</code> methods. These methods are divided into two groups:
019: * <ul>
020: * <li>
021: * The non-stream <code>get</code> methods <code>getString()</code>,
022: * <code>getBinary()</code>, <code>getDate()</code>, <code>getDecimal()</code>,
023: * <code>getLong()</code>, <code>getDouble()</code> and <code>getBoolean()</code>.
024: * </li>
025: * <li>
026: * <code>getStream()</code>.
027: * </li>
028: * </ul>
029: * </li>
030: * <li>
031: * Once a <code>Value</code> object has been read once using <code>getStream()</code>, all subsequent calls to
032: * <code>getStream()</code> will return the same <code>Stream</code> object. This may mean, for example, that the
033: * stream returned is fully or partially consumed. In order to get a fresh stream the <code>Value</code> object
034: * must be reacquired via {@link Property#getValue()} or {@link Property#getValues()}.
035: * </li>
036: * <li>
037: * Once a <code>Value</code> object has been read once using <code>getStream()</code>, any subsequent call to any
038: * of the non-stream <code>get</code> methods will throw an <code>IllegalStateException</code>. In order to
039: * successfully invoke a non-stream <code>get</code> method, the <code>Value</code> must be reacquired
040: * via {@link Property#getValue()} or {@link Property#getValues()}.
041: * </li>
042: * <li>
043: * Once a <code>Value</code> object has been read once using a non-stream get method, any subsequent call to
044: * <code>getStream()</code> will throw an <code>IllegalStateException</code>. In order to successfully invoke
045: * <code>getStream()</code>, the <code>Value</code> must be reacquired via {@link Property#getValue()} or
046: * {@link Property#getValues()}.
047: * </ul>
048: * <p/>
049: * Two <code>Value</code> instances, <code>v1</code> and <code>v2</code>, are considered equal if and only if:
050: * <ul>
051: * <li><code>v1.getType() == v2.getType()</code>, and,</li>
052: * <li><code>v1.getString().equals(v2.getString())</code></li>
053: * </ul>
054: * Actually comparing two <code>Value</code> instances by converting them to
055: * string form may not be practical in some cases (for example, if the values are very large
056: * binaries). Consequently, the above is intended as a normative definition of <code>Value</code> equality
057: * but not as a procedural test of equality. It is assumed that implementations will have efficient means
058: * of determining equality that conform with the above definition.
059: *
060: * An implementation is only required to support equality comparisons on <code>Value</code> instances that were
061: * acquired from the same <code>Session</code> and whose contents have not been read. The equality comparison must not
062: * change the state of the <code>Value</code> instances even though the <code>getString()</code> method in the above
063: * definition implies a state change.
064: */
065: public interface Value {
066:
067: /**
068: * Returns a <code>String</code> representation of this value.
069: * <p>
070: * If this value cannot be converted to a string, a
071: * <code>ValueFormatException</code> is thrown.
072: * <p>
073: * If <code>getStream</code> has previously been called on this
074: * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
075: * In this case a new <code>Value</code> instance must be acquired in order to
076: * successfully call <code>getString</code>.
077: * <p>
078: * A <code>RepositoryException</code> is thrown if another error occurs.
079: *
080: * @return A <code>String</code> representation of the value of this property.
081: * @throws ValueFormatException if conversion to a <code>String</code> is not possible.
082: * @throws IllegalStateException if <code>getStream</code> has previously
083: * been called on this <code>Value</code> instance.
084: * @throws RepositoryException if another error occurs.
085: */
086: public String getString() throws ValueFormatException,
087: IllegalStateException, RepositoryException;
088:
089: /**
090: * Returns an <code>InputStream</code> representation of this value.
091: * Uses the standard conversion to binary (see JCR specification).
092: * <p/>
093: * It is the responsibility of the caller to close the returned InputStream.
094: * <p>
095: * If a non-stream <code>get</code> method has previously been called on this
096: * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
097: * In this case a new <code>Value</code> instance must be acquired in order to successfully call
098: * <code>getStream</code>.
099: * <p>
100: * A <code>RepositoryException</code> is thrown if another error occurs.
101: *
102: * @deprecated As of JCR 2.0, {@link #getBinary()} should be used instead.
103: *
104: * @return An <code>InputStream</code> representation of this value.
105: * @throws IllegalStateException if a non-stream <code>get</code> method has previously
106: * been called on this <code>Value</code> instance.
107: * @throws RepositoryException if another error occurs.
108: */
109: public InputStream getStream() throws IllegalStateException,
110: RepositoryException;
111:
112: /**
113: * Returns a <code>Binary</code> representation of this value. The
114: * {@link Binary} object in turn provides methods to access the binary
115: * data itself.
116: * Uses the standard conversion to binary (see JCR specification).
117: *
118: * @return A <code>Binary</code> representation of this value.
119: * @throws RepositoryException if an error occurs.
120: * @since JCR 2.0
121: */
122: public Binary getBinary() throws RepositoryException;
123:
124: /**
125: * Returns a <code>long</code> representation of this value.
126: * <p>
127: * If this value cannot be converted to a <code>long</code>,
128: * a <code>ValueFormatException</code> is thrown.
129: * <p>
130: * If <code>getStream</code> has previously been called on this
131: * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
132: * In this case a new <code>Value</code> instance must be acquired in order to
133: * successfully call <code>getLong</code>.
134: * <p>
135: * A <code>RepositoryException</code> is thrown if another error occurs.
136: *
137: * @return A <code>long</code> representation of this value.
138: * @throws ValueFormatException if conversion to an <code>long</code> is not possible.
139: * @throws IllegalStateException if <code>getStream</code> has previously
140: * been called on this <code>Value</code> instance.
141: * @throws RepositoryException if another error occurs.
142: */
143: public long getLong() throws ValueFormatException,
144: IllegalStateException, RepositoryException;
145:
146: /**
147: * Returns a <code>double</code> representation of this value.
148: * <p>
149: * If this value cannot be converted to a <code>double</code>, a
150: * <code>ValueFormatException</code> is thrown.
151: * <p>
152: * If <code>getStream</code> has previously been called on this
153: * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
154: * In this case a new <code>Value</code> instance must be acquired in order to
155: * successfully call <code>getDouble</code>.
156: * <p>
157: * A <code>RepositoryException</code> is thrown if another error occurs.
158: *
159: * @return A <code>double</code> representation of this value.
160: * @throws ValueFormatException if conversion to a <code>double</code> is not possible.
161: * @throws IllegalStateException if <code>getStream</code> has previously
162: * been called on this <code>Value</code> instance.
163: * @throws RepositoryException if another error occurs.
164: */
165: public double getDouble() throws ValueFormatException,
166: IllegalStateException, RepositoryException;
167:
168: /**
169: * Returns a <code>BigDecimal</code> representation of this value.
170: * <p>
171: * If this value cannot be converted to a <code>BigDecimal</code>, a
172: * <code>ValueFormatException</code> is thrown.
173: * <p>
174: * If <code>getStream</code> has previously been called on this
175: * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
176: * In this case a new <code>Value</code> instance must be acquired in order to
177: * successfully call <code>getDouble</code>.
178: * <p>
179: * A <code>RepositoryException</code> is thrown if another error occurs.
180: *
181: * @return A <code>BigDecimal</code> representation of this value.
182: * @throws ValueFormatException if conversion to a <code>BigDecimal</code> is not possible.
183: * @throws IllegalStateException if <code>getStream</code> has previously
184: * been called on this <code>Value</code> instance.
185: * @throws RepositoryException if another error occurs.
186: * @since JCR 2.0
187: */
188: public BigDecimal getDecimal() throws ValueFormatException,
189: IllegalStateException, RepositoryException;
190:
191: /**
192: * Returns a <code>Calendar</code> representation of this value.
193: * <p>
194: * The object returned is a copy of the stored value, so changes to it are not reflected in internal storage.
195: * <p>
196: * If this value cannot be converted to a <code>Calendar</code>, a
197: * <code>ValueFormatException</code> is thrown.
198: * <p>
199: * If <code>getStream</code> has previously been called on this
200: * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
201: * In this case a new <code>Value</code> instance must be acquired in order to
202: * successfully call <code>getDate</code>.
203: * <p>
204: * A <code>RepositoryException</code> is thrown if another error occurs.
205: *
206: * @return A <code>Calendar</code> representation of this value.
207: * @throws ValueFormatException if conversion to a <code>Calendar</code> is not possible.
208: * @throws IllegalStateException if <code>getStream</code> has previously
209: * been called on this <code>Value</code> instance.
210: * @throws RepositoryException if another error occurs.
211: */
212: public Calendar getDate() throws ValueFormatException,
213: IllegalStateException, RepositoryException;
214:
215: /**
216: * Returns a <code>Boolean</code> representation of this value.
217: * <p>
218: * If this value cannot be converted to a <code>Boolean</code>, a
219: * <code>ValueFormatException</code> is thrown.
220: * <p>
221: * If <code>getStream</code> has previously been called on this
222: * <code>Value</code> instance, an <code>IllegalStateException</code> is thrown.
223: * In this case a new <code>Value</code> instance must be acquired in order to
224: * successfully call <code>getBoolean</code>.
225: * <p>
226: * A <code>RepositoryException</code> is thrown if another error occurs.
227: *
228: * @return A <code>Boolean</code> representation of this value.
229: * @throws ValueFormatException if conversion to a <code>Boolean</code> is not possible.
230: * @throws IllegalStateException if <code>getStream</code> has previously
231: * been called on this <code>Value</code> instance.
232: * @throws RepositoryException if another error occurs.
233: */
234: public boolean getBoolean() throws ValueFormatException,
235: IllegalStateException, RepositoryException;
236:
237: /**
238: * Returns the <code>type</code> of this <code>Value</code>.
239: * One of:
240: * <ul>
241: * <li><code>PropertyType.STRING</code></li>
242: * <li><code>PropertyType.DATE</code></li>
243: * <li><code>PropertyType.BINARY</code></li>
244: * <li><code>PropertyType.DOUBLE</code></li>
245: * <li><code>PropertyType.LONG</code></li>
246: * <li><code>PropertyType.BOOLEAN</code></li>
247: * <li><code>PropertyType.NAME</code></li>
248: * <li><code>PropertyType.PATH</code></li>
249: * <li><code>PropertyType.REFERENCE</code></li>
250: * <li><code>PropertyType.WEAKREFERENCE</code></li>
251: * <li><code>PropertyType.URI</code></li></ul>
252: * See <code>{@link PropertyType}</code>.
253: * <p>
254: * The type returned is that which was set at property creation.
255: */
256: public int getType();
257: }
|