001 /*
002 * file CqFieldDefinition.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqFieldDefinition
008 *
009 * (C) Copyright IBM Corporation 2004, 2008. All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights: Use, duplication or
011 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
012 */
013
014 package com.ibm.rational.wvcm.stp.cq;
015
016 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018 import java.util.List;
019 import java.util.Map;
020
021 import javax.wvcm.WvcmException;
022 import javax.wvcm.PropertyNameList.PropertyName;
023
024 import com.ibm.rational.wvcm.stp.StpProperty;
025 import com.ibm.rational.wvcm.stp.StpResource;
026 import com.ibm.rational.wvcm.stp.StpProperty.Type;
027 import com.ibm.rational.wvcm.stp.cq.CqQuery.Filter.Operation;
028 import com.ibm.rational.wvcm.stpex.StpExBase;
029 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
030 import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
031
032
033 /**
034 * A client proxy for a field definition metadata object.
035 *
036 * <p>
037 * This object defines the characteristics of a field of a record type in a
038 * database schema. Since field definitions are schema objects, they cannot be
039 * created, modified, or deleted by the client. Any client may assume that a
040 * field definition will remain unchanged for the duration of an active session
041 * and therefore, the client need only fetch field definitions from the server
042 * once per session. Field definitions are usually fetched when the CqRecordType
043 * resource of which they are a part is fetched.
044 * <p>
045 * An array of CqFieldDefintions is used to define a query field path, used in
046 * both {@link CqQuery.DisplayField} and {@link CqQuery.FilterLeaf}
047 * specifications.
048 * <p>
049 * CqFieldDefinitions are also used in a {@link CqUserDb.SearchFilter} to limit
050 * a full-text search to values in specific fields.
051 * <p>
052 * The user-friendly specification for the location of a field definition has the form
053 * <pre>
054 * <b>cq.field:</b><i><record-type></i>/<i><field-name></i>@<i><db-set></i>/<i><user-db></i>
055 * </pre>
056 */
057 public interface CqFieldDefinition extends CqUserDbMember,
058 CqUserDb.SearchKey<List<String>>
059 {
060 /**
061 * An enumeration of the possible restrictions on assigning a value to a
062 * field.
063 */
064 public enum Requiredness implements StpExEnumeration
065 {
066 /** field is READ_ONLY; its value cannot be changed. */
067 READ_ONLY,
068
069 /** a field value is MANDATORY; a non-null value must be provided. */
070 MANDATORY,
071
072 /**
073 * a field value is OPTIONAL; a non-null value may be provider but is
074 * not required
075 */
076 OPTIONAL,
077
078 /** a field value is determined by calling the associated hook */
079 USE_HOOK;
080 }
081
082 /**
083 * The data type of the value of the field defined by this field definition.
084 */
085 public static final PropertyName<CqFieldValue.ValueType> FIELD_TYPE =
086 new PropertyName<CqFieldValue.ValueType>(PROPERTY_NAMESPACE,
087 "field-type");
088
089 /**
090 * Returns the value of the {@link #FIELD_TYPE} property as defined by this
091 * proxy.
092 *
093 * @return The field value type as a CqFieldValue.ValueType enumerator. Will
094 * never be <b>null</b>.
095 *
096 * @throws WvcmException if this proxy does not define a value for the
097 * {@link #FIELD_TYPE} property.
098 */
099 public CqFieldValue.ValueType getFieldType() throws WvcmException;
100
101 /** A short phrase describing the purpose and function of this field. */
102 PropertyName<String> HELP_TEXT =
103 new PropertyName<String>(PROPERTY_NAMESPACE, "help-text");
104
105 /**
106 * Returns the value of the {@link #HELP_TEXT HELP_TEXT} property as defined
107 * by this proxy.
108 *
109 * @return A string containing a short description of the role of this field
110 * in the schema.
111 *
112 * @throws WvcmException if this proxy does not define a value for the
113 * {@link #HELP_TEXT HELP_TEXT} property.
114 */
115 public String getHelpText() throws WvcmException;
116
117 /** Record type of the record referenced by this field */
118 PropertyName<CqRecord> REFERENCED_RECORD_TYPE =
119 new PropertyName<CqRecord>(PROPERTY_NAMESPACE, "referenced-record-type");
120
121 /**
122 * Returns the value of the {@link #REFERENCED_RECORD_TYPE
123 * REFERENCED_RECORD_TYPE} property as defined by this proxy.
124 *
125 * @return A CqRecordType proxy representing the type of record that
126 * that is referenced by this field; <b>null</b> if this field is
127 * not type {@link CqFieldValue.ValueType#RESOURCE} or
128 * {@link CqFieldValue.ValueType#RESOURCE_LIST}
129 *
130 * @throws WvcmException if this proxy does not define a value for the
131 * {@link #REFERENCED_RECORD_TYPE REFERENCED_RECORD_TYPE}
132 * property.
133 */
134 public CqRecordType getReferencedRecordType() throws WvcmException;
135
136 /**
137 * A CqRecordType proxy for the record-type resource of which this resource
138 * defines a field.
139 */
140 PropertyName<CqRecordType> RECORD_TYPE =
141 new PropertyName<CqRecordType>(PROPERTY_NAMESPACE, "record-type");
142
143 /**
144 * Returns the value of the {@link #RECORD_TYPE RECORD_TYPE} property as
145 * defined by this proxy.
146 *
147 * @return The CqRecordType proxy for the record-type that contains this
148 * field definition.
149 *
150 * @throws WvcmException if this proxy does not define a value for the
151 * {@link #RECORD_TYPE RECORD_TYPE} property.
152 */
153 public CqRecordType getRecordType() throws WvcmException;
154
155 /**
156 * The schema-defined behavior (read-only, mandatory, or optional) of this
157 * field for each state name in the record type's state table. (The
158 * schema-defined behavior for a field of a stateless record type is
159 * associated with the state name "*".) Also includes the default,
160 * system-imposed requiredness for the field as the value associated with
161 * the state name "".
162 */
163 PropertyName<Map<String, Requiredness>> REQUIREDNESS_BY_STATE =
164 new PropertyName<Map<String, Requiredness>>(PROPERTY_NAMESPACE,
165 "requiredness-by-state");
166
167 /**
168 * Returns the value of the {@link #REQUIREDNESS_BY_STATE
169 * REQUIREDNESS_BY_STATE} property as defined by this proxy.
170 *
171 * @return A Map from String to Requiredness objects specifying for each
172 * state of the record the Requiredness of this field. For stateless
173 * record types, which have no states, the "*" key is mapped to the
174 * schema-defined requiredness for the field. In all cases, the
175 * empty key ("") is mapped to the default (system-imposed)
176 * requiredness for the field.
177 *
178 * @throws WvcmException if this proxy does not define a value for the
179 * {@link #REQUIREDNESS_BY_STATE REQUIREDNESS_BY_STATE}
180 * property.
181 */
182 public Map<String, Requiredness> getRequirednessByState()
183 throws WvcmException;
184
185 /**
186 * A list of possible values for fields of this type.
187 * <p>
188 * In general, the content of a field's choice list is quite volatile and
189 * can depend on the state of the record it is in, the value of other fields
190 * of that record or related records, the current user's permissions, and
191 * other dynamic aspects of the database environment known only to the
192 * schema. So, in general, the choice list must be obtained in the context
193 * in which it is to be used at the time it is to be used. In this
194 * interface, that very dynamic value is expressed as the value of the
195 * {@link CqFieldValue#CHOICE_LIST CHOICE_LIST} meta-property of the
196 * CqFieldValue property representing the field of the record that is to be
197 * set with a value from the choice list.
198 * <p>
199 * {@link CqFieldValue#CHOICE_LIST} always returns the choice list for the
200 * field based on all factors that could influence its content. The values
201 * returned by this property are based only on the current state of the
202 * database, but not on the state of any specific record. If the schema is
203 * designed such that the choice list for this field does not depend on the
204 * value of other fields in the record, then the list returned by this
205 * property will be the same as that returned by
206 * {@link CqFieldValue#CHOICE_LIST}.
207 * <p>
208 * Currently, there is no way for a client to interrogate a schema to
209 * discover the dynamics of its choice list computations. When presenting
210 * choices to a user for the purpose of actually setting a field value into
211 * a specific record, {@link CqFieldValue#CHOICE_LIST} should always be used.
212 * In contexts where no specific record is indicated (as in defining a query,
213 * for example) the value of this property would be most appropriate.
214 * <p>
215 * If this property is empty, it neither implies that all values are
216 * permitted nor that no values are permitted; it just means that the schema
217 * designer has not provided any hints about the values permitted in the
218 * field.
219 * <p>
220 * Choice lists can be voluminous and, so, should be read from the server
221 * only when needed. Yet, as explained above, they can also be quite
222 * volatile and may easily change during the course of a session and not
223 * necessarily in direct response to anything the client is doing.
224 *
225 * @see CqFieldValue#CHOICE_LIST
226 */
227 PropertyName<List<String>> CHOICE_LIST =
228 new PropertyName<List<String>>(PROPERTY_NAMESPACE, "choice-list");
229
230 /**
231 * Returns the value of the {@link #CHOICE_LIST CHOICE_LIST}
232 * property as defined by this proxy.
233 *
234 * @return A List of the values defined statically by the database schema as
235 * valid values for fields of this description.
236 *
237 * @throws WvcmException if this proxy does not define a value for the
238 * {@link #CHOICE_LIST CHOICE_LIST} property.
239 */
240 public List<String> getChoiceList() throws WvcmException;
241
242 /**
243 * Whether or not values not in the field's choice list are permitted as
244 * legal field values.
245 * <p>
246 * The schema designer specifies whether the legal values for a given field
247 * are restricted to the contents of its choice list and that specification
248 * is captured by this property. If there is a restriction, specifying a
249 * value not in the choice list causes a validation error. If there is no
250 * restriction, values not in the choice list may be used. (Note that any
251 * values must still be validated by the schema at the time the record is
252 * delivered to the database.)
253 */
254 PropertyName<Boolean> HAS_OPEN_CHOICE_LIST =
255 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-open-choice-list");
256
257 /**
258 * Returns the value of the {@link #HAS_OPEN_CHOICE_LIST
259 * HAS_OPEN_CHOICE_LIST} property as defined by this proxy.
260 * Requires SQL-editor permission.
261 *
262 * @return <b>True</b> if legal values for this field are <i>not</i>
263 * constrained to those that appear in its choice list.
264 *
265 * @throws WvcmException if this proxy does not define a value for the
266 * {@link #HAS_OPEN_CHOICE_LIST HAS_OPEN_CHOICE_LIST} property.
267 *
268 */
269 public boolean getHasOpenChoiceList() throws WvcmException;
270
271 /**
272 * Whether or not the content of the field's choice list are computed with
273 * the aid of a hook-script.
274 *
275 * Requires SQL-editor permission
276 */
277 PropertyName<Boolean> HAS_SCRIPTED_CHOICE_LIST =
278 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
279 "has-scripted-choice-list");
280
281 /**
282 * Returns the value of the {@link #HAS_SCRIPTED_CHOICE_LIST
283 * HAS_SCRIPTED_CHOICE_LIST} property as defined by this proxy.
284 *
285 * @return <b>True</b> the content of the field's choice list are computed
286 * with the aid of a hook-script; <b>False</b> if not.
287 *
288 * @throws WvcmException if this proxy does not define a value for the
289 * {@link #HAS_OPEN_CHOICE_LIST HAS_OPEN_CHOICE_LIST} property.
290 *
291 * Requires SQL-editor permission
292 */
293 public boolean getHasScriptedChoiceList() throws WvcmException;
294
295 /**
296 * Indicates that the content of the choice list for this field is liable to
297 * be recalculated each time it is accessed. Such choice lists probably
298 * should not be cached on the client.
299 *
300 * Requires SQL-editor permission
301 */
302 PropertyName<Boolean> CALCULATES_CHOICE_LIST_EACH_ACCESS =
303 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
304 "calculates-choice-list-each-access");
305
306 /**
307 * Returns the value of the {@link #CALCULATES_CHOICE_LIST_EACH_ACCESS
308 * CALCULATES_CHOICE_LIST_EACH_ACCESS} property as defined by this proxy.
309 *
310 * @return <b>True</b> if the choice list for this field is liable to be
311 * recalculated each time it is referenced.
312 *
313 * @throws WvcmException if this proxy does not define a value for the
314 * {@link #CALCULATES_CHOICE_LIST_EACH_ACCESS CALCULATES_CHOICE_LIST_EACH_ACCESS}
315 * property.
316 *
317 * Requires SQL-editor permission
318 */
319 public boolean getCalculatesChoiceListEachAccess() throws WvcmException;
320
321 /**
322 * Identifies the dynamic choice list used by this field as its choice list
323 *
324 * Requires SQL-editor permission
325 */
326 PropertyName<CqDynamicChoiceList> DYNAMIC_CHOICE_LIST =
327 new PropertyName<CqDynamicChoiceList>(PROPERTY_NAMESPACE,
328 "dynamic-choice-list");
329
330 /**
331 * Returns the value of the {@link #DYNAMIC_CHOICE_LIST DYNAMIC_CHOICE_LIST}
332 * property as defined by this proxy.
333 *
334 * @return A CqDynamcChoiceList proxy for the dynamic choice list used by
335 * this field as its choice list; <b>null</b> if this field does
336 * not use a dynamic choice list as its choice list.
337 *
338 * @throws WvcmException if this proxy does not define a value for the
339 * {@link #DYNAMIC_CHOICE_LIST DYNAMIC_CHOICE_LIST} property.
340 *
341 * Requires SQL-editor permission
342 */
343 public CqDynamicChoiceList getDynamicChoiceList() throws WvcmException;
344
345 /**
346 * The maximum length of a string permitted as this field's value.
347 *
348 * This property requires the CQ SQL Editor permission.
349 */
350 PropertyName<Long> MAXIMUM_STRING_LENGTH =
351 new PropertyName<Long>(PROPERTY_NAMESPACE, "maximum-string-length");
352
353 /**
354 * Returns the value of the {@link #MAXIMUM_STRING_LENGTH
355 * MAXIMUM_STRING_LENGTH} property as defined by this proxy.
356 *
357 * @return The maximum string length permitted for the value of this field.
358 *
359 * @throws WvcmException if this proxy does not define a value for the
360 * {@link #MAXIMUM_STRING_LENGTH MAXIMUM_STRING_LENGTH}
361 * property.
362 *
363 * Requires SQL-editor permission
364 */
365 public long getMaximumStringLength() throws WvcmException;
366
367 /** Whether or not this field can be a security context field */
368 PropertyName<Boolean> CAN_BE_SECURITY_CONTEXT =
369 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "can-be-security-context");
370
371 /**
372 * Returns the value of the {@link #CAN_BE_SECURITY_CONTEXT
373 * CAN_BE_SECURITY_CONTEXT} property as defined by this proxy.
374 *
375 * @return true if this field can be a security context field
376 *
377 * @throws WvcmException if this proxy does not define a value for the
378 * {@link #CAN_BE_SECURITY_CONTEXT CAN_BE_SECURITY_CONTEXT}
379 * property.
380 */
381 boolean getCanBeSecurityContext() throws WvcmException;
382
383 /** Whether or not this field is a security context field */
384 PropertyName<Boolean> IS_SECURITY_CONTEXT =
385 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-security-context");
386
387 /**
388 * Returns the value of the {@link #IS_SECURITY_CONTEXT IS_SECURITY_CONTEXT}
389 * property as defined by this proxy.
390 *
391 * @return True if this field is a security context field
392 *
393 * @throws WvcmException if this proxy does not define a value for the
394 * {@link #IS_SECURITY_CONTEXT IS_SECURITY_CONTEXT} property.
395 */
396 boolean getIsSecurityContext() throws WvcmException;
397
398 /** The column name for this field in the database table for its record */
399 PropertyName<String> DB_NAME =
400 new PropertyName<String>(PROPERTY_NAMESPACE, "db-name");
401
402 /**
403 * Returns the value of the {@link #DB_NAME DB_NAME} property as defined by
404 * this proxy.
405 *
406 * @return A String containing the database column name for this field
407 *
408 * @throws WvcmException if this proxy does not define a value for the
409 * {@link #DB_NAME DB_NAME} property.
410 */
411 String getDbName() throws WvcmException;
412
413 /** Whether or not this field is owned by the system (built-in) */
414 PropertyName<Boolean> IS_SYSTEM_OWNED =
415 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-system-owned");
416
417 /**
418 * Returns the value of the {@link #IS_SYSTEM_OWNED IS_SYSTEM_OWNED}
419 * property as defined by this proxy.
420 *
421 * @return True if this field is system owned.
422 *
423 * @throws WvcmException if this proxy does not define a value for the
424 * {@link #IS_SYSTEM_OWNED IS_SYSTEM_OWNED} property.
425 */
426 boolean getIsSystemOwned() throws WvcmException;
427
428 /**
429 * Returns a list of the comparison operators that may be used with this
430 * field in a {@link CqQuery.FilterLeaf} construct.
431 */
432 PropertyName<Operation[]> LEGAL_COMP_OPS =
433 new PropertyName<Operation[]>(PROPERTY_NAMESPACE, "legal-comp-ops");
434
435 /**
436 * Returns the value of the {@link #LEGAL_COMP_OPS LEGAL_COMP_OPS} property
437 * as defined by this proxy.
438 *
439 * @return An array of CqQuery.Filter.Operation enumerators, each specifying
440 * a comparison operator that can be used with this field. Will
441 * never be <b>null</b>.
442 *
443 * @throws WvcmException if this proxy does not define a value for the
444 * {@link #LEGAL_COMP_OPS LEGAL_COMP_OPS} property.
445 */
446 Operation[] getLegalCompOps() throws WvcmException;
447
448 /**
449 * true if and only if this property may be used in forming queries.
450 */
451 public static final PropertyName<Boolean> IS_AVAILABLE_FOR_QUERIES =
452 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
453 "is-available-for-queries");
454
455 /**
456 * Returns the value of the
457 * {@link CqFieldDefinition#IS_AVAILABLE_FOR_QUERIES
458 * IS_AVAILABLE_FOR_QUERIES} property as defined by this proxy.
459 *
460 * @return <b>true</b> if this property may be used in a query filter.
461 *
462 * @throws WvcmException if this proxy does not define a value for the
463 * {@link CqFieldDefinition#IS_AVAILABLE_FOR_QUERIES
464 * IS_AVAILABLE_FOR_QUERIES} property.
465 */
466 public boolean getIsAvailableForQueries() throws WvcmException;
467
468 /**
469 * The data type of the values of the field defined by this field
470 * definition using the generic StpProperty.Type enumeration.
471 *
472 * @see #FIELD_TYPE
473 */
474 public static final PropertyName<StpProperty.Type> VALUE_TYPE =
475 new PropertyName<StpProperty.Type>(PROPERTY_NAMESPACE, "value-type");
476
477 /**
478 * Returns the value of the {@link CqFieldDefinition#VALUE_TYPE} property as
479 * defined by this proxy.
480 *
481 * @return The value type. Will never be <b>null</b>.
482 *
483 * @throws WvcmException if this proxy does not define a value for the
484 * {@link CqFieldDefinition#VALUE_TYPE} property.
485 *
486 * @see #getFieldType()
487 */
488 public StpProperty.Type getValueType() throws WvcmException;
489 }