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:


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()


Copyright 2001-2013 DYNAMIDE.COM. All Rights Reserved.