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 * © 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><parent-folder-path></i>/<i><report-name></i>@<i><db-set></i>/<i><user-db></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 }