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
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.io.OutputStream;
019import java.util.List;
020
021import javax.wvcm.Feedback;
022import javax.wvcm.WvcmException;
023import javax.wvcm.PropertyNameList.PropertyName;
024
025import com.ibm.rational.wvcm.stp.cq.CqQuery.FilterLeaf;
026import 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 */
036public 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}