DataSetBuilder

java.lang.Object
- org.das2.qds.util.DataSetBuilder

```
public class DataSetBuilder
extends java.lang.Object
```
allows dataset of unknown length to be built. Presently, this only builds QUBES, but should allow for geometry changes. TODO: consider using WritableDataSet interface. The guessRecCount parameter is the initial number of allocated records, and is also the extension when this number of records is passed. The final physical dataset size is not affected by this, because the data is copied.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`DataSetBuilder.DataSetResolver` this was introduced to avoid properties where BUNDLE_1 would temporarily hold the name.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`PROP_VALIDMAX`
`static java.lang.String`	`PROP_VALIDMIN`
`static java.lang.String`	`UNRESOLVED_PROP_QDATASET`
`protected double`	`validMax`
`protected double`	`validMin`

Constructor Summary

Constructors
Constructor and Description
`DataSetBuilder(int rank)` Create a new builder for a rank 0 dataset.
`DataSetBuilder(int rank, int guessRecCount)` Create a new builder for a rank 1 dataset.
`DataSetBuilder(int rank, int guessRecCount, int dim1)` Create a new builder for a rank 2 dataset.
`DataSetBuilder(int rank, int guessRecCount, int dim1, int dim2)` Create a new builder for a rank 3 dataset.
`DataSetBuilder(int rank, int guessRecCount, int dim1, int dim2, int dim3)` Create a new builder for a rank 4 dataset.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addPropertyChangeListener(java.beans.PropertyChangeListener l)` Adds a PropertyChangeListener to the listener list.
`DDataSet`	`getDataSet()` returns the result dataset, concatenating all the datasets it has built thus far, including the partial record.
`double`	`getFillValue()` Getter for property fillValue.
`int`	`getLength()` return the number of records added to the builder.
`java.util.Map<java.lang.String,java.lang.Object>`	`getProperties()` get a map of all the properties set thus far.
`int`	`getRecCount()` return the number of records accepted into this builder, and the length of the dataset if getDataSet is called.
`int`	`getRecordElements()` return the number of elements in each record.
`Units`	`getUnits(int i)` get the units for the column.
`double`	`getValidMax()`
`double`	`getValidMin()`
`double`	`getValue(int index0)` for index0==-1, return the last value entered into the rank 1 dataset.
`void`	`nextRecord()` This must be called each time a record is complete.
`void`	`nextRecord(Datum v)` add the double to the rank 1 builder.
`void`	`nextRecord(DatumVector v)` Use the DatumVector to fill the record.
`void`	`nextRecord(double v)` add the double to the rank 1 builder.
`void`	`nextRecord(double[] values)` In one step, specify all the values of the record and advance the counter.
`void`	`nextRecord(java.lang.Object... values)` In one step, specify all the values of the record and advance the counter.
`void`	`nextRecord(QDataSet v)` rank 0 datasets can be used to build the rank 1 datasets
`void`	`nextRecord(java.lang.String s)` add the string to the rank 1 builder, which will be parsed internally.
`void`	`nextRecords(QDataSet ds)` add each of the records of ds to the builder.
`void`	`putProperty(java.lang.String string, java.lang.Object o)` add the property to the dataset
`void`	`putUnresolvedProperty(java.lang.String type, java.lang.String pname, java.lang.String svalue)` mark the property as unresolved, for reference later.
`void`	`putValue(int index0, Datum d)` insert a value into the builder.
`void`	`putValue(int index0, double d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, Datum d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, double d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, int index2, Datum d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, int index2, double d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, int index2, int index3, Datum d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, int index2, int index3, double d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, int index2, int index3, QDataSet d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, int index2, QDataSet d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, QDataSet d)` insert a value into the builder.
`void`	`putValue(int index0, int index1, java.lang.String s)` insert a value into the builder, parsing the string with the column units.
`void`	`putValue(int index0, QDataSet d)` insert a value into the builder.
`void`	`putValue(int index0, java.lang.String s)` insert a value into the builder, parsing the string with the units.
`void`	`putValues(int index0, QDataSet values, int count)` copy the elements from one DDataSet into the builder (which can be done with a system call), ignoring dataset geometry.
`int`	`rank()` return the rank of the dataset we are building.
`void`	`removePropertyChangeListener(java.beans.PropertyChangeListener l)` Removes a PropertyChangeListener from the listener list.
`void`	`resolveProperty(java.lang.String svalue, java.lang.Object value)` we now know the value, so resolve any unresolved properties containing the string representation.
`void`	`setDataSetResolver(DataSetBuilder.DataSetResolver dataSetResolver)` add dataset resolved.
`void`	`setFillValue(double fillValue)` Setter for property fillValue.
`void`	`setLabel(int i, java.lang.String label)` set the label (short, descriptive label for human consumption) for the column, for rank 2 bundle datasets.
`void`	`setName(int i, java.lang.String name)` set the name (valid Jython identifier) for the column.
`void`	`setUnits(int i, Units u)` set the units for column i.
`void`	`setUnits(Units u)` set the units for the dataset.
`void`	`setValidMax(double validMax)` set the valid max property.
`void`	`setValidMin(double validMin)`
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - UNRESOLVED_PROP_QDATASET
```
public static final java.lang.String UNRESOLVED_PROP_QDATASET
```
    See Also:
    
    Constant Field Values
  - validMin
```
protected double validMin
```
  - PROP_VALIDMIN
```
public static final java.lang.String PROP_VALIDMIN
```
    See Also:
    
    Constant Field Values
  - validMax
```
protected double validMax
```
  - PROP_VALIDMAX
```
public static final java.lang.String PROP_VALIDMAX
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - DataSetBuilder
```
public DataSetBuilder(int rank)
```
    Create a new builder for a rank 0 dataset.
    
    Parameters:
    
    rank - the number of indeces of the result dataset.
  - DataSetBuilder
```
public DataSetBuilder(int rank,
                      int guessRecCount)
```
    Create a new builder for a rank 1 dataset. guessRecCount is the guess of dim0 size. Bad guesses will simply result in an extra array copy.
    
    Parameters:
    
    rank - must be 1.
    
    guessRecCount - initial allocation for the first dimension.
  - DataSetBuilder
```
public DataSetBuilder(int rank,
                      int guessRecCount,
                      int dim1)
```
    Create a new builder for a rank 2 dataset. guessRecCount is the guess of dim0 size. Bad guesses will simply result in an extra array copy.
    
    Parameters:
    
    rank - must be 2.
    
    guessRecCount - initial allocation for the first dimension.
    
    dim1 - fixed size of the second index.
  - DataSetBuilder
```
public DataSetBuilder(int rank,
                      int guessRecCount,
                      int dim1,
                      int dim2)
```
    Create a new builder for a rank 3 dataset. guessRecCount is the guess of dim0 size. Bad guesses will simply result in an extra array copy.
    
    Parameters:
    
    rank - must be 3.
    
    guessRecCount - initial allocation for the first dimension.
    
    dim1 - fixed size of the second index.
    
    dim2 - fixed size of the third index.
  - DataSetBuilder
```
public DataSetBuilder(int rank,
                      int guessRecCount,
                      int dim1,
                      int dim2,
                      int dim3)
```
    Create a new builder for a rank 4 dataset. guessRecCount is the guess of dim0 size. Bad guesses will simply result in an extra array copy.
    
    Parameters:
    
    rank - must be 4.
    
    guessRecCount - initial allocation for the first dimension.
    
    dim1 - fixed size of the second index.
    
    dim2 - fixed size of the third index.
    
    dim3 - fixed size of the fourth index.
- Method Detail
  - getValue
```
public double getValue(int index0)
```
    for index0==-1, return the last value entered into the rank 1 dataset.
    
    Parameters:
    
    index0 -
    
    Returns:
    
    Throws:
    
    java.lang.IllegalArgumentException - if the index is not -1
    
    java.lang.IllegalArgumentException - if nothing is yet written to the builder.
  - putValue
```
public void putValue(int index0,
                     double d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     double d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     int index2,
                     double d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    index2 - the third index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     int index2,
                     int index3,
                     double d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    index2 - the third index
    
    index3 - the third index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     Datum d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     Datum d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     int index2,
                     Datum d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    index2 - the third index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     int index2,
                     int index3,
                     Datum d)
```
    insert a value into the builder.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    index2 - the third index
    
    index3 - the fourth index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     QDataSet d)
```
    insert a value into the builder. Note these do Units checking and are therefore less efficient
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     QDataSet d)
```
    insert a value into the builder. Note these do Units checking and are therefore less efficient
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    d - the rank 0 dataset value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     int index2,
                     QDataSet d)
```
    insert a value into the builder. Note these do Units checking and are therefore less efficient
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    index2 - the third index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     int index2,
                     int index3,
                     QDataSet d)
```
    insert a value into the builder. Note these do Units checking and are therefore less efficient
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    index2 - the third index
    
    index3 - the fourth index
    
    d - the value to insert.
  - putValue
```
public void putValue(int index0,
                     java.lang.String s)
              throws java.text.ParseException
```
    insert a value into the builder, parsing the string with the units.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    s - the a string representation of the value parse and insert.
    
    Throws:
    
    java.text.ParseException
    
    Since:
    
    2018-05-28
    
    See Also:
    
    for the logic interpreting Strings.
  - putValue
```
public void putValue(int index0,
                     int index1,
                     java.lang.String s)
              throws java.text.ParseException
```
    insert a value into the builder, parsing the string with the column units.
    
    Parameters:
    
    index0 - The index to insert the data, or if -1, ignore and nextRecord() should be used.
    
    index1 - the second index
    
    s - the a string representation of the value parse and insert.
    
    Throws:
    
    java.text.ParseException
    
    See Also:
    
    for the logic interpreting Strings.
  - putValues
```
public void putValues(int index0,
                      QDataSet values,
                      int count)
```
    copy the elements from one DDataSet into the builder (which can be done with a system call), ignoring dataset geometry. TODO: since the element count allows for putting multiple records in at once, an index out of bounds may occur after the last record of current is written. This should only be used to insert one record (with multiple values) at a time. Note this does not increment the current index, and nextRecord must be called to move to the next index.
    
    Parameters:
    
    index0 - The index to put the values, or -1 for the current position.
    
    values - rank 1 dataset.
    
    count - the number of elements to copy
    
    See Also:
    
    to insert multiple records at once.
  - nextRecord
```
public void nextRecord()
```
    This must be called each time a record is complete. Note this currently advances to the next record and at this point the next record exists. In other words, the last call to nextRecord is not required. This logic may change, so that any fields written would be dropped unless nextRecord is called to commit the record. When -1 is used for the indexes of the streaming dimension, then this will increment the internal counter. TODO: Check for unspecified entries.
    
    See Also:
    
    which inserts all values at once.
  - nextRecord
```
public void nextRecord(double[] values)
```
    In one step, specify all the values of the record and advance the counter. This is intended to reduce the number of lines needed in scripts, and to support Jython where a double array would not be cast to an Object array. Also, columns 1..N-1 are declared dependent on column 0, when column 0 is UT times.
    
    Parameters:
    
    values - the record values.
    
    See Also:
    
    nextRecord(java.lang.Object...)
  - nextRecords
```
public void nextRecords(QDataSet ds)
```
    add each of the records of ds to the builder. This is somewhat equivalent to:
```
 
 for d in ds: dsb.nextRecord(d)
 
 
```
    (Note the above only works when ds is rank 1.) Though this is equivalent, this is provided because a future implementation may peek at the dataset to transfer data more efficiently.
    Parameters:
    
    ds - dataset with rank N, where N is the rank of this builder.
  - nextRecord
```
public void nextRecord(java.lang.Object... values)
```
    In one step, specify all the values of the record and advance the counter. This is intended to reduce the number of lines needed in scripts. In Jython:
    dsb= DataSetBuilder(2,100,2) dsb.nextRecord( [ '2014-001T00:00', 20. ] ) dsb.nextRecord( [ '2014-002T00:00', 21. ] ) dsb.nextRecord( [ '2014-003T00:00', 21.4 ] ) dsb.nextRecord( [ '2014-004T00:00', 19.7 ] ) ds= dsb.getDataSet()
    Also, columns 1..N-1 are declared dependent on column 0, when column 0 is UT times. Note an events record is also supported, with [ tstart, tstop, Color, msg ]
    Parameters:
    
    values - the record values, in an String, Datum, Rank 0 QDataSet, or Number.
  - nextRecord
```
public void nextRecord(DatumVector v)
```
    Use the DatumVector to fill the record. DatumVectors can have just one unit.
    
    Parameters:
    
    v -
  - nextRecord
```
public void nextRecord(QDataSet v)
```
    rank 0 datasets can be used to build the rank 1 datasets
    
    Parameters:
    
    v - rank 0 or rank 1 dataset
  - nextRecord
```
public void nextRecord(double v)
```
    add the double to the rank 1 builder.
    
    Parameters:
    
    v - the value
  - nextRecord
```
public void nextRecord(java.lang.String s)
```
    add the string to the rank 1 builder, which will be parsed internally.
    
    Parameters:
    
    s -
    
    Throws:
    
    java.lang.IllegalArgumentException - if the string cannot be parsed.
  - nextRecord
```
public void nextRecord(Datum v)
```
    add the double to the rank 1 builder.
    
    Parameters:
    
    v - the value
  - getLength
```
public int getLength()
```
    return the number of records added to the builder.
    
    Returns:
    
    the number of records added to the builder.
  - getRecordElements
```
public int getRecordElements()
```
    return the number of elements in each record.
    
    Returns:
    
    the number of elements in each record.
  - getDataSet
```
public DDataSet getDataSet()
```
    returns the result dataset, concatenating all the datasets it has built thus far, including the partial record. See https://sourceforge.net/p/autoplot/bugs/1469/ which considers if the partial record should be included. Clients should always call nextRecord on all completed records in case the logic changes. See also the AsciiParser, which has special code for handling the partial record.
    
    Returns:
    
    the result dataset
  - putProperty
```
public void putProperty(java.lang.String string,
                        java.lang.Object o)
```
    add the property to the dataset
    
    Parameters:
    
    string - name like QDataSet.UNITS
    
    o - the value
  - putUnresolvedProperty
```
public void putUnresolvedProperty(java.lang.String type,
                                  java.lang.String pname,
                                  java.lang.String svalue)
```
    mark the property as unresolved, for reference later. This was added for the QStream reader, which doesn't resolve
    
    Parameters:
    
    type - the property type, if qdataset this is resolved with dataSetResolver.
    
    pname - the property name ("gain")
    
    svalue - the arbitrary reference ("gain_04")
  - resolveProperty
```
public void resolveProperty(java.lang.String svalue,
                            java.lang.Object value)
```
    we now know the value, so resolve any unresolved properties containing the string representation. Note the entry is left in the unresolved properties.
    
    Parameters:
    
    svalue - the string reference
    
    value - the object value
  - setUnits
```
public void setUnits(Units u)
```
    set the units for the dataset.
    
    Parameters:
    
    u -
  - setUnits
```
public void setUnits(int i,
                     Units u)
```
    set the units for column i. This is only used with rank 2 (2-index) datasets.
    
    Parameters:
    
    i - the column number
    
    u - the units for the column
  - getUnits
```
public Units getUnits(int i)
```
    get the units for the column.
    
    Parameters:
    
    i -
    
    Returns:
    
    the units or null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the bundle has not been initialized.
    
    java.lang.IllegalArgumentException - if the rank
  - setLabel
```
public void setLabel(int i,
                     java.lang.String label)
```
    set the label (short, descriptive label for human consumption) for the column, for rank 2 bundle datasets.
    
    Parameters:
    
    i - the column number
    
    label - the label for the column
  - setName
```
public void setName(int i,
                    java.lang.String name)
```
    set the name (valid Jython identifier) for the column.
    
    Parameters:
    
    i - the column number
    
    name - the name (valid Jython identifier) for the column.
  - getProperties
```
public java.util.Map<java.lang.String,java.lang.Object> getProperties()
```
    get a map of all the properties set thus far.
    
    Returns:
  - addPropertyChangeListener
```
public void addPropertyChangeListener(java.beans.PropertyChangeListener l)
```
    Adds a PropertyChangeListener to the listener list.
    
    Parameters:
    
    l - The listener to add.
  - removePropertyChangeListener
```
public void removePropertyChangeListener(java.beans.PropertyChangeListener l)
```
    Removes a PropertyChangeListener from the listener list.
    
    Parameters:
    
    l - The listener to remove.
  - getFillValue
```
public double getFillValue()
```
    Getter for property fillValue.
    
    Returns:
    
    Value of property fillValue.
  - setFillValue
```
public void setFillValue(double fillValue)
```
    Setter for property fillValue.
    
    Parameters:
    
    fillValue - New value of property fillValue.
  - getValidMin
```
public double getValidMin()
```
  - setValidMin
```
public void setValidMin(double validMin)
```
  - getValidMax
```
public double getValidMax()
```
  - setValidMax
```
public void setValidMax(double validMax)
```
    set the valid max property.
    
    Parameters:
    
    validMax -
  - getRecCount
```
public int getRecCount()
```
    return the number of records accepted into this builder, and the length of the dataset if getDataSet is called.
    
    Returns:
    
    the number of records accepted into this builder
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - rank
```
public int rank()
```
    return the rank of the dataset we are building.
    
    Returns:
    
    the rank of the dataset we are building
  - setDataSetResolver
```
public void setDataSetResolver(DataSetBuilder.DataSetResolver dataSetResolver)
```
    add dataset resolved.
    
    Parameters:
    
    dataSetResolver -

Class DataSetBuilder

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNRESOLVED_PROP_QDATASET

validMin

PROP_VALIDMIN

validMax

PROP_VALIDMAX

Constructor Detail

DataSetBuilder

DataSetBuilder

DataSetBuilder

DataSetBuilder

DataSetBuilder

Method Detail

getValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValue

putValues

nextRecord

nextRecord

nextRecords

nextRecord

nextRecord

nextRecord

nextRecord

nextRecord

nextRecord

getLength

getRecordElements

getDataSet

putProperty

putUnresolvedProperty

resolveProperty

setUnits

setUnits

getUnits

setLabel

setName

getProperties

addPropertyChangeListener

removePropertyChangeListener

getFillValue

setFillValue

getValidMin

setValidMin

getValidMax

setValidMax

getRecCount

toString

rank

setDataSetResolver