net.sf.jasperreports.engine.query

## Class JRJpaQueryExecuter

- java.lang.Object
- - net.sf.jasperreports.engine.query.JRAbstractQueryExecuter
  - - net.sf.jasperreports.engine.query.JRJpaQueryExecuter

- All Implemented Interfaces:
    JRQueryExecuter

      public class JRJpaQueryExecuter
      extends JRAbstractQueryExecuter

  EJBQL query executer that uses the Java Persistence API.

  To use EJBQL in queries, an `javax.persistence.EntityManager` is needed. When running or filling reports the `em` need to be supplied with the named parameter `JRJpaQueryExecuterFactory.PARAMETER_JPA_ENTITY_MANAGER`.

  Example: `

       Map parameters = new HashMap();
       EntityManager em = emf.createEntityManager();
       parameters.put(JRJpaQueryExecuterFactory.PARAMETER_JPA_ENTITY_MANAGER, em);
       JasperRunManager.runReportToPdfFile(fileName, parameters);

  `

  When dealing with large result sets, pagination can be used by setting the `JRJpaQueryExecuterFactory.PROPERTY_JPA_QUERY_PAGE_SIZE` property in the report template.

  Example: `

       <property name="net.sf.jasperreports.ejbql.query.page.size" value="100"/>

  `

  Implementation-specific query hints can be set either using report properties in the report template, or by supplying the named parameter `JRJpaQueryExecuterFactory.PARAMETER_JPA_QUERY_HINTS_MAP` containing a `java.util.Map` with named/value query hints.

  Example using report property: `

       <property name="net.sf.jasperreports.ejbql.query.hint.fetchSize" value="100"/>

  ` The name of the query hint need to be prefixed with `net.sf.jasperreports.ejbql.query.hint.` (`JRJpaQueryExecuterFactory.PROPERTY_JPA_QUERY_HINT_PREFIX`). Above example will set a query hint with the name `fetchSize` and the `String` value `100`.

  Example using map: `

       Map hints = new HashMap();
       hints.put("fetchSize", Integer.valueOf(100));
       hints.put("anyName", anyObject());
       Map parameters = new HashMap();
       EntityManager em = emf.createEntityManager();
       parameters.put(JRJpaQueryExecuterFactory.PARAMETER_JPA_ENTITY_MANAGER, em);
       parameters.put(JRJpaQueryExecuterFactory.PARAMETER_JPA_QUERY_HINTS_MAP, hints);
       JasperRunManager.runReportToPdfFile(fileName, parameters);

  ` Note that when using report properties only `String` values can be set as query hint. When using a query hints map, any `Object` can be set as value.
  Version:
    $Id: JRJpaQueryExecuter.java 5878 2013-01-07 20:23:13Z teodord $
  Author:
    Marcel Overdijk (marceloverdijk@hotmail.com)
  See Also:
    `JRJpaQueryExecuterFactory`

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class net.sf.jasperreports.engine.query.JRAbstractQueryExecuter

      `JRAbstractQueryExecuter.QueryParameter, JRAbstractQueryExecuter.QueryParameterEntry, JRAbstractQueryExecuter.QueryParameterVisitor, JRAbstractQueryExecuter.ValuedQueryParameter, JRAbstractQueryExecuter.VisitExceptionWrapper`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static java.lang.String` | `CANONICAL_LANGUAGE`

    - ### Fields inherited from class net.sf.jasperreports.engine.query.JRAbstractQueryExecuter

      `CLAUSE_POSITION_ID, clauseFunctions, dataset`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JRJpaQueryExecuter(JasperReportsContext jasperReportsContext, JRDataset dataset, java.util.Map<java.lang.String,? extends JRValueParameter> parameters)`
    `JRJpaQueryExecuter(JRDataset dataset, java.util.Map<java.lang.String,? extends JRValueParameter> parameters)` Deprecated. Replaced by `JRJpaQueryExecuter(JasperReportsContext, JRDataset, Map)`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `cancelQuery()` Cancels the query if it's currently running.
    `void` | `close()` Closes resources kept open during the data source iteration.
    `JRDataSource` | `createDatasource()` Executes the query and creates a `JRDataSource` out of the result.
    `protected void` | `createQuery(java.lang.String queryString)` Creates the EJBQL query object.
    `protected JRDataSource` | `createResultDatasource()` Creates a data source out of the query result.
    `protected java.lang.String` | `getCanonicalQueryLanguage()` Returns a canonical query language for this query executer implementation.
    `protected java.lang.String` | `getEjbqlParameterName(java.lang.String parameterName)`
    `protected java.lang.String` | `getParameterReplacement(java.lang.String parameterName)` Returns the replacement text for a query parameter.
    `java.util.List<?>` | `getResultList()` Runs the query by calling `javax.persistence.Query.getResultList`.
    `java.util.List<?>` | `getResultList(int firstIndex, int resultCount)` Returns a page of the query results by calling `javax.persistence.Query.getResultList`.

    - ### Methods inherited from class net.sf.jasperreports.engine.query.JRAbstractQueryExecuter

      `addQueryMultiParameters, addQueryMultiParameters, addQueryParameter, addQueryParameter, appendClauseChunk, appendParameterChunk, appendParameterClauseChunk, appendQueryChunk, appendTextChunk, applyClause, checkParameter, findExtensionQueryFunction, getBooleanParameter, getBooleanParameter, getBooleanParameterOrProperty, getBooleanParameterOrProperty, getCollectedParameterNames, getCollectedParameters, getJasperReportsContext, getParameter, getParameterValue, getParameterValue, getPropertiesUtil, getQueryString, getStringParameter, getStringParameterOrProperty, getValueParameter, getValueParameter, parameterHasValue, parseQuery, registerClauseFunction, resolveFunction, unregisterClauseFunction, visitQueryParameters`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### CANONICAL_LANGUAGE

          protected static final java.lang.String CANONICAL_LANGUAGE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JRJpaQueryExecuter

          public JRJpaQueryExecuter(JasperReportsContext jasperReportsContext,
                            JRDataset dataset,
                            java.util.Map<java.lang.String,? extends JRValueParameter> parameters)

    - #### JRJpaQueryExecuter

          public JRJpaQueryExecuter(JRDataset dataset,
                            java.util.Map<java.lang.String,? extends JRValueParameter> parameters)

      Deprecated. Replaced by `JRJpaQueryExecuter(JasperReportsContext, JRDataset, Map)`.

  - ### Method Detail

    - #### getCanonicalQueryLanguage

          protected java.lang.String getCanonicalQueryLanguage()

      Description copied from class: `JRAbstractQueryExecuter`
      Returns a canonical query language for this query executer implementation.

      The canonical language is used to retrieve extensions for the query executer.

      The default implementation returns the runtime query language used in the dataset, but query executer implementations should override this method and return a fixed language.

      Overrides:
        `getCanonicalQueryLanguage` in class `JRAbstractQueryExecuter`
      Returns:
        a canonical query language

    - #### createDatasource

          public JRDataSource createDatasource()
                                        throws JRException

      Description copied from interface: `JRQueryExecuter`
      Executes the query and creates a `JRDataSource` out of the result.
      Returns:
        a `JRDataSource` wrapping the query execution result.
      Throws:
        `JRException`

    - #### createQuery

          protected void createQuery(java.lang.String queryString)

      Creates the EJBQL query object.
      Parameters:
        `queryString` - the query string

    - #### createResultDatasource

          protected JRDataSource createResultDatasource()

      Creates a data source out of the query result.
      Returns:
        the data source

    - #### close

          public void close()

      Description copied from interface: `JRQueryExecuter`
      Closes resources kept open during the data source iteration.

      This method is called after the report is filled or the dataset is iterated. If a resource is not needed after the data source has been created, it should be released at the end of `createDatasource`.

    - #### cancelQuery

          public boolean cancelQuery()
                              throws JRException

      Description copied from interface: `JRQueryExecuter`
      Cancels the query if it's currently running.

      This method will be called from a different thread if the client decides to cancel the filling process.
      Returns:
        `true` if and only if the query was running and it has been canceled
      Throws:
        `JRException`

    - #### getParameterReplacement

          protected java.lang.String getParameterReplacement(java.lang.String parameterName)

      Description copied from class: `JRAbstractQueryExecuter`
      Returns the replacement text for a query parameter.
      Specified by:
        `getParameterReplacement` in class `JRAbstractQueryExecuter`
      Parameters:
        `parameterName` - the parameter name
      Returns:
        the replacement text
      See Also:
        `JRQueryChunk.TYPE_PARAMETER`

    - #### getEjbqlParameterName

          protected java.lang.String getEjbqlParameterName(java.lang.String parameterName)

    - #### getResultList

          public java.util.List<?> getResultList()

      Runs the query by calling `javax.persistence.Query.getResultList`.

      All the result rows are returned.
      Returns:
        the result of the query as a list

    - #### getResultList

          public java.util.List<?> getResultList(int firstIndex,
                                        int resultCount)

      Returns a page of the query results by calling `javax.persistence.Query.getResultList`.
      Parameters:
        `firstIndex` - the index of the first row to return
        `resultCount` - the number of rows to return
      Returns:
        result row list

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com