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