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.util.Map getProperties(java.lang.Object obj, boolean dropExtraFields)
          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.util.Map getProperties(java.lang.Object obj, java.util.Collection propsToKeep)
          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.

getProperties

public java.util.Map getProperties(java.lang.Object obj,
                                   boolean dropExtraFields)
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. The dropExtraFields parameter controls whether or not 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.
dropExtraFields - If true, values specified for fieldNames that are not declared in the datasource on which this method is being called are discarded, otherwise they are kept.
Returns:
A map of fieldNames -> fieldValues derived as described above.

getProperties

public java.util.Map getProperties(java.lang.Object obj,
                                   java.util.Collection propsToKeep)
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.
Parameters:
obj - The object that is mined for values.
propsToKeep - specifies an explicit list of properties to retain the datasource on which this method is being called are discarded, otherwise they are kept.
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