Jasper Reports 简明教程

Reports Parameters

填充报告的主要输入是− 报告模板、参数和数据源。本章将介绍参数，在下一章中我们将讨论数据源。

The main input for filling a report are − report template, parameters, and data sources. This chapter will describe the parameters and in the next chapter we will discuss the data sources.

参数是对象引用，在报告填充操作期间传递给报告引擎。无法通过数据源传递的数据可以通过使用参数传递。可以通过参数传递诸如作者姓名、报告标题等数据。JasperReports 模板或 JRXML 模板可以具有零个或多个参数元素。

Parameters are the object references, those are passed during report-filling operations to the report engine. The data which cannot be passed through the data source, can be passed by using parameters. Data like author name, title of the report, etc. can be passed through parameters. A JasperReports template or JRXML template can have zero or more parameter elements.

Parameter Declaration

参数声明如下−

Parameter declaration as follows −

<parameter name = "exampleParameter" class = "java.lang.String" />

The Name Attribute

<parameter> 元素的 name 属性是必需的。它通过名称引用报告表达式中的参数。参数名称应为一个单词。它不应包含任何特殊字符，例如句点或逗号。

The name attribute of the <parameter> element is mandatory. It references the parameter in report expressions by name. Parameter name should be a single word. It should not contain any special characters like dot or comma.

The Class Attribute

class 属性也是必需的，它为参数值指定类名。它的默认值为 java.lang.String。这可以更改为运行时可用的任何类。无论报告参数的类型如何，引擎都会负责强制转换报告表达式中使用 $P{} 令牌的内容，从而使手动强制转换变得不必要。

The class attribute is also mandatory and it specifies the class name for the parameter values. Its default value is java.lang.String. This can be changed to any class available at runtime. Irrespective of the type of a report parameter, the engine takes care of casting in the report expressions in which the $P{} token is used, hence making the manual casts is unnecessary.

报表参数值始终打包在一个 java.util.Map 对象中，其具有参数名称作为其键。报表参数可以用在报表的查询字符串中，以进一步定制从数据库中检索出的数据集。它们的作用就像查询中的动态过滤器，向报表提供数据。

The report parameter values are always packed in a java.util.Map object, which has the parameter name as its key. Report parameters can be used in the query string of the report, so as to further customize the data set, retrieved from the database. These act like dynamic filters in the query that supplies data for the report.

Built-in Parameters

以下是预定义的报表参数，可随时用于表达式中：

Following are the pre-defined report parameters, ready to use in the expressions −

S.NO	Parameter Name and Description
1	REPORT_PARAMETERS_MAP Contains a map with all user defined and built-in parameters.
2	REPORT_CONNECTION This points to the user supplied class java.sql.Connection, used for JDBC datasources.
3	REPORT_DATA_SOURCE This is a user supplied instance of JRDataSource representing either one of the built-in data source types or a user-defined one.
4	REPORT_MAX_COUNT This is a java.lang.Integer value, allowing the users to limit the records from datasource.
5	REPORT_SCRIPTLET This points to net.sf.jasperreports.engine.JRAbstractScriptlet and contains an instance of the report scriptlet provided by the user.
6	REPORT_LOCALE This a java.util.Locale instance, containing the resource bundle desired locale.
7	REPORT_RESOURCE_BUNDLE This points to java.util.ResourceBundle object and contains localized messages.
8	REPORT_TIME_ZONE This is a java.util.TimeZone instance, used for the date formatting.
9	REPORT_VIRTUALIZER This is an instance of net.sf.jasperreports.engine.JRVirtualizer object, and used for the page virtualization (optimize memory consumption).
10	REPORT_CLASS_LOADER This is a java.lang.ClassLoader instance to be used during the report filling process to load resources such as images, fonts, and subreport templates
11	IS_IGNORE_PAGINATION If set to java.lang.Boolean.TRUE the report will be generated on one long page and page break will not occur.

Example

让我们将 ReportTitle 和 Author 传递给报表（由 JasperReportFill.java 生成）。修改后的文件 C:\tools\jasperreports-5.0.1\test\src\com\tutorialspoint\JasperReportFill.java 如下：

Let us pass ReportTitle and Author to the report (generated by JasperReportFill.java). Revised file C:\tools\jasperreports-5.0.1\test\src\com\tutorialspoint\JasperReportFill.java is as follows −

package com.tutorialspoint;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;

import net.sf.jasperreports.engine.JRException;
import net.sf.jasperreports.engine.JasperFillManager;
import net.sf.jasperreports.engine.data.JRBeanCollectionDataSource;

public class JasperReportFill {
   @SuppressWarnings("unchecked")
   public static void main(String[] args) {
      String sourceFileName =
         "C://tools/jasperreports-5.0.1/test/jasper_report_template.jasper";

      DataBeanList DataBeanList = new DataBeanList();
      ArrayList<DataBean> dataList = DataBeanList.getDataBeanList();

      JRBeanCollectionDataSource beanColDataSource =
      new JRBeanCollectionDataSource(dataList);

      Map parameters = new HashMap();
      /**
       * Passing ReportTitle and Author as parameters
       */
      parameters.put("ReportTitle", "List of Contacts");
      parameters.put("Author", "Prepared By Manisha");

      try {
         JasperFillManager.fillReportToFile(
         sourceFileName, parameters, beanColDataSource);
      } catch (JRException e) {
         e.printStackTrace();
      }
   }
}

POJO 文件 C:\tools\jasperreports-5.0.1\test\src\com\tutorialspoint\DataBean.java 的内容如下：

The contents of the POJO file C:\tools\jasperreports-5.0.1\test\src\com\tutorialspoint\DataBean.java are as below −

package com.tutorialspoint;

public class DataBean {
   private String name;
   private String country;

   public String getName() {
      return name;
   }

   public void setName(String name) {
      this.name = name;
   }

   public String getCountry() {
      return country;
   }

   public void setCountry(String country) {
      this.country = country;
   }
}

C:\tools\jasperreports-5.0.1\test\src\com\tutorialspoint\DataBeanList.java 文件的内容如下 −

The contents of the file C:\tools\jasperreports-5.0.1\test\src\com\tutorialspoint\DataBeanList.java are as given below −

package com.tutorialspoint;

import java.util.ArrayList;

public class DataBeanList {
   public ArrayList<DataBean> getDataBeanList() {
      ArrayList<DataBean> dataBeanList = new ArrayList<DataBean>();

      dataBeanList.add(produce("Manisha", "India"));
      dataBeanList.add(produce("Dennis Ritchie", "USA"));
      dataBeanList.add(produce("V.Anand", "India"));
      dataBeanList.add(produce("Shrinath", "California"));

      return dataBeanList;
   }

   /**
    * This method returns a DataBean object,
    * with name and country set in it.
    */
   private DataBean produce(String name, String country) {
      DataBean dataBean = new DataBean();
      dataBean.setName(name);
      dataBean.setCountry(country);

      return dataBean;
   }
}

让我们将参数 <*ReportTitle*> 和 <*Author*> 添加到我们的现有报表模板（第 Report Designs 章）。报表标题和作者将显示在报表开头。修改后的报表模板（jasper_report_template.jrxml）如下。将其保存到 C:\tools\jasperreports-5.0.1\test 目录中：

Let’s add parameters the <*ReportTitle*> and <*Author*> to our existing report template (Chapter Report Designs). The Report Title and Author will be displayed at the beginning of the report. The revised report template (jasper_report_template.jrxml) is as follows. Save it to C:\tools\jasperreports-5.0.1\test directory −

<?xml version = "1.0"?>
<!DOCTYPE jasperReport PUBLIC
   "//JasperReports//DTD Report Design//EN"
   "http://jasperreports.sourceforge.net/dtds/jasperreport.dtd">

<jasperReport xmlns = "http://jasperreports.sourceforge.net/jasperreports"
   xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation = "http://jasperreports.sourceforge.net/jasperreports
   http://jasperreports.sourceforge.net/xsd/jasperreport.xsd"
   name = "jasper_report_template" pageWidth = "595"
   pageHeight = "842" columnWidth = "515"
   leftMargin = "40" rightMargin = "40" topMargin = "50" bottomMargin = "50">

   <parameter name = "ReportTitle" class = "java.lang.String"/>
   <parameter name = "Author" class = "java.lang.String"/>

   <queryString>
      <![CDATA[]]>
   </queryString>

   <field name = "country" class = "java.lang.String">
      <fieldDescription><![CDATA[country]]></fieldDescription>
   </field>

   <field name = "name" class = "java.lang.String">
      <fieldDescription><![CDATA[name]]></fieldDescription>
   </field>

   <title>
      <band height = "70">

         <line>
            <reportElement x = "0" y = "0" width = "515" height = "1"/>
         </line>

         <textField isBlankWhenNull = "true" bookmarkLevel = "1">
            <reportElement x = "0" y = "10" width = "515" height = "30"/>

            <textElement textAlignment = "Center">
               <font size = "22"/>
            </textElement>

            <textFieldExpression class = "java.lang.String">
               <![CDATA[$P{ReportTitle}]]>
            </textFieldExpression>

            <anchorNameExpression>
               <![CDATA["Title"]]>
            </anchorNameExpression>
         </textField>

         <textField isBlankWhenNull = "true">
            <reportElement  x = "0" y = "40" width = "515" height = "20"/>

            <textElement textAlignment = "Center">
               <font size = "10"/>
            </textElement>

            <textFieldExpression class = "java.lang.String">
               <![CDATA[$P{Author}]]>
            </textFieldExpression>
         </textField>

      </band>
   </title>

   <columnHeader>
      <band height = "23">

         <staticText>
            <reportElement mode = "Opaque" x = "0" y = "3" width = "535" height = "15"
               backcolor = "#70A9A9" />

            <box>
               <bottomPen lineWidth = "1.0" lineColor = "#CCCCCC" />
            </box>

            <textElement />

            <text>
               <![CDATA[]]>
            </text>
         </staticText>

         <staticText>
            <reportElement x = "414" y = "3" width = "121" height = "15" />

            <textElement textAlignment = "Center" verticalAlignment = "Middle">
               <font isBold = "true" />
            </textElement>

            <text>
               <![CDATA[Country]]>
            </text>
         </staticText>

         <staticText>
            <reportElement x = "0" y = "3" width = "136" height = "15" />

            <textElement textAlignment = "Center" verticalAlignment = "Middle">
               <font isBold = "true" />
            </textElement>

            <text><![CDATA[Name]]></text>
         </staticText>

      </band>
   </columnHeader>

   <detail>
      <band height = "16">

         <staticText>
            <reportElement mode = "Opaque" x = "0" y = "0" width = "535" height = "14"
               backcolor = "#E5ECF9" />

            <box>
               <bottomPen lineWidth = "0.25" lineColor = "#CCCCCC" />
            </box>

            <textElement />

            <text>
               <![CDATA[]]>
            </text>
         </staticText>

         <textField>
            <reportElement x = "414" y = "0" width = "121" height = "15" />

            <textElement textAlignment = "Center" verticalAlignment = "Middle">
               <font size = "9" />
            </textElement>

            <textFieldExpression class = "java.lang.String">
               <![CDATA[$F{country}]]>
            </textFieldExpression>
         </textField>

         <textField>
            <reportElement x = "0" y = "0" width = "136" height = "15" />
            <textElement textAlignment = "Center" verticalAlignment = "Middle" />

            <textFieldExpression class = "java.lang.String">
               <![CDATA[$F{name}]]>
            </textFieldExpression>
         </textField>

      </band>
   </detail>

</jasperReport>

Report Generation

我们将使用常规的 ANT 构建过程编译并执行以上文件。文件 build.xml（保存在 C:\tools\jasperreports-5.0.1\test 目录下）的内容如下。

We will compile and execute the above file using our regular ANT build process. The contents of the file build.xml (saved under directory C:\tools\jasperreports-5.0.1\test) are as below.

导入文件 - baseBuild.xml 从第 Environment Setup 章选取并应该放置在与 build.xml 相同的目录中。

The import file - baseBuild.xml is picked from the chapter Environment Setup and should be placed in the same directory as the build.xml.

<?xml version = "1.0" encoding = "UTF-8"?>
<project name = "JasperReportTest" default = "viewFillReport" basedir = ".">
   <import file = "baseBuild.xml" />

   <target name = "viewFillReport" depends = "compile,compilereportdesing,run"
      description = "Launches the report viewer to preview
      the report stored in the .JRprint file.">


      <java classname = "net.sf.jasperreports.view.JasperViewer" fork = "true">
         <arg value = "-F${file.name}.JRprint" />
         <classpath refid = "classpath" />
      </java>
   </target>

   <target name = "compilereportdesing" description = "Compiles the JXML file and
      produces the .jasper file.">

      <taskdef name = "jrc" classname = "net.sf.jasperreports.ant.JRAntCompileTask">
         <classpath refid = "classpath" />
      </taskdef>

      <jrc destdir = ".">
         <src>
            <fileset dir = ".">
               <include name = "*.jrxml" />
            </fileset>
         </src>
         <classpath refid = "classpath" />
      </jrc>

   </target>

</project>

接下来，让我们打开命令行窗口并转到放置 build.xml 的目录。最后，执行以下命令 ant -Dmain-class=com.tutorialspoint.JasperReportFill （viewFullReport 是默认目标） -

Next, let’s open command line window and go to the directory where build.xml is placed. Finally, execute the command ant -Dmain-class=com.tutorialspoint.JasperReportFill (viewFullReport is the default target) as follows −

C:\tools\jasperreports-5.0.1\test>ant -Dmain-class=com.tutorialspoint.JasperReportFill
Buildfile: C:\tools\jasperreports-5.0.1\test\build.xml

clean-sample:
   [delete] Deleting directory C:\tools\jasperreports-5.0.1\test\classes
   [delete] Deleting: C:\tools\jasperreports-5.0.1\test\jasper_report_template.jasper
   [delete] Deleting: C:\tools\jasperreports-5.0.1\test\jasper_report_template.jrprint

compile:
   [mkdir] Created dir: C:\tools\jasperreports-5.0.1\test\classes
   [javac] C:\tools\jasperreports-5.0.1\test\baseBuild.xml:28: warning:
   'includeantruntime' was not set, defaulting to build.sysclasspath=last;
   set to false for repeatable builds
   [javac] Compiling 7 source files to C:\tools\jasperreports-5.0.1\test\classes

compilereportdesing:
   [jrc] Compiling 1 report design files.
   [jrc] log4j:WARN No appenders could be found for logger
   (net.sf.jasperreports.engine.xml.JRXmlDigesterFactory).
   [jrc] log4j:WARN Please initialize the log4j system properly.
   [jrc] log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig
   for more info.
   [jrc] File : C:\tools\jasperreports-5.0.1\test\jasper_report_template.jrxml ... OK.

run:
   [echo] Runnin class : com.tutorialspoint.JasperReportFill
   [java] log4j:WARN No appenders could be found for logger
   (net.sf.jasperreports.extensions.ExtensionsEnvironment).
   [java] log4j:WARN Please initialize the log4j system properly.

viewFillReport:
   [java] log4j:WARN No appenders could be found for logger
   (net.sf.jasperreports.extensions.ExtensionsEnvironment).
   [java] log4j:WARN Please initialize the log4j system properly.

BUILD SUCCESSFUL
Total time: 18 seconds

由于以上编译，JasperViewer 窗口会如以下屏幕所示打开：

As a result of above compilation, a JasperViewer window opens up as shown in the following screen −

在这里，我们看到，报表标题“联系人列表”和作者“由 Manisha 准备”显示在报表的开头。

Here, we see that, the ReportTitle "List Of Contacts" and Author "Prepared By Manisha" are displayed at the beginning of the report.