Parameter Contributor

What's for?

With parameter contributor, you can take some parameters, play with them, and put back in the map some other parameters, or replace values of existing ones.

Sample Use Case

Let's say that your report is displaying the grades for a given student. In your DB structure grades are kept in the table grades only for 1 year after the student got the degree. So you don't know which table you should get the list of grades from.

What you want is to fire a query with the student name (or id or whatever) to get the year of degree. Then if this year is (llower than) < currentYear - 1 the table you are interested in is historical_grades otherwise is grades.

Parameter Contributor can help you with that... how? Let's have a look!!

Grade List Report

Our Grade list Report is fairly simple, it has a parameter STUDENT_ID and a parameter GRADES_TABLE_NAME. The GRADES_TABLE_NAME param is not prompted to the user, it will be populated by our parameter contributor. In our query we'll use it after the from clause:

SELECT * FROM $P!{GRADES_TABLE_NAME} WHERE STUDENT_ID = $P{STUDENT_ID}

(Have you noticed the different usage of the 2 parameters in the query? this is not related to the Parameter Contributor: parameters included with $P! will not be wrapped by quotes in SQL, but just injected in the sql query.)

This is all we need here, the magic will happen in the parameter Contributor!

How can I include a new Parameter Contributor?

Parameter contributors are a JR extension point, so they are added as extensions.

Short answer is : with a jar.

Long answer is: we should have a look on what is inside this jar :)

The key elements in a parameterContributor are:

• Parameter Contributor (s ... you may have more than one contributor)
  • contains your business logic, is where the magic happens
  • has a method contributeParameters(Map<String, Object> parameters) . Here you have access to report parameters and you can add yours to the parameters map.
  • must implement net.sf.jasperreports.engine.ParameterContributor
• Parameter Contributor Factory:
  • describe the list of contributors that you wish to add.
  • must implement net.sf.jasperreports.engine.ParameterContributorFactory
• Extension Registry Factory:
  • will create the registry with your extensions to be loaded. In this case will just cointain our Parameter Contributor Factory
  • Is the one referenced from the jasperreports_extension.properties file
  • must implement: net.sf.jasperreports.extensions.ExtensionsRegistryFactory
• jasperreports_extension.properties:
  • You may have seen this already in other docs. Is the standard way to register extensions in JasperReports Library.
  • Is a properties file, so you'll find key=value structure
    • key: if you are registering a parameter contributor the prefix must be net.sf.jasperreports.extension.registry.factory.parameter.contributor . Followed by a name you like. should be unique in jasperContext
    • value : the class name of our Extension Registry Factory
    • net.sf.jasperreports.extension.registry.factory.parameter.contributor.grades.table=com.jaspersoft.parameter.contributor.GradesTableNameParameterContributorExtensionsRegistryFactory

GradesTableNameParameterContributor

Here you can can find the jar with the source included (parameterContributor_GradesTable_java17_jrs601.jar ). Have a look in the code will be easier than read a periphrasis here.

As we said the business logic is in: com.jaspersoft.parameter.contributor.GradesTableNameParameterContributor

package com.jaspersoft.parameter.contributor;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Calendar;
import java.util.Map;
import net.sf.jasperreports.engine.JRException;
import net.sf.jasperreports.engine.JRParameter;
import net.sf.jasperreports.engine.ParameterContributor;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
/**
* @author Gianluca Natali
*/
public class GradesTableNameParameterContributor implements
  ParameterContributor {
protected final Log logger = LogFactory
   .getLog(GradesTableNameParameterContributor.class);
public static final String STUDENT_ID_PARAM = "STUDENT_ID";
public static final String GRADES_TABLE_NAME_PARAM = "GRADES_TABLE_NAME";

@Override
public void contributeParameters(Map<String, Object> parameters)
   throws JRException {
  /* The contributor is not report dependent. So it will be executed for all your reports.
   * Here I check the presence of the parameter I use as flag. If is not there I will do nothing.
   */
  //This is the parameter inputed by the user
  String studentIdParam = (String) parameters.get(STUDENT_ID_PARAM);
  if (studentIdParam == null) { return; }
  // Retrieving the connection from report parameters
  Connection reportConnection = (Connection) parameters.get(JRParameter.REPORT_CONNECTION);
  // Fire the query to find the student
  Student student = findStudent(studentIdParam, reportConnection);
  // Here my business logic to retrieve the table name
  int currentYear = Calendar.getInstance().get(Calendar.YEAR);
  boolean isInHistoric = student.getYearOfDegree() < currentYear - 1;
  String gradesTableName = isInHistoric ? "historical_grades " : "grades";
  // Adding the grades table name to the parameters map
  parameters.put(GRADES_TABLE_NAME_PARAM, gradesTableName);
}


@Override
public void dispose() {
  // Here you can dispose elements used from the contributor. this will be
  // called after the report is filled. As example you could close a jdbc
  // connection opened in the contributeParameters method
}


protected Student findStudent(String studentId, Connection connection) {
  String query = "SELECT full_name, degree_year, student_id  FROM students where student_id=?";
  Student student = null;
  /*Retrieving the student from db. check the jar for details*/
  return student;
}


protected class Student {
  /*Student object definition. check the jar for details */
}
}

parametercontributor_gradestable_java17_jrs601.jar