001: /*
002:
003: This software is OSI Certified Open Source Software.
004: OSI Certified is a certification mark of the Open Source Initiative.
005:
006: The license (Mozilla version 1.0) can be read at the MMBase site.
007: See http://www.MMBase.org/license
008:
009: */
010:
011: package org.mmbase.bridge;
012:
013: /**
014: * This interface represents a value stored in a node.
015: *
016: * @author Pierre van Rooden
017: * @since MMBase 1.6
018: * @version $Id: FieldValue.java,v 1.12 2007/02/16 20:04:39 michiel Exp $
019: */
020: public interface FieldValue {
021:
022: /**
023: * Returns whether this value can be changed.
024: * Some field values (such as the values of the number, owner, and otype fields) cannot be changed
025: * through this interface (but some may be changed through other means).
026: *
027: * @return <code>true</code> if the value can be changed
028: */
029: public boolean canModify();
030:
031: public boolean isNull();
032:
033: /**
034: * Returns the value as an Object.
035: * The object type may vary and is dependent on how data was stored in a field.
036: * I.e. It may be possible for an Integer field to return it's value as a String
037: * if it was stored that way in the first place.
038: *
039: * @return the field value as an object
040: */
041: public Object get();
042:
043: /**
044: * Returns the Field object belonging to this value.
045: *
046: * @return the field object. Why not return Field?
047: */
048: public Field getField();
049:
050: /**
051: * Returns the Node to which this value belongs.
052: *
053: * @return the Node object
054: */
055: public Node getNode();
056:
057: /**
058: * Returns the value as an boolean (<code>true</code> or <code>false</code>).
059: * If the actual value is a Boolean object, this call returns it's (primitive) boolean value.
060: * If the actual value is a Number object, this call returns <code>true</code>
061: * if the value is a positive, non-zero, value. In other words, values '0'
062: * and '-1' are concidered <code>false</code>.
063: * If the value is a string, this call returns <code>true</code> if
064: * the value is "true" or "yes" (case-insensitive).
065: * In all other cases (including calling byte fields), <code>false</code>
066: * is returned.
067: *
068: * @return the field value as a boolean
069: */
070: public boolean toBoolean();
071:
072: /**
073: * Returns the value as a byte array.
074: * This function returns either the value of a byte field, or the byte value of a string
075: * (converted using the default encoding, i.e. UTF8)
076: * Other types of values return an empty byte-array.
077: *
078: * @return the field value as a byte array
079: */
080: public byte[] toByte();
081:
082: /**
083: * Returns the value as a float.
084: * This function attempts to convert the value to a float.
085: * Numeric fields are simply converted.
086: * Boolean fields return 0.0 if false, and 1.0 if true.
087: * String fields are parsed.
088: * If a parsed string contains an error, ot the field value is not of a type that can be converted
089: * (i.e. a byte array), this function returns -1.0.
090: *
091: * @return the field value as a float
092: */
093: public float toFloat();
094:
095: /**
096: * Returns the value as a double.
097: * This function attempts to convert the value to a double.
098: * Numeric fields are simply converted. Double may be truncated.
099: * Boolean fields return 0.0 if false, and 1.0 if true.
100: * String fields are parsed.
101: * If a parsed string contains an error, ot the field value is not of a type that can be converted
102: * (i.e. a byte array), this function returns -1.0.
103: *
104: * @return the field value as a double
105: */
106: public double toDouble();
107:
108: /**
109: * Returns the value as a long.
110: * This function attempts to convert the value to a long.
111: * Numeric fields are simply converted. Double and float values may be truncated.
112: * Boolean fields return 0 if false, and 1 if true.
113: * String fields are parsed.
114: * If a parsed string contains an error, ot the field value is not of a type that can be converted
115: * (i.e. a byte array), this function returns -1
116: *
117: * @return the field value as a long.
118: */
119: public long toLong();
120:
121: /**
122: * Returns the value as an int.
123: * This function attempts to convert the value to an int.
124: * Numeric fields are simply converted. Double and float values may be truncated.
125: * For Node values, the numeric key is returned.
126: * Long values return -1 of the value is too large.
127: * Boolean fields return 0 if false, and 1 if true.
128: * String fields are parsed.
129: * If a parsed string contains an error, ot the field value is not of a type that can be converted
130: * (i.e. a byte array), this function returns -1
131: *
132: * @return the field value as an int.
133: */
134: public int toInt();
135:
136: /**
137: * Returns the value as a Node.
138: * This function attempts to retrieve the node represented by the value.
139: * For numeric fields the node is retrieved using the numeric values as the node key.
140: * String fields are used as Node aliases, withw hich to retrieve the Node.
141: * If the node does not exist, or the value is of anotehr type, the function returns <code>null</code>.
142: *
143: * @return the field value as a Node
144: */
145: public Node toNode();
146:
147: /**
148: * Returns the value as a String.
149: * Byte arrays are converted to string using the default encoding (UTF8).
150: * Node values return a string representation of their numeric key.
151: * DOM Documents are serialized to a proper strign represnattion fo the xml.
152: * For other values the result is calling the toString() method on the actual object.
153: *
154: * @return the field value as a String
155: */
156: public String toString();
157:
158: /**
159: * Returns the value as a <code>org.w3c.dom.Document</code>
160: * If the node value is not itself a Document, the method attempts to
161: * attempts to convert the String value into an XML.
162: * If the value cannot be converted, this method returns <code>null</code>
163: *
164: * @return the field value as a Document
165: * @throws IllegalArgumentException if the Field is not of type TYPE_XML.
166: */
167: public org.w3c.dom.Document toXML() throws IllegalArgumentException;
168:
169: /**
170: * Returns the value as a <code>java.util.Date</code>
171: * If the value cannot be converted, this method returns <code>null</code>
172: * @return the field value as Date
173: * @since MMBase-1.8
174: */
175: public java.util.Date toDate();
176:
177: /**
178: * Returns the value as a <code>org.w3c.dom.Element</code>
179: * If the node value is not itself a Document, the method attempts to
180: * attempts to convert the String value into an XML.
181: * This method fails (throws a IllegalArgumentException) if the Field is not of type TYPE_XML.
182: * If the value cannot be converted, this method returns <code>null</code>
183: *
184: * @param tree the DOM Document to which the Element is added
185: * (as the document root element)
186: * @return the field value as an Element
187: * @throws IllegalArgumentException if the Field is not of type TYPE_XML.
188: */
189: public org.w3c.dom.Element toXML(org.w3c.dom.Document tree)
190: 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: }
|