jimm.datavision.source
Class DataSource

java.lang.Object
  jimm.datavision.source.DataSource

All Implemented Interfaces:

Writeable

Direct Known Subclasses:

CharSepSource, Database, MockDataSource, NCDatabase, ObjectSource

public abstract class DataSource
extends java.lang.Object
implements Writeable

An abstract data source.

Author:

Jim Menard, jimm@io.com

See Also:

Column, Table, Query

Field Summary

protected java.lang.String	metadataURL
protected Query	query
protected Report	report

Constructor Summary

DataSource(Report r, Query q)

Method Summary

void	addColumn(Column col) Called from ReportReader.column to add a column to a data source.
boolean	alreadyUsedSourceFile() Returns true if this data source uses a file to retrieve data and and has already done so.
abstract boolean	areRecordsSelectable() Used to enable/disable the "Select Records" menu item.
abstract boolean	areRecordsSortable() Used to enable/disable the "Sort By" menu item.
abstract boolean	canGroupRecords() Used to enable/disable the "Group By" menu item.
abstract boolean	canJoinTables() Used to enable/disable the "Table Linker" menu item.
boolean	canRunReports() Used to enable/disable the "Run" and "Export" menu items.
abstract java.util.Iterator	columns() Returns an iterator over all columns.
java.util.Iterator	columnsInTablesUsedInReport() Returns an iterator over all the columns in only the tables used by the report, or over all columns if this data source does not have tables.
boolean	containsReferenceTo(Parameter p) Returns true if the specified parameter exists within this data source's query.
protected abstract void	doWriteXML(XMLWriter out)
abstract DataCursor	execute()
abstract Column	findColumn(java.lang.Object id) Given an id, returns the column that has that id.
Query	getQuery()
Report	getReport()
java.lang.String	getSourceFile() Gets the path to a data source file.
int	indexOfSelectable(Selectable sel) Returns the index of the specified selectable.
abstract boolean	isConnectionEditable() Used to enable/disable the "Connection" menu item.
abstract boolean	isSQLGenerated() Used to enable/disable the "SQL Query Text" menu item.
boolean	needsSourceFile() Returns true if this data source uses a file to retrieve data and does not yet have one.
void	readMetadataFrom(java.lang.String urlString) Reads metadata from a URL.
void	reloadColumns() Called from Report.reloadColumns/code>, this method gives the data source a chance to tell its ancillary objects (such as the query) to reload column objects.
void	removeSort(Selectable s)
void	reuseSourceFile() Tells this data source to re-use (perhaps re-open) the current data source file.
void	setSourceFile(java.lang.String filePath) Accepts the path to a data source file.
abstract java.util.Iterator	tables() Returns an iterator over all tables, or null if the data source does not have tables (for example, a character-separated file data source).
abstract java.util.Iterator	tablesUsedInReport() Returns an iterator over all tables actually used in the report, or null if the data source does not have tables (for example, a character-separated file data source).
boolean	usesSourceFile() Returns true if this data source uses a file to retrieve data.
void	writeXML(XMLWriter out) Writes this data source and its query as an XML tag.

Methods inherited from class java.lang.Object

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

Field Detail

report

protected Report report

query

protected Query query

metadataURL

protected java.lang.String metadataURL

Constructor Detail

DataSource

public DataSource(Report r,
                  Query q)

Method Detail

canJoinTables

public abstract boolean canJoinTables()

Used to enable/disable the "Table Linker" menu item.

Returns:

true if the "Table Linker" menu item should be enabled.

isSQLGenerated

public abstract boolean isSQLGenerated()

Used to enable/disable the "SQL Query Text" menu item.

Returns:

true if the "SQL Query Text" menu item should be enabled.

isConnectionEditable

public abstract boolean isConnectionEditable()

Used to enable/disable the "Connection" menu item.

Returns:

true if the "Connection" menu item should be enabled.

areRecordsSelectable

public abstract boolean areRecordsSelectable()

Used to enable/disable the "Select Records" menu item.

Returns:

true if the "Select Records" menu item should be enabled.

areRecordsSortable

public abstract boolean areRecordsSortable()

Used to enable/disable the "Sort By" menu item.

Returns:

true if the "Sort By" menu item should be enabled.

canGroupRecords

public abstract boolean canGroupRecords()

Used to enable/disable the "Group By" menu item.

Returns:

true if the "Group By" menu item should be enabled.

canRunReports

public boolean canRunReports()

Used to enable/disable the "Run" and "Export" menu items. Most data sources will enable these, of course.

Returns:

true if the "Run" and "Export" menu items should be enabled.

usesSourceFile

public boolean usesSourceFile()

Returns true if this data source uses a file to retrieve data. The default implementation returns false.

Returns:

true if this data source uses a file to retrieve data

needsSourceFile

public boolean needsSourceFile()

Returns true if this data source uses a file to retrieve data and does not yet have one. The default implementation returns false.

Returns:

true if this data source uses a file to retrieve data and doesn't yet have one

alreadyUsedSourceFile

public boolean alreadyUsedSourceFile()

Returns true if this data source uses a file to retrieve data and and has already done so. The default implementation returns false.

Returns:

true if this data source uses a file to retrieve data

setSourceFile

public void setSourceFile(java.lang.String filePath)
                   throws java.io.FileNotFoundException

Accepts the path to a data source file. The default implementation does nothing.

Parameters:

filePath - the full path to a file

Throws:

java.io.FileNotFoundException

getSourceFile

public java.lang.String getSourceFile()

Gets the path to a data source file. The default implementation returns null.

Returns:

The full path to a file

reuseSourceFile

public void reuseSourceFile()
                     throws java.io.FileNotFoundException

Tells this data source to re-use (perhaps re-open) the current data source file. The default implementation does nothing.

Throws:

java.io.FileNotFoundException

getReport

public Report getReport()

getQuery

public Query getQuery()

execute

public abstract DataCursor execute()
                            throws java.lang.Exception

Throws:

java.lang.Exception

addColumn

public void addColumn(Column col)

Called from ReportReader.column to add a column to a data source.

The default implementation does nothing.

Parameters:

col - a column

reloadColumns

public void reloadColumns()

Called from Report.reloadColumns/code>, this method gives the data source a chance to tell its ancillary objects (such as the query) to reload column objects.

This is necessary, for example, after a SQL database data source has reloaded all of its table and column information. The old column objects no longer exist. New ones (with the same ids, we assume) have taken their place.

readMetadataFrom

public void readMetadataFrom(java.lang.String urlString)
                      throws java.lang.Exception

Reads metadata from a URL. We save the URL string so we can write it back out when we write to XML.

Parameters:

urlString - where to get the metadata

Throws:

java.lang.Exception

See Also:

MetadataReader

findColumn

public abstract Column findColumn(java.lang.Object id)

Given an id, returns the column that has that id. If no column with the specified id exists, returns null.

Returns:

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

indexOfSelectable

public int indexOfSelectable(Selectable sel)

Returns the index of the specified selectable.

Parameters:

sel - a selectable

tables

public abstract java.util.Iterator tables()

Returns an iterator over all tables, or null if the data source does not have tables (for example, a character-separated file data source).

Returns:

a possibly null iterator over all tables

tablesUsedInReport

public abstract java.util.Iterator tablesUsedInReport()

Returns an iterator over all tables actually used in the report, or null if the data source does not have tables (for example, a character-separated file data source).

Returns:

a possibly null iterator over all tables used in the report

columns

public abstract java.util.Iterator columns()

Returns an iterator over all columns.

Returns:

an iterator over all columns

columnsInTablesUsedInReport

public java.util.Iterator columnsInTablesUsedInReport()

Returns an iterator over all the columns in only the tables used by the report, or over all columns if this data source does not have tables.

Returns:

an iterator over all columns in only tables used by the report, or over all columns if this data source does not have tables

removeSort

public void removeSort(Selectable s)

containsReferenceTo

public boolean containsReferenceTo(Parameter p)

Returns true if the specified parameter exists within this data source's query.

Parameters:

p - a parameter

Returns:

true if the specified parameter exists within the query

See Also:

Query.containsReferenceTo(jimm.datavision.Parameter)

writeXML

public void writeXML(XMLWriter out)

Writes this data source and its query as an XML tag.

Specified by:

writeXML in interface Writeable

Parameters:

out - a writer that knows how to write XML

doWriteXML

protected abstract void doWriteXML(XMLWriter out)