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 * (C) 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
014package com.ibm.rational.wvcm.stp.cq;
015
016
017import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
018
019import java.io.File;
020import java.util.List;
021
022import javax.wvcm.Feedback;
023import javax.wvcm.ResourceList;
024import javax.wvcm.WvcmException;
025import javax.wvcm.PropertyNameList.PropertyName;
026
027import com.ibm.rational.wvcm.stp.cqex.CqExForm;
028import com.ibm.rational.wvcm.stpex.StpExEnumeration;
029import 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>&lt;record-type-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
038 * </pre>
039 */
040public 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}