public class DataSource extends Base implements IToJSON
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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String | OP_ADD Constant specifying the add operation. |
static java.lang.String | OP_CLIENT_EXPORT Constant specifying a clientExport operation. |
static java.lang.String | OP_CUSTOM Constant specifying a custom operation. |
static java.lang.String | OP_DOWNLOAD_FILE Constant specifying the downloadFile operation. See the Binary Fields overview in the client-side reference for further details. |
static java.lang.String | OP_FETCH Constant specifying the fetch operation. |
static java.lang.String | OP_GET_FILE Constant specifying a getFile operation. |
static java.lang.String | OP_GET_FILE_VERSION Constant specifying a getFileVersion operation. |
static java.lang.String | OP_HAS_FILE Constant specifying a hasFile operation. |
static java.lang.String | OP_HAS_FILE_VERSION Constant specifying a hasFileVersion operation. |
static java.lang.String | OP_LIST_FILE_VERSIONS Constant specifying a listFileVersions operation. |
static java.lang.String | OP_LIST_FILES Constant specifying a listFiles operation. |
static java.lang.String | OP_LOAD_SCHEMA Constant specifying the loadSchema operation. This is an operation used by the client-side framework to load the field definitions from a DataSource, and it is not customizable. |
static java.lang.String | OP_REMOVE Constant specifying the remove operation. |
static java.lang.String | OP_REMOVE_FILE Constant specifying a removeFile operation. |
static java.lang.String | OP_REMOVE_FILE_VERSION Constant specifying a removeFileVersion operation. |
static java.lang.String | OP_RENAME_FILE Constant specifying a renameFile operation. |
static java.lang.String | OP_SAVE_FILE Constant specifying a saveFile operation. |
static java.lang.String | OP_UNIQUE_NAME Constant specifying a uniqueName operation. |
static java.lang.String | OP_UPDATE Constant specifying the update operation. |
static java.lang.String | OP_VALIDATE Constant specifying the validate operation. |
static java.lang.String | OP_VIEW_FILE Constant specifying the viewFile operation. See the Binary Fields overview in the client-side reference for further details. |
Modifier and Type | Method and Description |
---|---|
long | add(java.lang.Object values) This convenience method is the equivalent of creating a DSRequest with an operationType of "add", calling setValues() on it, and then calling its execute() method. |
long | add(java.lang.Object values, RPCManager rpc) This convenience method is the equivalent of creating a DSRequest with an operationType of "add", calling setValues() and setRPCManager() on it, and then calling its execute() method. |
static void | addDynamicDSGenerator(DynamicDSGenerator ddsg) Registers the parameter DynamicDSGenerator with the DataSource system by placing it at the top of a stack of DynamicDSGenerators. |
static void | addDynamicDSGenerator(DynamicDSGenerator ddsg, java.util.regex.Pattern regex) Registers the parameter DynamicDSGenerator with the DataSource system. |
static void | addDynamicDSGenerator(DynamicDSGenerator ddsg, java.lang.String prefix) Registers the parameter DynamicDSGenerator with the DataSource system. |
static void | clearDynamicDSGenerators() Removes all user-added DynamicDSGenerators from the system |
static AdvancedCriteria | convertRelativeDates(AdvancedCriteria advancedCriteria) Converts all relative dates in a critierion to absolute dates relative to the time when this method is called. |
static AdvancedCriteria | convertRelativeDates(AdvancedCriteria advancedCriteria, java.util.Date baseDate) Converts all relative dates in a critierion to absolute dates relative to the time when this method is called. |
static Criterion | convertRelativeDates(Criterion criterion) Converts all relative dates in a critierion to absolute dates relative to the time when this method is called. |
static Criterion | convertRelativeDates(Criterion criterion, java.util.Date baseDate, DataSource ds) Converts all relative dates in a critierion to absolute dates relative to the time provided as base date. |
static Criterion | convertRelativeDates(Criterion criterion, java.util.Date baseDate, DataSource ds, boolean useEmbeddedTZ) Converts all relative dates in a critierion to absolute dates relative to the time provided as base date. |
DSResponse | execute(DSRequest req) This method carries out the actual processing of a DataSource request. |
DSResponse | executeAdd(DSRequest req) This method is called by DataSource.execute() for "add" operations. |
DSResponse | executeClientExport(DSRequest req) This method is called by DataSource.execute() for "clientExport" operations. |
DSResponse | executeCustom(DSRequest req) This method is called by DataSource.execute() for "custom" operations. |
DSResponse | executeFetch(DSRequest req) This method is called by DataSource.execute() for "fetch" operations. |
DSResponse | executeFileSource(DSRequest req) This method is called by DataSource.execute() for "fileSource" operations. |
DSResponse | executeRemove(DSRequest req) This method is called by DataSource.execute() for "remove" operations. |
DSResponse | executeUpdate(DSRequest req) This method is called by DataSource.execute() for "update" operations. |
java.util.List | fetch(java.lang.Object criteria) This convenience method is the equivalent of creating a DSRequest with an operationType of "fetch", calling setCriteria() on it, and then calling its execute() method. |
java.util.List | fetch(java.lang.String key, java.lang.Object value) This convenience method is the equivalent of creating a DSRequest with an operationType of "fetch", calling setCriteria() on it, and then calling its execute() method. |
java.util.Map | fetchById(java.lang.Object id) Same as DataSource.fetchById(Object, RPCManager) , without the optional RPCManager parameter |
java.util.Map | fetchById(java.lang.Object id, RPCManager rpc) Returns the record whose primary key matches the supplied id, or null if no such record exists. |
java.util.Map | fetchSingle(java.lang.Object criteria) This convenience method is the equivalent of creating a DSRequest with an operationType of "fetch", calling setCriteria() on it, calling its execute() method, then obtaining just the first item of the results. |
java.util.Map | fetchSingle(java.lang.String key, java.lang.Object value) This convenience method is the equivalent of creating a DSRequest with an operationType of "fetch", calling setCriteria() on it, calling its execute() method, then obtaining just the first item of the results. |
java.util.List | filter(java.lang.Object criteria) This convenience method is the equivalent of creating a DSRequest with an operationType of "filter", calling setCriteria() on it, and then calling its execute() method. |
java.util.List | filter(java.lang.String key, java.lang.Object value) This convenience method is the equivalent of creating a DSRequest with an operationType of "filter", calling setCriteria() on it, and then calling its execute() method. |
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.Document doc, DSRequest dsRequest) Instantiates a DataSource from an XML Document, with optional context DSRequest - the documentElement of the XML 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(org.w3c.dom.Element elem, DSRequest dsRequest) Instantiates a DataSource from an XML Element, with optional context DSRequest |
static DataSource | fromXML(java.io.Reader reader) Instantiates a DataSource from XML using a Reader |
static DataSource | fromXML(java.io.Reader reader, DSRequest dsRequest) Instantiates a DataSource from XML using a Reader, with optional context DSRequest |
static DataSource | fromXML(java.lang.String xml) Instantiates a DataSource from a String of XML |
static DataSource | fromXML(java.lang.String xml, DSRequest dsRequest) Instantiates a DataSource from a String of XML, with optional context DSRequest |
java.lang.String | getAuditChangedFieldsFieldName() Get the field name for the audit "changed fields" field configured for this DataSource . |
java.lang.String | getAuditRevisionFieldName() Get the field name for the audit revision field configured for this DataSource . |
java.lang.String | getAuditTimestampFieldName() Get the field name for the audit timestamp field configured for this DataSource . |
java.lang.String | getAuditTypeFieldName() Get the field name for the audit type field configured for this DataSource . |
java.lang.String | getAuditUserFieldName() Get the field name for the audit user field configured for this DataSource . |
static DynamicDSGenerator | getDefaultDynamicDSGenerator() Returns the default DynamicDSGenerator, or null if there is none |
static java.util.Map | getDynamicDSGenerators() Returns the non-default DynamicDSGenerators (ie, those that were registered against a startsWith string or a regular expression) |
java.lang.String | getEnumConstantProperty() Returns the name of the property this DataSource uses for constant name when translating enumerated types. |
java.lang.String | getEnumOrdinalProperty() Returns the name of the property this DataSource uses for ordinal number when translating enumerated types. |
java.lang.String | getEnumTranslateStrategy() Returns the strategy this DataSource uses for translating Java enumerated types (enums). |
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.io.Reader | getFile(DSFileSpec fileSpec) Gets the contents of a file stored in this DataSource. |
java.io.InputStream | getFileAsInputStream(DSFileSpec fileSpec) Gets the contents of a file stored in this DataSource |
java.lang.String | getFileAsString(DSFileSpec fileSpec) Gets the contents of a file stored in this DataSource |
java.lang.String | getFileContentsField() Get the field name for the fileContents field configured for this DataSource for fileSource operations. |
java.lang.String | getFileFormatField() Get the field name for the fileFormat field configured for this DataSource for fileSource operations. |
java.lang.String | getFileNameField() Get the field name for the fileName field configured for this DataSource for fileSource operations. |
java.lang.String | getFileTypeField() Get the field name for the fileType field configured for this DataSource for fileSource operations. |
java.lang.String | getID() Returns the "ID" property of the dataSource, exactly the same as DataSource.getName() |
java.util.List | getListProperties(java.util.List list) Takes a List of beans/Elements/Maps and for all fields on this DataSource that specify a valueXPath, applies the xpath to each object in the List using the Jakarta JXPath library. |
java.util.List | getListProperties(java.util.List list, boolean dropExtraFields, boolean dropIgnoredFields) Takes a List of beans/Elements/Maps and for all fields on this DataSource that specify a valueXPath, applies the xpath to each object in the List using the Jakarta JXPath library. |
java.lang.String | getName() Returns the "ID" property of the dataSource |
java.lang.String | getPrimaryKey() Returns the name of the primary key field. |
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, boolean dropIgnoredFields) 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.Class | getPropertyJavaClass(java.lang.String propertyName, DSField field, java.lang.Object value) Override point to allow subclasses to dynamically determine the Java class to use for a given property. |
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. |
java.util.Map | getRelatedDisplayRecord(java.lang.String fieldName, java.lang.Object displayValue) Deprecated. |
java.util.Map | getRelatedDisplayRecord(java.lang.String fieldName, java.lang.Object displayValue, DSRequest dsRequest) Returns the "related display record" for a given field. |
java.lang.String | getTableName() Returns the tableName property of the dataSource |
java.lang.Object | getTransactionObject(DSRequest req) Returns an object that can be used to manage transactions for this DataSource and other DataSources of the same type and provider. |
static java.lang.Object | getTransactionObject(DSRequest req, java.lang.String transactionObjectKey, java.lang.String shortTransactionObjectKey) Helper method retrieves connection/transaction object for specified type of data source implementation or null . |
boolean | hasFile(DSFileSpec fileSpec) Indicates whether a file exists in this DataSource. |
boolean | hasRecord(java.util.Map criteria) Returns true if the dataSource contains at least one record that matches the supplied criteria |
boolean | hasRecord(java.lang.String columnName, java.lang.Object value) Returns true if the dataSource contains at least one record where the columnName matches the value. |
protected void | initialized() This method is called after the DataSource has been initialized allowing further custom initialization. |
static boolean | isModificationOperation(java.lang.String operationType) Convenience method that returns true for operations that modify data and false for those that do not. |
boolean | isServerOnly() Returns true if this datasource has been declared with an attribute of "serverOnly=true". |
java.util.List | listFiles(java.lang.Object criteria) Get a list of files from the DataSource. |
java.util.List | listFiles(java.lang.Object criteria, DSRequest context) Get a list of files from the DataSource. |
java.util.List | listFiles(java.lang.String type, java.lang.String format) Get a list of files from the DataSource. |
java.util.List | listFiles(java.lang.String type, java.lang.String format, DSRequest context) Get a list of files from the DataSource. |
long | remove(java.lang.Object criteria) This convenience method is the equivalent of creating a DSRequest with an operationType of "remove", calling setCriteria() on it, and then calling its execute() method. |
static DynamicDSGenerator | removeDynamicDSGenerator() Unregisters the current default DynamicDSGenerator (ie, the one at the top of the stack). |
static DynamicDSGenerator | removeDynamicDSGenerator(java.util.regex.Pattern regex) Removes the DynamicDSGenerator registered against the parameter regexp Pattern |
static DynamicDSGenerator | removeDynamicDSGenerator(java.lang.String prefix) Removes the DynamicDSGenerator registered against the parameter prefix String |
java.util.List | removeFile(DSFileSpec fileSpec) Remove a file stored in this DataSource. |
java.util.List | renameFile(DSFileSpec oldSpec, DSFileSpec newSpec) Rename a file stored in this DataSource. |
java.util.Map | saveFile(DSFileSpec fileSpec, java.lang.Object contents) Save a file to the DataSource. |
void | setEnumConstantProperty(java.lang.String newValue) Sets the name of the property this DataSource should use for constant name when translating enumerated types. |
void | setEnumOrdinalProperty(java.lang.String newValue) Sets the name of the property this DataSource should use for ordinal number when translating enumerated types. |
void | setEnumTranslateStrategy(java.lang.String newValue) Sets the strategy this DataSource uses to translate enumerated types (objects of type enum). |
void | setOmitNullMapValuesInResponse(boolean omitNullMapValuesInResponse) Configure whether bindings with null values are dropped when sending a DSResponse to the browser. |
java.lang.Object | setProperties(java.util.Map properties, java.lang.Object target) Applies all properties in a Map to a target bean by calling setter methods according to the Java Beans naming convention ("name" -> setName()), including recursive traversal of sub-beans and JXPath-based setting of properties in nested beans. |
java.lang.Object | transformImportValue(java.lang.String fieldName, java.lang.Object rawValue, java.lang.String defaultStrategy) Deprecated. |
java.lang.Object | transformImportValue(java.lang.String fieldName, java.lang.Object rawValue, java.lang.String defaultStrategy, DSRequest dsRequest) Transforms the passed-in rawValue and returns the result of the transformation. |
void | transformMultipleFields(DSRequest req) Transforms the values for fields declared multiple:true in the incoming DSRequest. |
void | transformMultipleFields(DSResponse res) Transforms the values for fields declared multiple:true in a DSResponse. |
long | update(java.lang.Object criteria, java.lang.Object values) This convenience method is the equivalent of creating a DSRequest with an operationType of "update", calling setValues() and setCriteria() on it, and then calling its execute() method. |
long | update(java.lang.Object criteria, java.lang.Object values, RPCManager rpc) This convenience method is the equivalent of creating a DSRequest with an operationType of "update", calling setValues(), setCriteria() and setRPCManager() on it, and then calling its execute() method. |
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. |
ErrorReport | validate(java.util.Map data, boolean reportMissingRequiredFields, ValidationContext context) Takes a Map of fieldName -> value (data argument) and optional ValidationContext and validates the data using the validators specified on this dataSource. |
ErrorReport | validate(java.util.Map data, ErrorReport errors) Deprecated. Please use DataSource.validateRecord(Map, ErrorReport, ValidationContext) instead. |
ErrorReport | validateRecord(java.util.Map data, ErrorReport errors, ValidationContext context) Overriding point to add custom validation, that could not be covered using standard per-field validation. |
public static final java.lang.String OP_VIEW_FILE
public static final java.lang.String OP_DOWNLOAD_FILE
public static final java.lang.String OP_LOAD_SCHEMA
public static final java.lang.String OP_FETCH
public static final java.lang.String OP_ADD
public static final java.lang.String OP_REMOVE
public static final java.lang.String OP_UPDATE
public static final java.lang.String OP_CUSTOM
public static final java.lang.String OP_VALIDATE
public static final java.lang.String OP_CLIENT_EXPORT
public static final java.lang.String OP_GET_FILE
public static final java.lang.String OP_HAS_FILE
public static final java.lang.String OP_LIST_FILES
public static final java.lang.String OP_SAVE_FILE
public static final java.lang.String OP_RENAME_FILE
public static final java.lang.String OP_REMOVE_FILE
public static final java.lang.String OP_LIST_FILE_VERSIONS
public static final java.lang.String OP_GET_FILE_VERSION
public static final java.lang.String OP_HAS_FILE_VERSION
public static final java.lang.String OP_REMOVE_FILE_VERSION
public static final java.lang.String OP_UNIQUE_NAME
public void setOmitNullMapValuesInResponse(boolean omitNullMapValuesInResponse)
DSResponse
to the browser. To send such bindings, both this property and the active DSRequest
property by the same name must be set false
. (If no setting is specified in the DSRequest, it defaults to RPCManager.omitNullMapValuesInResponse
.) Rules:
JPADataSource
and HibernateDataSource
automatically set omitNullValuesInResponse
since nulls are not usually needed client-sideomitNullMapValuesInResponse
to reduce data if nulls are common and your client-side logic doesn't depend on having explicit nulls.omitNullMapValuesInResponse
- whether to drop bindings with null valuespublic static void addDynamicDSGenerator(DynamicDSGenerator ddsg)
DynamicDSGenerator.getDataSource(String, DSRequest)
method of the DynamicDSGenerator. If that returns null
, it will proceed to call the same method on any other DynamicDSGenerators in the stack, in reverse order of their registration (the normal LIFO ordering of a stack). Only if all the registered DynamicDSGenerators return null does the framework revert to the normal system of obtaining a DataSource instance. NOTE:
DataSource.addDynamicDSGenerator(DynamicDSGenerator, String)
and DataSource.addDynamicDSGenerator(DynamicDSGenerator, Pattern)
for APIs that are more likely to be suitablenull
for DataSources that you cannot provide an instance ofddsg
- A DynamicDSGenerator to register as the new defaultDataSource.removeDynamicDSGenerator()
public static DynamicDSGenerator removeDynamicDSGenerator()
If there are other default DynamicDSGenerators on the stack (because DataSource.addDynamicDSGenerator(DynamicDSGenerator)
has been called more than once), the next one in the stack becomes the current default. Otherwise, there is no default DynamicDSGenerator and the framework will fall back to using the normal system for obtaining DataSource instances.
Note, this API applies only to the stack of default DynamicDSGenerators - ie, those that were not registered against a prefix string or regular expression. It is quite possible to remove the last default DynamicDSGenerator and still have all of your DataSources generated dynamically via the prefix- or regex-based generators. See DataSource.addDynamicDSGenerator(DynamicDSGenerator, String)
and DataSource.addDynamicDSGenerator(DynamicDSGenerator, Pattern)
DataSource.addDynamicDSGenerator(DynamicDSGenerator, String)
, DataSource.addDynamicDSGenerator(DynamicDSGenerator, Pattern)
public static void addDynamicDSGenerator(DynamicDSGenerator ddsg, java.lang.String prefix)
You can add multiple DynamicDSGenerators using this API. If two or more are registered with prefixes that match a given DataSource ID, the one added first wins. Eg, if you have prefixes "c" and "cust" registered, then the "customer" DataSource will be provided by whichever of those two DynamicDSGenerators was registered first. Note that this "earliest first" basis also applies to DynamicDSGenerators registered with a regexp; if you had a DataSource ID that matched both a prefix and a regexp, whichever one of the two registrations came first would be used - there is no priority given to one or the other styles of ID matching.
ddsg
- A DynamicDSGenerator to register as the defaultprefix
- A prefix String as described abovepublic static void addDynamicDSGenerator(DynamicDSGenerator ddsg, java.util.regex.Pattern regex)
java.util.regex.Pattern
You can add multiple DynamicDSGenerators using this API. If two or more are registered with regular expressions that match a given DataSource ID, the one added first wins. This also applies to DynamicDSGenerators registered with a simple prefix String.
ddsg
- A DynamicDSGenerator to register as the defaultregex
- A Pattern representing a regular expression to match against incoming DataSource IDspublic static DynamicDSGenerator getDefaultDynamicDSGenerator()
public static java.util.Map getDynamicDSGenerators()
public static DynamicDSGenerator removeDynamicDSGenerator(java.lang.String prefix)
public static DynamicDSGenerator removeDynamicDSGenerator(java.util.regex.Pattern regex)
public static void clearDynamicDSGenerators()
protected void initialized() throws java.lang.Exception
The default implementation does nothing.
java.lang.Exception
- if an error occurs during initializationpublic static DataSource fromXML(org.w3c.dom.Element elem) throws java.lang.Exception
elem
- XML Element containing the DataSource definitionjava.lang.Exception
- if an error occurs during DataSource instantiationpublic static DataSource fromXML(org.w3c.dom.Element elem, DSRequest dsRequest) throws java.lang.Exception
elem
- XML Element containing the DataSource definitiondsRequest
- DSRequest to use as a context object if the creation of this DataSource involves the automatic creation of further, possibly user-generated, DataSources (eg, if this DataSource inheritsFrom a user-generated one)java.lang.Exception
- if an error occurs during DataSource instantiationpublic static DataSource fromXML(org.w3c.dom.Document doc) throws java.lang.Exception
doc
- XML Document containing the DataSource definitionjava.lang.Exception
- if an error occurs during DataSource instantiationpublic static DataSource fromXML(org.w3c.dom.Document doc, DSRequest dsRequest) throws java.lang.Exception
doc
- XML Document containing the DataSource definitiondsRequest
- DSRequest to use as a context object if the creation of this DataSource involves the automatic creation of further, possibly user-generated, DataSources (eg, if this DataSource inheritsFrom a user-generated one)java.lang.Exception
- if an error occurs during DataSource instantiationpublic static DataSource fromXML(java.lang.String xml) throws java.lang.Exception
xml
- XML string containing the DataSource definitionjava.lang.Exception
- if an error occurs during DataSource instantiationpublic static DataSource fromXML(java.lang.String xml, DSRequest dsRequest) throws java.lang.Exception
xml
- XML string containing the DataSource definitiondsRequest
- DSRequest to use as a context object if the creation of this DataSource involves the automatic creation of further, possibly user-generated, DataSources (eg, if this DataSource inheritsFrom a user-generated one)java.lang.Exception
- if an error occurs during DataSource instantiationpublic static DataSource fromXML(java.io.Reader reader) throws java.lang.Exception
reader
- Reader supplying XML containing the DataSource definitionjava.lang.Exception
- if an error occurs during DataSource instantiationpublic static DataSource fromXML(java.io.Reader reader, DSRequest dsRequest) throws java.lang.Exception
reader
- Reader supplying XML containing the DataSource definitiondsRequest
- DSRequest to use as a context object if the creation of this DataSource involves the automatic creation of further, possibly user-generated, DataSources (eg, if this DataSource inheritsFrom a user-generated one)java.lang.Exception
- if an error occurs during DataSource instantiationpublic java.lang.String getID()
DataSource.getName()
public java.lang.String getName()
public java.lang.String getTableName()
public java.util.List getFieldNames()
public java.lang.String getPrimaryKey()
public DSField getField(java.lang.String fieldName)
fieldName
- the name of the field whose definition you wantDSField
public java.lang.String getRecordXPath()
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.
public static boolean isModificationOperation(java.lang.String operationType)
public void transformMultipleFields(DSRequest req)
See client-side docs for DataSourceField.multipleStorage for possible behaviors. This transformation is performed in DataSource.execute(), before operationType-specific methods like executeFetch or executeUpdate() are called.
req
- the request to be transformed.public void transformMultipleFields(DSResponse res)
See client-side docs for DataSourceField.multipleStorage for possible behaviors. This transformation is performed in DataSource.execute(), after operationType-specific methods like executeFetch or executeUpdate() are called.
res
- the DSResponse to be transformed.public DSResponse execute(DSRequest req) throws java.lang.Exception
DataSource.transformMultipleFields(DSRequest)
and DataSource.transformMultipleFields(DSResponse)
.req
- The DSRequest object representing this operationjava.lang.Exception
public java.lang.String getAuditTypeFieldName()
DataSource
.DataSource
.public java.lang.String getAuditRevisionFieldName()
DataSource
.DataSource
.public java.lang.String getAuditTimestampFieldName()
DataSource
.DataSource
.public java.lang.String getAuditUserFieldName()
DataSource
.DataSource
.public java.lang.String getAuditChangedFieldsFieldName()
DataSource
.DataSource
.public java.lang.Object setProperties(java.util.Map properties, java.lang.Object target)
When DataSourceField.valueXPath is set, the valueXPath is treated as a Jakarta JXPath expression. If some intervening objects in a JXPath are nulls
, this method attempts to create missing objects if possible - see JXPathContextObjectFactory
documentation for details.
Entries in the "properties" Map where there is no same-named DataSource field are discarded.
This method can be used to recursively populate an object graph of Beans and Collections, using multiple DataSources to define rules for how subobjects are populated. Specifically, if the "properties" Map has entries whose values are Maps, if the corresponding field on the DataSource is declared as being of a DataSource type (ie, the type property is set to the ID of some valid DataSource), these properties will be applied via a recursive call to DataSource.setProperties() using the indicated DataSource. This will also occur for a Collection within the "properties" Map if the target bean has a corresponding property of Collection type.
When the type to use is ambiguous (for example, a property on the target bean is declared as a base type with many sub-types, or is an abstract type like List) the DataSourceField properties javaClass, javaCollectionClass and javaKeyClass can be used to specify a concrete type - see the client-side reference docs for further details.
Ultimately, this method calls DataTools.setProperties(Map, Object, DataSource)
- see the documentation of these method for details of treatment of object vs primitive type, Java Generics, Enums, and other cases.
properties
- Map of DataSource fieldName -> valuetarget
- Target object to which the values are to be appliedpublic java.util.List getListProperties(java.util.List list)
list
- The List of objects that is mined for values.public java.util.List getListProperties(java.util.List list, boolean dropExtraFields, boolean dropIgnoredFields)
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.list
- The List of objects 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.dropIgnoredFields
- If true, values specified for fieldNames that are declared in the datasource on which this method is being called with the property ignore: true are are discarded; otherwise they are keptpublic java.util.Map getProperties(java.lang.Object obj)
obj
- The object that is mined for values.public java.util.Map getProperties(java.lang.Object obj, boolean dropExtraFields, boolean dropIgnoredFields)
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.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.dropIgnoredFields
- If true, values specified for fieldNames that are declared in the datasource on which this method is being called with the property ignore: true are are discarded; otherwise they are keptpublic java.util.Map getProperties(java.lang.Object obj, java.util.Collection propsToKeep)
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.public ErrorReport validate(java.util.Map data, boolean reportMissingRequiredFields) throws java.lang.Exception
data
- Map of DataSource fieldName -> valuereportMissingRequiredFields
- 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.java.lang.Exception
- if an exception occurs during validationpublic ErrorReport validate(java.util.Map data, boolean reportMissingRequiredFields, ValidationContext context) throws java.lang.Exception
data
- Map of DataSource fieldName -> valuereportMissingRequiredFields
- 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.context
- ValidationContext
to use during validation; if null
is passed, then new ValidationContext
will be created. NOTE that if passing validationContext, outer code is responsible to call validationContext.freeResources()
;java.lang.Exception
- if an exception occurs during validation@Deprecated public ErrorReport validate(java.util.Map data, ErrorReport errors) throws java.lang.Exception
DataSource.validateRecord(Map, ErrorReport, ValidationContext)
instead.java.lang.Exception
public ErrorReport validateRecord(java.util.Map data, ErrorReport errors, ValidationContext context) throws java.lang.Exception
errors
parameter and return complete ErrorReport
object or null
if there were no errors. Implementing this method is the right way to introduce whole-record validation behavior that applies to all operationTypes that perform validation ("validate", "add", "update" and possible future types) as well as other contexts where validation is performed, such as the BatchUploader or mass import of records.
Note this method has no default behavior.
data
- Map of DataSource fieldName -> valueerrors
- ErrorReport
with validation errors reported by validators on this datasource, or null
if there were no errors.context
- ValidationContext
, where record is validated, see ValidationContext
javadocs for details.null
if there were no errors.java.lang.Exception
- if an exception occurs during validation.public DSResponse executeFetch(DSRequest req) throws java.lang.Exception
req
- The DSRequest object representing this operationjava.lang.Exception
public DSResponse executeRemove(DSRequest req) throws java.lang.Exception
req
- The DSRequest object representing this operationjava.lang.Exception
public DSResponse executeAdd(DSRequest req) throws java.lang.Exception
req
- The DSRequest object representing this operationjava.lang.Exception
public DSResponse executeUpdate(DSRequest req) throws java.lang.Exception
req
- The DSRequest object representing this operationjava.lang.Exception
public DSResponse executeCustom(DSRequest req) throws java.lang.Exception
req
- The DSRequest object representing this operationjava.lang.Exception
public DSResponse executeClientExport(DSRequest req) throws java.lang.Exception
req
- The DSRequest object representing this operationjava.lang.Exception
public DSResponse executeFileSource(DSRequest req) throws java.lang.Exception
The actual operation to be performed is indicated by the request's operationType
. The operationType
may be one of the following:
DSResponse
appropriate for a "fetch" operation, using the fileName, fileType and fileFormat (or other criteria) provided by the DSRequest
. Only include the fileContents in the outputs for the "getFile" operationType.oldValues
, since they may be primary keys (so that providing only the new values would not be sufficient).In each case, the fileName, fileType, fileFormat and fileContents are provided in the DSRequest using those field names. The default implementation uses getFileNameField()
, getFileTypeField()
, getFileFormatField()
and getFileContentsField()
to construct the appropriate sub-request to access the real fields of the DataSource.
In constructing a DSResponse, you must use the field names fileName, fileType, fileFormat and fileContents rather than the real fields of the DataSource.
The default implementation issues a sub-request of type "fetch", "add", "remove" or "update", with an operationId equal to the operationType provided here, and with field names translated according the DataSource configuration. Therefore, you can customize the sub-request operationTypes, by checking for the relevant operationId.
Note that the "renameFile" operationId is implemented, by default, to perform an "update" operation, unless the fileNameField, fileFormatField or fileTypeField are primary keys. If one of those fields is a primary key, then "renameFile" is instead implemented as a "remove" followed by an "add", since there can be difficulties updating primary keys.
req
- The DSRequest object representing this operation.java.lang.Exception
public java.lang.String getFileNameField()
This allows fileSource operations to always use "fileName" as a field name, no matter where this DataSource stores the fileName.
The default implementation works as follows:
public java.lang.String getFileContentsField()
fileNameField
, fileTypeField
, or fileFormatField
.public java.lang.String getFileTypeField()
public java.lang.String getFileFormatField()
public java.io.Reader getFile(DSFileSpec fileSpec) throws java.lang.Exception
fileSpec
- A specifier for the file.java.lang.Exception
public java.lang.String getFileAsString(DSFileSpec fileSpec) throws java.lang.Exception
fileSpec
- A specifier for the file.java.lang.Exception
public java.io.InputStream getFileAsInputStream(DSFileSpec fileSpec) throws java.lang.Exception
fileSpec
- A specifier for the file.java.lang.Exception
public boolean hasFile(DSFileSpec fileSpec) throws java.lang.Exception
fileSpec
- A specifier for the file.java.lang.Exception
public java.util.Map saveFile(DSFileSpec fileSpec, java.lang.Object contents) throws java.lang.Exception
fileSpec
- A specifier for the file. A fileName is always required. Some DataSources will require that the fileType and fileFormat be specified.contents
- The contents of the file.java.lang.Exception
public java.util.List listFiles(java.lang.Object criteria, DSRequest context) throws java.lang.Exception
criteria
- Criteria to apply. References to fileName
, fileContents
and fileType
will be translated to the native field names configured for this DataSource.context
- DSRequest which provides the security context in which this method should run.fileName
, fileType
and fileFormat
fields populated, but not the fileContents
field. (You can use getFile()
to get the fileContents
).java.lang.Exception
public java.util.List listFiles(java.lang.Object criteria) throws java.lang.Exception
criteria
- Criteria to apply. References to fileName
, fileContents
and fileType
will be translated to the native field names configured for this DataSource.fileName
, fileType
and fileFormat
fields populated, but not the fileContents
field. (You can use getFile()
to get the fileContents
).java.lang.Exception
public java.util.List listFiles(java.lang.String type, java.lang.String format, DSRequest context) throws java.lang.Exception
type
- The file type (e.g. "ds")format
- The file format (e.g. "xml" or "js")context
- DSRequest which provides the security context in which this method should run.fileName
, fileType
and fileFormat
fields populated, but not the fileContents
field. (You can use getFile()
to get the fileContents
).java.lang.Exception
public java.util.List listFiles(java.lang.String type, java.lang.String format) throws java.lang.Exception
type
- The file type (e.g. "ds")format
- The file format (e.g. "xml" or "js")fileName
, fileType
and fileFormat
fields populated, but not the fileContents
field. (You can use getFile()
to get the fileContents
).java.lang.Exception
public java.util.List renameFile(DSFileSpec oldSpec, DSFileSpec newSpec) throws java.lang.Exception
oldSpec
- The original fileSpec.newSpec
- The new fileSpec.fileName
, fileType
, and fileFormat
fields populated, but not the fileContents
field.java.lang.Exception
public java.util.List removeFile(DSFileSpec fileSpec) throws java.lang.Exception
fileSpec
- A specifier for the file.fileName
, fileType
and fileFormat
fields populated, but not the fileContents
field.java.lang.Exception
public java.util.List fetch(java.lang.Object criteria) throws java.lang.Exception
criteria
- The criteria to use for the fetch operationList
with retrieved data.java.lang.Exception
public java.util.List fetch(java.lang.String key, java.lang.Object value) throws java.lang.Exception
key
- The criterion keyvalue
- The criterion valueList
with retrieved data.java.lang.Exception
public java.util.List filter(java.lang.Object criteria) throws java.lang.Exception
criteria
- The criteria to use for the filter operationList
with retrieved data.java.lang.Exception
public java.util.List filter(java.lang.String key, java.lang.Object value) throws java.lang.Exception
key
- The criterion keyvalue
- The criterion valueList
with retrieved data.java.lang.Exception
public long add(java.lang.Object values) throws java.lang.Exception
values
- The values to use for the add operationlong
number of affected rows.java.lang.Exception
public long add(java.lang.Object values, RPCManager rpc) throws java.lang.Exception
values
- The values to use for the add operationlong
number of affected rows.java.lang.Exception
public long update(java.lang.Object criteria, java.lang.Object values) throws java.lang.Exception
criteria
- The criteria to use for the update operationvalues
- The values to use for the update operationlong
number of affected rows.java.lang.Exception
public long update(java.lang.Object criteria, java.lang.Object values, RPCManager rpc) throws java.lang.Exception
criteria
- The criteria to use for the update operationvalues
- The values to use for the update operationrpc
- The RPCManager to use for the update operationlong
number of affected rows.java.lang.Exception
public long remove(java.lang.Object criteria) throws java.lang.Exception
criteria
- The criteria to use for the remove operationlong
number of affected rows.java.lang.Exception
public java.util.Map fetchSingle(java.lang.String key, java.lang.Object value) throws java.lang.Exception
Note that this method expects the specified criterion to result in a single result, and will throw an exception if the multiple records match the request.
key
- The criterion keyvalue
- The criterion valueMap
of retrieved object properties.java.lang.Exception
public java.util.Map fetchSingle(java.lang.Object criteria) throws java.lang.Exception
Note that this method expects the specified criteria to result in a single result, and will throw an exception if the multiple records match the request.
criteria
- The criteria to use for the fetch operationMap
of retrieved object properties.java.lang.Exception
public java.lang.Object getTransactionObject(DSRequest req) throws java.lang.Exception
This method is part of the Automatic Transactions feature, which is effective only in Power edition and above.
java.lang.Exception
public static java.lang.Object getTransactionObject(DSRequest req, java.lang.String transactionObjectKey, java.lang.String shortTransactionObjectKey) throws java.lang.Exception
null
. SQLDataSource
:
Connection conn = DataSource.getTransactionObject(req, SQLTransaction.CONNECTION_ATTR + dbName);
where dbName
is name of database as configured in server.properties file. Returned conn
is instance of java.sql.Connection
to specified data base.HibernateDataSource
:
Transaction tx = DataSource.getTransactionObject(req, HibernateTransaction.TRANSACTION_ATTR);
Session session = HibernateTransaction.getTransactionSession(tx);
session
and tx
instances of hibernate session and transaction object used by HibernateDataSource
.JPADataSource
:
JPAConnectionHolder holder = DataSource.getTransactionObject(req, EMF.TRANSACTION_ATTR);
JPAConnectionHolder
instance contains references to entity manager and transaction object used by JPADataSource
instances.RPCManager
and will be handled by data source object which started transaction. This method is part of the Automatic Transactions feature, which is effective only in Power edition and above.req
- DSRequest
transactionObjectKey
- String
Name of transaction object key.Object
containing connection/transaction. Actual type of instance depends on passed parameter transactionObjectKey
. null
is returned if specified request does not contain reference to RPCManager
or specified object is not set.java.lang.Exception
- if provided DSRequest
is null
.public boolean hasRecord(java.lang.String columnName, java.lang.Object value) throws java.lang.Exception
columnName
- The columnName to use in the search criteriavalue
- The value to look for in the search criteriajava.lang.Exception
public boolean hasRecord(java.util.Map criteria) throws java.lang.Exception
criteria
- A Map containing the search criteriajava.lang.Exception
public java.util.Map fetchById(java.lang.Object id) throws java.lang.Exception
DataSource.fetchById(Object, RPCManager)
, without the optional RPCManager parameterid
- The primary key value to match, or a set of primary key values in a Mapjava.lang.Exception
public java.util.Map fetchById(java.lang.Object id, RPCManager rpc) throws java.lang.Exception
id
- The primary key value to match, or a set of primary key values in a Maprpc
- An optional RPCManager to apply to the DSRequest we generate to implement the fetch. If provided, this gives access to the RPCManager's shared state. For example, it may allow the fetch to share a database transaction or give it access to an HttpSessionjava.lang.Exception
public java.lang.String getEnumTranslateStrategy()
DataSource.setEnumTranslateStrategy(String)
for details of valid translate strategiespublic void setEnumTranslateStrategy(java.lang.String newValue)
enum.toString()
newValue
- A String containing the new enum translate strategypublic java.lang.String getEnumOrdinalProperty()
public java.lang.String getEnumConstantProperty()
public void setEnumOrdinalProperty(java.lang.String newValue)
newValue
- The new ordinal property namepublic void setEnumConstantProperty(java.lang.String newValue)
newValue
- The new constant value property namepublic java.lang.Class getPropertyJavaClass(java.lang.String propertyName, DSField field, java.lang.Object value) throws java.lang.Exception
Your overriding method is passed the name of the property we are trying to populate, the raw value we are going to use to populate it, and the DSField object associated with the property. It is envisaged that this will be sufficient context to dynamically decide on a Class to use. For example, if the raw Map passed in contains a given property, your code might decide to use Class B rather than the normal Class A.
Note that whatever class you return from this method will be used as the parameter type for the corresponding setter on the bean we are populating. This means that this method (and indeed the declarative "javaClass" property) is only useful if your Javabean property type is a supertype of whatever class you return from this method. Examples of valid use cases would include things like your Javabean property is of an interface or abstract type, or of a general base type like Object.
propertyName
- Name of the property we are trying to populate, for contextfield
- The associated DSField
value
- The raw value we are trying to assign to this property. Note this will ordinarily be a Map or a List of MapsDataSourceField.javaClass
)java.lang.Exception
public static AdvancedCriteria convertRelativeDates(AdvancedCriteria advancedCriteria)
DataSource.convertRelativeDates(com.isomorphic.criteria.AdvancedCriteria, java.util.Date)
this method will assume that the relative point in time to convert against is now.advancedCriteria
- the AdvancedCriteria for which to convert relative dates.DataSource.convertRelativeDates(com.isomorphic.criteria.Criterion)
public static AdvancedCriteria convertRelativeDates(AdvancedCriteria advancedCriteria, java.util.Date baseDate)
advancedCriteria
- the AdvancedCriteria for which to convert relative dates.baseDate
- the relative point in time to convert dates against.DataSource.convertRelativeDates(com.isomorphic.criteria.Criterion, java.util.Date, DataSource)
public static Criterion convertRelativeDates(Criterion criterion)
In order for the client to automatically send relative dates to the server you need to set DataSource.autoConvertRelativeDates to false.
If you want to store a client side criteria containing relative dates for later parsing server side you need to use the LOGICAL_DATE_CONSTRUCTOR mode of JSONEncoder when encoding the criteria on the client and then use AdvancedCriteria.decodeClientCriteria(String)
to decode the criteria on the server.
In such case you would have to serialize the critiera on the client before sending it to the server.
var encodedCriteria = isc.JSON.encode(criteria, {dateFormat: 'logicalDateConstructor'}); // Add the encoded criteria to your datasource. overnightReports.addData({ storedCriteria: encodedCriteria });
final JSONEncoder jsonEncoder = new JSONEncoder(); jsonEncoder.setDateFormat(JSONDateFormat.LOGICAL_DATE_CONSTRUCTOR); // Encode the criteria using the above JSONEncoder. final String encodedCriteria = JSON.encode(criteria, jsonEncoder); // Add the encoded criteria to your datasource. final Record newRecord = new Record(); newRecord.setAttribute("storedCriteria", encodedCriteria); overnightReports.addData(newRecord);
criterion
- the criterion to convert relative dates for.public static Criterion convertRelativeDates(Criterion criterion, java.util.Date baseDate, DataSource ds)
criterion
- the criterion to convert relative dates for.baseDate
- the relative point in time to convert dates against.ds
- the DataSource applicable to this criterion. Pass null if you do not have access to the dataSource, but be aware that this may lead to inaccurate handling of date values (because we are unable to distinguish between "date" and "datetime" fields, we treat all values as datetimes)public static Criterion convertRelativeDates(Criterion criterion, java.util.Date baseDate, DataSource ds, boolean useEmbeddedTZ)
This API can potentially use the client's timezone to determine what is meant by concepts such as "the start of today" or "the end of tomorrow", if the client supplies its timezone in the relativeDate definition (this happens in SmartClient versions from 11.1 onwards, Smart GWT versions 6.1 onwards). However, please note that the client actually sends up its current offest from UTC, not a real timezone identifier; this is unavoidable, as it is not possible to reliably detect the actual timezone identifier from Javascript.
The offset from GMT/UTC is usually adequate to correctly convert datetimes, but without real timezone information we get subtle errors in cases where a date range straddles the changeover to or from daylight savings time (DST); because we don't really know the timezone, we don't know how DST applies to it.
For example, consider a user in the US Pacific timezone who specifies a date range of "$yesterday" to "$tomorrow" at local midday on 13 March 2016. On that date, the US Pacific timezone switches from "Pacific Standard Time" to "Pacific Daylight Time" at 1am. Therefore PDT, which is UTC-07:00, is in force, and this is what is sent to the server. However, "$yesterday" should correctly be resolved as local midday on the previous day, March 12. On March 12, the US Pacific timezone was on PST, so the correct UTC start time is 2016-03-12 20:00:00 UTC. But the server doesn't know about the DST changeover because it doesn't know that the client is in US Pacific; it only knows that the offset from UTC is -07:00. Therefore, the start time will be incorrectly calculated as 2016-03-12 19:00:00 UTC.
criterion
- the criterion to convert relative dates for.baseDate
- the relative point in time to convert dates against.ds
- the DataSource applicable to this criterion. Pass null if you do not have access to the dataSource, but be aware that this may lead to inaccurate handling of date values (because we are unable to distinguish between "date" and "datetime" fields, we treat all values as datetimes)useEmbeddedTZ
- If true, uses the timezone offset embedded in a relativeDate definition, if one is present. If this parameter is false, or there is no embedded timezone, the server timezone is used. Note, no embedded timezone information is sent from the client in versions earlier than 11.1 / 6.1 (SmartClient / Smart GWT)@Deprecated public java.util.Map getRelatedDisplayRecord(java.lang.String fieldName, java.lang.Object displayValue) throws java.lang.Exception
DataSource.getRelatedDisplayRecord(String, Object, DSRequest)
is the one that you must override if you want to customize the behavior.java.lang.Exception
DataSource.getRelatedDisplayRecord(String, Object, DSRequest)
public java.util.Map getRelatedDisplayRecord(java.lang.String fieldName, java.lang.Object displayValue, DSRequest dsRequest) throws java.lang.Exception
includeFrom
field on the same DataSource that the foreignKey declaration targetsNow assume that the Colors dataSource contains these records:
{id: 1, name:"Cyan"} {id: 2, name:"Magenta"} {id: 3, name:"Yellow"}Now, calling
getRelatedDisplayRecord("color", "Yellow")
on an instance of the "Widgets" dataSource will return{id: 3, name:"Yellow"}The framework uses this method during data import, to map display values provided in import datasets like CSV files, to their proper corresponding key values
fieldName
- The name of the field to obtain the related display record fordisplayValue
- The display value to use for looking up the related display recordjava.lang.Exception
@Deprecated public java.lang.Object transformImportValue(java.lang.String fieldName, java.lang.Object rawValue, java.lang.String defaultStrategy) throws java.lang.Exception
DataSource.transformImportValue(String, Object, String, DSRequest)
is the one that you must override if you want to customize the behavior.java.lang.Exception
DataSource.transformImportValue(String, Object, String, DSRequest)
public java.lang.Object transformImportValue(java.lang.String fieldName, java.lang.Object rawValue, java.lang.String defaultStrategy, DSRequest dsRequest) throws java.lang.Exception
data import
, immediately before values are translated to an appropriate data type and validated. The base implementation transforms display values in the import dataset to their underlying key values, for fields that have a "related display record". See DataSource.getRelatedDisplayRecord(String, Object)
for more details. You can add any transformations you require by overriding this method, but if you require the built-in displayValue-to-key transformation described above, be sure to invoke the super-method.
Transformed values are cached during import process in a DataImport
instance. All builtin tools use new DataImport
instance, so this makes no effect on import results, except optimizing performance. But, if you end up using DataImport directly and want to use it for multiple imports, keep in mind that transformed values are cached and may affect the results.
fieldName
- The name of the field for which are performing a transformationrawValue
- The value to transformdefaultStrategy
- The importStrategy ("display" or "key") to use if this field declares an importStrategy of "auto", or does not declare an importStrategy. See the client-side FieldImportStrategy
docs for detailsnull
if the concept of a related display record is not applicable to the supplied field, or if no related display record is found: untransformed original rawValue
for "display" importStrategy or null
for "displayRequired" importStrategy.java.lang.Exception
public boolean isServerOnly()