FieldValue


1   /*
2   
3   This software is OSI Certified Open Source Software.
4   OSI Certified is a certification mark of the Open Source Initiative.
5   
6   The license (Mozilla version 1.0) can be read at the MMBase site.
7   See http://www.MMBase.org/license
8   
9   */
10  
11  package org.mmbase.bridge;
12  
13  /**
14   * This interface represents a value stored in a node.
15   *
16   * @author Pierre van Rooden
17   * @since MMBase 1.6
18   * @version $Id: FieldValue.java,v 1.11 2005/05/02 17:23:06 michiel Exp $
19   */
20  public interface FieldValue {
21  
22      /**
23       * Returns whether this value can be changed.
24       * Some field values (such as the values of the number, owner, and otype fields) cannot be changed
25       * through this interface (but some may be changed through other means).
26       *
27       * @return  <code>true</code> if the value can be changed
28       */
29      public boolean canModify();
30  
31  
32      public boolean isNull();
33  
34      /**
35       * Returns the value as an Object.
36       * The object type may vary and is dependent on how data was stored in a field.
37       * I.e. It may be possible for an Integer field to return it's value as a String
38       * if it was stored that way in the first place.
39       *
40       * @return  the field value as an object
41       */
42      public Object   get();
43  
44      /**
45       * Returns the Field object belonging to this value.
46       *
47       * @return  the field object
48       */
49      public Object   getField();
50  
51      /**
52       * Returns the Node to which this value belongs.
53       *
54       * @return  the Node object
55       */
56      public Node getNode();
57  
58      /**
59       * Returns the value as an boolean (<code>true</code> or  <code>false</code>).
60       * If the actual value is a Boolean object, this call returns it's (primitive) boolean value.
61       * If the actual value is a Number object, this call returns <code>true</code>
62       * if the value is a positive, non-zero, value. In other words, values '0'
63       * and '-1' are concidered <code>false</code>.
64       * If the value is a string, this call returns <code>true</code> if
65       * the value is "true" or "yes" (case-insensitive).
66       * In all other cases (including calling byte fields), <code>false</code>
67       * is returned.
68       *
69       * @return  the field value as a boolean
70       */
71      public boolean toBoolean();
72  
73      /**
74       * Returns the value as a byte array.
75       * This function returns either the value of a byte field, or the byte value of a string
76       * (converted using the default encoding, i.e. UTF8)
77       * Other types of values return an empty byte-array.
78       *
79       * @return  the field value as a byte array
80       */
81      public byte[] toByte();
82  
83      /**
84       * Returns the value as a float.
85       * This function attempts to convert the value to a float.
86       * Numeric fields are simply converted.
87       * Boolean fields return 0.0 if false, and 1.0 if true.
88       * String fields are parsed.
89       * If a parsed string contains an error, ot the field value is not of a type that can be converted
90       * (i.e. a byte array), this function returns -1.0.
91       *
92       * @return  the field value as a float
93       */
94      public float toFloat();
95  
96      /**
97       * Returns the value as a double.
98       * This function attempts to convert the value to a double.
99       * Numeric fields are simply converted. Double may be truncated.
100      * Boolean fields return 0.0 if false, and 1.0 if true.
101      * String fields are parsed.
102      * If a parsed string contains an error, ot the field value is not of a type that can be converted
103      * (i.e. a byte array), this function returns -1.0.
104      *
105      * @return  the field value as a double
106      */
107     public double toDouble();
108 
109     /**
110      * Returns the value as a long.
111      * This function attempts to convert the value to a long.
112      * Numeric fields are simply converted. Double and float values may be truncated.
113      * Boolean fields return 0 if false, and 1 if true.
114      * String fields are parsed.
115      * If a parsed string contains an error, ot the field value is not of a type that can be converted
116      * (i.e. a byte array), this function returns -1
117      *
118      * @return  the field value as a long.
119      */
120     public long toLong();
121 
122     /**
123      * Returns the value as an int.
124      * This function attempts to convert the value to an int.
125      * Numeric fields are simply converted. Double and float values may be truncated.
126      * For Node values, the numeric key is returned.
127      * Long values return -1 of the value is too large.
128      * Boolean fields return 0 if false, and 1 if true.
129      * String fields are parsed.
130      * If a parsed string contains an error, ot the field value is not of a type that can be converted
131      * (i.e. a byte array), this function returns -1
132      *
133      * @return  the field value as an int.
134      */
135     public int toInt();
136 
137     /**
138      * Returns the value as a Node.
139      * This function attempts to retrieve the node represented by the value.
140      * For numeric fields the node is retrieved using the numeric values as the node key.
141      * String fields are used as Node aliases, withw hich to retrieve the Node.
142      * If the node does not exist, or the value is of anotehr type, the function returns <code>null</code>.
143      *
144      * @return  the field value as a Node
145      */
146     public Node toNode();
147 
148     /**
149      * Returns the value as a String.
150      * Byte arrays are converted to string using the default encoding (UTF8).
151      * Node values return a string representation of their numeric key.
152      * DOM Documents are serialized to a proper strign represnattion fo the xml.
153      * For other values the result is calling the toString() method on the actual object.
154      *
155      * @return  the field value as a String
156      */
157     public String   toString();
158 
159     /**
160      * Returns the value as a <code>org.w3c.dom.Document</code>
161      * If the node value is not itself a Document, the method attempts to
162      * attempts to convert the String value into an XML.
163      * If the value cannot be converted, this method returns <code>null</code>
164      *
165      * @return  the field value as a Document
166      * @throws  IllegalArgumentException if the Field is not of type TYPE_XML.
167      */
168     public org.w3c.dom.Document   toXML() throws IllegalArgumentException  ;
169 
170     /**
171      * Returns the value as a <code>java.util.Date</code>
172      * If the value cannot be converted, this method returns <code>null</code>
173      * @return the field value as Date
174      * @since MMBase-1.8
175      */
176     public java.util.Date   toDate();
177 
178     /**
179      * Returns the value as a <code>org.w3c.dom.Element</code>
180      * If the node value is not itself a Document, the method attempts to
181      * attempts to convert the String value into an XML.
182      * This method fails (throws a IllegalArgumentException) if the Field is not of type TYPE_XML.
183      * If the value cannot be converted, this method returns <code>null</code>
184      *
185      * @param tree the DOM Document to which the Element is added
186      *             (as the document root element)
187      * @return  the field value as an Element
188      * @throws  IllegalArgumentException if the Field is not of type TYPE_XML.
189      */
190     public org.w3c.dom.Element   toXML(org.w3c.dom.Document   tree) throws IllegalArgumentException  ;
191 
192     /**
193      * Sets the value, passing any Object
194      * The object type may vary and is generally stored in memory as-is, which means that,
195      * generally, the get() method returns the same object.
196      * Note that for an XML field String values are converted to a XML document, and individual builders
197      * may make their own changes.
198      * The object is converted to the actual type (using the getXXX() methods detailed above) once the node
199      * is stored, though that does not affect the data in-memory until the Node is read anew from the storage.
200      * Note that this behavior may change in the future and therefor code should not be dependent on this.
201      * By preference, use the more specific methods for setting data (i.e. setString()).
202      *
203      * @see #get
204      * @param value the field value as an Object
205      */
206     public void set(Object   value);
207 
208     /*
209      * Sets the value of the specified field using an object, but without dispatching to the right
210      * type first.
211      * @since MMBase-1.8
212      */
213     public void setObject(Object   value);
214 
215     /**
216      * Sets the value, passing a boolean value.
217      * This value is converted to a Boolean object.
218      *
219      * @see #toBoolean
220      * @param value the field value as a boolean
221      */
222     public void setBoolean(boolean value);
223 
224     /**
225      * Sets the value, passing a float value.
226      * This value is converted to a Float object.
227      *
228      * @see #toFloat
229      * @param value the field value as a float
230      */
231     public void setFLoat(float value);
232 
233     /**
234      * Sets the value, passing a double value.
235      * This value is converted to a Double object.
236      *
237      * @see #toDouble
238      * @param value the field value as a double
239      */
240     public void setDouble(double value);
241 
242     /**
243      * Sets the value, passing a long value.
244      * This value is converted to a Long object.
245      *
246      * @see #toLong
247      * @param value the field value as a long
248      */
249     public void setLong(long value);
250 
251     /**
252      * Sets the value, passing a int value.
253      * This value is converted to a Integer object.
254      *
255      * @see #toInt
256      * @param value the field value as a int
257      */
258     public void setInt(int value);
259 
260     /**
261      * Sets the value, passing a byte array.
262      *
263      * @see #toByte
264      * @param value the field value as a byte array
265      */
266     public void setByte(byte[] value);
267 
268     /**
269      * Sets the value, passing a String.
270      *
271      * @see #toString
272      * @param value the field value as a String
273      */
274     public void setString(String   value);
275 
276     /**
277      * Sets the value, passing a Node.
278      *
279      * @see #toNode
280      * @param value the field value as a Node
281      */
282     public void setNode(Node value);
283 
284     /**
285      * Sets the value, passing a org.w3c.dom.Document object.
286      *
287      * @see #toXML(org.w3c.dom.Document)
288      * @param value the field value as a XML Document
289      */
290     public void setXML(org.w3c.dom.Document   value);
291 
292     /**
293      * Sets the value, passing a java.util.Date object.
294      * @see #toDate
295      * @param value the field value as a java.util.Date Document
296      * @since MMBase-1.8
297      */
298     public void setDate(java.util.Date   value);
299 
300 }
301
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags