1 /**
2 * 2007, Digitalis Informatica. All rights reserved. Distribuicao e Gestao de Informatica, Lda. Estrada de Paco de Arcos
3 * num.9 - Piso -1 2780-666 Paco de Arcos Telefone: (351) 21 4408990 Fax: (351) 21 4408999 http://www.digitalis.pt
4 */
5 package pt.digitalis.dif.dem.objects.parameters;
6
7 import java.math.BigDecimal;
8 import java.util.Date;
9 import java.util.List;
10 import java.util.Map;
11
12 import pt.digitalis.dif.controller.interfaces.IDIFContext;
13 import pt.digitalis.dif.dem.Entity;
14 import pt.digitalis.dif.dem.interfaces.IStageInstance;
15 import pt.digitalis.dif.dem.objects.parameters.constraints.IParameterConstraint;
16 import pt.digitalis.dif.dem.objects.parameters.errors.ParameterErrorList;
17 import pt.digitalis.dif.dem.objects.parameters.rules.IParameterRule;
18 import pt.digitalis.dif.dem.objects.parameters.validators.IParameterValidator;
19 import pt.digitalis.dif.exception.objects.ParameterException;
20 import pt.digitalis.dif.utils.extensions.document.DocumentRepositoryEntry;
21
22 /**
23 * This class will define a Parameter.
24 * <p>
25 * It will hold information relative to the Parameter value, ID key and validation constraints.
26 *
27 * @param <T>
28 * generic type of the parameter
29 * @author Pedro Viegas <a href="mailto:pviegas@digitalis.pt">pviegas@digitalis.pt</a>
30 * @created Nov 23, 2007
31 */
32 public interface IParameter<T> extends Cloneable {
33
34 /**
35 * Creates a new instance of the current object
36 *
37 * @return {@link IParameter} clone
38 * @throws CloneNotSupportedException
39 */
40 public IParameter<T> clone() throws CloneNotSupportedException;
41
42 /**
43 * Parameter Initializer. Since IoC provides the construction this should be called after TODO: Refactor this
44 * method!! This is a bad coding practice! Methods should have between 3 and 7 arguments. Nine is too much. Use
45 * encapsulation.
46 *
47 * @param id
48 * the parameter id
49 * @param parentType
50 * the parent entity type
51 * @param parentID
52 * the id of the parent entity
53 * @param persistToRepository
54 * if the parameter value should be persisted to the repository
55 * @param allowAnonymous
56 * if a USER scoped parameter should allow anonymous access
57 * @param parameterScope
58 * the scope of the parameter
59 * @param defaultValue
60 * the parameter default value
61 * @param constraints
62 * the string that defines the constraints to apply
63 * @param formLinked
64 * the form name of null if not set
65 * @param readonly
66 * @param referencedInARuleFromAnotherParameter
67 * the new referencedInARuleFromAnotherParameter value to set
68 * @param required
69 * @param formConfigurable
70 * T if the form is configurable
71 * @param validators
72 * a validator list to validate the parameter values
73 * @param rules
74 * the parameter rules
75 * @param value
76 */
77 public void forceInitialize(boolean allowAnonymous, Map<String, IParameterConstraint> constraints, T defaultValue,
78 String formLinked, String id, ParameterScope parameterScope, String parentID, Entity parentType,
79 boolean persistToRepository, boolean readonly, boolean referencedInARuleFromAnotherParameter,
80 boolean required, boolean formConfigurable, List<IParameterRule<T>> rules,
81 Map<String, IParameterValidator> validators, T value);
82
83 /**
84 * @return the constraints
85 */
86 public Map<String, IParameterConstraint> getConstraints();
87
88 /**
89 * @return the form name of null if not set
90 */
91 public String getFormLinked();
92
93 /**
94 * @return the id
95 */
96 public String getId();
97
98 /**
99 * @return the persistScope
100 */
101 public ParameterScope getParameterScope();
102
103 /**
104 * @return the parentID
105 */
106 public String getParentID();
107
108 /**
109 * @return the parentType
110 */
111 public Entity getParentType();
112
113 /**
114 * Inspector for the 'rules' attribute.
115 *
116 * @return the rules value
117 */
118 public List<IParameterRule<T>> getRules();
119
120 /**
121 * @return the list of supported class types for the parameter value
122 */
123 public List<String> getSupportedClasses();
124
125 /**
126 * @return the validators
127 */
128 public Map<String, IParameterValidator> getValidators();
129
130 /**
131 * Returns the parameter value. This method will check a number of possible sources for the value of the parameter
132 * depending on it's scope and attributes.
133 *
134 * @param context
135 * the DIF context to read if needed
136 * @return the value
137 * @throws ParameterException
138 * if the parameter could not be read
139 */
140 public T getValue(IDIFContext context) throws ParameterException;
141
142 /**
143 * @param context
144 * the DIF context to read if needed
145 * @return the value of the parameter as a Double
146 * @throws ParameterException
147 * if a conversion error occurs
148 */
149 public BigDecimal getValueAsBigDecimal(IDIFContext context) throws ParameterException;
150
151 /**
152 * @param context
153 * the DIF context to read if needed
154 * @return the value of the parameter as a boolean
155 * @throws ParameterException
156 * if the parameter value cannot be read
157 */
158 public boolean getValueAsBoolean(IDIFContext context) throws ParameterException;
159
160 /**
161 * @param context
162 * the DIF context to read if needed
163 * @return the value of the parameter as a Date
164 * @throws ParameterException
165 * if a conversion error occurs
166 */
167 public Date getValueAsDate(IDIFContext context) throws ParameterException;
168
169 /**
170 * Returns the parameter value as a Document Note: Only Document types parameters will correctly respond to this
171 * method. All others will report an invalid usage {@link ParameterException}
172 *
173 * @param context
174 * the DIF context to read if needed
175 * @return the string representation of the parameter value
176 * @throws ParameterException
177 * if the parameter value cannot be read
178 */
179 public DocumentRepositoryEntry getValueAsDocument(IDIFContext context) throws ParameterException;
180
181 /**
182 * @param context
183 * the DIF context to read if needed
184 * @return the value of the parameter as a Double
185 * @throws ParameterException
186 * if a conversion error occurs
187 */
188 public Double getValueAsDouble(IDIFContext context) throws ParameterException;
189
190 /**
191 * @param context
192 * the DIF context to read if needed
193 * @return the value of the parameter as an Long
194 * @throws ParameterException
195 * if a conversion error occurs
196 */
197 public Long getValueAsLong(IDIFContext context) throws ParameterException;
198
199 /**
200 * Returns the parameter value as a String
201 *
202 * @param context
203 * the DIF context to read if needed
204 * @return the string representation of the parameter value
205 * @throws ParameterException
206 * if the parameter value cannot be read
207 */
208 public String getValueAsString(IDIFContext context) throws ParameterException;
209
210 /**
211 * Parameter Initializer. Since IoC provides the construction this should be called after TODO: Refactor this
212 * method!! This is a bad coding practice! Methods should have between 3 and 7 arguments. Nine is too much. Use
213 * encapsulation.
214 *
215 * @param id
216 * the parameter id
217 * @param parentType
218 * the parent entity type
219 * @param parentID
220 * the id of the parent entity
221 * @param formConfigurable
222 * if the parameter can be configured for a given form
223 * @param persistToRepository
224 * if the parameter value should be persisted to the repository
225 * @param allowAnonymousAccess
226 * if a USER scoped parameter should allow anonymous access
227 * @param parameterScope
228 * the scope of the parameter
229 * @param defaultValue
230 * the parameter default value
231 * @param constraintDefinition
232 * the string that defines the constraints to apply
233 * @param validators
234 * a validator list to validate the parameter values
235 * @param rules
236 * the parameter rules
237 * @throws ParameterException
238 * if the default value can't be converted to the inner parameter type
239 */
240 public void initialize(String id, Entity parentType, String parentID, boolean formConfigurable,
241 boolean persistToRepository, boolean allowAnonymousAccess, ParameterScope parameterScope,
242 String defaultValue, String constraintDefinition, Map<String, IParameterValidator> validators,
243 List<IParameterRule<T>> rules) throws ParameterException;
244
245 /**
246 * @return the allowAnonymous
247 */
248 public boolean isAllowAnonymous();
249
250 /**
251 * Inspector for the 'formConfigurable' attribute.
252 *
253 * @return the formConfigurable value
254 */
255 public boolean isFormConfigurable();
256
257 /**
258 * @return T if the current parameter is of a numeric type
259 */
260 public boolean isNumeric();
261
262 /**
263 * @return the persistToRepository
264 */
265 public boolean isPersistToRepository();
266
267 /**
268 * @return the readonly
269 */
270 public boolean isReadonly();
271
272 /**
273 * Inspector for the 'referencedInARuleFromAnotherParameter' attribute.
274 *
275 * @return the referencedInARuleFromAnotherParameter value
276 */
277 public boolean isReferencedInARuleFromAnotherParameter();
278
279 /**
280 * @return the required
281 */
282 public boolean isRequired();
283
284 /**
285 * @return T if we can set the parameter with a String value representation
286 */
287 public boolean isStringSetterSupported();
288
289 /**
290 * Updates the value of the parameter from the relevant sources. This method will check a number of possible sources
291 * for the value of the parameter depending on it's scope and attributes.
292 *
293 * @param stageInstance
294 * the DIF stage to read if needed
295 * @return return the error message if the validation fails
296 */
297 public ParameterErrorList refreshParameterValue(IStageInstance stageInstance);
298
299 /**
300 * Sets the value of the parameter to its default and runs all constraints and validations
301 *
302 * @param stageInstance
303 * the requested stage
304 * @return return the error messages if the validation fails
305 */
306 public ParameterErrorList setDefaultValue(IStageInstance stageInstance);
307
308 /**
309 * Sets the value of the parameter to its default and runs all constraints and validations
310 *
311 * @param stageInstance
312 * the requested stage
313 * @param initializationInProgress
314 * T if called within the dif parameter initialization
315 * @return return the error messages if the validation fails
316 */
317 public ParameterErrorList setDefaultValue(IStageInstance stageInstance, boolean initializationInProgress);
318
319 /**
320 * Modifier for the 'formConfigurable' attribute.
321 *
322 * @param formConfigurable
323 * the new formConfigurable value to set
324 */
325 public void setFormConfigurable(boolean formConfigurable);
326
327 /**
328 * @param formLinked
329 */
330 public void setFormLinked(String formLinked);
331
332 /**
333 * Modifier for the 'referencedInARuleFromAnotherParameter' attribute.
334 *
335 * @param referencedInARuleFromAnotherParameter
336 * the new referencedInARuleFromAnotherParameter value to set
337 */
338 public void setReferencedInARuleFromAnotherParameter(boolean referencedInARuleFromAnotherParameter);
339
340 /**
341 * Sets the value of the parameter and runs all constraints and validations
342 *
343 * @param value
344 * the value to set
345 * @param stageInstance
346 * the DIF stage to read if needed. WARNING: If null is interpreted like an initialization and no scope
347 * repositories will be accessed/updated.
348 * @return return the error messages if the validation fails
349 */
350 public ParameterErrorList setValue(T value, IStageInstance stageInstance);
351
352 /**
353 * Sets the value of the parameter and runs all constraints and validations
354 *
355 * @param value
356 * the value to set
357 * @param stageInstance
358 * the DIF stage to read if needed. WARNING: If null is interpreted like an initialization and no scope
359 * repositories will be accessed/updated.
360 * @param initializationInProgress
361 * T if called within the dif parameter initialization
362 * @return return the error messages if the validation fails
363 */
364 public ParameterErrorList setValue(T value, IStageInstance stageInstance, boolean initializationInProgress);
365
366 /**
367 * Sets the value of the parameter converting if from a string representation and runs all constraints and
368 * validations
369 *
370 * @param value
371 * the value to set
372 * @param stageInstance
373 * the DIF stage to read if needed.
374 * @return return the error messages if the validation fails
375 */
376 public ParameterErrorList setValueFromString(String value, IStageInstance stageInstance);
377
378 /**
379 * Sets the value of the parameter converting if from a string representation and runs all constraints and
380 * validations
381 *
382 * @param value
383 * the value to set
384 * @param stageInstance
385 * the DIF stage to read if needed.
386 * @param initializationInProgress
387 * T if called within the dif parameter initialization
388 * @return return the error messages if the validation fails
389 */
390 public ParameterErrorList setValueFromString(String value, IStageInstance stageInstance,
391 boolean initializationInProgress);
392 }