Class: com.sybase.djc.ant.PersistentObjectProperty (Persistent Object Property) EAServer 6.3 Help
Description This property is used to configure object-relational mapping for a persistent object (entity class) that is generated during deployment of EJB entity beans.
Configuration

Configuration is achieved using an XML (Ant) configuration script, such as the following: 

<project name="ejbjar-example-user">
  <import file="ant-config-tasks.xml"/>
  <target name="configure-user">
    <setProperties component="ejb.components.example.CustomerInventory">
      <persistentObject
        table="cust_inv"
        isolationLevel="RepeatableRead"
        selectWithUpdateLock="true"
        />
    </setProperties>
  </target>
</project>
This example assumes the prior deployment of an EJB-JAR file named example.jar. The above script would be placed in file ejbjar-example-user.xml in the config directory of your EAServer installation. To run the script, assuming that the bin directory of your EAServer installation is in the PATH, you would use one of the the following commands: 
recompile ejbjar-example-user      (Windows)

recompile.sh ejbjar-example-user   (Unix / Linux)

Alternatively, the above script can be named sybase-ejbjar-config.xml and placed alongside ejb-jar.xml in the META-INF directory inside an EJB-JAR file (prior to deployment).

Note: you can define multiple properties, for multiple components, in the same configuration script.

Nested Properties allowLocalCacheReads, allowVerifyWithCache, cacheChildren, cacheLock, cacheLockTimeout, cacheSize, cacheTimeout, dataSource, deferDelete, deferInsert, deferUpdate, deleteStatement, distributedCache, flushOnFind, indexCreator, insertStatement, isolationLevel, keyGenerator, lockDataRows, parentVersion, selectView, selectWithSharedLock, selectWithUpdateLock, table, tableCreator, tableVersion, timestampColumn, touchColumn, updateStatement, verifyStatement, versionColumn

Property: allowLocalCacheReads (Allow Local Cache Reads)
Description When using a distributed cache, this property enables read operations from the local cache (whereas commit-time verify operations and changes are issued to the distributed cache). Use of this property might result in transactions that must to be retried due to commit-time verification failure, however when most access to a given data item is from a single cluster member, verify failures are unlikely and this property may help to improve performance by reducing inter-node communication.
Only Used If Property distributedCache is not empty.
Default Value false
Legal Values false, true

Property: allowVerifyWithCache (Allow Verify With Cache)
Description When using a cache, depending on the isolationLevel a commit-time verification query might need be sent to the database. If a database trigger can be created to notify the cache (before DB transaction commits) whenever a row is updated or deleted, then full consistency can be guaranteed even if verification is performed against the cache. If more than one application server process accesses the database, then either:
  • The database trigger must notify all servers, or
  • The database trigger must notify one server in a cluster (where distributedCache is used).

This property allows verification against the cache for read-only transactions. Transactions that issue updates will still perform verification queries against the database. The key advantage of this property is to avoid communications with the database server for read-only transactions using cached data, while retaining full consistency.

Two mechanisms are available for database triggers to notify the cache when a row is inserted or updated.

  1. TDS (Tabular Data Stream) RPC notification. This is available with Sybase ASE databases. To configure:

    • Create an entry (e.g. with name "EAS") in your Sybase sql.ini (or interfaces) file that refers to the JTDS handler of your selected EAServer instance.
      • The default JTDS handler of EAServer is port 2005.
      • Multiple "query" entries can be used to support notification failover in a cluster, if you are using a distributed cache.

    • Use sp_addserver to register the EAServer instance with Sybase ASE, e.g. 
              sp_addserver EAS, null, eas
    • From your database trigger(s) (for delete and update) notify the cache to flush an entry using the cm_flush stored procedure, e.g. 
              exec eas...cm_flush "cache-name", @key
      where the variable @key refers to the key for the entry you wish to flush. Note: flush keys must be strings or numbers. Therefore "allowVerifyWithCache" cannot currently be used for entities with composite keys.

  2. Notification via the REST Service Invoker (using HTTP POST). This requires your database server to be able to send simple HTTP requests to the cache. Oracle and Sybase SQL Anywhere (and some other database servers) provide facilities for making HTTP calls from database triggers. The URL for flushing cache entries using HTTP POST with form data parameters is: 
            http://my-host:8000/rest/protected/text/sql.CacheManager.flush
    where the required form data parameters are "cacheName" and "cacheKey". Alternatively a simple XML request can be sent to the URL: 
            http://my-host:8000/rest/protected/xml-1.0/sql.CacheManager.flush
    where the HTTP request content is: 
            <flushRequest>
          <cacheName>cache-name</cacheName>
          <cacheKey>key-value</cacheKey>
        </flushRequest>
    In either case the HTTP connection must be made using HTTP basic authentication. The predefined username "cm-flush@system" (which can be encoded as "cm-flush$system" within an HTTP URL) can be used for this purpose. Use the "set-password" script to configure a password for this username.

    Note: HTTP GET using query parameters can be used instead of HTTP POST.

Note: the "cache-name" for an entity "MyEntity" in an EJB-JAR named "MyMymodule" is "mymodule.MyEntity". If in doubt, check your server log on startup for "Registering object cache" messages.

See also: REST Service.

Default Value false
Legal Values false, true

Property: cacheChildren (Cache Children)
Description When query methods refer to this entity using the parentVersion property, the query methods must also be explicitly referenced by this entity. The syntax of this property is a comma-separated list of "ChildEntity.QueryName", e.g. "Order.findByCustomer".

Property: cacheChildren (Cache Children)
Description When query methods refer to this entity using the parentVersion property, the query methods must also be explicitly referenced by this entity. The syntax of this property is a comma-separated list of "ChildEntity.QueryName", e.g. "Order.findByCustomer".

Property: cacheLock (Cache Lock)
Description When the name of the selected isolationLevel ends with "Cache", this property determines whether exclusive locks should be used to ensure that only one transaction at a time can access any cache entry. The purpose of this property is to permit the use of caching with entities that have some level of update contention. This property should not be relied upon to ensure exclusive access to the underlying database table rows. It is best used in combination with optimistic concurrency control (versionColumn).
Default Value false
Legal Values false, true

Property: cacheLockTimeout (Cache Lock Timeout)
Description The number of seconds that a transaction will wait when trying to obtain a lock. If a lock is not acquired in this period, the transaction will be rolled back.
Only Used If Property cacheLock has the value "true".
Default Value 10
Minimum Value 0
Maximum Value 2147483647

Property: cacheSize (Cache Size)
Description The maximum number of database rows that will be held in local cache. To avoid overflow, rows are removed from cache using a least-recently-used (LRU) discard strategy.
Default Value 1000
Minimum Value 0
Maximum Value 2147483647

Property: cacheTimeout (Cache Timeout)
Description The maximum number of seconds that a row stored in cache will be considered valid. This property should not be used to attempt to control the cache size, because invalid rows are only discarded from cache when an attempt is made to access them. A value of zero is interpreted as an infinite timeout.
Default Value 0
Minimum Value 0
Maximum Value 2147483647

Property: dataSource (Data Source)
Description Name of the data source for the database in which the table is lcoated.

Property: deferDelete (Defer Delete)
Description Indicates whether SQL delete statements will be deferred (and batched) until transaction commit time. Only used if the data source is configured to use an optimized driver.
Default Value true
Legal Values false, true

Property: deferInsert (Defer Insert)
Description Indicates whether SQL insert statements will be deferred (and batched) until transaction commit time. Only used if the data source is configured to use an optimized driver.
Default Value true
Legal Values false, true

Property: deferUpdate (Defer Update)
Description Indicates whether SQL update statements will be deferred (and batched) until transaction commit time. Only used if the data source is configured to use an optimized driver.
Default Value true
Legal Values false, true

Property: deleteStatement (Delete Statement)
Description A SQL statement to be used for deleting a row from the database table for this entity. If this requires multiple statements, they should be separated by double-semicolon ";;". Persistent fields may be referenced in the SQL statement as ":myFieldName" or ":old.myFieldName". If no SQL statement is specified, the persistence manager will generate a default SQL statement.

Example: "delete from my_cust where cust_id = :id"

Note: it is permitted to use the JDBC "{call ...}" escape syntax to utilize database stored procedures.

Property: distributedCache (Distributed Cache)
Description Name of a distributed cache to be used if the isolationLevel property is cache-enabled. Distributed caches generally will not perform as well as local caches, but offer the advantages of being able to hold more objects and being able to survive the failure of cluster members.

Property: flushOnFind (Flush On Find)
Description Indicates whether deferred SQL delete, insert and update statements should be flushed to the database whenever a query method is invoked. See also: deferDelete, deferInsert, deferUpdate.
Default Value true
Legal Values false, true

Property: indexCreator (Index Creator)
Description A SQL statement to be used for creating any non-primary indexes for the database table. If this requires multiple statements, they should be separated by double-semicolon ";;".

Example: "create index my_cust_name_index on my_cust (cust_name)"

Note: this property is only used if the persistence manager also creates the table.

See also: tableCreator.

Property: insertStatement (Insert Statement)
Description A SQL statement to be used for inserting a row into the database table for this entity. If this requires multiple statements, they should be separated by double-semicolon ";;". Persistent fields may be referenced in the SQL statement as ":myFieldName" or as ":new.myFieldName". If no SQL statement is specified, the persistence manager will generate a default SQL statement.

Example: "insert into my_cust (cust_id, cust_name, cust_balance) values (:id, :name, :balance)"

Note: it is permitted to use the JDBC "{call ...}" escape syntax to utilize database stored procedures.

Property: isolationLevel (Isolation Level)
Description Specifies a default logical isolation level for all queries issued by the persistence manager for this entity class. A logical isolation level is distinct from the sqlIsolationLevel that is applied to any JDBC database connections that are participating in the transaction. Typically the SQL isolation level is ReadCommitted, and for some entity classes or query methods a higher isolation level is requested.

This can be overridden (raised or lowered) on a per-query basis by using the isolationLevel query method property.

Note that if the isolation level ends with "Cache", it applies only to the findByPrimaryKey query. Any other queries will use a default isolation level without the "Cache" suffix. Use explicit per-query isolation levels to enable caching for queries other than findByPrimaryKey.

The available isolation levels and their interpretations are:

  • ReadCache

    Queries are satisfied by reading from the local cache if possible. Otherwise data is loaded from the remote database.

    Not recommended, as use of this isolation level can result in "lost" updates. Instead, use ReadCacheVerifyUpdates.

  • ReadCacheVerifyUpdates

    Queries are satisfied by reading from the local cache if possible. Otherwise data is loaded from the remote database. If the entity is changed or removed, the corresponding SQL update/delete will verify that the data was not changed after it was loaded from the DBMS.

    This setting is suitable for cases where it is acceptable for a read-only transaction to use stale cache data. To limit the use of stale data, you can specify a cache timeout for the local cache.

  • ReadCommitted

    Queries are satisfied by reading from the remote database.

    If the entity is changed or removed, the corresponding SQL update/delete does not verify that the data was not changed after it was loaded from the DBMS.

    Not recommended, as use of this isolation level can result in "lost" updates. Instead, use ReadCommittedVerifyUpdates.

  • ReadCommittedVerifyUpdates

    Queries are satisfied by reading from the remote database. If the entity is changed or removed, the corresponding SQL update/delete verifies that the data was not changed after it was loaded from the DBMS.

    This setting provides a good balance of data integrity and performance. However, for some application data models, the maintenance of full data integrity requires a higher isolation level such as RepeatableRead.

  • ReadCommittedWithCache

    Queries are satisfied by reading from the local cache if possible. Otherwise data is loaded from the remote database. If the entity is changed or removed, the corresponding SQL update/delete does not verify that the data was not changed after it was loaded from the DBMS. Otherwise, for read-only access, and only if data was loaded from the local cache, a commit-time verify step ensures that the data has not changed since it was originally loaded from the DBMS. This ensures that any cached data that was used is still current at commit time, but does not prevent concurrent or conflicting updates.

    This setting is not recommended, as it can result in lost updates. Instead, use ReadCommittedVerifyUpdatesWithCache.

  • ReadCommittedVerifyUpdatesWithCache

    Queries are satisfied by reading from the local cache if possible. Otherwise data is loaded from the remote database. If the entity is changed or removed, the corresponding SQL update/delete verifies that the data was not changed after it was loaded from the DBMS. Otherwise, for read-only access, and only if data was loaded from the local cache, a commit-time verify step ensures that the data has not changed since it was originally loaded from the DBMS. This ensures that any cached data that was used is still current at commit time. This setting does not prevent concurrent updates but does prevent conflicting updates.

    This setting is suitable for cases where it is not acceptable for a read-only transaction to use stale data, and where commit-time verification is cheaper than satisfying queries from the DBMS. In particular, where tableVersion is used, or where a JDBC/JIT driver wrapper is used (the JIT driver wrappers can batch verification statements together at commit-time).

  • RepeatableRead

    Queries are satisfied by reading from the remote database. If the entity is changed or removed, the corresponding SQL update/delete will verify that the data was not changed after it was loaded from the DBMS. Otherwise, for read-only access, a commit-time verify step ensures that the data has not changed since it was loaded from the DBMS. If pessimistic locking is enabled with the selectWithSharedLock or selectWithUpdateLock property, verification is skipped as the shared/exclusive locks that are obtained at load time will prevent conflicting updates.

    This setting is suitable for cases where uncontrolled concurrent updates may result in data integrity problems (even for read-only access). RepeatableReadWithCache may provide better performance, although if many transactions are updating the same rows, pessimistic locking with no cache is probably preferable.

  • RepeatableReadWithCache

    Queries are satisfied by reading from the local cache if possible. Otherwise data is loaded from the remote database. If the entity is changed or removed, the corresponding SQL update/delete verifies that the data was not changed after it was loaded from the DBMS. Otherwise, for read-only access, a commit-time verify step ensures that the data has not changed since it was originally loaded from the DBMS.

    This setting is suitable for cases where uncontrolled concurrent updates may result in data integrity problems (even for read-only access), where it is not acceptable for a read-only transaction to use stale cache data, and where commit-time verification is cheaper than satisfying queries from the DBMS. In particular, where tableVersion is used, or where a JDBC/JIT driver wrapper is used (the JIT driver wrappers can batch verification statements together at commit-time).

  • Serializable

    Like RepeatableRead, except guarantees that the set of rows satisfying the query cannot change before the current transaction completes.

    Note: this isolation level is not supported when using Oracle databases. Use RepeatableRead instead, or add additional application-level versioning.

  • SerializableWithCache

    Like RepeatableReadWithCache, except guarantees that the set of rows satisfying the query cannot change before the current transaction completes.

    Note: this isolation level is not supported when using Oracle databases. Use RepeatableRead instead, or add additional application-level versioning.

Property: keyGenerator (Key Generator)
Description This property can be used to specify the use of auto-generated keys if the entity class has an integer-typed primary key field (including java.math.BigDecimal with scale of zero). The available formats for this property are:
FormatDescription
sequence seq-nameOracle sequence
select @@identitySybase-style identity column
key-table.key-column += batch-size Key generator table, e.g. "cust_key.next_id += 100"

Property: lockDataRows (Lock Data Rows)
Description Enable this if you using a Sybase database and you want the "lock datarows" clause to be added to the table creation SQL (only used for automatic table creation).
Default Value false
Legal Values false, true

Property: parentVersion (Parent Version)
Description Allows cached entities to be associated with a particular version of a "parent" object, while guaranteeing a high level of transactional consistency. The syntax of this property is "ParentEntity[ForeignKey].version", The parent entity refers to another entity which uses versionColumn. The foreign key is a persistent field of the current entity which is assumed to be the primary key for the corresponding parent object. This is particularly useful in combination with an isolationLevel of RepeatableReadWithCache or SerializableWithCache.

As an example, a foreign key field "custId" declared on an "Order" entity could be associated with a parent "Customer" entity by using the parent version expression "Customer[custId].version".

Property: selectView (Select View)
Description If persistent fields of the entity class are mapped to multiple tables, the persistence manager will create a view that brings together all of the persistent fields from the various tables. You can use this property to specify the name of the generated database view. By default, the view name is "cmp_sv_table", where table is the main table name.

See also: table.

Property: selectWithSharedLock (Select With Shared Lock)
Description Enable this to give a hint for the persistence manager to acquire a shared lock on each row retrieved from the database table.

Note: if the selected isolationLevel does not require that rows be protected from concurrent updates, this property may be ignored. You should therefore always use the isolationLevel property to express your data consistency requirements.

Default Value false
Legal Values false, true

Property: selectWithUpdateLock (Select With Update Lock)
Description Enable this to give a hint for the persistence manager to acquire an exclusive lock on each row retrieved from the database table.

Note: if the selected isolationLevel does not require that rows be protected from concurrent updates, this property may be ignored. You should therefore always use the isolationLevel property to express your data consistency requirements.

See also: touchColumn.

Default Value false
Legal Values false, true

Property: table (Table)
Description Name of the database table for this entity class. If the database requires quoted identifiers, this should be enabled using the useQuotedIdentifiers property. If this entity class is mapped to multiple tables, use this property to name the "main" table, and use the table persistent field property or the joinTable persistent field property to specify column mapping information for secondary or join tables.

Property: tableCreator (Table Creator)
Description A SQL statement to be used for creating the database table and its primary index if the table doesn't already exist. If this requires multiple statements, they should be separated by double-semicolon ";;".

Example: "create table my_cust (cust_id integer not null, cust_balance decimal(20,4) not null, cust_name varchar(50) not null, primary key (cust_id))"

See also: indexCreator.

Property: tableVersion (Table Version)
Description The name of a version table and version column (e.g. "ref_tv.version") representing a single row which holds a version number that is incremented by the persistence manager whenever any row is deleted, inserted or updated in the database table. This is useful for reducing the overheads of version checking when using optimistic concurrency control for database tables that are infrequently updated. It is particularly useful in combination with an isolationLevel of RepeatableReadWithCache or SerializableWithCache.

If, due to triggers or other database-specific mechanisms, this "table version" column is also updated when ad-hoc updates are made to the database table by a client which is not performing version management, then the trigger or other mechanism must be disabled when the persistence manager is in use. This disabling is needed to prevent an update issued by the persistence manager resulting in a double increment of the "table version" column (one time by the persistence manager and one time by the database server).

See also: disableTriggers (Data Source Property).

Property: timestampColumn (Timestamp Column)
Description The name of a column that holds a row timestamp which is automatically set (or changed) by the database server whenever a row is inserted (or updated).

Property: touchColumn (Touch Column)
Description The name of an integer-typed database column that can be "touched" (updated) in order to acquire an exclusive lock on a database row. This is only needed if you use selectWithUpdateLock and the database does not have builtin support for acquiring exclusive locks at select time (e.g. Sybase ASE).

Property: updateStatement (Update Statement)
Description A SQL statement to be used for updating a row in the database table for this entity. If this requires multiple statements, they should be separated by double-semicolon ";;". Persistent fields may be referenced in the SQL statement as ":myFieldName", ":old.myFieldName", or ":new.myFieldName". If no SQL statement is specified, the persistence manager will generate a default SQL statement.

Example: "update my_cust set cust_name = :new.name, cust_balance = :new.balance where cust_id = :id and cust_balance = :old.balance and cust_name = :old.name"

Note: it is permitted to use the JDBC "{call ...}" escape syntax to utilize database stored procedures.

Property: verifyStatement (Verify Statement)
Description A SQL statement to be used for verifying that a row in the database table for this entity has not changed. If this requires multiple statements, they should be separated by double-semicolon ";;". Persistent fields may be referenced in the SQL statement as ":myFieldName", or ":old.myFieldName". If no SQL statement is specified, the persistence manager will generate a default SQL statement.

Example: "select count(*) from my_cust where cust_id = :id and cust_balance = :old.balance and cust_name = :old.name"

Note: it is permitted to use the JDBC "{call ...}" escape syntax to utilize database stored procedures.

Property: versionColumn (Version Column)
Description The name of an integer-typed column that holds a row version which is automatically set (or changed) by the persistence manager whenever a row is inserted (or updated).

If, due to triggers or other database-specific mechanisms, this version column is also updated when ad-hoc updates are made to the database table by a client which is not performing version management, then the trigger or other mechanism must be disabled when the persistence manager is in use. This disabling is needed to prevent an update issued by the persistence manager resulting in a double increment of the version column (one time by the persistence manager and one time by the database server).

See also: disableTriggers (Data Source Property).