Property


1   /*
2    * $Id: Property.java,v 1.3 2004/07/31 11:49:25 benjmestrallet Exp $
3    *
4    * Copyright 2002-2004 Day Management AG, Switzerland.
5    *
6    * Licensed under the Day RI License, Version 2.0 (the "License"),
7    * as a reference implementation of the following specification:
8    *
9    *   Content Repository API for Java Technology, revision 0.12
10   *        <http://www.jcp.org/en/jsr/detail?id=170>
11   *
12   * You may not use this file except in compliance with the License.
13   * You may obtain a copy of the License files at
14   *
15   *     http://www.day.com/content/en/licenses/day-ri-license-2.0
16   *     http://www.apache.org/licenses/LICENSE-2.0
17   *
18   * Unless required by applicable law or agreed to in writing, software
19   * distributed under the License is distributed on an "AS IS" BASIS,
20   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21   * See the License for the specific language governing permissions and
22   * limitations under the License.
23   */
24  package javax.jcr;
25  
26  import javax.jcr.nodetype.PropertyDef;
27  import java.io.InputStream  ;
28  import java.util.Calendar  ;
29  
30  /**
31   * A <code>Property</code> object represents the smallest granularity of content
32   * storage.
33   * <p/>
34   * <b>Level 1 and 2</b>
35   * <p/>
36   * A property must have one and only one parent node. A property does
37   * not have children. When we say that node A "has" property B it means that B
38   * is a child of A.
39   * <p/>
40   * A property consists of a name and a value. See <code>{@link Value}</code>.
41   *
42   * @author Peeter Piegaze
43   * @author Stefan Guggisberg
44   */
45  public interface Property extends Item {
46  
47    /**
48     * Sets the value of this <code>Property</code> to <code>value</code>.
49     * If this property's property type is not constrained by the node type of
50     * its parent node, then the property type is changed to that of the supplied
51     * <code>value</code>. If the property type is constrained, then a
52     * best-effort conversion is attempted. If conversion fails, a
53     * <code>ValueFormatException</code> is thrown immediately (not on <code>save</code>).
54     * The change will be persisted (if valid) on <code>save</code>
55     *
56     * @param value The new value to set the property to.
57     * @throws ValueFormatException if the type or format of the specified value
58     *                              is incompatible with the <code>type</code> of this property.
59     * @throws RepositoryException  if another error occurs.
60     */
61    public void setValue(Value value) throws ValueFormatException, RepositoryException;
62  
63    /**
64     * Sets the value of this <code>Property</code> to the array <code>values</code>.
65     * If this property's property type is not constrained by the node type of
66     * its parent node, then the property type is changed to that of the supplied
67     * <code>value</code>. If the property type is constrained, then a
68     * best-effort conversion is attempted. If conversion fails, a
69     * <code>ValueFormatException</code> is thrown immediately (not on <code>save</code>).
70     * If this property is not a multi-valued then a ValueFormatException is
71     * thrown immediately. The change will be persisted (if valid) on <code>save</code>
72     *
73     * @param values The new value to set the property to.
74     * @throws ValueFormatException if the type or format of the specified value
75     *                              is incompatible with the <code>type</code> of this property.
76     * @throws RepositoryException  if another error occurs.
77     */
78    public void setValue(Value[] values) throws ValueFormatException, RepositoryException;
79  
80    /**
81     * Sets the value of this <code>Property</code> to <code>value</code>.
82     * Same as <code>{@link #setValue(Value value)}</code> except that the
83     * value is specified as a <code>String</code>.
84     *
85     * @param value The new value to set the property to.
86     * @throws ValueFormatException if the type or format of the specified value
87     *                              is incompatible with the <code>type</code> of this property.
88     * @throws RepositoryException  if another error occurs.
89     */
90    public void setValue(String   value) throws ValueFormatException, RepositoryException;
91  
92    /**
93     * Sets the value of this <code>Property</code> to <code>value</code>.
94     * Same as <code>{@link #setValue(Value value)}</code> except that the
95     * value is specified as a <code>boolean</code>.
96     *
97     * @param value The new value to set the property to.
98     * @throws ValueFormatException if the type or format of the specified value
99     *                              is incompatible with the <code>type</code> of this property.
100    * @throws RepositoryException  if another error occurs.
101    */
102   public void setValue(boolean value) throws ValueFormatException, RepositoryException;
103 
104   /**
105    * Sets the value of this <code>Property</code> to <code>value</code>.
106    * Same as <code>{@link #setValue(Value value)}</code> except that the
107    * value is specified as a <code>long</code>.
108    *
109    * @param value The new value to set the property to.
110    * @throws ValueFormatException if the type or format of the specified value
111    *                              is incompatible with the <code>type</code> of this property.
112    * @throws RepositoryException  if another error occurs.
113    */
114   public void setValue(long value) throws ValueFormatException, RepositoryException;
115 
116   /**
117    * Sets the value of this <code>Property</code> to <code>value</code>.
118    * Same as <code>{@link #setValue(Value value)}</code> except that the
119    * value is specified as a <code>double</code>.
120    *
121    * @param value The new value to set the property to.
122    * @throws ValueFormatException if the type or format of the specified value
123    *                              is incompatible with the <code>type</code> of this property.
124    * @throws RepositoryException  if another error occurs.
125    */
126   public void setValue(double value) throws ValueFormatException, RepositoryException;
127 
128   /**
129    * Sets the value of this <code>Property</code> to <code>value</code>.
130    * Same as <code>{@link #setValue(Value value)}</code> except that the
131    * value is specified as a <code>InputStream</code>.
132    *
133    * @param value The new value to set the property to.
134    * @throws ValueFormatException if the type or format of the specified value
135    *                              is incompatible with the <code>type</code> of this property.
136    * @throws RepositoryException  if another error occurs.
137    */
138   public void setValue(InputStream   value) throws ValueFormatException, RepositoryException;
139 
140   /**
141    * Sets the value of this <code>Property</code> to <code>value</code>.
142    * Same as <code>{@link #setValue(Value value)}</code> except that the
143    * value is specified as a <code>Calendar</code>.
144    *
145    * @param value The new value to set the property to.
146    * @throws ValueFormatException if the type or format of the specified value
147    *                              is incompatible with the <code>type</code> of this property.
148    * @throws RepositoryException  if another error occurs.
149    */
150   public void setValue(Calendar   value) throws ValueFormatException, RepositoryException;
151 
152   /**
153    * Returns the value of this property.
154    * Returns the value of the <code>Property</code> as a generic
155    * <code>Value</code> object or <code>null</code> if the
156    * <code>Property</code> has no value.
157    *
158    * @return the value
159    * @throws RepositoryException if an error occurs.
160    */
161   public Value getValue() throws RepositoryException;
162 
163   /**
164    * Returns an array of all the values of this property. Used to access
165    * multi-value properties.
166    *
167    * @return a <code>Value</code> array
168    * @throws RepositoryException if an error occurs.
169    */
170   public Value[] getValues() throws RepositoryException;
171 
172   /**
173    * Returns a <code>String</code> representation of the value of this
174    * <code>Property</code>. A shortcut for
175    * <code>Property.getValue().getString()</code>. See {@link Value}.
176    * If this Property is multi-valued, this method returns the first value.
177    *
178    * @return A string representation of the value of this <code>Property</code>.
179    */
180   public String   getString();
181 
182   /**
183    * Returns a <code>double</code> representation of the value of this
184    * <code>Property</code>. A shortcut for
185    * <code>Property.getValue().getDouble()</code>. See {@link Value}.
186    * If this Property is multi-valued, this method returns the first value.
187    *
188    * @return A string representation of the value of this <code>Property</code>.
189    */
190   public double getDouble();
191 
192   /**
193    * Returns a <code>InputStream</code> representation of the value of this
194    * <code>Property</code>. A shortcut for
195    * <code>Property.getValue().getStream()</code>. See {@link Value}.
196    * If this Property is multi-valued, this method returns the first value.
197    *
198    * @return A string representation of the value of this <code>Property</code>.
199    */
200   public InputStream   getStream();
201 
202   /**
203    * Returns a <code>Calendar</code> representation of the value of this
204    * <code>Property</code>. A shortcut for
205    * <code>Property.getValue().getDate()</code>. See {@link Value}.
206    * If this Property is multi-valued, this method returns the first value.
207    *
208    * @return A string representation of the value of this <code>Property</code>.
209    */
210   public Calendar   getDate();
211 
212   /**
213    * Returns a <code>boolean</code> representation of the value of this
214    * <code>Property</code>. A shortcut for
215    * <code>Property.getValue().getBoolean()</code>. See {@link Value}.
216    * If this Property is multi-valued, this method returns the first value.
217    *
218    * @return A string representation of the value of this <code>Property</code>.
219    */
220   public boolean getBoolean();
221 
222   /**
223    * Returns a <code>Slong</code> representation of the value of this
224    * <code>Property</code>. A shortcut for
225    * <code>Property.getValue().getLong()</code>. See {@link Value}.
226    * If this Property is multi-valued, this method returns the first value.
227    *
228    * @return A long representation of the value of this <code>Property</code>.
229    */
230   public long getLong();
231 
232   /**
233    * Indicates whether this property has a value.
234    * <p/>
235    * <b>Level 1 and 2:</b>
236    * <p/>
237    * Returns true if this property has a value. A property with no value
238    * is the same as a property with value set to <code>null</code>.
239    *
240    * @return <code>true</code> if the property has content;
241    *         <code>false</code> otherwise.
242    */
243   public boolean hasValue();
244 
245   /**
246    * Returns the length of the value of this property.
247    * <p/>
248    * <b>Level 1 and 2:</b>
249    * <p/>
250    * Returns the length of the value of this property in bytes if the value
251    * is a <code>PropertyType.BINARY</code>, otherwise it returns the number
252    * of characters needed to display the value (for strings this is the string
253    * length, for numeric types it is the number of characters needed to
254    * display the number). Returns �1 if the implementation cannot determine
255    * the length. Returns 0 if the property has no value.
256    *
257    * @return an integer
258    */
259   public long getLength();
260 
261   /**
262    * Returns the definition of <i>this</i> <code>Property</code>. This method
263    * is actually a shortcut to searching through this property's parent's
264    * node type (and its supertypes) for the property definition applicable
265    * to this property.
266    *
267    * @return a <code>PropertyDefNT</code> object.
268    * @see javax.jcr.nodetype.NodeType#getPropertyDefs
269    */
270   public PropertyDef getDefinition();
271 }
272
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags