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, 2015.  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
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.util.List;
019import java.util.Map;
020
021import javax.wvcm.WvcmException;
022import javax.wvcm.PropertyNameList.PropertyName;
023
024import com.ibm.rational.wvcm.stp.StpProperty;
025import com.ibm.rational.wvcm.stp.StpResource;
026import com.ibm.rational.wvcm.stp.StpProperty.Type;
027import com.ibm.rational.wvcm.stp.cq.CqQuery.Filter.Operation;
028import com.ibm.rational.wvcm.stpex.StpExBase;
029import com.ibm.rational.wvcm.stpex.StpExEnumeration;
030import 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 */
057public 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    /** For a back reference field, this property represent the name of another field
429     *  which forward references to this field.
430     */
431    PropertyName<String> BACK_REFERENCE_FIELDNAME =
432        new PropertyName<String>(PROPERTY_NAMESPACE, "back_reference_fieldname");
433
434    
435    /**
436     * Returns the value of the {@link #BACK_REFERENCE_FIELDNAME}
437     * property as defined by this proxy.
438     * 
439     * @return The name of another field which forward references to this field.
440     * 
441     * @throws WvcmException if this proxy does not define a value for the
442     *             {@link #BACK_REFERENCE_FIELDNAME} property.
443     */
444    String getBackReferenceFieldName() throws WvcmException;
445    
446    /**
447     * Returns a list of the comparison operators that may be used with this
448     * field in a {@link CqQuery.FilterLeaf} construct.
449     */
450    PropertyName<Operation[]> LEGAL_COMP_OPS =
451        new PropertyName<Operation[]>(PROPERTY_NAMESPACE, "legal-comp-ops");
452
453    /**
454     * Returns the value of the {@link #LEGAL_COMP_OPS LEGAL_COMP_OPS} property
455     * as defined by this proxy.
456     * 
457     * @return An array of CqQuery.Filter.Operation enumerators, each specifying
458     *         a comparison operator that can be used with this field. Will
459     *         never be <b>null</b>.
460     * 
461     * @throws WvcmException if this proxy does not define a value for the
462     *             {@link #LEGAL_COMP_OPS LEGAL_COMP_OPS} property.
463     */
464    Operation[] getLegalCompOps() throws WvcmException;
465
466    /**
467     * true if and only if this property may be used in forming queries.
468     */
469    public static final PropertyName<Boolean> IS_AVAILABLE_FOR_QUERIES =
470        new PropertyName<Boolean>(PROPERTY_NAMESPACE,
471                                  "is-available-for-queries");
472
473    /**
474     * Returns the value of the
475     * {@link CqFieldDefinition#IS_AVAILABLE_FOR_QUERIES
476     * IS_AVAILABLE_FOR_QUERIES} property as defined by this proxy.
477     * 
478     * @return <b>true</b> if this property may be used in a query filter.
479     * 
480     * @throws WvcmException if this proxy does not define a value for the
481     *             {@link CqFieldDefinition#IS_AVAILABLE_FOR_QUERIES
482     *             IS_AVAILABLE_FOR_QUERIES} property.
483     */
484    public boolean getIsAvailableForQueries() throws WvcmException;
485
486    /**
487     * The data type of the values of the field defined by this field
488     * definition using the generic StpProperty.Type enumeration.
489     * 
490     * @see #FIELD_TYPE
491     */
492    public static final PropertyName<StpProperty.Type> VALUE_TYPE =
493        new PropertyName<StpProperty.Type>(PROPERTY_NAMESPACE, "value-type");
494
495    /**
496     * Returns the value of the {@link CqFieldDefinition#VALUE_TYPE} property as
497     * defined by this proxy.
498     * 
499     * @return The value type. Will never be <b>null</b>.
500     * 
501     * @throws WvcmException if this proxy does not define a value for the
502     *             {@link CqFieldDefinition#VALUE_TYPE} property.
503     *             
504     * @see #getFieldType()
505     */
506    public StpProperty.Type getValueType() throws WvcmException;
507}