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     * © 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>&lt;record-type&gt;</i>/<i>&lt;field-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</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    }