com.isomorphic.datasource
Class DataSource

java.lang.Object
  |
  +--com.isomorphic.base.Base
        |
        +--com.isomorphic.datasource.DataSource

All Implemented Interfaces:

IToJSON, com.isomorphic.datasource.IType

public class DataSource

extends com.isomorphic.base.Base

implements com.isomorphic.datasource.IType, IToJSON

A DataSource is metadata that provides a high-level, implementation independant description of a set of permanently stored objects that will be manipulated within a SmartClient application.

The server-side DataSource object supports declarative validation, XPath-based mapping of DataSource fields to Java Objects and XML structures, and dynamic instantiation from XML. See the client reference for the client-side capabilities of DataSource objects.

Field Summary

static java.lang.String	OP_ADD Constant specifying the add operation.
static java.lang.String	OP_CUSTOM Constant specifying a custom operation.
static java.lang.String	OP_FETCH Constant specifying the fetch operation.
static java.lang.String	OP_REMOVE Constant specifying the remove operation.
static java.lang.String	OP_UPDATE Constant specifying the update operation.
static java.lang.String	OP_VALIDATE Constant specifying the validate operation.

Method Summary

static DataSource	fromXML(org.w3c.dom.Document doc) Instantiates a DataSource from an XML Document - the documentElement of this document is expected to contain the DataSource definition.
static DataSource	fromXML(org.w3c.dom.Element elem) Instantiates a DataSource from an XML Element
static DataSource	fromXML(java.io.Reader reader) Instantiates a DataSource from XML using a Reader
static DataSource	fromXML(java.lang.String xml) Instantiates a DataSource from a String of XML
DSField	getField(java.lang.String fieldName) Returns the field definition for the specified field.
java.util.List	getFieldNames() Returns the list of field names in the DataSource as a List of strings.
java.util.Map	getProperties(java.lang.Object obj) Takes a bean/Element/Map and for all fields on this DataSource that specify a valueXPath, applies the xpath to the object using the Jakarta JXPath library.
java.lang.String	getRecordXPath() For an XML DataSource, returns the XPath expression used to retrieve the set of XML elements that constitute the records of this DataSource.
static boolean	isModificationOperation(java.lang.String operationType) Convenience method that returns true for operations that modify data and false for those that do not.
void	setProperties(java.util.Map properties, java.lang.Object target) Takes a Map of fieldName -> value (properties argument) and for all fields that specify a valueXPath, applies the value to the target object via xpath using the Jakarta JXPath library.
ErrorReport	validate(java.util.Map data, boolean reportMissingRequiredFields) Takes a Map of fieldName -> value (data argument) and validates the data using the validators specified on this dataSource.

Methods inherited from interface com.isomorphic.js.IToJSON

toJSON

Field Detail

OP_FETCH

public static final java.lang.String OP_FETCH

Constant specifying the fetch operation. The fetch operation typically provides a set of criteria and expects a set of records as a response.

OP_ADD

public static final java.lang.String OP_ADD

Constant specifying the add operation. The add operation is a request to add a set of records to a whatever backing store is used as the datasource.

OP_REMOVE

public static final java.lang.String OP_REMOVE

Constant specifying the remove operation. The remove operation is a request to remove a set of records from whatever backing store is used as the datasource.

OP_UPDATE

public static final java.lang.String OP_UPDATE

Constant specifying the update operation. The update operation typically provides a set of criteria and new values for certain fields and expects that records matching the provided criteria will be updated with the new values.

OP_CUSTOM

public static final java.lang.String OP_CUSTOM

Constant specifying a custom operation. ISC components do not send operations of this type. It is reserved for use by custom UI components or custom DataSources.

OP_VALIDATE

public static final java.lang.String OP_VALIDATE

Constant specifying the validate operation.

Method Detail

fromXML

public static DataSource fromXML(org.w3c.dom.Element elem)
                          throws java.lang.Exception

Instantiates a DataSource from an XML Element

Parameters:

elem - XML Element containing the DataSource definition

Returns:

an instance of DataSource

Throws:

java.lang.Exception - if an error occurs during DataSource instantiation

fromXML

public static DataSource fromXML(org.w3c.dom.Document doc)
                          throws java.lang.Exception

Instantiates a DataSource from an XML Document - the documentElement of this document is expected to contain the DataSource definition.

Parameters:

doc - XML Document containing the DataSource definition

Returns:

an instance of DataSource

Throws:

java.lang.Exception - if an error occurs during DataSource instantiation

fromXML

public static DataSource fromXML(java.lang.String xml)
                          throws java.lang.Exception

Instantiates a DataSource from a String of XML

Parameters:

xml - XML string containing the DataSource definition

Returns:

an instance of DataSource

Throws:

java.lang.Exception - if an error occurs during DataSource instantiation

fromXML

public static DataSource fromXML(java.io.Reader reader)
                          throws java.lang.Exception

Instantiates a DataSource from XML using a Reader

Parameters:

reader - Reader supplying XML containing the DataSource definition

Returns:

an instance of DataSource

Throws:

java.lang.Exception - if an error occurs during DataSource instantiation

getFieldNames

public java.util.List getFieldNames()

Returns the list of field names in the DataSource as a List of strings.

Returns:

the list of field names in the DataSource as a List of strings

getField

public DSField getField(java.lang.String fieldName)

Returns the field definition for the specified field.

Parameters:

fieldName - the name of the field whose definition you want

Returns:

the field definition for the specified field

See Also:

DSField

getRecordXPath

public java.lang.String getRecordXPath()

For an XML DataSource, returns the XPath expression used to retrieve the set of XML elements that constitute the records of this DataSource.

For example, an "ItemSearch" might return metadata along with the set of <Item> elements that one might want to display in a grid. The XPath expression to retrieve just the <Item> elements in this case might be "//Item", which would select all <Item> elements anywhere in the returned document.

Returns:

the XPath expression

isModificationOperation

public static boolean isModificationOperation(java.lang.String operationType)

Convenience method that returns true for operations that modify data and false for those that do not.

Returns:

true if operationType is one of "add", "remove" or "update" and false otherwise.

setProperties

public void setProperties(java.util.Map properties,
                          java.lang.Object target)

Takes a Map of fieldName -> value (properties argument) and for all fields that specify a valueXPath, applies the value to the target object via xpath using the Jakarta JXPath library. If no valueXPath is specified, this method attempts to treat the target as a bean for that value. Values specified for fieldNames that are not declared in the datasource on which this method is being called are discarded.

Parameters:

properties - Map of DataSource fieldName -> value

target - Target object to which the values are to be applied

getProperties

public java.util.Map getProperties(java.lang.Object obj)

Takes a bean/Element/Map and for all fields on this DataSource that specify a valueXPath, applies the xpath to the object using the Jakarta JXPath library. If no valueXPath is specified, this method attempts to treat the target as a bean for that value. Values specified for fieldNames that are not declared in the datasource on which this method is being called are discarded.

Parameters:

obj - The object that is mined for values.

Returns:

A map of fieldNames -> fieldValues derived as described above.

validate

public ErrorReport validate(java.util.Map data,
                            boolean reportMissingRequiredFields)
                     throws java.lang.Exception

Takes a Map of fieldName -> value (data argument) and validates the data using the validators specified on this dataSource.

Parameters:

data - Map of DataSource fieldName -> value

reportMissingRequiredFields - for operations like update or fetch/filter only partial fields may be specified by the user. In those cases you want to ignore missing required fields.

Returns:

ErrorReport or null if there were no errors.

Throws:

java.lang.Exception - if an exception occurs during validation