001    /*
002     * file CqReport.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cq.CqReport
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    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import java.io.OutputStream;
019    import java.util.List;
020    
021    import javax.wvcm.Feedback;
022    import javax.wvcm.WvcmException;
023    import javax.wvcm.PropertyNameList.PropertyName;
024    
025    import com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf;
026    import com.ibm.rational.wvcm.stpex.StpExBase;
027    
028    /**
029     * A proxy interface for a ClearQuest report definition.
030     * <p>
031     * The user-friendly specification for the location of a report has the form
032     * <pre>
033     *  <b>cq.query:</b><i>&lt;parent-folder-path&gt;</i>/<i>&lt;report-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
034     * </pre>
035     */
036    public interface CqReport extends CqQueryFolderItem
037    {
038        /**
039         * Whether or not this report definition is complete and ready to use for
040         * generating reports.
041         */
042        PropertyName<Boolean> IS_VALID =
043            new PropertyName<Boolean>(StpExBase.PROPERTY_NAMESPACE, "is-valid");
044    
045        /**
046         * Returns the value of the {@link #IS_VALID IS_VALID} property as defined
047         * by this proxy.
048         * 
049         * @return The value. Will never be <b>null</b>.
050         * 
051         * @throws WvcmException if this proxy does not define a value for the
052         *             {@link #IS_VALID IS_VALID} property.
053         */
054        boolean getIsValid() throws WvcmException;
055    
056        /**
057         * The type of record upon which this report generates reports.
058         */
059        PropertyName<CqRecordType> PRIMARY_RECORD_TYPE =
060            new PropertyName<CqRecordType>(PROPERTY_NAMESPACE, "primary-record-type");
061    
062        /**
063         * Returns the value of the {@link #PRIMARY_RECORD_TYPE PRIMARY_RECORD_TYPE}
064         * property as defined by this proxy.
065         * 
066         * @return A CqRecordType proxy for the type of record included in reports
067         *         generated by this report. May be <b>null</b> if not yet defined.
068         * 
069         * @throws WvcmException if this proxy does not define a value for the
070         *             {@link #PRIMARY_RECORD_TYPE PRIMARY_RECORD_TYPE} property.
071         */
072        CqRecordType getPrimaryRecordType() throws WvcmException;
073    
074        /**
075         * The query that selects the records to be included in the report.
076         */
077        PropertyName<CqQuery> QUERY =
078            new PropertyName<CqQuery>(PROPERTY_NAMESPACE, "query");
079    
080        /**
081         * Returns the value of the {@link #QUERY QUERY}
082         * property as defined by this proxy.
083         * 
084         * @return A CqQuery proxy for the query that selects the records to be
085         * included in the reports generated by this report definition.
086         * 
087         * @throws WvcmException if this proxy does not define a value for the
088         *             {@link #QUERY QUERY} property.
089         */
090        CqQuery getQuery() throws WvcmException;
091    
092        /**
093         * Defines a new value for the {@link #QUERY QUERY} property of this proxy.
094         * 
095         * @param value A CqQuery object specifying the new query that will select
096         * records for this report.
097         */
098        void setQuery(CqQuery value);
099    
100        /**
101         * The report format that specifies how the records selected by the report's
102         * query will be formatted into a report document.
103         */
104        PropertyName<CqReportFormat> REPORT_FORMAT =
105            new PropertyName<CqReportFormat>(PROPERTY_NAMESPACE, "report-format");
106    
107        /**
108         * Returns the value of the {@link #REPORT_FORMAT REPORT_FORMAT} property as
109         * defined by this proxy.
110         * 
111         * @return A CqReportFormat proxy for the report format of this report.
112         * 
113         * @throws WvcmException if this proxy does not define a value for the
114         *             {@link #REPORT_FORMAT REPORT_FORMAT} property.
115         */
116        CqReportFormat getReportFormat() throws WvcmException;
117    
118        /**
119         * Defines a new value for the {@link #REPORT_FORMAT REPORT_FORMAT} property
120         * of this proxy.
121         * 
122         * @param value A CqReportFormat proxy specifying the new report format to
123         *            use for this report.
124         */
125        void setReportFormat(CqReportFormat value);
126    
127        /**
128         * Creates a new report resource at the location specified by this proxy and
129         * immediately delivers it to the database.
130         * 
131         * @param feedback A Feedback object specifying the properties, if any, to
132         *            be included in the proxy returned by this method.
133         * @return A CqReport proxy for the newly created report, populated with the
134         *         property values requested by the feedback argument.
135         * @throws WvcmException If the report cannot be created at the specified
136         *             location, one or more of the dirty properties of this
137         *             resource are inappropriate for the new report, or the new
138         *             report cannot be delivered to the database.
139         */
140        CqReport doCreateReport(Feedback feedback) throws WvcmException;
141    
142        /**
143         * Creates a new report resource at the location specified by this proxy.
144         * 
145         * @param feedback A Feedback object specifying the properties, if any, to
146         *            be included in the proxy returned by this method.
147         * @param deliveryOrder If {@link CqProvider#HOLD} the created report is
148         *            left in a writable state in the change context--the new report
149         *            in the change context must be delivered before it becomes
150         *            visible to other providers. If not {@link CqProvider#HOLD},
151         *            the modified and moribund resources specified by this
152         *            parameter will be delivered to or deleted from the database in
153         *            the order indicated. To deliver all modified and moribund
154         *            resources in an arbitrary order, use
155         *            {@link CqProvider#DELIVER_ALL}. To deliver just this new
156         *            report, use {@link CqProvider#DELIVER}. Must not be <b>null</b>.
157         * @return A CqReport proxy for the newly created report, populated with the
158         *         property values requested by the feedback argument.
159         * @throws WvcmException If the report cannot be created at the specified
160         *             location, one or more of the dirty properties of this
161         *             resource are inappropriate for the new report, or one of the
162         *             resources to be delivered cannot be delivered.
163         */
164        CqReport doCreateReport(Feedback feedback,
165                                List<CqContextResource> deliveryOrder)
166            throws WvcmException;
167    
168        /**
169         * Executes the query associated with this report and generates an HTML
170         * formatted report from the result set based on the report's designated
171         * report format.
172         * 
173         * @param reportHTML An open OutputSteam that will receive the generated
174         *            HTML.
175         * @param targetRow The first row of the result set to be included in the
176         *            report.
177         * @param maxRows The maximum number of rows to be included in the report
178         * @param dynamicFilters Any dynamic filters needed to execute the query.
179         * @throws WvcmException If there are errors
180         */
181        void doMakeReport(OutputStream reportHTML,
182                          long targetRow,
183                          long maxRows,
184                          FilterLeaf... dynamicFilters) throws WvcmException;
185    }