org.squashtest.csp.tm.domain.report.query
Interface ReportQuery

All Known Implementing Classes:

HibernateExecutionProgressQuery, HibernateReportQuery, HibernateRequirementCoverageByTestsQuery

public interface ReportQuery

Abstract : ========== This interface represents the query that the client needs to use to retrieve the data and build the model that will feed the view for a given Report. An implementation of the ReportQuery interface is both dedicated to : - a given Report, - a given implementation of the underlying repository. Data Filtering : =============== As for SquashTM v 0.23.0 and future version, as long as the issue is not addressed, a Report plugin is granted full, unfiltered access to the repository. Until low level security routines are injected in the middle, it's up to the author of a Report to check his data against a dedicated service that will be gracefully injected by the Report service engine. That service is DataFilteringService instance. The use of the DataFilteringService is tightly coupled to the implementation of ReportQueryDao and the actual content of the query. Thus, there is no formal way to use that service in the scope of that interface, but let's say that the DataFilteringService should be used between the moment the query is executed and the moment its result is returned. Implementing the ReportQuery interface : ======================================================== 1/ The Implementation must match a particular repository. since the query is meant to be executed by a particular Dao, we need to know if the said Dao can support the particular implementation of the ReportQuery. This will be tested using a ReportQueryFlavor. You must ensure that your report will return the correct ReportQueryFlavor subclass when asked to, ie the one supported by the ReportQueryDao. 2/ Narrowing the result set. A ReportQuery will fetch data, that may be filtered by several means :

• Security checks (see above),
• User filters (see above),
• Criterions (see right below)

Security checks and you must provide a (hidden) structure to maintain the criteria that will narrow the results when querying the repository. The constructor of the actual class must then define which criteria do exists and what are their names. Beyond the interface here the inner management of the criteria can of course be as complex as you want (type safety, request generator etc). - by convention giving a null value to a criterion means that the said criterion will be unused. However providing no value at all to a given criterion before execution means that the criterion will be either unused, either applied with default value, it's up to the choice of the implementor. From an user point of view, when in doubt, always set a value to all of the criterion.

Author:

bsiri

Method Summary

Collection<String>	getCriterionNames()
ReportQueryFlavor	getFlavor()
Object[]	getValue(String name)
boolean	isCriterionExists(String name) Checks if the given name matches one of the criterion used by this query.
void	setCriterion(String name, Object... values) This method will set a criterion.
void	SetDataFilteringService(DataFilteringService service) setter for a DataFilteringService.

Method Detail

getFlavor

ReportQueryFlavor getFlavor()

Returns:

an instance of a subclass of ReportQueryFlavor, that will identify which kind of Dao that Query should be processed through.

SetDataFilteringService

void SetDataFilteringService(DataFilteringService service)

setter for a DataFilteringService. Will be invoked by the system. See above, Data Filtering.

Parameters:

service -

setCriterion

void setCriterion(String name,
                  Object... values)

This method will set a criterion. Using a null value will nullify the use of that criterion.

Parameters:

name - the name of the criterion you will feed with one or several values.

values - an array (which can contains 0, 1 or more elements) containing the actual parameters.

getCriterionNames

Collection<String> getCriterionNames()

Returns:

the list of the criterion filtering that report.

isCriterionExists

boolean isCriterionExists(String name)

Checks if the given name matches one of the criterion used by this query.

Parameters:

name - the name one wants to check.

Returns:

true if the ReportQuery instance declares a criterion bearing that name, false otherwise.

getValue

Object[] getValue(String name)

Parameters:

name - the name of the criterion one want to check or retrieve the actual paramters

Returns:

the parameters for that criterion, or null if the criterion was deactivated or if the criterion doesn't exists (use isCriterionExists() if you need to know what does null means in that later case).