com.isomorphic.datasource

## Class BasicDataSource

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

- All Implemented Interfaces:
    IToJSON
  Direct Known Subclasses:
    AIDataSource, HibernateDataSource, JPADataSource, RestConnector, 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 inValues)` 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.
    `boolean` | `hasCustomDefaultFetchOperation()` Returns true if this dataSource declares a custom default fetch operation: that is, an `operationBinding` with `operationType "fetch"` and no declared `operationId`
    `boolean` | `hasCustomLogic()` Returns true if this dataSource declares either a `serverObject` or `serverScript` property (see the client-side docs for details of those two properties).
    `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, get1ManyRelationFields, getAuditChangedFieldsFieldName, getAuditRevisionFieldName, getAuditTimestampFieldName, getAuditTypeFieldName, getAuditUserFieldName, getDefaultDynamicDSGenerator, getDirectFields, getDynamicDSGenerators, getEnumConstantProperty, getEnumOrdinalProperty, getEnumTranslateStrategy, getField, getFieldNames, getFile, getFileAsInputStream, getFileAsString, getFileContentsField, getFileFormatField, getFileNameField, getFileTypeField, getID, getJoinDSName, getJoinDSName, getListProperties, getListProperties, getListProperty, getManyManyRelationFields, getMapProperty, getName, getNonIncludedFields, getObjectProperty, getOperationProperty, getPrimaryKey, getProperties, getProperties, getProperties, getProperty, getPropertyJavaClass, getRecordXPath, getRelatedDisplayRecord, getRelatedDisplayRecord, getRelatedDSName, getRelatedDSName, getRelatedTableAlias, getRelationFields, getTableName, getTransactionObject, getTransactionObject, has1ManyRelationFields, hasFile, hasManyManyRelationFields, hasRecord, hasRecord, hasRelationFields, initialized, is1ManyRelationField, isManyManyRelationField, isModificationOperation, isRelationField, isServerOnly, listFiles, listFiles, 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

    - #### getAuditRecord

          public java.util.Map getAuditRecord(DSRequest req,
                                              java.util.Map inValues)
                                       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.

    - #### hasCustomLogic

          public boolean hasCustomLogic()

      Returns true if this dataSource declares either a `serverObject` or `serverScript` property (see the client-side docs for details of those two properties). Note, you can also add custom logic to a DataSource by creating a custom subclass and overriding the `execute(()`method (for example), but this method does not take account of such customizations. If you need to know if a DataSource instance might have custom logic by virtue of being a subclass, you can use native Java approaches: either do an instanceof check, or override `hasCustomLogic()` in yout subclass and cause it to return true.``

    - #### hasCustomDefaultFetchOperation

          public boolean hasCustomDefaultFetchOperation()

      Returns true if this dataSource declares a custom default fetch operation: that is, an `operationBinding` with `operationType "fetch"` and no declared `operationId`