001 /*
002 * file CqRecordType.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqRecordType
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
017 import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
018
019 import java.io.File;
020 import java.util.List;
021
022 import javax.wvcm.Feedback;
023 import javax.wvcm.ResourceList;
024 import javax.wvcm.WvcmException;
025 import javax.wvcm.PropertyNameList.PropertyName;
026
027 import com.ibm.rational.wvcm.stp.cqex.CqExForm;
028 import com.ibm.rational.wvcm.stpex.StpExEnumeration;
029 import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
030
031
032 /**
033 * A proxy for the specification of a record type in a database.
034 *
035 * The user-friendly specification for the location of a record type has the form
036 * <pre>
037 * <b>cq.record:</b><i><record-type-name></i>@<i><db-set></i>/<i><user-db></i>
038 * </pre>
039 */
040 public interface CqRecordType
041 extends CqUserDbMember, CqUserDb.SearchKey<Boolean>
042 {
043 /** A list of the field definitions of this record type */
044 PropertyName<ResourceList<CqFieldDefinition>> FIELD_DEFINITIONS =
045 new PropertyName<ResourceList<CqFieldDefinition>>(PROPERTY_NAMESPACE,
046 "field-definitions");
047
048 /**
049 * Returns the value of the {@link #FIELD_DEFINITIONS FIELD_DEFINITIONS}
050 * property as defined by this proxy.
051 *
052 * @return A ResourceList of CqFieldDefinition record proxies; one proxy
053 * per field of this record type. Will never by <b>null</b>.
054 *
055 * @throws WvcmException if this proxy does not define a value for the
056 * {@link #FIELD_DEFINITIONS FIELD_DEFINITIONS} property.
057 */
058 public ResourceList<CqFieldDefinition> getFieldDefinitions()
059 throws WvcmException;
060
061 /** All of the actions defined on this record type. */
062 PropertyName<ResourceList<CqAction>> ACTION_LIST =
063 new PropertyName<ResourceList<CqAction>>(PROPERTY_NAMESPACE,
064 "action-list");
065
066 /**
067 * Returns the value of the {@link #ACTION_LIST ACTION_LIST} property as
068 * defined by this proxy.
069 *
070 * @return A ResourceList of CqAction proxies containing all of the actions
071 * defined for this record type.
072 *
073 * @throws WvcmException if this proxy does not define a value for the
074 * {@link #ACTION_LIST ACTION_LIST} property.
075 */
076 public ResourceList<CqAction> getActionList()
077 throws WvcmException;
078
079 /**
080 * The names of all the states defined for this record type. Will be an
081 * empty list if this is a stateless record type.
082 */
083 PropertyName<List<String>> STATE_NAME_LIST =
084 new PropertyName<List<String>>(PROPERTY_NAMESPACE,
085 "state-name-list");
086
087 /**
088 * Returns the value of the {@link #STATE_NAME_LIST STATE_NAME_LIST}
089 * property as defined by this proxy.
090 *
091 * @return A list of Strings, each containing the name of a state of this
092 * record type. Will be an empty list if this is a stateless
093 * record type.
094 *
095 * @throws WvcmException if this proxy does not define a value for the
096 * {@link #STATE_NAME_LIST STATE_NAME_LIST}
097 * property.
098 */
099 public List<String> getStateNameList()
100 throws WvcmException;
101
102 /** Answers whether or not this record type is a stateless record type. */
103 PropertyName<Boolean> IS_STATELESS =
104 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-stateless");
105
106 /**
107 * Returns the value of the {@link #IS_STATELESS IS_STATELESS} property as
108 * defined by this proxy.
109 *
110 * @return <b>true</b> if this is a stateless record type.
111 *
112 * @throws WvcmException if this proxy does not define a value for the
113 * {@link #IS_STATELESS IS_STATELESS} property.
114 */
115 public boolean getIsStateless()
116 throws WvcmException;
117
118 /** Answers whether or not records of this type may be submitted by clients. */
119 PropertyName<Boolean> IS_SUBMITTABLE =
120 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
121 "is-submittable");
122
123 /**
124 * Returns the value of the {@link #IS_SUBMITTABLE IS_SUBMITTABLE} property
125 * as defined by this proxy.
126 *
127 * @return <b>true</b> if records of this type may be submitted by clients.
128 *
129 * @throws WvcmException if this proxy does not define a value for the
130 * {@link #IS_SUBMITTABLE IS_SUBMITTABLE} property.
131 */
132 public boolean getIsSubmittable()
133 throws WvcmException;
134
135 /** All of the named hooks associated with this record type. */
136 PropertyName<ResourceList<CqHook>> NAMED_HOOK_LIST =
137 new PropertyName<ResourceList<CqHook>>(PROPERTY_NAMESPACE,
138 "named-hook-list");
139
140 /**
141 * Returns the value of the {@link #NAMED_HOOK_LIST NAMED_HOOK_LIST}
142 * property as defined by this proxy.
143 *
144 * @return A ResourceList of CqHook proxies containing all the named hooks
145 * of this record type.
146 *
147 * @throws WvcmException if this proxy does not define a value for the
148 * {@link #NAMED_HOOK_LIST NAMED_HOOK_LIST} property.
149 */
150 public ResourceList<CqHook> getNamedHookList()
151 throws WvcmException;
152
153 /** Answers whether or not records of this type can be security contexts. */
154 PropertyName<Boolean> CAN_BE_SECURITY_CONTEXT =
155 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
156 "can-be-security-context");
157
158 /**
159 * Returns the value of the {@link #CAN_BE_SECURITY_CONTEXT
160 * CAN_BE_SECURITY_CONTEXT} property as defined by this proxy.
161 *
162 * @return <b>true</b> if records of this type can be security contexts
163 *
164 * @throws WvcmException if this proxy does not define a value for the
165 * {@link #CAN_BE_SECURITY_CONTEXT CAN_BE_SECURITY_CONTEXT}
166 * property.
167 */
168 public boolean getCanBeSecurityContext()
169 throws WvcmException;
170
171 /**
172 * Answers whether or a record of this record type is used as a security
173 * context
174 */
175 PropertyName<Boolean> IS_SECURITY_CONTEXT =
176 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
177 "is-security-context");
178
179 /**
180 * Returns the value of the {@link #IS_SECURITY_CONTEXT IS_SECURITY_CONTEXT}
181 * property as defined by this proxy.
182 *
183 * @return <b>true</b> if records of this type are used as security
184 * contexts.
185 *
186 * @throws WvcmException if this proxy does not define a value for the
187 * {@link #IS_SECURITY_CONTEXT IS_SECURITY_CONTEXT}
188 * property.
189 */
190 public boolean getIsSecurityContext()
191 throws WvcmException;
192
193 /**
194 * Answers whether or not this is the definition of a record type family.
195 */
196 PropertyName<Boolean> IS_FAMILY =
197 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-family");
198
199 /**
200 * Returns the value of the {@link #IS_FAMILY IS_FAMILY} property as defined
201 * by this proxy.
202 *
203 * @return <b>true</b> if this is a record type family specification.
204 *
205 * @throws WvcmException if this proxy does not define a value for the
206 * {@link #IS_FAMILY IS_FAMILY} property.
207 */
208 public boolean getIsFamily()
209 throws WvcmException;
210
211 /**
212 * Answers whether or not this record type is a built-in record type, not
213 * added by a schema developer or package.
214 */
215 PropertyName<Boolean> IS_BUILT_IN_SYSTEM_OWNED =
216 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-built-in-system-owned");
217
218 /**
219 * Returns the value of the
220 * {@link #IS_BUILT_IN_SYSTEM_OWNED IS_BUILD_IN_SYSTEM_OWNED} property as
221 * defined by this proxy.
222 *
223 * @return <b>true</b> if this record type is defined for all ClearQuest
224 * schemas as part of the base implementation.
225 *
226 * @throws WvcmException if this proxy does not define a value for the
227 * {@link #IS_BUILT_IN_SYSTEM_OWNED IS_BUILT_IN_SYSTEM_OWNED}
228 * property.
229 */
230 public boolean getIsBuiltInSystemOwned()
231 throws WvcmException;
232
233 /**
234 * The record types that are members of this record type family. The list
235 * is empty is this is not a record type family.
236 */
237 PropertyName<ResourceList<CqRecordType>> FAMILY_MEMBERS =
238 new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE,
239 "family-members");
240
241 /**
242 * Returns the value of the {@link #FAMILY_MEMBERS} property as defined by
243 * this proxy
244 *
245 * @return A ResourceList containing a CqRecordType proxy for each record
246 * type that is a member of this record type family; Will never be
247 * <b>null</b> but may be empty if this is not a record type family
248 * or if no members are defined.
249 *
250 * @throws WvcmException if this proxy does not define a value for the
251 * {@link #FAMILY_MEMBERS} property.
252 */
253 public ResourceList<CqRecordType> getFamilyMembers()
254 throws WvcmException;
255
256 /**
257 * A list of the record type families this record is a member of.
258 */
259 PropertyName<ResourceList<CqRecordType>> PARENT_FAMILIES =
260 new PropertyName<ResourceList<CqRecordType>>(PROPERTY_NAMESPACE,
261 "parent-families");
262
263 /**
264 * Returns the value of the {@link #PARENT_FAMILIES} property as defined by
265 * this proxy
266 *
267 * @return A ResourceList containing a CqRecordType proxy for each record
268 * type family that this record type is a member of; Will never be
269 * <b>null</b> but may be empty if this record type is not a member
270 * of a record type family.
271 *
272 * @throws WvcmException if this proxy does not define a value for the
273 * {@link #PARENT_FAMILIES} property.
274 */
275 public ResourceList<CqRecordType> getParentFamilies()
276 throws WvcmException;
277
278 /**
279 * A list of the schema-defined fields that constitute the unique key for
280 * records of this type, presented in sort-key order starting from the
281 * primary sort key. (Note: In this release computation of this property
282 * requires the IS_RAW_SQL_WRITER permission.)
283 */
284 PropertyName<ResourceList<CqFieldDefinition>> KEY_FIELDS =
285 new PropertyName<ResourceList<CqFieldDefinition>>(PROPERTY_NAMESPACE,
286 "key-fields");
287
288 /**
289 * Returns the value of the {@link CqRecordType#KEY_FIELDS KEY_FIELDS} property as
290 * defined by this proxy.
291 *
292 * @return A ResourceList of CqFieldDefinition proxies each representing a
293 * key field of this record type presented in sort-key order..
294 *
295 * @throws WvcmException if this proxy does not define a value for the
296 * {@link CqRecordType#KEY_FIELDS KEY_FIELDS} property.
297 */
298 public ResourceList<CqFieldDefinition> getKeyFields() throws WvcmException;
299
300 /**
301 * Answers whether or not records of this type may be used as a UCM
302 * activity.
303 */
304 PropertyName<Boolean> IS_UCM_ENABLED =
305 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-ucm-enabled");
306
307 /**
308 * Returns the value of the {@link #IS_UCM_ENABLED IS_UCM_ENABLED} property
309 * as defined by this proxy.
310 *
311 * @return <b>true</b> if records of this type may be used as a UCM
312 * activity.
313 *
314 * @throws WvcmException if this proxy does not define a value for the
315 * {@link #IS_UCM_ENABLED IS_UCM_ENABLED} property.
316 */
317 public boolean getIsUcmEnabled()
318 throws WvcmException;
319
320 /**
321 * Returns specified fields from records that are of this record type and
322 * match a specified filtering expression. This proxy does not need to
323 * define any properties as only its location is needed to establish the
324 * record type to be selected and the database from which to select them.
325 *
326 * @param displayFields An array of {@link CqQuery.DisplayField} objects,
327 * each specifying a value to be returned from each selected
328 * record and collectively specifying the order in which the
329 * matched records are to be included in the response. Must not
330 * be <b>null</b>.
331 * @param filtering A {@link CqQuery.Filter} object specifying how the
332 * records of this type are to be selected for inclusion in the
333 * response. May be <b>null</b>, in which case all records of
334 * this record type will be included (up to the limits imposed by
335 * the targetRow and maxRows parameters).
336 * @param targetRow Specifies the first record that is to be included in the
337 * response among the records that match the filter, where a
338 * value of 1 specifies the first matching record. The ordering
339 * of matched records is defined by the display fields array.
340 * @param maxRows The maximum number of records that should be included in
341 * the response to this request. A value of Long.MAX_VALUE will
342 * request that the targeted record and all records after it in
343 * the prescribed ordering should be included in the response; If
344 * this parameter is 0, no records will be included. If the
345 * filter matches fewer than the maximum records requested, it is
346 * not an error.
347 * @param options An instance of {@link CqQuery.ListOptions} that specifies
348 * optional attributes for controlling the performance of the
349 * query or its response. May be <b>null</b>, in which case
350 * server-specified values will be used for each attribute.
351 *
352 * @return A CqResultSet of CqRowData objects each representing a record
353 * selected by the filter and containing the values specified by the
354 * display fields array. The values in each CqRowData object are
355 * ordered according to the display fields array. The total row
356 * count, if requested, is available as a field of the returned
357 * CqResultSet.
358 *
359 * @throws WvcmException if any errors occur during the execution of the
360 * query or the formation of the response.
361 *
362 * @see CqQuery#doExecute(long, long, com.ibm.rational.wvcm.stp.cq.CqQuery.ListOptions, com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf[])
363 */
364 CqResultSet doQuery(CqQuery.DisplayField[] displayFields,
365 CqQuery.Filter filtering,
366 long targetRow,
367 long maxRows,
368 CqQuery.ListOptions options)
369 throws WvcmException;
370
371 /**
372 * Returns specified fields from records that are of the type defined by
373 * this record type and match a specified filtering expression. This proxy
374 * does not need to define any properties as only its location is needed to
375 * establish the type of records to be selected and the database from which
376 * to select them.
377 *
378 * @param displayFields An array of {@link CqQuery.DisplayField} objects,
379 * each specifying a value to be returned from each selected
380 * record and collectively specifying the order in which the
381 * matched records are to be included in the response. Must not
382 * be <b>null</b>.
383 * @param filtering A {@link CqQuery.Filter} node specifying how the records
384 * of this type are to be selected for inclusion in the response.
385 * May be <b>null</b>, in which case all records of this record
386 * type will be included (up to the limits imposed by the
387 * targetRow and maxRows parameters).
388 * @param options An instance of {@link CqQuery.FileOptions} that specifies
389 * optional attributes for controlling the format of the response
390 * response. May be <b>null</b>, in which case server-specified
391 * values will be used for each attribute.
392 * @param feedback A Feedback instance specifying properties to be returned
393 * from the operation in the CqRecordType proxy. May be <b>null</b>.
394 *
395 * @param result The File into which the result set is to be written. Must
396 * not be <b>null</b>.
397 *
398 * @return A proxy for this record type, populated with the properties
399 * requested by the Feedback argument.
400 *
401 * @throws WvcmException if any errors occur during the execution of the
402 * query or the formation of the response.
403 */
404 CqRecordType doQuery(CqQuery.DisplayField[] displayFields,
405 CqQuery.Filter filtering,
406 File result,
407 Feedback feedback,
408 CqQuery.FileOptions options)
409 throws WvcmException;
410
411 /**
412 * Returns specified fields from records that are of the type defined by
413 * this record type and match a specified filtering expression. To launch
414 * this method this proxy does not need to define any properties as only its
415 * location is needed to establish the type of records to be selected and
416 * the database from which to select them.
417 *
418 * @param sql A String containing an SQL select statement specifying the
419 * fields to be returned by the query and the filter to be used
420 * to select the records.
421 *
422 * @param targetRow Specifies the first record that is to be included in the
423 * response among the records that match the filter, where a
424 * value of 1 specifies the first matching record. The ordering
425 * of matched records is defined by the display fields array.
426 *
427 * @param maxRows The maximum number of records that should be included in
428 * the response to this request. A value of Long.MAX_VALUE will
429 * request that the targeted record and all records after it in
430 * the prescribed ordering should be included in the response; If
431 * this parameter is 0, no records will be included. If the
432 * filter matches fewer than the maximum records requested, it is
433 * not an error.
434 *
435 * @param options An instance of {@link CqQuery.ListOptions} that specifies
436 * optional attributes for controlling the performance of the
437 * query or its response. May be <b>null</b>, in which case
438 * server-specified values will be used for each attribute.
439 *
440 * @return A CqResultSet containing a list of CqRowData objects, each
441 * representing a record selected by the filter and containing the
442 * values specified by the SQL string. The values in each CqRowData
443 * object are ordered according to the SQL select statement.
444 *
445 * @throws WvcmException if any errors occur during the execution of the
446 * query or the formation of the response.
447 */
448 CqResultSet doQuery(String sql,
449 long targetRow,
450 long maxRows,
451 CqQuery.ListOptions options)
452 throws WvcmException;
453
454 /**
455 * Returns specified fields from records that are of the type defined by
456 * this record type and match a specified filtering expression. To launch
457 * this method this proxy does not need to define any properties as only its
458 * location is needed to establish the type of records to be selected and
459 * the database from which to select them.
460 *
461 * @param sql A String containing an SQL specification for the fields to be
462 * returned by the query and the filter to be used to select the
463 * records.
464 *
465 * @param result The File into which the result set is to be written. Must
466 * not be <b>null</b>.
467 *
468 * @param feedback A Feedback instance specifying properties to be returned
469 * from the operation in the CqRecordType proxy. May be <b>null</b>.
470 *
471 * @param options An instance of FileOptions that specifies optional
472 * attributes for controlling the format of the response
473 * response. May be <b>null</b>, in which case server-specified
474 * values will be used for each attribute.
475 *
476 * @return A proxy for this record type, populated with the properties
477 * requested by the Feedback argument.
478 *
479 * @throws WvcmException if any errors occur during the execution of the
480 * query or the formation of the response.
481 */
482 CqRecordType doQuery(String sql,
483 File result,
484 Feedback feedback,
485 CqQuery.FileOptions options)
486 throws WvcmException;
487 }