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:
    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

      `inInitState, 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_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.List` | `getListProperty(java.lang.String key)` Returns the value of the specified attribute as a List.
    `java.util.Map` | `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.

    - ### Methods inherited from class com.isomorphic.datasource.DataSource

      `add, addDynamicDSGenerator, addDynamicDSGenerator, addDynamicDSGenerator, clearDynamicDSGenerators, convertRelativeDates, convertRelativeDates, convertRelativeDates, convertRelativeDates, execute, executeAdd, executeClientExport, executeCustom, executeFetch, executeFileSource, executeRemove, executeUpdate, fetch, fetch, fetchById, fetchById, fetchSingle, fetchSingle, filter, filter, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, getAuditRevisionFieldName, getAuditTimestampFieldName, getAuditTypeFieldName, getAuditUserFieldName, getDefaultDynamicDSGenerator, getDynamicDSGenerators, getEnumConstantProperty, getEnumOrdinalProperty, getEnumTranslateStrategy, getField, getFieldNames, getFile, getFileAsInputStream, getFileAsString, getFileContentsField, getFileFormatField, getFileNameField, getFileTypeField, getID, getListProperties, getListProperties, getName, getPrimaryKey, getProperties, getProperties, getProperties, getPropertyJavaClass, getRecordXPath, getRelatedDisplayRecord, getRelatedDisplayRecord, 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, update, 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

      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>`

      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 java.util.Map 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)`

    - #### 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.