org.jdesktop.dataset
Class DataSet

java.lang.Object
  extended by org.jdesktop.dataset.DataSet

public class DataSet
extends java.lang.Object

A DataSet is the top-level class for managing multiple DataTables as a group, allowing explicit support for master-detail relationships. A DataSet contains one or more DataTables, one or more DataRelations, and one or more DataValues. Through the DataSet API one has a sort of unified access to all these elements in a single group. As a canonical example, a single DataSet could have DataTables for Customers, Orders, and OrderItems, and the relationships between them.

The DataSet internal structure read from a DataSet XML schema using the createFromSchema(String) method, which also supports reading from an InputStream or File. The internal structure can then be persisted back as an XML schema by retrieving its String form using getSchema() and then saving that.

Separately, all the data in a DataSet (e.g. rows in the internal DataTables) can be read (readXml(String)) or written (writeXml()).

DataSet has standard methods for adding or removing single DataTables, DataRelationTables, and DataValues. Note that these instances are automatically tracked, so if their names are changed through their own API, that name change is reflected automatically in the DataSet.

Author:
rbair
See Also:
DataTable, DataRelationTable, DataValue, DataRelation

Nested Class Summary
static class DataSet.OutputControl
          Flag used for writeXml(OutputControl) to indicate whether all rows, or just modified rows should be spit out.
 
Field Summary
protected static java.lang.String DEFAULT_NAME_PREFIX
          Prefix used by the name generator for automatically-generated DataSet names.
 
Constructor Summary
DataSet()
          Instantiates a DataSet with an automatically-generated name.
DataSet(java.lang.String name)
          Instantiates a DataSet with a specific name; the name can be useful when persisting the DataSet or when working with multiple DataSets.
 
Method Summary
 void clear()
          Requests that each DataTable in this DataSet clear itself; this is a synchronous operation since the clear operation is not anticipated to take more than a couple of milliseconds at worst.
static DataSet createFromSchema(java.io.File f)
          Deprecated. Replaced by DataSetUtility.readDataSetFromXml(Reader, String[])
static DataSet createFromSchema(java.io.InputStream is)
          Deprecated. Replaced by DataSetUtility.readDataSetFromXml(Reader, String[])
static DataSet createFromSchema(java.lang.String schema)
          Deprecated. use DataSetUtils.createFromXmlSchema instead
 DataRelation createRelation()
          Creates a new DataRelation with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.
 DataRelation createRelation(java.lang.String name)
          Creates a new, named DataRelation, and adds it to this DataSet; the table will belong to this DataSet.
 DataRelationTable createRelationTable()
          Creates a new DataRelationTable with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.
 DataRelationTable createRelationTable(java.lang.String name)
          Creates a new, named DataRelationTable, and adds it to this DataSet; the table will belong to this DataSet.
 DataTable createTable()
          Creates a new DataTable with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.
 DataTable createTable(java.lang.String name)
          Creates a new, named DataTable, and adds it to this DataSet; the table will belong to this DataSet.
 DataValue createValue()
          Creates a new DataValue with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.
 DataValue createValue(java.lang.String name)
          Creates a new, named DataValue, and adds it to this DataSet; the table will belong to this DataSet.
 void dropRelation(DataRelation relation)
          Removes a given DataRelation from this DataSet.
 void dropRelation(java.lang.String relationName)
          Removes a given DataRelation from this DataSet.
 void dropRelationTable(DataRelationTable table)
          Removes a given DataRelationTable from this DataSet.
 void dropRelationTable(java.lang.String tableName)
          Removes a given DataRelationTable from this DataSet.
 void dropTable(DataTable table)
          Removes a given DataTable from this DataSet.
 void dropTable(java.lang.String tableName)
          Removes a given DataTable from this DataSet.
 void dropValue(DataValue value)
          Removes a given DataValue from this DataSet.
 void dropValue(java.lang.String valueName)
          Removes a given DataValue from this DataSet.
 java.util.List<DataRow> filterRows(java.util.List<DataRow> rows, DataSelector ds)
          Returns a list of rows that match a given selector; convenience method.
 java.util.List<DataColumn> getColumns(java.lang.String path)
           
 java.lang.Object getElement(java.lang.String path)
          Given some path, return the proper element.
 java.lang.String getName()
          Returns the current name for the DataSet.
 DataRelation getRelation(java.lang.String relationName)
          Looks up a DataRelation in this set by name.
 java.util.List<DataRelation> getRelations()
          Retrieves a list of all DataRelation in this set.
 DataRelationTable getRelationTable(java.lang.String name)
          Looks up a DataRelationTable in this DataSet, by name.
 java.util.List<DataRow> getRows(java.lang.String path)
          TODO
 java.lang.String getSchema()
          Deprecated. Replaced by DataSetUtility.writeDataSetAsXml(Writer, DataSet)
 DataTable getTable(java.lang.String tableName)
          Looks up a DataTable in this DataSet, by name.
 java.util.List<DataTable> getTables()
          Returns a List of the DataTables in this DataSet.
 DataValue getValue(java.lang.String valueName)
          Looks up a DataValue in this set by name.
 java.util.List<DataValue> getValues()
          Retrieves a list of all DataValues in this set.
protected  boolean hasElement(java.lang.String name)
          Checks whether this DataSet has a relation, table or value by the given name.
 void load()
          Requests that each DataTable in this DataSet load itself; this is an asynchronous operation.
 void loadAndWait()
          Requests that each DataTable in this DataSet load itself; this is a synchronous operation.
static void main(java.lang.String[] args)
          Test function from command line; no arguments needed
 void readXml(java.io.File f)
          Same as readXml(String), but using a File as input source.
 void readXml(java.io.InputStream is)
          Same as readXml(String), but using an InputStream as input source.
 void readXml(java.lang.String xml)
          Loads DataSet data from an XML Document in String format; when complete, the DataSet will have been populated from the Document.
 void refresh()
          Requests that each DataTable in this DataSet refresh itself; this is an asynchronous operation.
 void refreshAndWait()
          Requests that each DataTable in this DataSet refresh itself; this is a synchronous operation.
 void save()
          Requests that each DataTable in this DataSet save itself; this is an asynchronous operation.
 void saveAndWait()
          Requests that each DataTable in this DataSet save itself; this is a synchronous operation.
 void setName(java.lang.String name)
          Assigns a new name to this DataSet.
 java.lang.String toString()
           
 java.lang.String writeXml()
          Writes out the data in this DataSet as XML, and returns this as a String; all rows are exported.
 java.lang.String writeXml(DataSet.OutputControl flags)
          Writes out the data in this DataSet as XML, and returns this as a String.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_NAME_PREFIX

protected static final java.lang.String DEFAULT_NAME_PREFIX
Prefix used by the name generator for automatically-generated DataSet names.

See Also:
Constant Field Values
Constructor Detail

DataSet

public DataSet()
Instantiates a DataSet with an automatically-generated name.


DataSet

public DataSet(java.lang.String name)
Instantiates a DataSet with a specific name; the name can be useful when persisting the DataSet or when working with multiple DataSets. See setName(String) for comments about DataSet naming.

Parameters:
name - The name for the DataSet.
Method Detail

setName

public void setName(java.lang.String name)
Assigns a new name to this DataSet. Names are not controlled for uniqueness, so the caller must take care to not use the same name for more than one DataSet. Any String that is a valid Java identifier can be used; see comments on DataSetUtils.isValidName(String)..

Parameters:
name - The new name for the DataSet.

getName

public java.lang.String getName()
Returns the current name for the DataSet.

Returns:
the current name for the DataSet.

createTable

public DataTable createTable()
Creates a new DataTable with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.

Returns:
a new DataTable assigned to this DataSet.

createTable

public DataTable createTable(java.lang.String name)
Creates a new, named DataTable, and adds it to this DataSet; the table will belong to this DataSet. If the DataSet already has a table with that name, the new, empty DataTable will take its place.

Parameters:
name - The new DataTable's name.
Returns:
a new unnamed DataTable assigned to this DataSet.

createRelationTable

public DataRelationTable createRelationTable()
Creates a new DataRelationTable with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.

Returns:
a new DataRelationTable assigned to this DataSet.

createRelationTable

public DataRelationTable createRelationTable(java.lang.String name)
Creates a new, named DataRelationTable, and adds it to this DataSet; the table will belong to this DataSet. If the DataSet already has a table with that name, the new, empty DataRelationTable will take its place.

Parameters:
name - The new DataRelationTable's name.
Returns:
a new unnamed DataRelationTable assigned to this DataSet.

createRelation

public DataRelation createRelation()
Creates a new DataRelation with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.

Returns:
a new DataRelation assigned to this DataSet.

createRelation

public DataRelation createRelation(java.lang.String name)
Creates a new, named DataRelation, and adds it to this DataSet; the table will belong to this DataSet. If the DataSet already has a table with that name, the new, empty DataRelation will take its place.

Parameters:
name - The new DataRelation's name.
Returns:
a new unnamed DataRelation assigned to this DataSet.

createValue

public DataValue createValue()
Creates a new DataValue with an automatically-generated name, and adds it to this DataSet; the table will belong to this DataSet.

Returns:
a new DataValue assigned to this DataSet.

createValue

public DataValue createValue(java.lang.String name)
Creates a new, named DataValue, and adds it to this DataSet; the table will belong to this DataSet. If the DataSet already has a table with that name, the new, empty DataValue will take its place.

Parameters:
name - The new DataValue's name.
Returns:
a new unnamed DataValue assigned to this DataSet.

dropTable

public void dropTable(DataTable table)
Removes a given DataTable from this DataSet.

Parameters:
table - The DataTable instance to remove.

dropTable

public void dropTable(java.lang.String tableName)
Removes a given DataTable from this DataSet.

Parameters:
tableName - The name of the table to remove.

dropRelationTable

public void dropRelationTable(DataRelationTable table)
Removes a given DataRelationTable from this DataSet.

Parameters:
table - The DataRelationTable instance to remove.

dropRelationTable

public void dropRelationTable(java.lang.String tableName)
Removes a given DataRelationTable from this DataSet.

Parameters:
tableName - The name of the table to remove.

dropRelation

public void dropRelation(DataRelation relation)
Removes a given DataRelation from this DataSet.

Parameters:
relation - The DataRelation instance to remove.

dropRelation

public void dropRelation(java.lang.String relationName)
Removes a given DataRelation from this DataSet.

Parameters:
relationName - The name of the relation to remove.

dropValue

public void dropValue(DataValue value)
Removes a given DataValue from this DataSet.

Parameters:
value - The DataValue instance to remove.

dropValue

public void dropValue(java.lang.String valueName)
Removes a given DataValue from this DataSet.

Parameters:
valueName - The name of the value to remove.

hasElement

protected boolean hasElement(java.lang.String name)
Checks whether this DataSet has a relation, table or value by the given name.

Parameters:
name - The name to lookup.
Returns:
true if this DataSet has a table, relation or value with that name.

getElement

public java.lang.Object getElement(java.lang.String path)
Given some path, return the proper element. Paths are:

Parameters:
path - The identifier for the element in question; see desc.
Returns:
the element in question as an Object, or null if it doesn't identify anything in this DataSet.

getRows

public java.util.List<DataRow> getRows(java.lang.String path)
TODO


filterRows

public java.util.List<DataRow> filterRows(java.util.List<DataRow> rows,
                                          DataSelector ds)
Returns a list of rows that match a given selector; convenience method.

Parameters:
rows - The rows to select from.
ds - The DataSelector with indices to filter with.
Returns:
a List of DataRows matching the given DataSelector; empty if none match.

getColumns

public java.util.List<DataColumn> getColumns(java.lang.String path)

getTable

public DataTable getTable(java.lang.String tableName)
Looks up a DataTable in this DataSet, by name.

Parameters:
tableName - The name of the table to retrieve.
Returns:
the DataTable, if found, or null, if not.

getTables

public java.util.List<DataTable> getTables()
Returns a List of the DataTables in this DataSet.

Returns:
a List of the DataTables in this DataSet; empty if no tables in this DataSet.

getRelationTable

public DataRelationTable getRelationTable(java.lang.String name)
Looks up a DataRelationTable in this DataSet, by name.

Parameters:
name - The name of the relation table to retrieve.
Returns:
the DataRelationTable, if found, or null, if not.

getValue

public DataValue getValue(java.lang.String valueName)
Looks up a DataValue in this set by name.

Parameters:
valueName - The name of the DataValue.
Returns:
the named DataValue, or null if no value with that name.

getValues

public java.util.List<DataValue> getValues()
Retrieves a list of all DataValues in this set.

Returns:
list of all DataValues in this set, empty if none assigned.

getRelation

public DataRelation getRelation(java.lang.String relationName)
Looks up a DataRelation in this set by name.

Parameters:
relationName - The name of the DataRelation.
Returns:
the named DataRelation, or null if no value with that name.

getRelations

public java.util.List<DataRelation> getRelations()
Retrieves a list of all DataRelation in this set.

Returns:
list of all DataRelation in this set, empty if none assigned.

load

public void load()
Requests that each DataTable in this DataSet load itself; this is an asynchronous operation. See DataTable.load(); tables must have been assigned a DataProvider already.


loadAndWait

public void loadAndWait()
Requests that each DataTable in this DataSet load itself; this is a synchronous operation. See DataTable.loadAndWait(); tables must have been assigned a DataProvider already.


refresh

public void refresh()
Requests that each DataTable in this DataSet refresh itself; this is an asynchronous operation. See DataTable.refresh(); tables must have been assigned a DataProvider already.


refreshAndWait

public void refreshAndWait()
Requests that each DataTable in this DataSet refresh itself; this is a synchronous operation. See DataTable.refreshAndWait(); tables must have been assigned a DataProvider already.


clear

public void clear()
Requests that each DataTable in this DataSet clear itself; this is a synchronous operation since the clear operation is not anticipated to take more than a couple of milliseconds at worst. See DataTable.clear();


save

public void save()
Requests that each DataTable in this DataSet save itself; this is an asynchronous operation. See DataTable.save(); tables must have been assigned a DataProvider already.


saveAndWait

public void saveAndWait()
Requests that each DataTable in this DataSet save itself; this is a synchronous operation. See DataTable.saveAndWait(); tables must have been assigned a DataProvider already.


createFromSchema

public static DataSet createFromSchema(java.lang.String schema)
Deprecated. use DataSetUtils.createFromXmlSchema instead


getSchema

public java.lang.String getSchema()
Deprecated. Replaced by DataSetUtility.writeDataSetAsXml(Writer, DataSet)

Construct and return a proper schema file describing the DataSet

Returns:
A schema representing this DataSet.

createFromSchema

public static DataSet createFromSchema(java.io.File f)
                                throws java.io.FileNotFoundException
Deprecated. Replaced by DataSetUtility.readDataSetFromXml(Reader, String[])

Same as createFromSchema(String), but using a File as input source.

Parameters:
f - The File to read from.
Returns:
a newly instantiated DataSet.
Throws:
java.io.FileNotFoundException

createFromSchema

public static DataSet createFromSchema(java.io.InputStream is)
Deprecated. Replaced by DataSetUtility.readDataSetFromXml(Reader, String[])

Same as createFromSchema(String), but using a InputStream as input source.

Parameters:
is - The InputStream to read from.
Returns:
a newly instantiated DataSet.

readXml

public void readXml(java.io.File f)
Same as readXml(String), but using a File as input source.

Parameters:
f - The XML Document, as a File.

readXml

public void readXml(java.io.InputStream is)
Same as readXml(String), but using an InputStream as input source.

Parameters:
is - The XML Document, as an InputStream.

readXml

public void readXml(java.lang.String xml)
Loads DataSet data from an XML Document in String format; when complete, the DataSet will have been populated from the Document.

Parameters:
xml - The XML Document, as a String.

writeXml

public java.lang.String writeXml()
Writes out the data in this DataSet as XML, and returns this as a String; all rows are exported.

Returns:
the contents of this DataSet, as XML, in a String.

writeXml

public java.lang.String writeXml(DataSet.OutputControl flags)
Writes out the data in this DataSet as XML, and returns this as a String.

Parameters:
flags - Value indicating whether all rows (OutputControl.ALL_ROWS) or only new and modified rows should be spit out.
Returns:
the contents of this DataSet, as XML, in a String.

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

main

public static void main(java.lang.String[] args)
Test function from command line; no arguments needed



Copyright © 2005 Sun Microsystems All Rights Reserved.