1 /*
2 * $Source: /usr/cvsroot/melati/poem/src/main/java/org/melati/poem/PoemType.java,v $
3 * $Revision: 1.29 $
4 *
5 * Copyright (C) 2000 William Chesters
6 *
7 * Part of Melati (http://melati.org), a framework for the rapid
8 * development of clean, maintainable web applications.
9 *
10 * Melati is free software; Permission is granted to copy, distribute
11 * and/or modify this software under the terms either:
12 *
13 * a) the GNU General Public License as published by the Free Software
14 * Foundation; either version 2 of the License, or (at your option)
15 * any later version,
16 *
17 * or
18 *
19 * b) any version of the Melati Software License, as published
20 * at http://melati.org
21 *
22 * You should have received a copy of the GNU General Public License and
23 * the Melati Software License along with this program;
24 * if not, write to the Free Software Foundation, Inc.,
25 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
26 * GNU General Public License and visit http://melati.org to obtain the
27 * Melati Software License.
28 *
29 * Feel free to contact the Developers of Melati (http://melati.org),
30 * if you would like to work out a different arrangement than the options
31 * outlined here. It is our intention to allow Melati to be used by as
32 * wide an audience as possible.
33 *
34 * This program is distributed in the hope that it will be useful,
35 * but WITHOUT ANY WARRANTY; without even the implied warranty of
36 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
37 * GNU General Public License for more details.
38 *
39 * Contact details for copyright holder:
40 *
41 * William Chesters <williamc At paneris.org>
42 * http://paneris.org/~williamc
43 * Obrechtstraat 114, 2517VX Den Haag, The Netherlands
44 */
45
46 package org.melati.poem;
47
48 import java.util.Enumeration;
49
50 /**
51 * A data type.
52 * <p>
53 * PoemTypes come in two flavours: the predefined ones and those that can be
54 * defined by the application programmer; the former have a negative type code,
55 * the latter a positive one.
56 */
57 public interface PoemType {
58
59 /**
60 * Check if value is of the right type and an allowed value,
61 * throw appropriate Exception if not.
62 *
63 * @param raw the raw value to check
64 * @throws TypeMismatchPoemException if the raw is of the wrong type
65 * @throws ValidationPoemException if the raw has an illegal value
66 */
67 void assertValidRaw(Object raw)
68 throws TypeMismatchPoemException, ValidationPoemException;
69
70 /**
71 * Get the possible values for this field, null for rangeable types with
72 * no range set.
73 * NOTE Null is a possible value for nullable types
74 * @return an Enumeration of possibilities or null
75 */
76 Enumeration possibleRaws();
77
78 /**
79 * The String representation of the Field.
80 *
81 * @param raw the value
82 * @return a String representation
83 * @throws TypeMismatchPoemException if the raw is of the wrong type
84 * @throws ValidationPoemException if the raw has an illegal value
85 */
86 String stringOfRaw(Object raw)
87 throws TypeMismatchPoemException, ValidationPoemException;
88
89 /**
90 * Get an Object from its String representation.
91 *
92 * @param rawString the String representation to convert
93 * @return an Object of the correct type
94 * @throws ParsingPoemException if the String representation is not well formed
95 * @throws ValidationPoemException if the raw has an illegal value
96 */
97 Object rawOfString(String rawString)
98 throws ParsingPoemException, ValidationPoemException;
99
100 /**
101 * Check if an Object is valid, throw appropriate Exception if not.
102 *
103 * @param cooked the Object to check
104 * @throws TypeMismatchPoemException if the raw is of the wrong type
105 * @throws ValidationPoemException if the raw has an illegal value
106 */
107 void assertValidCooked(Object cooked)
108 throws TypeMismatchPoemException, ValidationPoemException;
109
110 /**
111 * Create an Object from a raw Object, a no-op for all but ReferencePoemTypes.
112 * @param raw the object, typically a troid
113 * @return the Persistent or the raw unchanged
114 * @throws TypeMismatchPoemException if the raw is of the wrong type
115 * @throws PoemException if there is another problem, such as no object with that troid
116 */
117 Object cookedOfRaw(Object raw)
118 throws TypeMismatchPoemException, PoemException;
119
120 /**
121 * Return the Object value, a no-op for all but ReferencePoemTypes,
122 * for which it returns the troid as an Integer.
123 *
124 * @param cooked the Persistent or Object
125 * @return a Persistent's troid or the raw unchanged
126 * @throws TypeMismatchPoemException if the raw is of the wrong type
127 */
128 Object rawOfCooked(Object cooked) throws TypeMismatchPoemException;
129
130 /**
131 * A localised String representation of the oject.
132 *
133 * @param style as in <TT>java.text.DateFormat.SHORT</TT>, ...
134 * @return a String representation of an Object
135 * @throws TypeMismatchPoemException if the raw is of the wrong type
136 * @throws PoemException if there is an access violation
137 */
138 String stringOfCooked(Object cooked, PoemLocale locale, int style)
139 throws TypeMismatchPoemException, PoemException;
140
141 /**
142 * Whether the type is nullable.
143 *
144 * @return the type's nullability
145 */
146 boolean getNullable();
147
148 /**
149 * Return a PoemType which can can represent another,
150 * or null.
151 *
152 * @param other the other type to check
153 * @return the other or null
154 */
155 PoemType canRepresent(PoemType other);
156
157 /**
158 * Get a new type with a nullablity, presumably different.
159 *
160 * @param nullable the nullability we want
161 * @return this or a clone with the desired nullability
162 */
163 PoemType withNullable(boolean nullable);
164
165 /**
166 * Set the type of the ColumnInfo.
167 *
168 * @param columnInfo the ColumnInfo to set the type of
169 * @throws AccessPoemException if our AccessToken does not permit modification
170 */
171 void saveColumnInfo(ColumnInfo columnInfo) throws AccessPoemException;
172
173 /**
174 * The field type used in the Data Structure Definition language.
175 * @return the Type name
176 */
177 String toDsdType();
178 }