com.dynamide.db
Interface IDatasource

All Superinterfaces:

IDatasourceBasic

All Known Implementing Classes:

DatasourceHelper, Login, RDBDatasource, Session, SimpleDatasource

public interface IDatasource
extends IDatasourceBasic

All datasources should implement this interface, which allows them to plug into the Dynamide framework. All the Dynamide Widgets get their values from an IDatasource, so by implementing this interface, all the Dynamide Widgets are data-aware for your particular datasource implementation.

Implementations are expected to handle their own lazy initialization if desired. Since there is no open() call, the underlying data provider should be opened when getFieldValue(), next() or go() is called. Alternatively, open the underlying data during construction.

Implementations should notify all Fields by using Field.set("value", value), etc., when the underlying data changes. The Fields are registered with the Session, and will continue to hold their values until the Field.setValue() method is called. It is not necessary to notify Widgets, Pages or the Session when changing Field values, as long as the Field object reference itself is not changed.

Implementations may wish to provide the following method or constructor arguments which are not part of the interface:

• setColumnNames -- set list of columns, or update this when data are available.
• a constructor or open() method to retrieve the data. Once constructed and registered with the Session, the datasource is assumed to be on the first "row", with data available. Implementors are responsible for lazy or delayed initialization.

Field Summary

static int	AFTER Constant used in insertRow(int) to specify that the new row should come after the current row.
static int	BEFORE Constant used in insertRow(int) to specify that the new row should come before the current row.
static int	BEFORE_FIRST Constant used in go(int) to navigate to the first record.
static int	BEGIN Constant used in go(int) to navigate to the first record.
static int	END Constant used in go(int) to navigate to the last record.
static int	ROW_COUNT_NOT_ALLOWED Constant returned by getRowCount() if row counts are not supported, e.g. large SQL datasets.
static int	ROW_INDEX_UNKNOWN Constant returned by getCurrentRowIndex() if row indices are not known or are not supported.

Method Summary

void	cancel()
void	clear()
java.lang.String	dumpErrorsHTML()
java.lang.Object	get(java.lang.String what) Method to work with things like WebMacro, that automatically call Foo.get("bar") when you invoke $foo.bar if foo is of class Foo.
int	getCurrentRowIndex() The zero-based index of the current row: single-row implementations can always return 0, implementations that don't support row indices should return IDatasource.ROW_INDEX_UNKNOWN;
IDatasource	getDatasourceHelper() By default, simply return a reference to "this", since the implementing class is an instance of IDatasource.
Field	getField(java.lang.String fieldName) Maintain a list of Field objects; return the live Field when asked by this method.
Field	getField(java.lang.String fieldName, java.lang.String fieldIndex) This class can support indexed Fields, by any arbitrary String index, which will for tabular datasets, be the zero-based row index; however the index can be any valid string which could itself be a search specifier that is used by this method.
java.util.Map	getFields()
java.lang.String	getID() A unique name within the Application for this datasource, it becomes the ID by which Widgets can discover the datasource.
Property	getProperty(java.lang.String propertyName) Rather than having a complicated interface to IDatasource, specialized behaviors can be set/retrieved using setProperty/getProperty, for example, "isMultiRowEditable".
int	getRowCount() The row count of the current dataset, or IDatasource.ROW_COUNT_NOT_ALLOWED if the operation is not supported.
boolean	go(int distance) go(0) should go to the first row in the set, if supported, go(-1) should go back a row, if supported, go(1) should go forward a row if supported, go(IDatasource.END) should go to the last row in the set, leaving the last row active, that is, not after the last row, and all unsupported actions should simply be no-ops.
boolean	insertRow(int index)
boolean	isReadOnly() Updateable datasets should return false.
boolean	isRowCountAllowed() Report if calling getRowCount() will be allowed.
java.util.Iterator	iterator() Return an Iterator which knows how to properly iterate over your implementation.
void	onRowChanged() Provides notification that a seek or go operation has occured.
boolean	post() If isReadOnly() returns false, and the underlying data can be updated, return true.
void	reload()
boolean	seek(int zeroBasedIndex) Jump to the absolute zero based index.
boolean	seekBegin()
boolean	seekEnd()
void	setFieldValue(java.lang.String fieldName, java.lang.Object value) The editable Dynamide Widgets can use this to modify the underlying Fields.
boolean	setFieldValue(java.lang.String fieldName, java.lang.Object value, java.lang.String fieldIndex) Optional operation: Dynamide Widgets can use this to modify the underlying datasource if the datasource supports indexed Fields.
void	setProperty(java.lang.String name, java.lang.String value) Rather than having a complicated interface to IDatasource, specialized behaviors can be set/retrieved using setProperty/getProperty, for example, "isMultiRowEditable".

Field Detail

BEFORE_FIRST

static final int BEFORE_FIRST

Constant used in go(int) to navigate to the first record.

See Also:

Constant Field Values

BEGIN

static final int BEGIN

Constant used in go(int) to navigate to the first record.

See Also:

Constant Field Values

END

static final int END

Constant used in go(int) to navigate to the last record.

See Also:

Constant Field Values

BEFORE

static final int BEFORE

Constant used in insertRow(int) to specify that the new row should come before the current row.

See Also:

Constant Field Values

AFTER

static final int AFTER

Constant used in insertRow(int) to specify that the new row should come after the current row.

See Also:

Constant Field Values

ROW_INDEX_UNKNOWN

static final int ROW_INDEX_UNKNOWN

Constant returned by getCurrentRowIndex() if row indices are not known or are not supported.

See Also:

Constant Field Values

ROW_COUNT_NOT_ALLOWED

static final int ROW_COUNT_NOT_ALLOWED

Constant returned by getRowCount() if row counts are not supported, e.g. large SQL datasets.

See Also:

Constant Field Values

Method Detail

getDatasourceHelper

IDatasource getDatasourceHelper()

By default, simply return a reference to "this", since the implementing class is an instance of IDatasource. This method exists so that IDatasourceBasic implementations can be wrapped in an IDatasource interface.

Specified by:

getDatasourceHelper in interface IDatasourceBasic

See Also:

IDatasourceBasic

getID

java.lang.String getID()

A unique name within the Application for this datasource, it becomes the ID by which Widgets can discover the datasource.

Specified by:

getID in interface IDatasourceBasic

getField

Field getField(java.lang.String fieldName)

Maintain a list of Field objects; return the live Field when asked by this method. IDatasource supports the concept of the "current row", so that getField indexes into a tabular dataset by the fieldName of the column, for the current row. The caller gets different cell values by a) calling next() or some other navigation method, or b) calling getField(fieldName, fieldIndex) if indexed fields are supported.

Specified by:

getField in interface IDatasourceBasic

getField

Field getField(java.lang.String fieldName,
               java.lang.String fieldIndex)

This class can support indexed Fields, by any arbitrary String index, which will for tabular datasets, be the zero-based row index; however the index can be any valid string which could itself be a search specifier that is used by this method.

getFields

java.util.Map getFields()

Specified by:

getFields in interface IDatasourceBasic

Returns:

a Map of all the fields owned.

setFieldValue

void setFieldValue(java.lang.String fieldName,
                   java.lang.Object value)
                   throws DatatypeException

The editable Dynamide Widgets can use this to modify the underlying Fields. If the underlying dataset does not support updates, you may wish to implement this as a no-op.

Throws:

DatatypeException

setFieldValue

boolean setFieldValue(java.lang.String fieldName,
                      java.lang.Object value,
                      java.lang.String fieldIndex)

Optional operation: Dynamide Widgets can use this to modify the underlying datasource if the datasource supports indexed Fields. If the underlying dataset does not support indexed Fields, you can return false from the method.

get

java.lang.Object get(java.lang.String what)
                     throws java.lang.Exception

Method to work with things like WebMacro, that automatically call Foo.get("bar") when you invoke $foo.bar if foo is of class Foo. The Dynamide Session search order should be useful for most implementations: get(String) searches Property objects then Fields.

Specified by:

get in interface IDatasourceBasic

Throws:

java.lang.Exception

getProperty

Property getProperty(java.lang.String propertyName)
                     throws java.lang.Exception

Rather than having a complicated interface to IDatasource, specialized behaviors can be set/retrieved using setProperty/getProperty, for example, "isMultiRowEditable". Most implementations should also just return the Property String value from any calls to IDatasource.get(String).

Throws:

java.lang.Exception

See Also:

get(String)

setProperty

void setProperty(java.lang.String name,
                 java.lang.String value)
                 throws DatatypeException

Rather than having a complicated interface to IDatasource, specialized behaviors can be set/retrieved using setProperty/getProperty, for example, "isMultiRowEditable".

Throws:

DatatypeException

iterator

java.util.Iterator iterator()

Description copied from interface: IDatasourceBasic

Return an Iterator which knows how to properly iterate over your implementation. You can support remove(), or throw an UnsupportedOperationException. Single-row datasource would return an iterator that returned one row, then set hasNext to false. All implementations should provide one row of data, even if this row contains only empty strings for values. For single row datasets, here is a simple implementation, which can be done in an inner class:

  public class MyClass implements IDatasourceBasic{
      public class MyDatasourceIterator implements Iterator {
          private MyClass m_target;
          private int m_iterCount = 0;
          public SessionDatasourceIterator(MyClass target){
              m_target = target;
          }
          public Object next(){
              m_iterCount++;
              return m_target;
          }
          public boolean hasNext(){
              return (m_iterCount < 1);
          }
          public void remove(){
              throw new UnsupportedOperationException();
          }
      }
  }
 

Specified by:

iterator in interface IDatasourceBasic

See Also:

IDatasourceBasic.iterator()

isReadOnly

boolean isReadOnly()

Updateable datasets should return false.

post

boolean post()

If isReadOnly() returns false, and the underlying data can be updated, return true. Otherwise return false.

clear

void clear()

cancel

void cancel()

reload

void reload()
            throws java.lang.Exception

Throws:

java.lang.Exception

go

boolean go(int distance)

go(0) should go to the first row in the set, if supported, go(-1) should go back a row, if supported, go(1) should go forward a row if supported, go(IDatasource.END) should go to the last row in the set, leaving the last row active, that is, not after the last row, and all unsupported actions should simply be no-ops.

Returns:

true if navigation to a different row was achieved.

seekBegin

boolean seekBegin()

seekEnd

boolean seekEnd()

seek

boolean seek(int zeroBasedIndex)

Jump to the absolute zero based index.

onRowChanged

void onRowChanged()

Provides notification that a seek or go operation has occured.

insertRow

boolean insertRow(int index)

Parameters:

index - Is one of IDatasource.BEGIN, IDatasource.END, IDatasource.AFTER, IDatasource.BEFORE or is an absolute index the new row will occupy. For examle, if there is one row in the dataset, then insertRow(0) would insert the new row at index 0, before the current row, while insertRow(1) would place the new row at index 1, after the current row. IDatasource.AFTER would place the new row after the current row, regardless of absolute index, and IDatasource.BEFORE would place the row before the current row.

Returns:

false if operation is not supported or raises an error.

isRowCountAllowed

boolean isRowCountAllowed()

Report if calling getRowCount() will be allowed. For some datasets it may not be advisable, e.g. for large SQL datasets, to allow getRowCount(), but this method simply tells the caller whether calling getRowCount() will return meaningful data. getRowCount() may return IDatasource.ROW_COUNT_NOT_ALLOWED, but does not throw Exceptions.

Returns:

true if calling getRowCount() is allowed

getRowCount

int getRowCount()

The row count of the current dataset, or IDatasource.ROW_COUNT_NOT_ALLOWED if the operation is not supported. If not supported, be sure to return false from isRowCountAllowed().

Returns:

the current row count, or IDatasource.ROW_COUNT_NOT_ALLOWED

getCurrentRowIndex

int getCurrentRowIndex()

The zero-based index of the current row: single-row implementations can always return 0, implementations that don't support row indices should return IDatasource.ROW_INDEX_UNKNOWN;

dumpErrorsHTML

java.lang.String dumpErrorsHTML()