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