com.jrefinery.report.targets.pageable.pagelayout
Class PageLayouter

java.lang.Object
  |
  +--com.jrefinery.report.function.AbstractFunction
        |
        +--com.jrefinery.report.targets.pageable.pagelayout.PageLayouter
All Implemented Interfaces:
java.lang.Cloneable, java.util.EventListener, Expression, Function, ReportListener
Direct Known Subclasses:
FlowPageLayouter, SimplePageLayouter

public abstract class PageLayouter
extends AbstractFunction

The baseclass for all PageLayouter. A page layouter is the layoutmanager of an logical page. This layoutmanager is responsible for handling and detecting page breaks, for placing the various Root-Bands (bands that are contained directly in an report) on the page and for the global appeareance of an page (columns, band placement policy etc.)

A PageLayouter for an Report is defined by the ReportProperty pageable.layoutManager by setting the classname of the page layouter. The specified class must contain an DefaultConstructor and must be an instance of PageLayouter.

All PageLayouter may define a set of LayoutConstraints for use in the Root-Bands. These constraints can be used to configure the layouting process. It is up to the layoutmanager implementation, which constraints are recognized and how these constraints are used.

All layoutmanagers should document their known constraints.

Author:
Thomas Morgner

Nested Class Summary
protected static class PageLayouter.LayoutManagerState
          Represents the state of the page layouter.
 
Field Summary
 
Fields inherited from interface com.jrefinery.report.function.Expression
AUTOACTIVATE_PROPERTY
 
Constructor Summary
PageLayouter()
          Creates a new page layouter.
 
Method Summary
protected  void clearCurrentEvent()
          Clears the current event.
 void clearLogicalPage()
          Clears the logical page reference.
protected  void clearSaveState()
          Clear the saveState.
 java.lang.Object clone()
          Returns a clone of the PageLayouter.
protected  void endPage()
          Ends a page.
protected  ReportEvent getCurrentEvent()
          Returns the current report event.
 int getDependencyLevel()
          The dependency level defines the level of execution for this function.
 PageLayouter.LayoutManagerState getLayoutManagerState()
          Return the last stored LayoutManager state or null if there is no state stored.
 LogicalPage getLogicalPage()
          Returns the logical page.
 ReportDefinition getReport()
          Returns the report that should be printed.
 java.lang.Object getValue()
          Return a self-reference.
 boolean isFinishingPage()
          Returns the 'finishing page' flag.
 boolean isGeneratedPageEmpty()
          Maintains a flag, whether the generated page was completly empty.
abstract  boolean isNewPageStarted()
          Returns true, if the PageLayouter has successfully started a new page.
 boolean isPageEnded()
          Checks whether this page has ended.
 boolean isPageRestartDone()
          Returns whether the restarting of the page is completed.
 boolean isRestartingPage()
          Returns the 'restarting page' flag.
 void restoreSaveState(ReportState ancestor)
          Restores the state.
protected abstract  PageLayouter.LayoutManagerState saveCurrentState()
          Save the current state into the LayoutManagerState object.
protected  void setCurrentEvent(ReportEvent currentEvent)
          Sets the current event (also updates the report reference).
 void setDependencyLevel(int deplevel)
          Overrides the depency level.
 void setFinishingPage(boolean finishingPage)
          Sets the 'finishing page' flag.
protected  void setGeneratedPageEmpty(boolean generatedPageEmpty)
          Defines a flag, whether the generated page was completly empty.
 void setLogicalPage(LogicalPage logicalPage)
          Sets the logical page for the layouter.
 void setPageRestartDone(boolean pageRestartDone)
          Defines whether the restarting of the page is completed.
 void setRestartingPage(boolean restartingPage)
          Sets the 'restarting page' flag.
protected  void startPage()
          Restarts the current page.
 
Methods inherited from class com.jrefinery.report.function.AbstractFunction
getDataRow, getInstance, getName, getProperties, getProperty, getProperty, groupFinished, groupStarted, initialize, isActive, itemsAdvanced, itemsFinished, itemsStarted, pageFinished, pageStarted, reportDone, reportFinished, reportInitialized, reportStarted, setDataRow, setName, setProperties, setProperty
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PageLayouter

public PageLayouter()
Creates a new page layouter. The function depency level is set to -1 (highest priority).

Method Detail

isPageRestartDone

public boolean isPageRestartDone()
Returns whether the restarting of the page is completed. Restarting the page is separated into two processes. The first step restores the save state, and the second step starts to print the page header and opens the logical page. The second step is not executed, if no more content is printed.

Returns:
true, if the restart process for this page is completed, false otherwise.

setPageRestartDone

public void setPageRestartDone(boolean pageRestartDone)
Defines whether the restarting of the page is completed. Restarting the page is separated into two processes. The first step restores the save state, and the second step starts to print the page header and opens the logical page. The second step is not executed, if no more content is printed.

Parameters:
pageRestartDone - set to true, if the restart process for this page is completed, false otherwise.

isGeneratedPageEmpty

public boolean isGeneratedPageEmpty()
Maintains a flag, whether the generated page was completly empty.

Returns:
true, if the page was empty when the logical page was closed, false otherwise.

setGeneratedPageEmpty

protected void setGeneratedPageEmpty(boolean generatedPageEmpty)
Defines a flag, whether the generated page was completly empty.

Parameters:
generatedPageEmpty - true, if the page was empty when the logical page was closed, false otherwise.

setLogicalPage

public void setLogicalPage(LogicalPage logicalPage)
Sets the logical page for the layouter.

Parameters:
logicalPage - the logical page (null not permitted).
Throws:
java.lang.NullPointerException - it the logical page is null

clearLogicalPage

public void clearLogicalPage()
Clears the logical page reference. This method must be called after the page has been processed.


getLogicalPage

public LogicalPage getLogicalPage()
Returns the logical page.

Returns:
the logical page.

isFinishingPage

public boolean isFinishingPage()
Returns the 'finishing page' flag.

When set to true, indicates that the current page is shut down. The page footer should be printed and the state stored. Trying to end the page again while the finishing process is not complete will result in an IllegalState.

If the page should be finished while the page is restarted, will throw an ReportProcessing exception, as this would result in an infinite loop.

Returns:
true if the current page is currently shut down, false otherwise.

setFinishingPage

public void setFinishingPage(boolean finishingPage)
Sets the 'finishing page' flag.

Parameters:
finishingPage - the new flag value.
See Also:
isFinishingPage()

isRestartingPage

public boolean isRestartingPage()
Returns the 'restarting page' flag.

Is set to true, while the page is started. The last saved state is restored and the page header gets prepared. Trying the start the page again while the restarting process is not complete or while the page is currently being finished, will result in an IllegalState.

Returns:
true if the current page is currently restarting, false otherwise

setRestartingPage

public void setRestartingPage(boolean restartingPage)
Sets the 'restarting page' flag.

Parameters:
restartingPage - sets the restarting page flag.
See Also:
isRestartingPage()

getReport

public ReportDefinition getReport()
Returns the report that should be printed. This is the report contained in the last ReportEvent received, or null, if no event occurred here.

Returns:
the report.

getCurrentEvent

protected ReportEvent getCurrentEvent()
Returns the current report event.

Returns:
the event.

setCurrentEvent

protected void setCurrentEvent(ReportEvent currentEvent)
Sets the current event (also updates the report reference).

Parameters:
currentEvent - event.

clearCurrentEvent

protected void clearCurrentEvent()
Clears the current event.


endPage

protected void endPage()
                throws ReportProcessingException
Ends a page. During the process, an PageFinished event is generated and the state advances to the next page. The Layoutmanager-State is saved and the logical page is closed.

While this method is executed, the FinishingPage flag is set to true.

You are not able to print on the logical page after the page is finished.

Throws:
java.lang.IllegalStateException - if the page end is requested a second time
ReportProcessingException - if the page end is requested while the page is restarted.

startPage

protected void startPage()
Restarts the current page. The logical page is opened again and the PageStartedEvent is fired. While this method is executed, the RestartingPage flag is set to true.


isPageEnded

public boolean isPageEnded()
Checks whether this page has ended. If this method returns true, no printing to the logical page is allowed.

Returns:
true, if the logical page is closed and no printing is allowed

isNewPageStarted

public abstract boolean isNewPageStarted()
Returns true, if the PageLayouter has successfully started a new page. The start of the new page is delayed, until the first content is printed.

Returns:
true, if a new page has already been started, false otherwise.

saveCurrentState

protected abstract PageLayouter.LayoutManagerState saveCurrentState()
Save the current state into the LayoutManagerState object. The concrete implementation is responsible to save all required information so that the printing can be continued after the pagebreak is done.

Returns:
a valid saveState, never null

getLayoutManagerState

public PageLayouter.LayoutManagerState getLayoutManagerState()
Return the last stored LayoutManager state or null if there is no state stored.

Returns:
the last LayoutManagerState.

clearSaveState

protected void clearSaveState()
Clear the saveState. This should be called after the saveState has been restored.


getValue

public java.lang.Object getValue()
Return a self-reference. This backdoor is used to extract the current PageLayoutManager instance from the DataRow. Please don't use it in your functions, it is required for the PageableReportProcessor.

Returns:
this PageLayouter.

getDependencyLevel

public int getDependencyLevel()
The dependency level defines the level of execution for this function. Higher dependency functions are executed before lower dependency functions. For ordinary functions and expressions, the range for dependencies is defined to start from 0 (lowest dependency possible) to 2^31 (upper limit of int).

PageLayouter functions override the default behaviour an place them self at depency level -1, an so before any userdefined function.

Specified by:
getDependencyLevel in interface Expression
Overrides:
getDependencyLevel in class AbstractFunction
Returns:
the level.

setDependencyLevel

public void setDependencyLevel(int deplevel)
Overrides the depency level. Should be lower than any other function depency.

Specified by:
setDependencyLevel in interface Expression
Overrides:
setDependencyLevel in class AbstractFunction
Parameters:
deplevel - the new depency level.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Returns a clone of the PageLayouter.

Be aware, this does not create a deep copy. If you have complex structures contained in objects, you have to overwrite this function.

Specified by:
clone in interface Function
Overrides:
clone in class AbstractFunction
Returns:
a clone of the function.
Throws:
java.lang.CloneNotSupportedException - this should never happen.

restoreSaveState

public void restoreSaveState(ReportState ancestor)
                      throws ReportProcessingException
Restores the state.

Parameters:
ancestor - the ancestor state.
Throws:
ReportProcessingException - if the printing failed or a pagebreak is requested while the page is restored.
java.lang.IllegalStateException - if there is no SavedState but this is not the first page.