KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > mmbase > datatypes > DataType


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.datatypes;
12
13 import java.util.*;
14 import java.io.Serializable JavaDoc;
15
16 import org.mmbase.bridge.*;
17 import org.mmbase.datatypes.processors.*;
18 import org.mmbase.bridge.util.Queries;
19 import org.mmbase.storage.search.*;
20 import org.mmbase.core.util.Fields;
21 import org.mmbase.core.AbstractDescriptor;
22 import org.mmbase.datatypes.DataTypes;
23 import org.mmbase.util.*;
24 import org.mmbase.util.logging.*;
25
26 /**
27  * A value in MMBase (such as the value of a field, or function parameter) is associated with a
28  * 'datatype'. A DataType is actually an elaborated wrapper arround a Class object, but besides
29  * this basic type of the value, it also defines restrictions on the values, a default value,
30  * Processors, and perhaps other properties (e.g. properties which describe indications for edit
31  * tool implementations).
32  *
33  * There are several extensions of DataType which normally add other kinds of restrictions which are
34  * specific for certain classes of values. All implementations of DataType extend from {@link
35  * BasicDataType}, but they can sometimes implement different extensions of DataType at the same time
36  * ('multiple inheritance').
37  *
38  * @author Pierre van Rooden
39  * @author Michiel Meeuwissen
40  * @since MMBase-1.8
41  * @version $Id: DataType.java,v 1.54 2006/07/18 12:56:55 michiel Exp $
42  */

43
44 public interface DataType extends Descriptor, Cloneable JavaDoc, Comparable JavaDoc, Serializable JavaDoc {
45
46     /**
47      * The XML Namespace to be used for creating datatype XML
48      */

49     public static final String JavaDoc XMLNS = org.mmbase.datatypes.util.xml.DataTypeReader.NAMESPACE_DATATYPES_1_0;
50
51     // XXXX MM: I think 'action' must be gone; it is silly.
52
static final int PROCESS_GET = 1;
53     static final int PROCESS_SET = 2;
54
55     /**
56      * Return value for {@link DataType.Restriction#getEnforceStrength}. This means that the value
57      * must be enforced always, and furthermore, that extensions (based on clone) cannot loosen
58      * it. For example, the absolute maximum for any datatype backed by a integer is
59      * Integer.MAX_VALUE, there is no way you can even store a bigger value in this, so this restriction is 'absolute'.
60      */

61     static final int ENFORCE_ABSOLUTE = Integer.MAX_VALUE;
62
63     /**
64      * Return value for {@link DataType.Restriction#getEnforceStrength}. This means that the value must be enforced always.
65      */

66     static final int ENFORCE_ALWAYS = 100000;
67
68     /**
69      * Return value for {@link DataType.Restriction#getEnforceStrength}. This means that the value must be enforced only if it was changed.
70      */

71     static final int ENFORCE_ONCHANGE = 10000;
72
73     /**
74      * Return value for {@link DataType.Restriction#getEnforceStrength}. This means that the value must be enforced only on creation.
75      */

76     static final int ENFORCE_ONCREATE = 1000;
77
78     /**
79      * Return value for {@link DataType.Restriction#getEnforceStrength}. This means that the
80      * value must be enforced never, so the restriction serves only as UI indication.
81      */

82     static final int ENFORCE_NEVER = 0;
83
84     /**
85      * Returned by {@link #validate} if no errors: an empty (nonmodifiable) Collection.
86      */

87     public static final Collection VALID = Collections.EMPTY_LIST;
88
89     /**
90      * Inherit properties and processors from the passed datatype.
91      */

92     public void inherit(BasicDataType origin);
93
94     /**
95      * Return the DataType from which this one inherited, or <code>null</code>
96      */

97     public DataType getOrigin();
98
99     /**
100      * Return an identifier for the basic type (i.e., 'string', 'int', 'datetime') supported by this datatype.
101      */

102     public String JavaDoc getBaseTypeIdentifier();
103
104     /**
105      * Return the datatype's basic (MMBase) type (i.e., STRING, INTEGER, DATETIME) as definied in the Field interface
106      * Note that in some cases (i.e. with older clouds) this may differ from the basic type of the datatype's field,
107      * which defines in what format the data is stored.
108      * @see Field#getType
109      */

110     public int getBaseType();
111
112         /**
113      * Returns the type of values that this data type accepts.
114      * @return the type as a Class
115      */

116     public Class JavaDoc getTypeAsClass();
117
118     /**
119      * Checks if the passed object is of the correct class (compatible with the type of this data type),
120      * and throws an IllegalArgumentException if it doesn't.
121      * @param value the value whose type (class) to check
122      * @throws IllegalArgumentException if the type is not compatible
123      */

124     public void checkType(Object JavaDoc value);
125
126     /**
127      * Tries to 'cast' an object for use with this parameter. E.g. if value is a String, but this
128      * parameter is of type Integer, then the string can be parsed to Integer.
129      *
130      *
131      * @param value The value to be filled in a value with this DataType.
132      * @param node Sometimes a node might be needed.
133      * @param field Sometimes a (or 'the') field might be needed.
134      */

135     public Object JavaDoc cast(Object JavaDoc value, Node node, Field field);
136
137     /**
138      * Before actually 'cast' an object to the right type, it may undergo some conversion by the
139      * datatype, e.g. enumerations may get resolved (enumerations have the feature that they can
140      * e.g. resolve java-constants to their values).
141      *
142      * This does not garantuee that the value has the 'proper' type, but only that it now can be
143      * cast to the right type without further problems. ({@link org.mmbase.util.Casting#toType} should do).
144      *
145      * preCast should not change the actual type of value. It is e.g. used in the
146      * Node#setStringValue, and the processor may expect a String there.
147      */

148     public Object JavaDoc preCast(Object JavaDoc value, Node node, Field field);
149
150     /**
151      * Returns the default value of this data type.
152      * @return the default value
153      */

154     public Object JavaDoc getDefaultValue();
155
156     /**
157      * @javadoc
158      */

159     public void setDefaultValue(Object JavaDoc def);
160
161     /**
162      * @javadoc
163      */

164     public DataType rewrite(Object JavaDoc owner);
165
166     /**
167      * @javadoc
168      */

169     public boolean isFinished();
170
171     /**
172      * @javadoc
173      */

174     public void finish(Object JavaDoc owner);
175
176
177     /**
178      * @see #validate(Object, Node, Field)
179      * @return The error message(s) if the value is not compatible. An empty collection if valid.
180      * @param value the value to be validated
181      */

182     public Collection /*<LocalizedString>*/ validate(Object JavaDoc value);
183
184     /**
185      * Checks if the passed object obeys the restrictions defined for this type.
186      * @param value the value to validate
187      * @param node the node for which the datatype is checked. If not <code>null</code>, and the
188      * datatype is determined as unique, than uniquness is checked for this value using the passed field.
189      * @param field the field for which the datatype is checked.
190      *
191      * @return The error message(s) if the value is not compatible. An empty collection if the value is valid.
192      */

193     public Collection /*<LocalizedString> */ validate(Object JavaDoc value, Node node, Field field);
194
195     /**
196      * Returns whether this field is required (should have content).
197      * Note that the MMBase core does not generally enforce required fields to be filled -
198      * If not provided, a default value (generally an empty string or the integer value -1)
199      * is filled in by the system.
200      *
201      * @return <code>true</code> if the field is required
202      */

203     public boolean isRequired();
204
205     /**
206      * Returns the 'required' restriction, containing the value, errormessages, and fixed status of this attribute.
207      * @return the restriction as a {@link DataType.Restriction}
208      */

209     public DataType.Restriction getRequiredRestriction();
210
211     /**
212      * Sets whether the data type requires a value, which means that it may not remain unfilled.
213      * @param required <code>true</code> if a value is required
214      * @throws InvalidStateException if the datatype was finished (and thus can no longer be changed)
215      */

216     public void setRequired(boolean required);
217
218     /**
219      * Returns whether this field has a unique restriction.
220      * Uniqueness is generally achieved through association of the datatype with one or more sets of fields.
221      * This is notably different from other datatype properties.
222      *
223      * Note that the MMBase core does not generally enforce uniqueness, but the storage layer might.
224      *
225      * @return <code>true</code> if the field is unique
226      */

227     public boolean isUnique();
228
229     /**
230      * Returns the 'unique' restriction, containing the value, error messages, and fixed status of this attribute.
231      * @return the restriction as a {@link DataType.Restriction}
232      */

233     public DataType.Restriction getUniqueRestriction();
234
235     /**
236      * Sets whether the data type requires a value.
237      * @param unique <code>true</code> if a value is unique
238      * @throws InvalidStateException if the datatype was finished (and thus can no longer be changed)
239      */

240     public void setUnique(boolean unique);
241
242     /**
243      * Returns an iterator over all possible values for this datatype, as {@link java.util.Map.Entry}s, or
244      * <code>null</code> if no enumeration restrictions apply. Every Map entry contains as key the
245      * 'value' for this datatype and as value it contains the description for this value in the
246      * given locale.
247      *
248      * This Iterator skips all entries which are impossible because of other restrictions on this datatype.
249      *
250      * @param locale for which to produce
251      * @param cloud Possibly the possible values depend on a cloud (security)
252      * @param node Possibly the possible values depend on an actual node (this may be, and in the default implementation is, ignored)
253      * @param field Possibly the possible values depend on an actual field (this may be, and in the default implementation is, ignored)
254      *
255      */

256     public Iterator getEnumerationValues(Locale locale, Cloud cloud, Node node, Field field);
257
258     /**
259      * Returns a (gui) value from a list of retsricted enumerated values, or
260      * <code>null</code> if no enumeration restrictions apply or teh value cannot be found.
261      *
262      * @param locale for which to produce
263      * @param cloud Possibly the possible values depend on a cloud (security)
264      * @param node Possibly the possible values depend on an actual node (this may be, and in the default implementation is, ignored)
265      * @param field Possibly the possible values depend on an actual field (this may be, and in the default implementation is, ignored)
266      * @param key the key for which to look up the (gui) value
267      */

268     public Object JavaDoc getEnumerationValue(Locale locale, Cloud cloud, Node node, Field field, Object JavaDoc key);
269
270     /**
271      * @return the LocalizedEntryListFactory which will be used to produce the result of {@link
272      * #getEnumerationValues}. Never <code>null</code>. This can be used to add more possible values.
273      */

274     public LocalizedEntryListFactory getEnumerationFactory();
275
276     /**
277      * The enumeration for this datatype as a {@link Restriction}.
278      */

279     public DataType.Restriction getEnumerationRestriction();
280
281     /**
282      * @javadoc
283      */

284     public CommitProcessor getCommitProcessor();
285
286     /**
287      * @javadoc
288      */

289     public void setCommitProcessor(CommitProcessor cp);
290
291     /**
292      * Returns the default processor for this action
293      * @param action either {@link #PROCESS_GET}, or {@link #PROCESS_SET}
294      * XXX What exactly would be against getGetProcesor(), getSetProcessor() ?
295      */

296     public Processor getProcessor(int action);
297
298     /**
299      * Returns the processor for this action and processing type
300      * @param action either {@link #PROCESS_GET}, or {@link #PROCESS_SET}
301      * @param processingType the MMBase type defining the type of value to process
302      */

303     public Processor getProcessor(int action, int processingType);
304
305     /**
306      * Sets the processor for this action
307      * @param action either {@link #PROCESS_GET}, or {@link #PROCESS_SET}
308      */

309     public void setProcessor(int action, Processor processor);
310
311     /**
312      * Sets the processor for this action
313      * @param action either {@link #PROCESS_GET}, or {@link #PROCESS_SET}
314      * @param processingType the MMBase type defining the type of value to process
315      */

316     public void setProcessor(int action, Processor processor, int processingType);
317
318     /**
319      * Returns a cloned instance of this datatype, inheriting all validation rules.
320      * Unlike the original datatype though, the cloned copy is declared unfinished even if the original
321      * was finished. This means that the cloned datatype can be changed.
322      */

323     public Object JavaDoc clone();
324
325     /**
326      * Returns a cloned instance of this datatype, inheriting all validation rules.
327      * Similar to calling clone(), but changes the data type name if one is provided.
328      * @param name the new name of the copied datatype (can be <code>null</code>, in which case the name is not changed).
329      */

330     public Object JavaDoc clone(String JavaDoc name);
331
332
333     /**
334      * Returns a DOM element describing this DataType.
335      * @todo EXPERIMENTAL.
336      */

337     public org.w3c.dom.Element JavaDoc toXml();
338
339     /**
340      * Fills this datatype in another XML (for example in the xml of {@link #getOrigin}, to make one XML, fully describing the DataType).
341      * The implementation of this method is <em>unfinished</em>!
342      * @todo EXPERIMENTAL
343      * @param element a 'datatype' element.
344      */

345     public void toXml(org.w3c.dom.Element JavaDoc element);
346
347     /**
348      * A restriction controls (one aspect of) the acceptable values of a DataType. A DataType generally has several restrictions.
349      */

350     public interface Restriction extends Serializable JavaDoc {
351
352         /**
353          * @javadoc
354          */

355         public String JavaDoc getName();
356
357         /**
358          * A Value describing the restriction, so depending on the semantics of this restriction, it
359          * can have virtually every type (as long as it is Serializable)
360          */

361         public Serializable JavaDoc getValue();
362
363         /**
364          * @javadoc
365          */

366         public void setValue(Serializable JavaDoc value);
367
368         /**
369          * If the restriction does not hold, the following error description can be used. On default
370          * these descriptions are searched in a resource bundle based on the name of this
371          * restriction.
372          */

373         public LocalizedString getErrorDescription();
374
375         /**
376          * @javadoc
377          */

378         public void setErrorDescription(LocalizedString errorDescription);
379
380         /**
381          * This function should contain the actual logic of the restriction. This does not consider
382          * the 'enforceStrength' (that is only used in the containing DataType implementation).
383          *
384          * @param value The value to check the restriction for
385          * @param node Some constrainst may need the Node.
386          * @param field Some constrainst may need the Field.
387          * @return Whether the supplied value is a valid value for this restriction.
388          */

389         public boolean valid(Object JavaDoc value, Node node, Field field);
390
391         /**
392          * If a restriction is 'fixed', the value and error-description cannot be changed any more.
393          */

394         public void setFixed(boolean fixed);
395
396         /**
397          * See {@link DataType#ENFORCE_ALWAYS}, {@link DataType#ENFORCE_ONCHANGE}, {@link DataType#ENFORCE_NEVER}.
398          */

399         public int getEnforceStrength();
400
401         /**
402          * @javadoc
403          */

404         public void setEnforceStrength(int v);
405
406     }
407
408 }
409
Popular Tags