jimm.datavision.source
Class DataSource

java.lang.Object
  extended by 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)