用程序处理报表参数

参数是报表生成之前想报表设计文件输入的报表元素。报表的应用程序可以访问报表的参数的属性，最常用的属性是name和value，你可以使用参数名或通用编码来获取参数。

为报表设计创建一个参数定义任务
一个IGetParameterDefinitionTask对象提供链接到报表设计所有参数的接口。通过调用 ReportEngine.createGetParameterDefinitionTask( )创建一个参数定义对象，使用结束后调用他的close方法关闭。

测试报表设计是否有参数
IGetParameterDefinitionTask.getParameterDefns( )可以测试报表设计是否有参数，它返回一个参数集合，调用集合的isEmpty( )方法可以测试集合中是否有元素。

获取报表设计的参数
通过IGetParameterDefinitionTask.getParameterDefn( )方法获取一个已知名字的参数，它返回一个IParameterDefnBase类型对象，也可以调用getParameterDefns( )方法返回一个参数集合。
getParameterDefns( )需要一个boolean参数，如果为false返回一个未分组的参数集合，如果为true返回报表设计中定义的参数组。
调用IParameterDefnBase.getParameterType( )可以检验参数是否是一个组。如果是一个组则返回IParameterDefnBase.PARAMETER_GROUP，如果是一个级联参数组则返回 IParameterDefnBase.CASCADING_PARAMETER_GROUP。为获取一组报表参数，使用方法 IParameterGroupDefn.getContents( )，它返回一个数据类型是IScalarParameterDefn的ArrayList对象。

获取报表参数的默认值
这个任务是可选的。调用IGetParameterDefinitionTask.getDefaultValue( )获取一个已知参数的默认值，它返回的是一个Object。可以通过调用IScalarParameterDefn.getDataType( )来获取Object的有效类型，它返回一个IScalarParameterDefn定义的int类型的静态变量。调用 IGetParameterDefinitionTask.getDefaultValues( )来获取报表设计的所有参数的默认值，它返回一个HashMap对象存储了从参数名到默认值的映射。

使用常量列表提供的效值
许多报表参数只接受常量列表的值，这些值可能是静态常量，也可能是数据库里查出来的数据list。使用 IGetParameterDefinitionTask.getSelectionList( )可以返回参数所能接受的参数（IParameterSelectionChoice）的集合，如果集合为null，则可以接受任何值。 IParameterSelectionChoice的getLabel( )方法返回现实的文本，getValue( )返回值。

获取每个报表参数的属性
这个任务是可选的。使用IScalarParameterDefn的方法可以获取表参数的属性。应用程序使用属性生成用户自定义接口。例如，获取参数的数据类型使用getDataType( )方法。

为参数设置值
调用IGetParameterDefinitionTask.setParameterValue( )为参数设置值。如果你是通过应用程为日期数值等参数返回一个字符串，要把他们转化成和本地无关的格式。调用方法 ReportParameterConverter.parse( )方法可以完成这项工作。getParameterValues( )方法返回一个HashMap包含了已经设置的所有参数。

实例
下面的代码展示了如何设置一个已知参数名的参数值：

Java代码

1. // Create a parameter definition task.  
2. IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable );  
3. // Instantiate a scalar parameter.  
4. IScalarParameterDefn param = (IScalarParameterDefn)   
5. task.getParameterDefn( "customerID" );  
6. // Get the default value of the parameter. In this case,   
7. // the data type of the parameter, customerID, is Double.  
8. int customerID = ((Double) task.getDefaultValue( param )).intValue( );  
9. // Get a value for the parameter. This example assumes that   
10. // this step creates a correctly typed object, inputValue.  
11. // Set the value of the parameter.  
12. task.setParameterValue( "customerID", inputValue );  
13. // Get the values set by the application for all parameters.  
14. HashMap parameterValues = task.getParameterValues( );  
15. // Close the parameter definition task.  
16. task.close( );  

// Create a parameter definition task.
IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable );
// Instantiate a scalar parameter.
IScalarParameterDefn param = (IScalarParameterDefn) 
task.getParameterDefn( "customerID" );
// Get the default value of the parameter. In this case, 
// the data type of the parameter, customerID, is Double.
int customerID = ((Double) task.getDefaultValue( param )).intValue( );
// Get a value for the parameter. This example assumes that 
// this step creates a correctly typed object, inputValue.
// Set the value of the parameter.
task.setParameterValue( "customerID", inputValue );
// Get the values set by the application for all parameters.
HashMap parameterValues = task.getParameterValues( );
// Close the parameter definition task.
task.close( );

下面的代码展示了如何使用报表参数集合，例子中使用ReportParameterConverter将字符串转化成用户接口接受的参数格式。

Java代码

1. // Create a parameter definition task.  
2. IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable );  
3. // Create a collection of the parameters in the report design.  
4. Collection params = task.getParameterDefns( false );  
5. // Get the default values of the parameters.  
6. HashMap parameterValues = task.getDefaultValues( );  
7. // Get values for the parameters. Later code in this example  
8. // assumes that this step creates a HashMap object,  
9. // inputValues. The keys in the HashMap are the parameter  
10. // names and the values are those that the user provided.  
11. // Iterate through the report parameters, setting the values   
12. // in standard locale-independent format.  
13. Iterator iterOuter = params.iterator( );  
14. ReportParameterConverter cfgConverter =  
15.         new ReportParameterConverter( "", Locale.getDefault() );  
16. while ( iterOuter.hasNext( ) ) {  
17. IParameterDefnBase param = (IParameterDefnBase) iterOuter.next( );  
18. String value = (String) inputValues.get( param.getName( ));  
19. if ( value != null ) {  
20. parameterValues.put( param.getName( ),   
21. cfgConverter.parse( value, param.getDataType( ) ) );  
22. }  
23. }  
24. // Close the parameter definition task.  
25. task.close( );  

// Create a parameter definition task.
IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable );
// Create a collection of the parameters in the report design.
Collection params = task.getParameterDefns( false );
// Get the default values of the parameters.
HashMap parameterValues = task.getDefaultValues( );
// Get values for the parameters. Later code in this example
// assumes that this step creates a HashMap object,
// inputValues. The keys in the HashMap are the parameter
// names and the values are those that the user provided.
// Iterate through the report parameters, setting the values 
// in standard locale-independent format.
Iterator iterOuter = params.iterator( );
ReportParameterConverter cfgConverter =
        new ReportParameterConverter( "", Locale.getDefault() );
while ( iterOuter.hasNext( ) ) {
IParameterDefnBase param = (IParameterDefnBase) iterOuter.next( );
String value = (String) inputValues.get( param.getName( ));
if ( value != null ) {
parameterValues.put( param.getName( ), 
cfgConverter.parse( value, param.getDataType( ) ) );
}
}
// Close the parameter definition task.
task.close( );

使用级联参数
级联参数参数是一组可供用户选择的参数值的集合。第一个参数的选择会影响到第二个参数中的值。参数使用一个或多个查询来从数据集把数据展示给用户。参数定义任务根据前面的选择以行为单位过滤参数组中的数据。
使用报表引擎实现级联参数，要进行如下工作：
■使用IGetParameterDefinitionTask.evaluateQuery( )方法为级联参数准备数据，它需要参数group的名字作为参数。
■调用IGetParameterDefinitionTask.getSelectionListForCascadingGroup( )获取参数组的第一个参数的值，它需要两个参数，参数名和对象数组，对第一个参数来说这个数组是空的。该方法返回一个 IParameterSelectionChoice集合。
■ 再次调用getSelectionListForCascadingGroup( )方法获取后面的参数，这次Object[ ]中放的是前面获取的参数值。

下面的代码展示了如何通过查询实现级联参数：

Java代码

1. // Create a grouped collection of the design’s parameters.  
2. Collection params = task.getParameterDefns( true );  
3. // Iterate through the parameters to find the cascading group.  
4. Iterator iter = params.iterator( );  
5. while ( iter.hasNext( ) ) {  
6. IParameterDefnBase param = (IParameterDefnBase) iter.next();  
7. if ( param.getParameterType() ==   
8. IParameterDefnBase.CASCADING_PARAMETER_GROUP ) {  
9. ICascadingParameterGroup group = (ICascadingParameterGroup) param;  
10. Iterator i2 = group.getContents( ).iterator( );  
11. // Run the query for the cascading parameters.  
12. task.evaluateQuery( group.getName() );  
13. Object[ ] userValues = new Object[group.getContents( ).size( )];  
14. // Get the report parameters in the cascading group.  
15. int i = 0;  
16. while ( i2.hasNext( ) ) {  
17. IScalarParameterDefn member = (IScalarParameterDefn) i2.next( );  
18. // Get the values for the parameter.  
19. Object[ ] setValues = new Object[i];  
20. if ( i > 0 )  System.arraycopy( userValues, 0, setValues, 0, i );  
21. Collection c = task.getSelectionListForCascadingGroup(  
22.    group.getName(),setValues );  
23. // Iterate through the values for the parameter.  
24. Iterator i3 = c.iterator();  
25. while ( i3.hasNext( ) ) {  
26. IParameterSelectionChoice s =   
27. ( IParameterSelectionChoice ) i3.next( );  
28. String choiceValue = s.getValue( );  
29. String choiceLabel = s.getLabel( );  
30. }  
31. // Get the value for the parameter from the list of  
32. // choices. This example does not provide the code for  
33. // this task.  
34. userValues[i] = inputChoiceValue;  
35. i++;  
36. }  
37. }  
38. }  

本文地址：http://birt.group.iteye.com/group/topic/11308