JPADataSource (SmartClient Enterprise Server API 10.0p (2021-05-26))

com.isomorphic.datasource.DataSource
- com.isomorphic.datasource.BasicDataSource
- - com.isomorphic.jpa.JPADataSource

All Implemented Interfaces:

IToJSON, RPCManagerCompletionCallback

Direct Known Subclasses:

GAEJPADataSource, JPA2DataSource
```
public class JPADataSource
extends BasicDataSource
implements RPCManagerCompletionCallback
```
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_FETCH, OP_FILE_SOURCE, OP_GET_FILE, OP_HAS_FILE, OP_LIST_FILES, OP_REMOVE, OP_REMOVE_FILE, OP_RENAME_FILE, OP_SAVE_FILE, OP_UPDATE, OP_VALIDATE

Method Summary

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)`
`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.
`void`	`onFailure(boolean transactionFailed)` Rolls back current transaction.
`void`	`onFailure(RPCManager rpc, boolean transactionFailed)` Implementation of RPCManagerCompletionCallback.onFailure().
`void`	`onSuccess()` Commits current transaction.
`void`	`onSuccess(RPCManager rpc)` Implementation of RPCManagerCompletionCallback.onSuccess().

Methods inherited from class com.isomorphic.datasource.BasicDataSource
getAuditDataSource, getProperty, shouldAutoJoinTransaction, shouldAutoStartTransaction, transformMultipleFields, transformMultipleFields

Methods inherited from class com.isomorphic.datasource.DataSource
add, addDynamicDSGenerator, addDynamicDSGenerator, addDynamicDSGenerator, clearDynamicDSGenerators, executeClientExport, executeCustom, executeFileSource, fetch, fetch, 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, getListProperties, getListProperties, getPrimaryKey, getProperties, getProperties, getProperties, getPropertyJavaClass, getRecordXPath, getTransactionObject, getTransactionObject, hasFile, hasRecord, hasRecord, initialized, isModificationOperation, isServerOnly, listFiles, listFiles, remove, removeDynamicDSGenerator, removeDynamicDSGenerator, removeDynamicDSGenerator, removeFile, renameFile, saveFile, setEnumConstantProperty, setEnumOrdinalProperty, setEnumTranslateStrategy, setProperties, update, validate

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
```
    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.
    
    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.
    
    Returns:
    DSField field.
  - 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 metods, com.isomorphic.datasource.DataSource.transformMultipleFields(DSRequest) and com.isomorphic.datasource.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.
  - getTransactionObjectKey
```
public java.lang.String getTransactionObjectKey(boolean longForm)
```
  - onSuccess
```
public void onSuccess()
               throws java.lang.Exception
```
    Commits current transaction.
    
    Throws:
    
    java.lang.Exception - when commit fails.
  - onSuccess
```
public void onSuccess(RPCManager rpc)
               throws java.lang.Exception
```
    Implementation of RPCManagerCompletionCallback.onSuccess(). When participating in automatic transactions - commits transaction stored in connectionHolder object. If connectionHolder is not initialized (meaning we did not participate in automatic transaction) - commits current transaction.
    
    Specified by:
    
    onSuccess in interface RPCManagerCompletionCallback
    
    Parameters:
    rpc - RPCManager which manages transactions.
    
    Throws:
    
    java.lang.Exception - when commit fails.
  - onFailure
```
public void onFailure(boolean transactionFailed)
```
    Rolls back current transaction.
    
    Parameters:
    transactionFailed - boolean true if failure happened while committing current transaction; otherwise false.
  - onFailure
```
public void onFailure(RPCManager rpc,
             boolean transactionFailed)
               throws java.lang.Exception
```
    Implementation of RPCManagerCompletionCallback.onFailure(). When participating in automatic transactions - rolls back transaction stored in connectionHolder object. If connectionHolder is not initialized (meaning we did not participate in automatic transaction) - rolls back current transaction.
    
    Specified by:
    
    onFailure in interface RPCManagerCompletionCallback
    
    Parameters:
    rpc - RPCManager which manages transactions.
    transactionFailed - boolean true if at least one failure happened in a request that was being managed by a user-provided or automatic transaction; otherwise false.
    
    Throws:
    
    java.lang.Exception - when roll back fails.
  - increaseOpCount
```
public void increaseOpCount()
```
    Increases operations count by 1. Used to update statistics for Automatic Transactions.

Class JPADataSource

Field Summary

Fields inherited from class com.isomorphic.datasource.DataSource

Method Summary

Methods inherited from class com.isomorphic.datasource.BasicDataSource

Methods inherited from class com.isomorphic.datasource.DataSource

Methods inherited from interface com.isomorphic.js.IToJSON

Field Detail

BEAN_CLASS_PROPERTY

AUTO_DERIVE_PROPERTY

SCHEMA_BEAN_PROPERTY

ID_CLASS_PROPERTY

ESCAPE_CHARACTER

JPA_CONFIG_PROPERTY

configName

beanClass

beanName

idClass

strictSQLFiltering

USE_QUALIFIED_CLASS_NAME_PROPERTY

useQualifiedClassName

em

tx

shouldRollBackTransaction

connectionHolder

additionalFields

relatedUpdates

generateRelatedUpdates

Method Detail

init

deriveDS

getFieldNames

getField

execute

executeFetch

executeAdd

executeRemove

executeUpdate

escapeValueForFilter

markTransactionForRollBack

freeResources

getTransactionObjectKey

onSuccess

onSuccess

onFailure

onFailure

increaseOpCount