jimm.datavision
Class Report

java.lang.Object
  extended by jimm.datavision.Report
All Implemented Interfaces:
Nameable, Writeable
Direct Known Subclasses:
Subreport

public class Report
extends java.lang.Object
implements Nameable, Writeable

A report holds data source information, accepts parameters from the user, runs a query, and uses a layout engine to format the output. It may contain many different sections, each of which can contain logic for surpressing itself.

Author:
Jim Menard, jimm@io.com

Field Summary
protected  java.util.Collection aggregateFields
           
protected  boolean askedForParameters
           
protected  java.lang.String author
           
protected  boolean caseSensitiveDatabaseNames
          Flag for Database data sources.
protected  java.lang.String databasePassword
           
protected  DataSource dataSource
           
protected  Field defaultField
          This field holds default format, border, and bounds values for all fields.
protected  java.lang.String description
           
protected  SectionArea details
           
protected  java.util.HashMap formulas
           
protected  java.util.ArrayList groups
           
protected  LayoutEngine layoutEngine
           
protected  java.lang.String name
           
protected static double OUTPUT_DTD_VERSION
           
protected  SectionArea pageFooters
           
protected  SectionArea pageHeaders
           
protected  PaperFormat paperFormat
           
protected  java.util.TreeMap parameters
           
protected  boolean parametersHaveValues
           
protected  ParameterReader paramReader
           
protected  boolean paramsSetManually
           
protected  SectionArea reportFooters
           
protected  SectionArea reportHeaders
           
protected  DataCursor rset
           
protected  Scripting scripting
           
protected  Formula startFormula
           
protected  java.util.HashMap subreports
           
protected  java.lang.String title
           
protected  java.util.HashMap usercols
           
static java.lang.String XML_ENCODING_ATTRIBUTE
          The string to write at the top of an XML file in the XML decl.
static java.lang.String XML_JAVA_ENCODING
          The string to use when reading and writing XML files.
 
Constructor Summary
Report()
          Constructs an empty report.
 
Method Summary
 void add(java.lang.Object obj)
          Figure out what obj is and add it.
 void addFormula(Formula f)
           
 void addGroup(Group g)
           
 void addParameter(Parameter p)
           
 void addSubreport(Subreport sub)
           
 void addUserColumn(UserColumn uc)
           
protected  void askForDataSourceFile()
          Asks the user for a data source file if necessary.
protected  void askForParameters()
          Asks the user for parameter values.
 void askForPassword(Database db)
          Sets a database's user name and password.
 boolean caseSensitiveDatabaseNames()
          Returns the value of the caseSensitiveDatabaseNames flag.
protected  void collectAggregateFields()
          Collects all aggregate fields and lets each one initialize itself.
protected  java.util.List collectUsedParameters()
          Returns a list of all the parameters actually used in the report.
 java.lang.Object columnValue(Selectable selectable)
          Returns the current value of the specified selectable.
 boolean contains(Field f)
          Returns true if the specified field exists within this report.
 boolean contains(Section s)
          Returns true if this report contains the specified section.
 boolean containsReferenceTo(Field f)
          Returns true if the specified field exists within this report either directly (as a field) or indirectly (as a formula used by a aggregate, parameter, user column, or another formula).
 boolean containsReferenceTo(Formula f)
          Returns true if the specified formula exists within this report either directly (as a formula field) or indirectly (as a formula used by a aggregate or by another formula).
 boolean containsReferenceTo(Parameter p)
          Returns true if the specified parameter exists within this report either directly (as a parameter field) or indirectly (as a parameter used by a aggregate or by another parameter or in the query's where clause).
 boolean containsReferenceTo(UserColumn uc)
          Returns true if the specified user column exists within this report either directly (as a user column field) or indirectly (inside a aggregate or formula).
 int countGroups()
           
 SectionArea details()
           
 java.lang.Object eval(java.lang.String language, java.lang.String evalString, java.lang.String displayName)
          Evaluates an evalString using language and returns the results.
 void evaluateFormulasIn(Section s)
          Evalues the formulas in the specified section.
 Column findColumn(java.lang.String id)
          Given an id (a column name), returns the column that has that id.
 Field findField(java.lang.Object id)
          Given an id, returns the field that has that id.
 Formula findFormula(java.lang.Object id)
          Returns the formula with the specified id or null if one is not found.
 Formula findFormulaByName(java.lang.String name)
          Returns the formula with the specified name or null if one is not found.
 Group findGroup(Section section)
          Returns the group associated with the specified section, or null if there isn't one.
 Group findGroup(Selectable selectable)
          Returns the group associated with the specified column, or null if there isn't one.
 Parameter findParameter(java.lang.Object id)
          Returns the parameter with the specified id or null if one is not found.
 Parameter findParameterByName(java.lang.String name)
          Returns the parameter with the specified name or null if one is not found.
 Selectable findSelectable(java.lang.Object id, java.lang.String type)
           
 Subreport findSubreport(java.lang.Object id)
          Returns the subreport with the specified id or null if one is not found.
 UserColumn findUserColumn(java.lang.Object id)
          Returns the user column with the specified id or null if one is not found.
 UserColumn findUserColumnByName(java.lang.String name)
          Returns the user column with the specified name or null if one is not found.
 SectionArea footers()
           
 java.util.Iterator formulas()
           
 java.lang.Long generateNewFormulaId()
          Generates and returns a new unique formula id number.
protected  java.lang.Long generateNewId(java.util.Iterator iter)
          Generates and returns a new unique id number.
 java.lang.Long generateNewParameterId()
          Generates and returns a new unique parameter id number.
 java.lang.Long generateNewSubreportId()
          Generates and returns a new unique user column id number.
 java.lang.Long generateNewUserColumnId()
          Generates and returns a new unique user column id number.
 java.util.AbstractList getAggregateFieldsFor(Field field)
          Collects all aggregate fields that are aggregating the specified field.
 java.lang.String getAuthor()
           
 DataCursor getCurrentRow()
          Returns the current row of data.
 DataSource getDataSource()
           
 Field getDefaultField()
          Returns the field that holds default format, border, and bounds values for all fields.
 java.lang.String getDescription()
           
protected  java.awt.Frame getDesignFrame()
          Returns the Frame associated with the design window for this report; may be null.
 Section getFirstSectionByArea(int area)
          Returns the first section in the list of the specified type.
 java.lang.String getName()
          Returns the name.
 PaperFormat getPaperFormat()
           
 java.lang.Object getParameterValue(java.lang.Object paramId)
          Returns the value of the specified parameter.
 Scripting getScripting()
           
 SectionArea getSectionArea(int area)
          Returns the section area corresponding to area, but only if area is not group header or group footer.
 ReportSectionLoc getSectionLocation(Section s)
          Returns a structure useful only by this report for re-inserting a section.
 Formula getStartFormula()
          Returns the report's start formula; may be null.
 java.lang.String getTitle()
           
 java.util.Iterator groups()
           
 java.util.Iterator groupsReversed()
          Returns an iterator over the groups in reverse order.
 boolean hasDataSource()
           
 boolean hasFields()
          Returns true if this report contains some field anywhere.
 boolean hasGroups()
           
 boolean hasParameterFields()
          Returns true if this report contains some parameter field anywhere.
 SectionArea headers()
           
 void initializeSections()
           
 Group innermostGroup()
          Returns the last (innermost) group in the report, or null if there are no groups.
 Section insertSectionBelow(Section goBelowThis)
          Creates and returns a new section below the specified one.
 Section insertSectionBelow(Section section, Section goBelowThis)
          Inserts a (possibly newly created) section below the specified one.
 boolean isInsideGroup(Section section)
          Returns true if the specified section is contained in any group.
 boolean isOneOfAKind(Section s)
          Returns true if the specified section is the only section of its kind; that is, the only section in the collection in which it is contained.
 boolean isUsedBySomeGroup(Selectable g)
          Returns true if the specified data source column is a group column.
 SectionArea pageFooters()
           
 SectionArea pageHeaders()
           
 int pageNumber()
          Returns the current page number.
 java.util.Iterator parameters()
           
 void parametersSetManually(boolean val)
          Lets the caller tell the report to ask for parameters (val is false, the default value) or to not ask (val is true).
protected  void processResultRow()
          Processes a single data source row.
 void read(java.io.File f)
          Reads an XML file and builds the contents of this report.
 void read(org.xml.sax.InputSource in)
          Reads an XML stream using a org.xml.sax.InputSource and builds the contents of this report.
 void reinsertSection(ReportSectionLoc loc)
          Reinserts a section based on the location information previously retrieved by a call to getSectionLocation(jimm.datavision.Section).
 void reloadColumns()
          Tells this report to reload all references to column objects.
 void remove(java.lang.Object obj)
          Figure out what obj is and remove it.
 void removeAllGroups()
           
 void removeField(Field f)
           
 void removeFormula(Formula f)
           
 void removeGroup(Group g)
           
 void removeParameter(Parameter p)
           
 void removeSection(Section s)
          Removes the specified section.
 void removeSubreport(Subreport sub)
           
 void removeUserColumn(UserColumn uc)
           
protected  void resetCachedValues()
          Tells each formula that it should re-evaluate.
 int rowNumber()
          Returns the current data row number.
 void run()
          Spawns a new thread that runs the report, using the layout engine to generate output.
 void runReport()
          Runs the data source's query and hands rows to the layout engine.
 Section sectionContaining(Field f)
          Returns the section containing the specified field, or null if the field is not in the report.
 void setAuthor(java.lang.String newAuthor)
           
 void setCaseSensitiveDatabaseNames(boolean val)
          Sets the value of caseSensitiveDatabaseNames.
 void setDatabaseConnection(java.sql.Connection conn)
          Sets the database connection.
 void setDatabasePassword(java.lang.String pwd)
          Sets the database password.
 void setDataSource(DataSource newDataSource)
          Sets the data source.
 void setDescription(java.lang.String newDescription)
           
 void setLayoutEngine(LayoutEngine layoutEngine)
          Sets the layout engine to use.
 void setName(java.lang.String newName)
          Sets the name.
 void setPaperFormat(PaperFormat newPaperFormat)
           
 void setParameterXMLInput(java.io.File f)
          Remembers name of parameter XML file.
 void setParameterXMLInput(org.xml.sax.InputSource in)
          Remembers an input source and reads parameter values from it later.
 void setStartFormula(Formula newStartFormula)
           
 void setTitle(java.lang.String newTitle)
           
 java.util.Iterator subreports()
           
protected  void updateAggregates()
          Updates each aggregate field.
protected  void updateGroupCounters()
          Lets each group update its line counter.
protected  void updateGroups()
          Updates each group's value based on the current value of the column each group uses.
 java.util.Iterator userColumns()
           
 java.lang.Object value(java.lang.String labelOrId)
          Returns the value of the object (Column, Formula, Parameter, UserColumn, or SpecialField) identified by labelOrId.
 void withFieldsDo(FieldWalker f)
          Iterates over all fields in the report, passing the section to the specified FieldWalker.
 void withSectionsDo(SectionWalker s)
          Iterates over all sections in the report, passing the section to the specified SectionWalker.
protected  void writeComment(XMLWriter out)
           
protected  void writeDescription(XMLWriter out)
           
 void writeFile(java.lang.String fileName)
          Writes the contents of this report as an XML file.
protected  void writePage(XMLWriter out)
           
protected  void writeReport(XMLWriter out)
           
protected  void writeStartFormula(XMLWriter out)
           
 void writeXML(XMLWriter out)
          Writes the contents of this report as an XML file.
protected  void writeXMLDecl(XMLWriter out)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

XML_JAVA_ENCODING

public static final java.lang.String XML_JAVA_ENCODING
The string to use when reading and writing XML files. Pass it to OutputStreamWriters and InputStreamReaders.

See Also:
Constant Field Values

XML_ENCODING_ATTRIBUTE

public static final java.lang.String XML_ENCODING_ATTRIBUTE
The string to write at the top of an XML file in the XML decl.

See Also:
Constant Field Values

OUTPUT_DTD_VERSION

protected static final double OUTPUT_DTD_VERSION
See Also:
Constant Field Values

name

protected java.lang.String name

title

protected java.lang.String title

author

protected java.lang.String author

description

protected java.lang.String description

startFormula

protected Formula startFormula

dataSource

protected DataSource dataSource

formulas

protected java.util.HashMap formulas

parameters

protected java.util.TreeMap parameters

usercols

protected java.util.HashMap usercols

subreports

protected java.util.HashMap subreports

groups

protected java.util.ArrayList groups

reportHeaders

protected SectionArea reportHeaders

reportFooters

protected SectionArea reportFooters

pageHeaders

protected SectionArea pageHeaders

pageFooters

protected SectionArea pageFooters

details

protected SectionArea details

rset

protected DataCursor rset

layoutEngine

protected LayoutEngine layoutEngine

paperFormat

protected PaperFormat paperFormat

aggregateFields

protected java.util.Collection aggregateFields

databasePassword

protected java.lang.String databasePassword

askedForParameters

protected boolean askedForParameters

parametersHaveValues

protected boolean parametersHaveValues

paramsSetManually

protected boolean paramsSetManually

paramReader

protected ParameterReader paramReader

caseSensitiveDatabaseNames

protected boolean caseSensitiveDatabaseNames
Flag for Database data sources.


scripting

protected Scripting scripting

defaultField

protected Field defaultField
This field holds default format, border, and bounds values for all fields. For all format ivars, if the value of the ivar is null then the value is obtained from this default field's format.

Constructor Detail

Report

public Report()
Constructs an empty report.

Method Detail

initializeSections

public void initializeSections()

setLayoutEngine

public void setLayoutEngine(LayoutEngine layoutEngine)
Sets the layout engine to use.

Parameters:
layoutEngine - a layout engine

generateNewId

protected java.lang.Long generateNewId(java.util.Iterator iter)
Generates and returns a new unique id number. The number is one larger than the largest in a given list of Identity objects whose identifiers must be Long objects.

Parameters:
iter - an iterator over a collection if Identity objects whose identifiers must be Longs
Returns:
a Long

generateNewFormulaId

public java.lang.Long generateNewFormulaId()
Generates and returns a new unique formula id number.

Returns:
a long id

generateNewParameterId

public java.lang.Long generateNewParameterId()
Generates and returns a new unique parameter id number.

Returns:
a long id

generateNewUserColumnId

public java.lang.Long generateNewUserColumnId()
Generates and returns a new unique user column id number.

Returns:
a long id

generateNewSubreportId

public java.lang.Long generateNewSubreportId()
Generates and returns a new unique user column id number.

Returns:
a long id

findField

public Field findField(java.lang.Object id)
Given an id, returns the field that has that id. If no field with the specified id exists, returns null.

Returns:
a field, or null if no field with the specified id exists

getName

public java.lang.String getName()
Description copied from interface: Nameable
Returns the name.

Specified by:
getName in interface Nameable

setName

public void setName(java.lang.String newName)
Description copied from interface: Nameable
Sets the name.

Specified by:
setName in interface Nameable
Parameters:
newName - the new name

getTitle

public java.lang.String getTitle()

setTitle

public void setTitle(java.lang.String newTitle)

getAuthor

public java.lang.String getAuthor()

setAuthor

public void setAuthor(java.lang.String newAuthor)

getDescription

public java.lang.String getDescription()

setDescription

public void setDescription(java.lang.String newDescription)

getStartFormula

public Formula getStartFormula()
Returns the report's start formula; may be null.

Returns:
the report's start formula; may be null

setStartFormula

public void setStartFormula(Formula newStartFormula)

getScripting

public Scripting getScripting()

eval

public java.lang.Object eval(java.lang.String language,
                             java.lang.String evalString,
                             java.lang.String displayName)
                      throws org.apache.bsf.BSFException
Evaluates an evalString using language and returns the results. Called by Formula.evaluate(jimm.datavision.field.Field) after it has created the evalString.

Parameters:
language - the language to use
evalString - the string to evaluate
displayName - a name (for example, a formula name) to display with error messages
Returns:
the result
Throws:
org.apache.bsf.BSFException

value

public java.lang.Object value(java.lang.String labelOrId)
Returns the value of the object (Column, Formula, Parameter, UserColumn, or SpecialField) identified by labelOrId.

Parameters:
labelOrId - the label or id of a

getDefaultField

public Field getDefaultField()
Returns the field that holds default format, border, and bounds values for all fields. For all format ivars, if the value of the ivar is null then the value is obtained from this default field's format. If you need those values, clone them before using them.

Returns:
the default field

getDataSource

public DataSource getDataSource()

hasDataSource

public boolean hasDataSource()

setDataSource

public void setDataSource(DataSource newDataSource)
Sets the data source. Called by ReportReader.database(org.xml.sax.Attributes), ReportReader.charSepSource(org.xml.sax.Attributes), or user code.

If we already have a data source (for example, someone has called setDatabaseConnection(java.sql.Connection)), the existing data source will be stomped on. Both ReportReader.database(org.xml.sax.Attributes) and ReportReader.charSepSource(org.xml.sax.Attributes) call hasDataSource() to check first.

Parameters:
newDataSource - a new data source

setDatabaseConnection

public void setDatabaseConnection(java.sql.Connection conn)
                           throws java.sql.SQLException
Sets the database connection. If this is called before reading a report XML file, then this connection will be used instead of the connection information specified in the report.

Note: this connection will not be closed when the report finishes or even if the database object's connection is reset.

Parameters:
conn - a database connection
Throws:
java.sql.SQLException

caseSensitiveDatabaseNames

public boolean caseSensitiveDatabaseNames()
Returns the value of the caseSensitiveDatabaseNames flag. By default, this flag is true.

Returns:
true if all mixed-case names should be quoted when appropriate

setCaseSensitiveDatabaseNames

public void setCaseSensitiveDatabaseNames(boolean val)
Sets the value of caseSensitiveDatabaseNames. Normally, any database data sources' query objects quote all mixed-case names where appropriate.


reloadColumns

public void reloadColumns()
Tells this report to reload all references to column objects. Called by a database when it resets its connection.

See Also:
Database.reset(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String)

findColumn

public Column findColumn(java.lang.String id)
Given an id (a column name), returns the column that has that id. If no column with the specified id exists, returns null. Calls DataSource.findColumn(java.lang.Object).

Returns:
a column, or null if no column with the specified id exists

getPaperFormat

public PaperFormat getPaperFormat()

setPaperFormat

public void setPaperFormat(PaperFormat newPaperFormat)

add

public void add(java.lang.Object obj)
Figure out what obj is and add it.


remove

public void remove(java.lang.Object obj)
Figure out what obj is and remove it.


findParameter

public Parameter findParameter(java.lang.Object id)
Returns the parameter with the specified id or null if one is not found. Note: don't use this method if you need a parameter's value. That value is supplied by the user. Call getParameterValue(java.lang.Object) instead, which asks the user to supply the value.

Parameters:
id - the parameter id
Returns:
the parameter with that id or null if one is not found

findParameterByName

public Parameter findParameterByName(java.lang.String name)
Returns the parameter with the specified name or null if one is not found.

Parameters:
name - the name string
Returns:
the parameter with that name or null if one is not found

addParameter

public void addParameter(Parameter p)

removeParameter

public void removeParameter(Parameter p)

parameters

public java.util.Iterator parameters()

findFormula

public Formula findFormula(java.lang.Object id)
Returns the formula with the specified id or null if one is not found.

Parameters:
id - the formula id
Returns:
the formula with that id or null if one is not found

findFormulaByName

public Formula findFormulaByName(java.lang.String name)
Returns the formula with the specified name or null if one is not found.

Parameters:
name - the name string
Returns:
the formula with that name or null if one is not found

addFormula

public void addFormula(Formula f)

removeFormula

public void removeFormula(Formula f)

formulas

public java.util.Iterator formulas()

findUserColumn

public UserColumn findUserColumn(java.lang.Object id)
Returns the user column with the specified id or null if one is not found.

Parameters:
id - the user column id
Returns:
the user column with that id or null if one is not found

findUserColumnByName

public UserColumn findUserColumnByName(java.lang.String name)
Returns the user column with the specified name or null if one is not found.

Parameters:
name - the name string
Returns:
the user column with that name or null if one is not found

addUserColumn

public void addUserColumn(UserColumn uc)

removeUserColumn

public void removeUserColumn(UserColumn uc)

userColumns

public java.util.Iterator userColumns()

findSubreport

public Subreport findSubreport(java.lang.Object id)
Returns the subreport with the specified id or null if one is not found.

Parameters:
id - the subreport id
Returns:
the subreport with that id or null if one is not found

addSubreport

public void addSubreport(Subreport sub)

removeSubreport

public void removeSubreport(Subreport sub)

subreports

public java.util.Iterator subreports()

findSelectable

public Selectable findSelectable(java.lang.Object id,
                                 java.lang.String type)

getSectionArea

public SectionArea getSectionArea(int area)
Returns the section area corresponding to area, but only if area is not group header or group footer. Both of those possibly apply to multiple groups, so we can't tell which one is desired.

Parameters:
area - one of the SectionArea.* constants
Returns:
the section area corresponding to area

contains

public boolean contains(Section s)
Returns true if this report contains the specified section.

Returns:
true if this report contains the specified section

getFirstSectionByArea

public Section getFirstSectionByArea(int area)
Returns the first section in the list of the specified type. If the type is GROUP_HEADER or GROUP_FOOTER, return (a) null if there are no groups in the report or (b) the first header or footer of the first group.

Used by FieldClipping when trying to paste a field into either some other report or the same report if the original section is no longer in that report.

Returns:
a section; may be null

getSectionLocation

public ReportSectionLoc getSectionLocation(Section s)
Returns a structure useful only by this report for re-inserting a section. This structure may later be passed to reinsertSection(jimm.datavision.ReportSectionLoc). Used by DeleteSectionCommand.

We assume that s is contained within some SectionArea.

Parameters:
s - the section in question
Returns:
section location information

reinsertSection

public void reinsertSection(ReportSectionLoc loc)
Reinserts a section based on the location information previously retrieved by a call to getSectionLocation(jimm.datavision.Section). Used by DeleteSectionCommand.

Parameters:
loc - a section locatction

headers

public SectionArea headers()

footers

public SectionArea footers()

pageHeaders

public SectionArea pageHeaders()

pageFooters

public SectionArea pageFooters()

details

public SectionArea details()

addGroup

public void addGroup(Group g)

removeGroup

public void removeGroup(Group g)

removeAllGroups

public void removeAllGroups()

groups

public java.util.Iterator groups()

countGroups

public int countGroups()

hasGroups

public boolean hasGroups()

innermostGroup

public Group innermostGroup()
Returns the last (innermost) group in the report, or null if there are no groups.

Returns:
the last (innermost) group in the report, or null if there are no groups.

groupsReversed

public java.util.Iterator groupsReversed()
Returns an iterator over the groups in reverse order. Useful when displaying group footers.

Returns:
an iterator over the groups, in reverse order

removeField

public void removeField(Field f)

contains

public boolean contains(Field f)
Returns true if the specified field exists within this report.

Parameters:
f - a field
Returns:
true if the specified field exists within this report

sectionContaining

public Section sectionContaining(Field f)
Returns the section containing the specified field, or null if the field is not in the report.

Parameters:
f - a field
Returns:
the section containing the specified field, or null if the field is not in the report

containsReferenceTo

public boolean containsReferenceTo(Field f)
Returns true if the specified field exists within this report either directly (as a field) or indirectly (as a formula used by a aggregate, parameter, user column, or another formula).

Parameters:
f - a field
Returns:
true if the specified field exists within this report

containsReferenceTo

public boolean containsReferenceTo(Formula f)
Returns true if the specified formula exists within this report either directly (as a formula field) or indirectly (as a formula used by a aggregate or by another formula). This is not the same as answering the question, "Does this report contain this formula?" because we want to know if the visual portion of the report or some other formula accesses the specified formula.

Parameters:
f - a formula
Returns:
true if the specified parameter exists within some visual element of the report or within some formula

containsReferenceTo

public boolean containsReferenceTo(UserColumn uc)
Returns true if the specified user column exists within this report either directly (as a user column field) or indirectly (inside a aggregate or formula). This is not the same as answering the question, "Does this report contain this user column?" because we want to know if the visual portion of the report or some formula accesses the specified user column.

Parameters:
uc - a user column
Returns:
true if the specified parameter exists within some visual element of the report or within some formula

containsReferenceTo

public boolean containsReferenceTo(Parameter p)
Returns true if the specified parameter exists within this report either directly (as a parameter field) or indirectly (as a parameter used by a aggregate or by another parameter or in the query's where clause). This is not the same as answering the question, "Does this report contain this parameter?" because we want to know if the visual portion of the report or some formula accesses the specified parameter.

Parameters:
p - a parameter
Returns:
true if the specified parameter exists within some visual element of the report or within some formula or within the query's where clause

collectUsedParameters

protected java.util.List collectUsedParameters()
Returns a list of all the parameters actually used in the report.

Returns:
a list of parameters

findGroup

public Group findGroup(Selectable selectable)
Returns the group associated with the specified column, or null if there isn't one.

Parameters:
selectable - a selectable field
Returns:
the group associated with this column, or null if there isn't one

findGroup

public Group findGroup(Section section)
Returns the group associated with the specified section, or null if there isn't one.

Parameters:
section - a section
Returns:
the group associated with this section, or null if there isn't one

isInsideGroup

public boolean isInsideGroup(Section section)
Returns true if the specified section is contained in any group. The section may be either a header or a footer section.

Parameters:
section - a section
Returns:
true if the section is within some group

isUsedBySomeGroup

public boolean isUsedBySomeGroup(Selectable g)
Returns true if the specified data source column is a group column.

Returns:
true if the specified data source column is a group column

insertSectionBelow

public Section insertSectionBelow(Section goBelowThis)
Creates and returns a new section below the specified one.

Parameters:
goBelowThis - a section
Returns:
a new section

insertSectionBelow

public Section insertSectionBelow(Section section,
                                  Section goBelowThis)
Inserts a (possibly newly created) section below the specified one. Returns the inserted section.

Parameters:
section - the section to insert
goBelowThis - section goes below this one;
Returns:
a new section

removeSection

public void removeSection(Section s)
Removes the specified section.

Parameters:
s - a section

hasFields

public boolean hasFields()
Returns true if this report contains some field anywhere. Useful when the GUI is enabling menu items, for example.

Returns:
true if this report contains some field anywhere

hasParameterFields

public boolean hasParameterFields()
Returns true if this report contains some parameter field anywhere. This doesn't determine if any parameters have been created, but rather if any of the parameters are actually used in the report.

This method is not used by DataVision, but is useful for apps embedding DataVision that want to answer the question, "Do I have to read in a parameter XML file?"

Returns:
true if this report contains some parameter field anywhere

isOneOfAKind

public boolean isOneOfAKind(Section s)
Returns true if the specified section is the only section of its kind; that is, the only section in the collection in which it is contained.

Parameters:
s - a report section
Returns:
true if this section is a loner

setDatabasePassword

public void setDatabasePassword(java.lang.String pwd)
Sets the database password.


askForPassword

public void askForPassword(Database db)
Sets a database's user name and password. Called from Database.initializeConnection(). If we already have the password, give it to the database. If we don't, ask the user for both the user name (supplied to us) and the password and give them to the database.

Parameters:
db - the database

getParameterValue

public java.lang.Object getParameterValue(java.lang.Object paramId)
Returns the value of the specified parameter. First time at the start of each report run, asks user for parameter values.

Parameters:
paramId - a parameter id

parametersSetManually

public void parametersSetManually(boolean val)
Lets the caller tell the report to ask for parameters (val is false, the default value) or to not ask (val is true). Call this method with val = true when you set the parameters in your Java code manually.


askForParameters

protected void askForParameters()
                         throws UserCancellationException
Asks the user for parameter values. If the user cancels, we throw a UserCancellationException.

Throws:
UserCancellationException

askForDataSourceFile

protected void askForDataSourceFile()
                             throws UserCancellationException,
                                    java.io.FileNotFoundException
Asks the user for a data source file if necessary. If the user cancels, we throw a UserCancellationException.

Throws:
UserCancellationException - If the user cancels.
java.io.FileNotFoundException - If the source file can't be found.

run

public void run()
Spawns a new thread that runs the report, using the layout engine to generate output. The new thread runs the method runReport().

You may ask why this method is called run and it runs another method called runReport when the normal convention is for a thread to run a Runnable object that has a run method. The reason is purely historical. This method started non-threaded, and I don't want anyone else who relies on this method to have to change their code.

See Also:
runReport()

runReport

public void runReport()
Runs the data source's query and hands rows to the layout engine. This method is called from run(), which spawns a new thread in which this method is run. If you want to run a report, decide if you want it to run in a separate thread or not. If so, call run. If not, use this method.


getDesignFrame

protected java.awt.Frame getDesignFrame()
Returns the Frame associated with the design window for this report; may be null.

Returns:
a Frame; may be null

processResultRow

protected void processResultRow()
                         throws java.sql.SQLException
Processes a single data source row. Note that the next method of the result set has already been called.

Throws:
java.sql.SQLException

resetCachedValues

protected void resetCachedValues()
Tells each formula that it should re-evaluate.


evaluateFormulasIn

public void evaluateFormulasIn(Section s)
Evalues the formulas in the specified section. This is called by the layout engine just before the section gets output.

Parameters:
s - a section

columnValue

public java.lang.Object columnValue(Selectable selectable)
Returns the current value of the specified selectable. Only defined when running a report.

Returns:
the string or Double value of the column

pageNumber

public int pageNumber()
Returns the current page number. Asks the layout engine. Only defined when running a report.

Returns:
a page number

rowNumber

public int rowNumber()
Returns the current data row number. Only defined when running a report.


getCurrentRow

public DataCursor getCurrentRow()
Returns the current row of data. Only defined when running a report.


withSectionsDo

public void withSectionsDo(SectionWalker s)
Iterates over all sections in the report, passing the section to the specified SectionWalker. The sections are visited in the order in which they will be displayed.

Parameters:
s - a section walker

withFieldsDo

public void withFieldsDo(FieldWalker f)
Iterates over all fields in the report, passing the section to the specified FieldWalker.

Parameters:
f - a field walker

collectAggregateFields

protected void collectAggregateFields()
Collects all aggregate fields and lets each one initialize itself. Used once at the beginning of each run.


getAggregateFieldsFor

public java.util.AbstractList getAggregateFieldsFor(Field field)
Collects all aggregate fields that are aggregating the specified field. Used by the report design GUI.

Parameters:
field - a field
Returns:
a list of aggregate fields

updateAggregates

protected void updateAggregates()
Updates each aggregate field.


updateGroups

protected void updateGroups()
Updates each group's value based on the current value of the column each group uses.


updateGroupCounters

protected void updateGroupCounters()
Lets each group update its line counter.


setParameterXMLInput

public void setParameterXMLInput(java.io.File f)
Remembers name of parameter XML file.

Parameters:
f - an XML file

setParameterXMLInput

public void setParameterXMLInput(org.xml.sax.InputSource in)
Remembers an input source and reads parameter values from it later. To speicfy a URL, use InputSource("http://...").

Parameters:
in - the input source

read

public void read(java.io.File f)
          throws java.lang.Exception
Reads an XML file and builds the contents of this report. Uses a ReportReader.

Parameters:
f - a report XML file
Throws:
java.lang.Exception

read

public void read(org.xml.sax.InputSource in)
          throws java.lang.Exception
Reads an XML stream using a org.xml.sax.InputSource and builds the contents of this report. Uses a ReportReader. To specify a URL, use new InputSource("http://...").

Parameters:
in - a reader
Throws:
java.lang.Exception
See Also:
ReportReader.read(org.xml.sax.InputSource)

writeFile

public void writeFile(java.lang.String fileName)
Writes the contents of this report as an XML file.

Parameters:
fileName - a file name string

writeXML

public void writeXML(XMLWriter out)
Writes the contents of this report as an XML file.

Specified by:
writeXML in interface Writeable
Parameters:
out - an indent writer

writeXMLDecl

protected void writeXMLDecl(XMLWriter out)

writeComment

protected void writeComment(XMLWriter out)

writeReport

protected void writeReport(XMLWriter out)

writeDescription

protected void writeDescription(XMLWriter out)

writeStartFormula

protected void writeStartFormula(XMLWriter out)

writePage

protected void writePage(XMLWriter out)