BasicDataSource (SmartClient Enterprise Server API 13.0p (2024-12-20))

java.lang.Object
- com.isomorphic.base.Base
- - com.isomorphic.datasource.DataSource
  - - com.isomorphic.datasource.BasicDataSource

All Implemented Interfaces:

IToJSON

Direct Known Subclasses:

HibernateDataSource, JPADataSource, SQLDataSource
```
public class BasicDataSource
extends DataSource
```
A BasicDataSource is a DataSource that can create itself from configuration information expressed in XML.
BasicDataSource is the right class to extend when creating a custom DataSource connector.

See Also:

Serialized Form

Field Summary
- Fields inherited from class com.isomorphic.datasource.DataSource
  OP_ADD, OP_CLIENT_EXPORT, OP_CUSTOM, OP_DOWNLOAD_FILE, OP_FETCH, OP_GET_FILE, OP_GET_FILE_VERSION, OP_HAS_FILE, OP_HAS_FILE_VERSION, OP_LIST_FILE_VERSIONS, OP_LIST_FILES, OP_LOAD_SCHEMA, OP_REMOVE, OP_REMOVE_FILE, OP_REMOVE_FILE_VERSION, OP_RENAME_FILE, OP_SAVE_FILE, OP_UNIQUE_NAME, OP_UPDATE, OP_VALIDATE, OP_VIEW_FILE

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`DataSource`	`getAuditDataSource()` This method returns the audit `DataSource` associated with this `DataSource` if it has the audit=true property set.
`java.util.Map`	`getAuditRecord(DSRequest req, java.util.Map values)` Convenience version of the `three-argument version`, but the third argument (oldvalues) is null, so is not suitable for "update" requests
`java.util.Map`	`getAuditRecord(DSRequest req, java.util.Map inValues, java.util.Map oldValues)` Given a base record, a context `DSRequest` and optionally an "old" record, returns a record with all the audit fields populated in accordance with the rules specified in the `DataSource`'s audit configuration.
`java.util.List`	`getListProperty(java.lang.String key)` Returns the value of the specified attribute as a List.
`DataTypeMap`	`getMapProperty(java.lang.String key)` Returns the value of the specified attribute as a Map.
`java.lang.Object`	`getObjectProperty(java.lang.String key)` Returns the value of the specified element(s) as an Object. Custom XML is transformed to Strings or Java collections by the following rules: Elements with just text (no child elements or attributes) become Strings Elements with child elements or attributes become Maps containing data derived from their subelements Repeating elements (more than one of the same name at the same level) become Lists Sample XML: Map `<DataSource> <mapCustomProperty key1="value1" key2="value2" /> </DataSource>` List of String `<DataSource> <listCustomProperty>ListElement1</listCustomProperty> <listCustomProperty>ListElement2</listCustomProperty> </DataSource>` List of Map `<DataSource> <mapCustomProperty key1="value1" key2="value2" /> <mapCustomProperty key1="value1" key2="value2" /> </DataSource>`
`java.lang.String`	`getProperty(java.lang.String key)` Returns a property from the DataSource config.
`boolean`	`shouldAutoJoinTransaction(DSRequest dsRequest)` Returns true if the parameter DSRequest should automatically join an existing transaction, taking into account the DSRequest-specific override provided by `DSRequest.setJoinTransaction(java.lang.Boolean)`, the `transaction policy` of the controlling RPCManager (if there is one), and autoJoinTransactions settings at the operationBinding, DataSource, dbName and global system levels.
`boolean`	`shouldAutoStartTransaction(DSRequest req, boolean ignoreExistingTransaction)` Returns true if the parameter DSRequest should automatically start a new transaction, taking into account the DSRequest-specific override provided by `DSRequest.setJoinTransaction(java.lang.Boolean)`, the `transaction policy` of the controlling RPCManager (if there is one), and autoJoinTransactions settings at the operationBinding, DataSource, dbName and global system levels
`void`	`transformMultipleFields(DSRequest req)` Transforms the values for fields declared multiple:true in the incoming DSRequest.
`void`	`transformMultipleFields(DSResponse res)` Transform the values for fields declared multiple:true in a DSResponse.
`protected void`	`writeMultiAudits(java.util.List valueSets, DSRequest originatingDSRequest)` Writes a collection of audit records to the audit DataSource associated with this DataSource.

Methods inherited from class com.isomorphic.datasource.DataSource
add, add, addDynamicDSGenerator, addDynamicDSGenerator, addDynamicDSGenerator, clearDynamicDSGenerators, convertRelativeDates, convertRelativeDates, convertRelativeDates, convertRelativeDates, convertRelativeDates, convertRelativeDates, execute, executeAdd, executeClientExport, executeCustom, executeFetch, executeFileSource, executeRemove, executeUpdate, fetch, fetch, fetchById, fetchById, fetchById, fetchSingle, fetchSingle, filter, filter, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, getAuditChangedFieldsFieldName, getAuditRevisionFieldName, getAuditTimestampFieldName, getAuditTypeFieldName, getAuditUserFieldName, getDefaultDynamicDSGenerator, getDirectFields, getDynamicDSGenerators, getEnumConstantProperty, getEnumOrdinalProperty, getEnumTranslateStrategy, getField, getFieldNames, getFile, getFileAsInputStream, getFileAsString, getFileContentsField, getFileFormatField, getFileNameField, getFileTypeField, getID, getListProperties, getListProperties, getName, getNonIncludedFields, getPrimaryKey, getProperties, getProperties, getProperties, getPropertyJavaClass, getRecordXPath, getRelatedDisplayRecord, getRelatedDisplayRecord, getRelatedTableAlias, getTableName, getTransactionObject, getTransactionObject, hasFile, hasRecord, hasRecord, initialized, isModificationOperation, isServerOnly, listFiles, listFiles, listFiles, listFiles, remove, removeDynamicDSGenerator, removeDynamicDSGenerator, removeDynamicDSGenerator, removeFile, renameFile, saveFile, setEnumConstantProperty, setEnumOrdinalProperty, setEnumTranslateStrategy, setOmitNullMapValuesInResponse, setProperties, transformImportValue, transformImportValue, transformResponse, update, update, validate, validate, validate, validateRecord

Methods inherited from interface com.isomorphic.js.IToJSON
toJSON

- Method Detail
  - getProperty
```
public java.lang.String getProperty(java.lang.String key)
```
    Returns a property from the DataSource config. This method allows a custom DataSource implementation to be configuration-driven like the built-in DataSource implementations are. So, if you add
```
    myNewProperty="some useful value"
 
```
    to the <DataSource> tag in your .ds.xml definition file, calling this method with a parameter of "myNewProperty" will return "some useful value" - the value you assigned in the DataSource definition.
    Parameters:
    
    key - The key to look up
    
    Returns:
    
    The property value as a String (non-String objects are converted using toString())
  - getObjectProperty
```
public java.lang.Object getObjectProperty(java.lang.String key)
```
    Returns the value of the specified element(s) as an Object.
    Custom XML is transformed to Strings or Java collections by the following rules:
    - Elements with just text (no child elements or attributes) become Strings
    - Elements with child elements or attributes become Maps containing data derived from their subelements
    - Repeating elements (more than one of the same name at the same level) become Lists
    - Map
      <DataSource> <mapCustomProperty key1="value1" key2="value2" /> </DataSource>
    - List of String
      <DataSource> <listCustomProperty>ListElement1</listCustomProperty> <listCustomProperty>ListElement2</listCustomProperty> </DataSource>
    - List of Map
      <DataSource> <mapCustomProperty key1="value1" key2="value2" /> <mapCustomProperty key1="value1" key2="value2" /> </DataSource>
    Parameters:
    
    key - the name of the element(s)
    
    Returns:
    
    the value of the specified element(s) as an Object
    
    See Also:
    
    BasicDataSource.getProperty(String), BasicDataSource.getListProperty(String), BasicDataSource.getMapProperty(String)
  - getListProperty
```
public java.util.List getListProperty(java.lang.String key)
```
    Returns the value of the specified attribute as a List.
    
    Parameters:
    
    key - the name of the attribute
    
    Returns:
    
    the value of the specified attribute as a List
    
    Throws:
    
    java.lang.ClassCastException - if requested property is not instanceof List
    
    See Also:
    
    BasicDataSource.getProperty(String), BasicDataSource.getObjectProperty(String), BasicDataSource.getMapProperty(String)
  - getMapProperty
```
public DataTypeMap getMapProperty(java.lang.String key)
```
    Returns the value of the specified attribute as a Map.
    
    Parameters:
    
    key - the name of the attribute
    
    Returns:
    
    the value of the specified attribute as a Map
    
    Throws:
    
    java.lang.ClassCastException - if requested property is not instanceof Map
    
    See Also:
    
    BasicDataSource.getProperty(String), BasicDataSource.getObjectProperty(String), BasicDataSource.getListProperty(String)
  - getAuditRecord
```
public java.util.Map getAuditRecord(DSRequest req,
                                    java.util.Map values)
                             throws java.lang.Exception
```
    Convenience version of the three-argument version, but the third argument (oldvalues) is null, so is not suitable for "update" requests
    
    Parameters:
    
    req - DSRequest required to provide context essential to generating correct audit properties (for example, so we know the type of operation)
    
    inValues - The "base record" to provide an audit record for
    
    Returns:
    
    a record populated with audit values, based on the base record
    
    Throws:
    
    java.lang.Exception
  - getAuditRecord
```
public java.util.Map getAuditRecord(DSRequest req,
                                    java.util.Map inValues,
                                    java.util.Map oldValues)
                             throws java.lang.Exception
```
    Given a base record, a context DSRequest and optionally an "old" record, returns a record with all the audit fields populated in accordance with the rules specified in the DataSource's audit configuration. This includes dropping fields that are marked audit: never, for example. See the client-side docs for the DataSource "audit" property for a full discussion of the options.
    This method is used by SmartClient's automatic auditing facility, but it can also be called from user code (eg, from a DMI) if you wish to leverage the framework's ability to generate audit records in accordance with the configuration rules, for some manual process.
    
    Parameters:
    
    req - DSRequest required to provide context essential to generating correct audit properties (for example, so we know the type of operation)
    
    inValues - The "base record" to provide an audit record for
    
    oldValues - The record as it was prior to updating, generally available from the request's oldValues. This parameter is only applicable to "update" operations; if it is not supplied for an update operation, we are unable to generate a fully correct audit record because we cannot populate the "changedFields" value
    
    Returns:
    
    a record populated with audit values, based on the base record
    
    Throws:
    
    java.lang.Exception
  - writeMultiAudits
```
protected void writeMultiAudits(java.util.List valueSets,
                                DSRequest originatingDSRequest)
                         throws java.lang.Exception
```
    Writes a collection of audit records to the audit DataSource associated with this DataSource. Is only applicable to suitable originating operations of type "add"; a "suitable" operation is one that added multiple records in a batch using the "multipleValues" strategy (scan the client-side documentation for "multiInsertStrategy"), and was for a dataSource that has no fields of type "sequence"
    Note, the framework will call this method automatically in the appropriate circumstances, as long as the "sql.multi.insert.allowAudit" flag is set to true in your server.properties file. Alternatively, you can call it manually from your own code.
    
    Parameters:
    
    valueSets - List of records to write audit records for
    
    originatingDSRequest - The "add" DSRequest that wrote the records we are going to audit. Required for essential context
    
    Throws:
    
    java.lang.Exception
  - shouldAutoStartTransaction
```
public boolean shouldAutoStartTransaction(DSRequest req,
                                          boolean ignoreExistingTransaction)
                                   throws java.lang.Exception
```
    Returns true if the parameter DSRequest should automatically start a new transaction, taking into account the DSRequest-specific override provided by DSRequest.setJoinTransaction(java.lang.Boolean), the transaction policy of the controlling RPCManager (if there is one), and autoJoinTransactions settings at the operationBinding, DataSource, dbName and global system levels
    This method is part of the Automatic Transactions feature, which is effective only in Power edition and above.
    
    Parameters:
    
    req - The DSRequest to check
    
    ignoreExistingTransaction - If true, indicates that we should not take into account any existing transaction for this RPCManager when deciding if a transaction should be autoStarted. This is useful if you want to know if a request would have started a new transaction if one hadn't already been started.
    
    Throws:
    
    java.lang.Exception
  - shouldAutoJoinTransaction
```
public boolean shouldAutoJoinTransaction(DSRequest dsRequest)
                                  throws java.lang.Exception
```
    Returns true if the parameter DSRequest should automatically join an existing transaction, taking into account the DSRequest-specific override provided by DSRequest.setJoinTransaction(java.lang.Boolean), the transaction policy of the controlling RPCManager (if there is one), and autoJoinTransactions settings at the operationBinding, DataSource, dbName and global system levels.
    This method is part of the Automatic Transactions feature, which is effective only in Power edition and above.
    
    Parameters:
    
    dsRequest - The DSRequest to check.
    
    Throws:
    
    java.lang.Exception
  - getAuditDataSource
```
public DataSource getAuditDataSource()
```
    This method returns the audit DataSource associated with this DataSource if it has the audit=true property set.
    The audit DataSource can only be accessed by ID if the original DataSource has been accessed first.
    
    Returns:
    
    The audit DataSource if audit was enabled, or null.
  - transformMultipleFields
```
public void transformMultipleFields(DSRequest req)
```
    Transforms the values for fields declared multiple:true in the incoming DSRequest. This allows advanced queries to take place on fields declared as multiple:true.
    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.
    
    Overrides:
    
    transformMultipleFields in class DataSource
    
    Parameters:
    
    req - the request to be transformed.
  - transformMultipleFields
```
public void transformMultipleFields(DSResponse res)
```
    Transform the values for fields declared multiple:true in a DSResponse.
    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.
    
    Overrides:
    
    transformMultipleFields in class DataSource
    
    Parameters:
    
    res - the DSResponse to be transformed.

Class BasicDataSource

Field Summary

Fields inherited from class com.isomorphic.datasource.DataSource

Method Summary

Methods inherited from class com.isomorphic.datasource.DataSource

Methods inherited from interface com.isomorphic.js.IToJSON

Method Detail

getProperty

getObjectProperty

getListProperty

getMapProperty

getAuditRecord

getAuditRecord

writeMultiAudits

shouldAutoStartTransaction

shouldAutoJoinTransaction

getAuditDataSource

transformMultipleFields

transformMultipleFields