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    
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>&lt;record-type-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</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    }