com.isomorphic.jpa

## Class JPADataSource

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

- All Implemented Interfaces:
    IToJSON
  Direct Known Subclasses:
    GAEJPADataSource, JPA2DataSource

      public class JPADataSource
      extends BasicDataSource

  Server side implementation of JPA 1.0 data source.

  This class supports search with advanced criteria.

  This class supports fields with `valueXPath` setting. Entity property is accessed (by priority):
  1. `valueXPath` - supports only simple XPath definitions: "property/subProperty/subSubProperty"
  2. `name` - most often used when data source field name is the same as entity property name
  Transaction management:
  - Operating under RPCManager (`DSRequest` has reference to `RPCManager`):
    - If participates in automatic transactions:
      - retrieves existing transaction from `RPCManager` (if exists);
      - starts new transaction (if not found in `RPCManager`);
    - If one transaction per operation is used - starts new transaction;
    - Registers itslef to `DSRequest.registerCallback()` for `onSuccess()`/ `onFailure()` execution to commit/roll back transaction;
    - Sets `DSRequest.setFreeOnExecute()` to `false` to postpone releasing of `EntityManager` avoiding lazy loading exceptions when creating JS response and traversing through persistent object tree;
    - Registers itslef to `RPCManager.registerFreeResourcesHandler()` for `freeResources()` execution to release `EntityManager`.
  - Operating without RPCManager:
    - starts new transaction;
    - commits/rolls back transaction and releases `EntityManager` if `DSRequest.setFreeOnExecute()` is set to `true` (default);
    - relies on calling code to call `onSuccess()`/`onFailure()` to commit/roll back transaction and to call `freeResources()` to release `EntityManager`.
      Example code for data source operation execution with manual transaction handling:

                        DSRequest req = new DSRequest("myDS", "fetch");
                        req.setFreeOnExecute(false);
                        DSResponse resp = req.execute();
                        List dataList = resp.getDataList();
                        //... traverse through persistent object tree
                        // Commit current transaction.
                        ((JPADataSource) r.getDataSource()).onSuccess();
                        // Release entity manager.
                        ((JPADataSource) r.getDataSource()).freeResources(req);

  Implementation is not thread-safe. Data source acquiring mechanism ensures that single instance of this class will be used in one thread only.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.Map` | `additionalFields` Holds list of additional fields requested by specific `DSRequest`.
    `static java.lang.String` | `AUTO_DERIVE_PROPERTY` Name of the data source definition property holding should data source be auto derived.
    `static java.lang.String` | `BEAN_CLASS_PROPERTY` Name of the data source definition property holding fully-qualified class name.
    `protected java.lang.Class` | `beanClass` Holds class from the DataSource definition.
    `protected java.lang.String` | `beanName` Holds bean name - simple class name with preceding underscore.
    `protected java.lang.String` | `configName` Holds config name - can be configured with "jpaConfig" parameter.
    `protected JPAConnectionHolder` | `connectionHolder` Holds connection information for Automatic Transactions.
    `protected javax.persistence.EntityManager` | `em` Holds entity manager for operations with underlying data.
    `static java.lang.Character` | `ESCAPE_CHARACTER` Holds character ('~') used to escape wild cards in 'like' clause.
    `protected java.lang.Boolean` | `generateRelatedUpdates` Holds value should related updates be generated.
    `static java.lang.String` | `ID_CLASS_PROPERTY` Name of the data source definition property holding fully-qualified class name for composite primary key.
    `protected java.lang.Class` | `idClass` Holds id class from the DataSource definition.
    `static java.lang.String` | `JPA_CONFIG_PROPERTY` Name of the JPA configuration name property.
    `protected java.util.List` | `relatedUpdates` Holds list of generated related updates.
    `static java.lang.String` | `SCHEMA_BEAN_PROPERTY` Name of the data source definition property holding should data source be auto derived from specified mapped entity.
    `protected boolean` | `shouldRollBackTransaction` Flag used to indicate that transaction should be rolled back.
    `protected boolean` | `strictSQLFiltering` If set to true, advanced filtering will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.
    `protected java.lang.Object` | `tx` Holds transaction object.
    `static java.lang.String` | `USE_QUALIFIED_CLASS_NAME_PROPERTY` Name of property specifying should fully-qualified class name be used in query string.
    `protected java.lang.Boolean` | `useQualifiedClassName` According to JPA specifications only simple class name can be used in queries.

    - ### 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 Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Map` | `deriveDS(java.lang.String schemaBean, java.lang.String id, boolean extended)` Creates data source configuration from specified fully qualified class name.
    `static java.lang.String` | `escapeValueForFilter(java.lang.Object value, char escapeChar)` Escapes characters "_" and "%" with specified character in value object.
    `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` | `executeFetch(DSRequest req)` This method is called by DataSource.execute() for "fetch" operations.
    `DSResponse` | `executeRemove(DSRequest dsRequest)` This method is called by DataSource.execute() for "remove" operations.
    `DSResponse` | `executeUpdate(DSRequest req)` This method is called by DataSource.execute() for "update" operations.
    `void` | `freeResources(DSRequest req)` Closes `EntityManager`.
    `DSField` | `getField(java.lang.String fieldName)` Returns `DSField` by specified name.
    `java.util.List` | `getFieldNames(boolean dropIgnored)` Returns combined list of data source configured and request configured field names.
    `java.lang.String` | `getTransactionObjectKey(boolean longForm)` Returns the key used to store the current transaction object for this DataSource and other DataSources of the same type and provider.
    `void` | `increaseOpCount()` Increases operations count by 1.
    `void` | `init(java.util.Map theConfig, DSRequest dsRequest)`
    `void` | `markTransactionForRollBack(DSResponse dsResponse)` Sets flag that current transaction should be rolled back.

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

      `getAuditDataSource, getListProperty, getMapProperty, getObjectProperty, getProperty, shouldAutoJoinTransaction, shouldAutoStartTransaction, transformMultipleFields, transformMultipleFields`

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

      `add, addDynamicDSGenerator, addDynamicDSGenerator, addDynamicDSGenerator, clearDynamicDSGenerators, convertRelativeDates, convertRelativeDates, convertRelativeDates, convertRelativeDates, executeClientExport, executeCustom, executeFileSource, 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, 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`

- - ### Field Detail

    - #### BEAN_CLASS_PROPERTY

          public static final java.lang.String BEAN_CLASS_PROPERTY

      Name of the data source definition property holding fully-qualified class name.
      See Also:
        Constant Field Values

    - #### AUTO_DERIVE_PROPERTY

          public static final java.lang.String AUTO_DERIVE_PROPERTY

      Name of the data source definition property holding should data source be auto derived.
      See Also:
        Constant Field Values

    - #### SCHEMA_BEAN_PROPERTY

          public static final java.lang.String SCHEMA_BEAN_PROPERTY

      Name of the data source definition property holding should data source be auto derived from specified mapped entity.
      See Also:
        Constant Field Values

    - #### ID_CLASS_PROPERTY

          public static final java.lang.String ID_CLASS_PROPERTY

      Name of the data source definition property holding fully-qualified class name for composite primary key.
      See Also:
        Constant Field Values

    - #### ESCAPE_CHARACTER

          public static final java.lang.Character ESCAPE_CHARACTER

      Holds character ('~') used to escape wild cards in 'like' clause. Avoid using backslash '\' or dollar sign '$' because it is often used in databases as DB escape or wild card characters.

    - #### JPA_CONFIG_PROPERTY

          public static final java.lang.String JPA_CONFIG_PROPERTY

      Name of the JPA configuration name property.
      See Also:
        Constant Field Values

    - #### configName

          protected java.lang.String configName

      Holds config name - can be configured with "jpaConfig" parameter. Holds empty string for default configuration.

    - #### beanClass

          protected java.lang.Class beanClass

      Holds class from the DataSource definition.

    - #### beanName

          protected java.lang.String beanName

      Holds bean name - simple class name with preceding underscore. Defaults to "_beanName" if class is anonymous. Used in creating query.

    - #### idClass

          protected java.lang.Class idClass

      Holds id class from the DataSource definition.

    - #### strictSQLFiltering

          protected boolean strictSQLFiltering

      If set to true, advanced filtering will follow SQL99 behavior for dealing with NULL values, which is often counter-intuitive to users.

    - #### USE_QUALIFIED_CLASS_NAME_PROPERTY

          public static final java.lang.String USE_QUALIFIED_CLASS_NAME_PROPERTY

      Name of property specifying should fully-qualified class name be used in query string.
      See Also:
        Constant Field Values

    - #### useQualifiedClassName

          protected java.lang.Boolean useQualifiedClassName

      According to JPA specifications only simple class name can be used in queries. Some providers follows these specs strictly (for example EclipseLink). Some providers allows using fully-qualified class name usage (for example Hibernate, Datanucleus). Setting defaults to `false` - simple class name usage. To resolve class name collisions this setting can be set to `true` (should be used with provider supporting fully-qualified class name usage).

    - #### em

          protected javax.persistence.EntityManager em

      Holds entity manager for operations with underlying data.

    - #### tx

          protected java.lang.Object tx

      Holds transaction object.

    - #### shouldRollBackTransaction

          protected boolean shouldRollBackTransaction

      Flag used to indicate that transaction should be rolled back.

    - #### connectionHolder

          protected JPAConnectionHolder connectionHolder

      Holds connection information for Automatic Transactions.

    - #### additionalFields

          protected java.util.Map additionalFields

      Holds list of additional fields requested by specific `DSRequest`.

    - #### relatedUpdates

          protected java.util.List relatedUpdates

      Holds list of generated related updates. Usage: set this field to empty list before executing `setProperties()`; subsequent calls to `setRelationFieldValue()` will add `DSResponse` objects for every change in related data sources.

    - #### generateRelatedUpdates

          protected java.lang.Boolean generateRelatedUpdates

      Holds value should related updates be generated. (Re)initialized on every `execute()` call. `true` - related updates will be generated; `false` - related updates will not be generated; `null` - related updates will be generated only for "add" and "update" operations, related updates will not be generated for "remove" operation.

  - ### Method Detail

    - #### init

          public void init(java.util.Map theConfig,
                           DSRequest dsRequest)
                    throws java.lang.Exception

      Overrides:
        `init` in class `BasicDataSource`
      Throws:
        `java.lang.Exception`

    - #### deriveDS

          public java.util.Map deriveDS(java.lang.String schemaBean,
                                        java.lang.String id,
                                        boolean extended)

      Creates data source configuration from specified fully qualified class name.
      Parameters:
        `schemaBean` - `String` Fully qualified class name.
        `id` - `String` Id for newly created data source.
        `extended` - `boolean` Extended properties will be captured if set to `true`.
      Returns:
        `Map<String, Object>` created data source configuration or `null` if it can not be created.

    - #### getFieldNames

          public java.util.List getFieldNames(boolean dropIgnored)

      Returns combined list of data source configured and request configured field names.
      Overrides:
        `getFieldNames` in class `DataSource`
      Parameters:
        `dropIgnored` - `boolean` `true` - ignored fields are dropped; `false` - ignored fields are included;
      Returns:
        `List` field names.

    - #### getField

          public DSField getField(java.lang.String fieldName)

      Returns `DSField` by specified name. First checks data source configured fields. Checks request configured fields if it is not found within data source configured fields. Returns `null` if `fieldName` parameter is `null` or field is not found.
      Overrides:
        `getField` in class `BasicDataSource`
      Parameters:
        `fieldName` - the name of the field whose definition you want
      Returns:
        `DSField` field.
      See Also:
        `DSField`

    - #### execute

          public DSResponse execute(DSRequest req)
                             throws java.lang.Exception

      Description copied from class: `DataSource`
      This method carries out the actual processing of a DataSource request. It can be overridden to provide centralized logic that applies to all operation types (such as transaction management, for example), or to implement special validation rules that cannot be handled by the built-in validation system. Generally, however, it is more appropriate to override the method specific to the operationType - executeFetch(), executeRemove(), executeAdd(), executeUpdate() or executeCustom(). Note that you must call the validate() method to retain correct validation behavior if you override this method and do not invoke super() This method is also the place where the transform happens if dataSourceField.multipleStorage is used. The transform is performed by two methods, `DataSource.transformMultipleFields(DSRequest)` and `DataSource.transformMultipleFields(DSResponse)`.
      Overrides:
        `execute` in class `DataSource`
      Parameters:
        `req` - The DSRequest object representing this operation
      Returns:
        A valid DSResponse
      Throws:
        `java.lang.Exception`

    - #### executeFetch

          public DSResponse executeFetch(DSRequest req)
                                  throws java.lang.Exception

      Description copied from class: `DataSource`
      This method is called by DataSource.execute() for "fetch" operations. It is the appropriate override point if you wish to provide custom handling of a "fetch".
      Overrides:
        `executeFetch` in class `DataSource`
      Parameters:
        `req` - The DSRequest object representing this operation
      Returns:
        A valid DSResponse
      Throws:
        `java.lang.Exception`

    - #### executeAdd

          public DSResponse executeAdd(DSRequest req)
                                throws java.lang.Exception

      Description copied from class: `DataSource`
      This method is called by DataSource.execute() for "add" operations. It is the appropriate override point if you wish to provide custom handling of an "add".
      Overrides:
        `executeAdd` in class `DataSource`
      Parameters:
        `req` - The DSRequest object representing this operation
      Returns:
        A valid DSResponse
      Throws:
        `java.lang.Exception`

    - #### executeRemove

          public DSResponse executeRemove(DSRequest dsRequest)
                                   throws java.lang.Exception

      Description copied from class: `DataSource`
      This method is called by DataSource.execute() for "remove" operations. It is the appropriate override point if you wish to provide custom handling of a "remove".
      Overrides:
        `executeRemove` in class `DataSource`
      Parameters:
        `dsRequest` - The DSRequest object representing this operation
      Returns:
        A valid DSResponse
      Throws:
        `java.lang.Exception`

    - #### executeUpdate

          public DSResponse executeUpdate(DSRequest req)
                                   throws java.lang.Exception

      Description copied from class: `DataSource`
      This method is called by DataSource.execute() for "update" operations. It is the appropriate override point if you wish to provide custom handling of an "update".
      Overrides:
        `executeUpdate` in class `DataSource`
      Parameters:
        `req` - The DSRequest object representing this operation
      Returns:
        A valid DSResponse
      Throws:
        `java.lang.Exception`

    - #### escapeValueForFilter

          public static java.lang.String escapeValueForFilter(java.lang.Object value,
                                                              char escapeChar)

      Escapes characters "_" and "%" with specified character in value object. Specified escape character is escaped (doubled) as well. Empty string is returned if value object is null.
      Parameters:
        `value` - `Object` Value which should be escaped.
        `escapeChar` - `char` escape character.
      Returns:
        `String` Escaped string value.

    - #### markTransactionForRollBack

          public void markTransactionForRollBack(DSResponse dsResponse)

      Sets flag that current transaction should be rolled back. If `DSResponse` is provided - sets it's status to failure.
      Parameters:
        `dsResponse` - `DSResponse` status will be set to failure if provided. Can be `null`.

    - #### freeResources

          public void freeResources(DSRequest req)

      Closes `EntityManager`. When participating in automatic transactions - closes `EntityManager` stored in `connectionHolder` object. If `connectionHolder` is not initialized (meaning we did not participate in automatic transaction) - closes current `EntityManager`.
      Overrides:
        `freeResources` in class `DataSource`

    - #### getTransactionObjectKey

          public java.lang.String getTransactionObjectKey(boolean longForm)

      Description copied from class: `DataSource`
      Returns the key used to store the current transaction object for this DataSource and other DataSources of the same type and provider. You can use this value to retrieve the object itself from the current RPCManager's attrbute map; can't see why user code would need to do this, so not doc'ing externally for now. You will need to override this method in subclasses if your subclass is capable of dealing simulatenously with multiple providers - for example, SQLDataSource, which can, eg, have an instance connected to MySQL and an instance connected to Oracle existing at the same time (they would be different DataSources, of course, but they would both be SQLDataSource instances)

      This method is part of the Automatic Transactions feature, which is effective only in Power edition and above.

      Overrides:
        `getTransactionObjectKey` in class `DataSource`

    - #### increaseOpCount

          public void increaseOpCount()

      Increases operations count by 1. Used to update statistics for Automatic Transactions.