Accessing a report parameter
A report parameter is a report element that provides input to a report design before an application generates the report. A report document does not use report parameters to create a formatted report. If an application already has the parameter names and the values to set, or the default values for all report parameters for a report design are always valid, or the report source is a report document, you do not need to perform the tasks in this section.
Report parameters have attributes that a reporting application can access. The most commonly used attributes are name and value. The report engine uses the report design logic and the report parameter values to perform tasks such as filtering a data set or displaying an external value in the report.
After the reporting application sets values for the report parameters, it must pass these values to the task that generates the report, as shown later in this chapter. To access report parameters and their default values and to set user‑supplied values to a parameter, the application uses the BIRT report engine API classes and interfaces shown in
Table 12-4.
An application can access report parameters by name or using generic code. Use generic code if the application must be able to run any report design, for example, to access report designs from a list that depends on user input. An application that runs only a fixed set of known report designs can access the report parameters by name.
Table 12-4 Classes and interfaces that support report parameters
Class or interface | Use |
ReportEngine class | Instantiates the task that accesses report parameters. To create the task object, call the createGetParameterDefinitionTask( ) method. This method returns an instance of IGetParameterDefinitionTask. |
IGetParameterDefinition
Task interface | Accesses a single report parameter or a collection of all the report parameters in a report design. Also provides access to valid values for parameters that use restricted sets of values, such as cascading parameters. |
IParameterDefnBase interface | The base interface for report parameter elements. Scalar parameters implement the derived interface, IScalarParameterDefn. Parameter groups implement the derived interface IParameterGroupDefn. To get information about parameter attributes, use objects implementing these interfaces. |
IParameterGroupDefn interface | The base interface for report parameter groups. Cascading parameter groups implement the derived interface ICascadingParameterGroup. |
IParameterSelection
Choice interface | Defines valid values for a report parameter that uses a restricted set of values, such as a cascading parameter. |
ReportParameterConverter class | Converts a String value provided by a user interface into a locale-independent format. |
Creating a parameter definition task object for the report design
A single IGetParameterDefinitionTask object provides access to all parameters in a report design. Create only one of these objects for each report design, by calling ReportEngine.createGetParameterDefinitionTask( ). Close the parameter definition task object after use by calling its close( ) method.
Testing whether a report design has report parameters
To test if a report design has report parameters, call the getParameterDefns( ) method on IGetParameterDefinitionTask. This method returns a Collection. To test whether the Collection has elements call the Collection.isEmpty( ) method. An application that runs only known report designs does not need to perform this task.
Getting the report parameters in a report design
To access a single report parameter of a known name, use the IGetParameterDefinitionTask.getParameterDefn( ) method. This method returns an object of type IParameterDefnBase.
Use the IGetParameterDefinitionTask.getParameterDefns( ) method to return a Collection of IParameterDefnBase objects. The application can then use an Iterator to access each report parameter from this Collection in turn. The getParameterDefns( ) method takes a Boolean argument. For an argument value of false, the method returns an ungrouped set of report parameters. For a value of true, the method returns parameter groups, as defined in the report design. To create a user interface that replicates the parameter group structure, use a value of true.
To check whether a report parameter is a group, the application must call IParameterDefnBase.getParameterType( ). This method returns IParameterDefnBase.PARAMETER_GROUP if the parameter is a group or IParameterDefnBase.CASCADING_PARAMETER_GROUP if the parameter is a cascading parameter group. To access the group’s report parameters, use the IParameterGroupDefn.getContents( ) method. This method returns an ArrayList object of objects of type IScalarParameterDefn.
Getting the default value of each report parameter
This task is optional. To get the default value of a single known report parameter, use IGetParameterDefinitionTask.getDefaultValue( ). This method returns an Object. To determine the effective class of the Object, use IScalarParameterDefn.getDataType( ). This method returns an int value, which is one of the static fields in IScalarParameterDefn. Call IGetParameterDefinitionTask.getDefaultValues( ) to get the default value of all parameters in the report design. This method returns a HashMap object, which maps the report parameter names and their default values.
Getting valid values for parameters using a restricted set of values
Some report parameters accept only values from a restricted list. In some cases, this list is a static list of values, such as RED, BLUE, or GREEN. In other cases, the list is dynamic and a query to a database provides the valid values. For example, a query can return the set of sales regions in a sales tracking database. To determine the list of valid values, call the method, IGetParameterDefinitionTask.getSelectionList( ). This method returns a Collection of IParameterSelectionChoice objects. IParameterSelectionChoice has two methods. getLabel( ) returns the display text and getValue( ) returns the value. If the Collection is null, the report parameter can take any value.
Getting the attributes of each report parameter
This task is optional. To get the attributes of a report parameter, use the IScalarParameterDefn methods. The application can use the attributes to generate a customized user interface. For example, to get the data type of a report parameter, use the getDataType( ) method.
Collecting an updated value for each report parameter
To provide new values for the report parameters, provide application logic such as a user interface or code to retrieve values from a database.
Call IGetParameterDefinitionTask.setParameterValue( ) to set the value of the parameter. If a user interface returns String values to your application for date and number parameters, convert the String into a locale-independent format before setting the value. To perform this task, call the method, ReportParameterConverter.parse( ), before calling setParameterValue( ).
After setting the report parameter values, call the method, IGetParameterDefinitionTask.getParameterValues( ). This method returns a HashMap object containing the current parameter values as set by calls to IGetParameterDefinitionTask.setParameterValue( ). Use this HashMap object to set parameter values for report generation, as described later in this chapter.