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><record-type></i>/<i><field-name></i>@<i><db-set></i>/<i><user-db></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}