Package net.sf.jasperreports.engine.design

Class JasperDesign

  • All Implemented Interfaces:
    Serializable, JRChangeEventsSupport, JRDefaultStyleProvider, JRIdentifiable, JRPropertiesHolder, JRReport
    public class JasperDesign
extends JRBaseReport
    JasperDesign is used for in-memory representation of a report design.

    The class contains all report properties and report elements inherited from the JRReport interface in their design time state.

    All its instances are subject to compilation before being used for filling and report generation. These instances are the raw material that the JasperReports library uses to generate reports. Such instances are usually obtained:

    • by parsing the JRXML report template files using the library's internal XML-parsing utility classes.
    • by applications that use JasperReports through API calls if working with JRXML files is not an option.

    The first option for creating report designs relies on editing the JRXML files and using them with the JasperCompileManager in order to prepare them for filling with data. Because they are well structured and are validated against a public XSD when parsed, these files can be easily edited using simple editors or specialized XML editors.

    The second option is recommended only in case the parent application that uses JasperReports inside the reporting module needs to create report templates at runtime. In most cases this is not needed because the report templates do not need to change with every report execution, and hence static report templates could be used. Only the data used to fill these static report templates is dynamic.

    However, there are cases when the actual report template is the result of some user input. The parent application might supply its users with a set of options when launching the reports that might take the form of some simplified report designer or wizard. In such cases, the actual report layout is not known or is not complete at design time, and can only be put together after the user's input is received.

    The most common use case scenario that requires dynamically built or ad hoc report templates (as we call them) is one in which the columns that are going to be present in a table-like report layout are not known at design time. Instead, the user will give the number of columns and their order inside the desired report at runtime.

    Developers have to make sure that the applications they create really need ad hoc reports and cannot rely solely on static report templates. Since dynamically built report templates have to be compiled on the fly at runtime, they can result in a certain loss of performance.

    Author:
    Teodor Danciu (teodord@users.sourceforge.net)
    See Also:
    JRReport, JRBaseReport, JRXmlLoader, Serialized Form

    • Constructor Detail

      • JasperDesign

        public JasperDesign()
        Constructs a JasperDesign object and fills it with the default variables and parameters.

    • Method Detail

      • setName

        public void setName​(String name)
        Sets the report name. It is strongly recommended that the report name matches the .jrxml file name, since report compilers usually use this name for the compiled .jasper file.

      • setLanguage

        public void setLanguage​(String language)
        Specifies the language used for report expressions (Java or Groovy). The default is Java.

      • setColumnCount

        public void setColumnCount​(Integer columnCount)
        Specifies the number of report columns.

      • setPrintOrder

        public void setPrintOrder​(PrintOrderEnum printOrder)
        Sets the print order. In case of multiple column reports, the engine can perform vertical or horizontal fill.
        See Also:
        VERTICAL,, HORIZONTAL

      • setColumnDirection

        public void setColumnDirection​(RunDirectionEnum columnDirection)
        Sets the column direction.

      • setPageWidth

        public void setPageWidth​(int pageWidth)
        Sets page width (including margins etc.). Default is 595.

      • setPageHeight

        public void setPageHeight​(int pageHeight)
        Sets page height (including margins etc.). Default is 842.

      • setColumnWidth

        public void setColumnWidth​(int columnWidth)
        Sets the column width.

      • setColumnSpacing

        public void setColumnSpacing​(int columnSpacing)
        Sets the spacing between columns.

      • setLeftMargin

        public void setLeftMargin​(int leftMargin)
        Sets the left margin. The working space is calculated by subtracting the margins from the page width.

      • setRightMargin

        public void setRightMargin​(int rightMargin)
        Sets the right margin. The working space is calculated by subtracting the margins from the page width.

      • setTopMargin

        public void setTopMargin​(int topMargin)
        Sets the top margin. The working space is calculated by subtracting the margins from the page height.

      • setBottomMargin

        public void setBottomMargin​(int bottomMargin)
        Sets the top margin. The working space is calculated by subtracting the margins from the page height.

      • setBackground

        public void setBackground​(JRBand background)
        Sets the background band.

      • setTitle

        public void setTitle​(JRBand title)
        Sets the title band.

      • setTitleNewPage

        public void setTitleNewPage​(boolean isTitleNewPage)
        Flag used to specify if the title section should be printed on a separate initial page.
        Parameters:
        isTitleNewPage - true if the title section should be displayed on a separate initial page, false if it will be displayed on the first page along with other sections.

      • setSummary

        public void setSummary​(JRBand summary)
        Sets the summary band.

      • setNoData

        public void setNoData​(JRBand noData)
        Sets the noData band.

      • setSummaryNewPage

        public void setSummaryNewPage​(boolean isSummaryNewPage)
        Flag used to specify if the summary section should be printed on a separate last page.
        Parameters:
        isSummaryNewPage - true if the summary section should be displayed on a separate last page, false if it will be displayed on the last page along with other sections, if there is enough space.

      • setSummaryWithPageHeaderAndFooter

        public void setSummaryWithPageHeaderAndFooter​(boolean isSummaryWithPageHeaderAndFooter)
        Flag used to specify if the summary section should be accompanied by the page header and footer.
        Parameters:
        isSummaryWithPageHeaderAndFooter - true if the summary section should be displayed on pages that have the page header and footer, false if it will be displayed on pages without header and footer.

      • setFloatColumnFooter

        public void setFloatColumnFooter​(boolean isFloatColumnFooter)
        Flag used to specify if the column footer section should be printed at the bottom of the column or if it should immediately follow the last detail or group footer printed on the current column.

      • setPageHeader

        public void setPageHeader​(JRBand pageHeader)
        Sets the page header band.

      • setPageFooter

        public void setPageFooter​(JRBand pageFooter)
        Sets the page footer band.

      • setLastPageFooter

        public void setLastPageFooter​(JRBand lastPageFooter)
        Sets the last page footer band.

      • setColumnHeader

        public void setColumnHeader​(JRBand columnHeader)
        Sets the column header band.

      • setColumnFooter

        public void setColumnFooter​(JRBand columnFooter)
        Sets the column footer band.

      • setScriptletClass

        public void setScriptletClass​(String scriptletClass)

      • setFormatFactoryClass

        public void setFormatFactoryClass​(String formatFactoryClass)

      • setResourceBundle

        public void setResourceBundle​(String resourceBundle)
        Sets the base name of the report associated resource bundle.

      • addImport

        public void addImport​(String value)
        Adds an import (needed if report expression require additional classes in order to compile).

      • removeImport

        public void removeImport​(String value)
        Removes an import.

      • resetDefaultStyle

        public void resetDefaultStyle()

      • setDefaultStyle

        public void setDefaultStyle​(JRStyle style)

      • getStylesList

        public List<JRStyle> getStylesList()
        Gets a list of report level styles. These styles can be referenced by report elements.

      • addStyle

        public void addStyle​(JRStyle style)
              throws JRException
        Adds a report style, that can be referenced by report elements.
        Throws:
        JRException

      • addStyle

        public void addStyle​(int index,
                     JRStyle style)
              throws JRException
        Inserts a report style, that can be referenced by report elements, at specified position.
        Throws:
        JRException

      • removeStyle

        public JRStyle removeStyle​(String styleName)
        Removes a report style from the list, based on the style name.

      • removeStyle

        public JRStyle removeStyle​(JRStyle style)
        Removes a report style from the list.

      • getScriptletsList

        public List<JRScriptlet> getScriptletsList()
        Gets a list of report scriptlets (excluding the one specified by scriptletClass).

      • getScriptletsMap

        public Map<String,​JRScriptlet> getScriptletsMap()
        Gets a map of report scriptlets (excluding the one specified by scriptletClass).

      • removeScriptlet

        public JRScriptlet removeScriptlet​(String scriptletName)
        Removes a report scriptlet, based on its name.

      • getParametersList

        public List<JRParameter> getParametersList()
        Gets a list of report parameters (including built-in ones).

      • getParametersMap

        public Map<String,​JRParameter> getParametersMap()
        Gets a map of report parameters (including built-in ones).

      • removeParameter

        public JRParameter removeParameter​(String parameterName)
        Removes a report parameter, based on its name.

      • setQuery

        public void setQuery​(JRDesignQuery query)
        Specifies the report query.

      • getFieldsList

        public List<JRField> getFieldsList()
        Gets a list of report fields.

      • getFieldsMap

        public Map<String,​JRField> getFieldsMap()
        Gets a map of report fields.

      • getSortFieldsList

        public List<JRSortField> getSortFieldsList()
        Gets a list of sort report fields.

      • getVariablesList

        public List<JRVariable> getVariablesList()
        Gets a list of report variables.

      • getVariablesMap

        public Map<String,​JRVariable> getVariablesMap()
        Gets a map of report variables.

      • getGroupsList

        public List<JRGroup> getGroupsList()
        Gets an array of report groups.

      • getGroupsMap

        public Map<String,​JRGroup> getGroupsMap()
        Gets a list of report groups.

      • removeGroup

        public JRGroup removeGroup​(String groupName)
        Removes a new group from the report design.

      • getExpressions

        public Collection<JRExpression> getExpressions()
        Returns a collection of all report expressions.

      • getDatasetsList

        public List<JRDataset> getDatasetsList()
        Returns the list of report sub datasets.
        Returns:
        list of JRDesignDataset objects

      • getDatasetMap

        public Map<String,​JRDataset> getDatasetMap()
        Returns the sub datasets of the report indexed by name.
        Returns:
        the sub datasets of the report indexed by name

      • addDataset

        public void addDataset​(int index,
                       JRDesignDataset dataset)
                throws JRException
        Inserts a sub dataset at specified position into the report.
        Parameters:
        index - the position
        dataset - the dataset
        Throws:
        JRException

      • removeDataset

        public JRDataset removeDataset​(String datasetName)
        Removes a sub dataset from the report.
        Parameters:
        datasetName - the dataset name
        Returns:
        the removed dataset

      • removeDataset

        public JRDataset removeDataset​(JRDataset dataset)
        Removes a sub dataset from the report.
        Parameters:
        dataset - the dataset to be removed
        Returns:
        the dataset

      • getMainDesignDataset

        public JRDesignDataset getMainDesignDataset()
        Returns the main report dataset.
        Returns:
        the main report dataset

      • setMainDataset

        public void setMainDataset​(JRDesignDataset dataset)
        Sets the main report dataset.

        This method can be used as an alternative to setting the parameters, fields, etc directly on the report.

        Parameters:
        dataset - the dataset

      • preprocess

        public void preprocess()
        Performs preliminary processing and calculations prior to compilation.

      • setIgnorePagination

        public void setIgnorePagination​(boolean ignorePagination)
        Sets the value of the ignore pagination flag.
        Parameters:
        ignorePagination - whether to ignore pagination when generating the report
        See Also:
        JRReport.isIgnorePagination()

      • addTemplate

        public void addTemplate​(JRReportTemplate template)
        Adds a report template.
        Parameters:
        template - the template to add.
        See Also:
        getTemplates()

      • addTemplate

        public void addTemplate​(int index,
                        JRReportTemplate template)
        Inserts a report template at specified position.
        Parameters:
        index - the template position.
        template - the template to insert.
        See Also:
        getTemplates()

      • removeTemplate

        public boolean removeTemplate​(JRReportTemplate template)
        Removes a report template.
        Parameters:
        template - the template to remove
        Returns:
        true if and only if the template has been found and removed

      • getTemplates

        public JRReportTemplate[] getTemplates()
        Description copied from interface: JRReport
        Returns the list of report templates.

        A report template is an expression which resolves at runtime to a template. Templates include styles which can be used in the report.

        The order in which the templates are included in the report is important:

        • A style's parent must appear before the style itself.
        • A style overrides styles with the same name that are placed before it. Also, report styles override templates styles with the same name.
        Specified by:
        getTemplates in interface JRReport
        Overrides:
        getTemplates in class JRBaseReport
        Returns:
        the list of report templates, or null if none
        See Also:
        JRTemplate, JRParameter.REPORT_TEMPLATES

      • setUUID

        public void setUUID​(UUID uuid)
        Sets the unique identifier for the report.
        Parameters:
        uuid - the identifier

      • hasUUID

        public boolean hasUUID()
        Determines whether the report has an existing unique identifier. Note that when no existing identifier is set, JRBaseReport.getUUID() would generate and return an identifier.
        Returns:
        whether the report has an externally set unique identifier
        See Also:
        setUUID(UUID)