bea.com | products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 
Search

Programming WebLogic Enterprise JavaBeans

 Previous Next Contents Index View as PDF  

WebLogic Server Container-Managed Persistence Service - Advanced Features

The following sections describe the advanced features of the container-managed persistence (CMP) service available with the WebLogic Server EJB container, where "advanced" refers to performance-related or special-purpose features. For a discussion of basic CMP features, see WebLogic Server Container-Managed Persistence Service - Basic Features.

Performance-related features:

Special-purpose features:

 


Read-Only Multicast Invalidation

Read-only multicast invalidation is an efficient means of invalidating cached data.

Invalidate a read-only entity bean by calling the following invalidate() method on either the CachingHome or CachingLocalHome interface:

Figure 6-1 Sample code showing CachingHome and CachingLocalHome interfaces

package weblogic.ejb;
public interface CachingHome {
	public void invalidate(Object pk) throws RemoteException;
public void invalidate (Collection pks) throws RemoteException;
public void invalidateAll() throws RemoteException;
public interface CachingLocalHome {
	public void invalidate(Object pk) throws RemoteException;
public void invalidate (Collection pks) throws RemoteException;
public void invalidateAll() throws RemoteException
}

The following example codes shows how to cast the home to CachingHome and then call the method:

Figure 6-2 Sample code showing how to cast the home and call the method

import javax.naming.InitialContext; 
import weblogic.ejb.CachingHome;
Context initial = new InitialContext(); 
Object o = initial.lookup("CustomerEJB_CustomerHome");
CustomerHome customerHome = (CustomerHome)o;
CachingHome customerCaching = (CachingHome)customerHome; 
customerCaching.invalidateAll();

When the invalidate() method is called, the read-only entity beans are invalidated in the local server, and a multicast message is sent to the other servers in the cluster to invalidate their cached copies. The next call to an invalidated read-only entity bean causes ejbLoad to be called. ejbLoad() reads the most current version of the persistent data from the underlying datastore

WebLogic Server calls the invalidate() method after the transaction update has completed. If the invalidation occurs during a transaction update, the previous version may be read if the isolation level does not permit reading uncommitted data.

 


Read-Mostly Pattern

WebLogic Server does not support a read-mostly cache strategy setting in weblogic-ejb-jar.xml. However, if you have EJB data that is only occasionally updated, you can create a "read-mostly pattern" by implementing a combination of read-only and read-write EJBs.

For an example of the read-mostly pattern, see the Read Mostly example in your WebLogic Server distribution:

%SAMPLES_HOME%/server/config/examples/ejb/extensions/readMostly

WebLogic Server provides an automatic invalidate() method for the Read-Mostly pattern. With this pattern, Read-Only entity bean and a Read-Write entity bean are mapped to the same data. To read the data, you use the Read-Only entity bean; to update the data, you use the Read-Write entity bean.

In a read-mostly pattern, a read-only entity EJB retrieves bean data at intervals specified by the read-timeout-seconds deployment descriptor element specified in the weblogic-ejb-jar.xml file. A separate read-write entity EJB models the same data as the read-only EJB, and updates the data at required intervals.

When creating a read-mostly pattern, use the following suggestions to reduce data consistency problems:

In a WebLogic Server cluster, clients of the read-only EJB benefit from using cached EJB data. Clients of the read-write EJB benefit from true transactional behavior, because the read-write EJB's state always matches the state of its data in the underlying datastore. See Entity EJBs in a Cluster for more information.

 


Relationship Caching with Entity Beans

Relationship caching improves the performance of entity beans by loading related beans into the cache and avoiding multiple queries by issuing a join query for the related bean.

Specifying Relationship Caching

To specify relationship caching:

  1. Set the relationship-caching deployment descriptor element in the bean's weblogic-cmp-rdbms-jar.xml file.
  2. For instructions on specifying deployment descriptors, see Specifying and Editing the EJB Deployment Descriptors.

    The XML code shown below specifies entity beans with the following relationships

    customerBean

    has a one-to-many relationship with

    accountBean

    accountBean

    has a one-to-one relationship with

    addressBean

    customerBean

    has a one-to-one relationship with

    phoneBean

The following XML example code shows how to specify relationship-caching:

<relationship-caching>
<caching-name>cacheMoreBeans</caching-name>
<caching-element>
<cmr-field>accounts<</cmr-field>
<group-name>acct_group</group-name>
<caching-element>
<cmr-field>address</cmr-field>
<group-name>addr_group</group-name>
</caching-element>
</caching-element>
	<caching-element>
<cmr-field>phone</cmr-field>
<group-name>phone_group</group-name>
</caching-element>
</relationship-caching>

The accounts and phone fields are container-managed relationship (cmr) fields in the customerBean table; the address field is a cmr field in the accountBean table; and the addr_group and phone_group are groups in the addressBean and phoneBean.

Using nested caching-element deployment descriptors enables the bean to load more than one level of related beans. In the above sample XML code, addressBean is the second level related bean because it is nested in the accountBean. Currently, there is no limitation on the number of caching-elements that you can specify. However, setting too many caching-element levels could have an impact on the performance of the current transaction.

Enabling Relationship Caching

To enable relationship caching:

  1. Specify a caching-name deployment descriptor element in the weblogic-query element of the weblogic-cmp-rdbms-jar.xml file.

    If a caching-name element is specified in a weblogic-query XML element, when the finder query is executed, WebLogic Server loads the related accountBean and phoneBean as well as the account's addressBeans into the cache.

  2. Make sure that the finder-load-bean element, specified in the weblogic-ejb-jar.xml file, in the bean that specifies an relationship (for example, customerBean in the above sample XML code) is not set to False or relationship caching will not be enabled. The finder-load-bean element's default is True.
  3. Specify a database-type deployment descriptor element in the bean's weblogic-cmp-rdbms-jar.xml file. This is because relationship caching uses outer joins for queries and outer joins don't have standard syntax for all databases.
  4. For instructions on specifying deployment descriptors, see Specifying and Editing the EJB Deployment Descriptors.

Since relationship caching uses join queries, and a join query might duplicate results for a table in the ResultSet, the number of caching-element deployment descriptors specified in the relationship-caching element will have a direct impact on the number of duplicate results in the ResultSet. For one-to-many relationships, do not specify too many caching-element deployment descriptors in the relationship-caching element because the number of duplicate results might multiply for each caching-element deployment descriptor

The relationship-caching deployment descriptor element is specified in the weblogic-cmp-rdbms-jar.xml file

Relationship Caching Limitations

The relationship caching feature has the following limitations:

  1. Relationship caching only works with one-to-one and one-to-many relationships.
  2. When using weblogic-ql, this feature only works with finder methods that return references to either EJBObject or EJBLocalObject beans.
  3. If you enable relationship caching for a finder or a select method, the result of the query will always be a distinct set even if the distinct keyword is not specified. This is because there is no way to identify the duplicate in the ResultSet is the result of the original data or the result of the outer join.

 


Combined Caching with Entity Beans

Combined caching allows multiple entity beans that are part of the same J2EE application to share a single runtime cache. Previously, you had to configure a separate cache for each entity bean that was part of an application. This caused some usability and performance problems in that it took more time to configure caches for each entity bean and more memory to run the application. This feature will help solve those problems.

To configure an application level cache:

  1. Verify that the weblogic-application.xml file is located in the META-INF directory of the EAR file.
  2. Provide an entry in the weblogic-application.xml file as follows:
    <weblogic-application>
    <ejb>
    <entity-cache>
    <entity-cache-name>large_account</entity-cache-name>
    <max-cache-size>
    <megabytes>1</megabytes>
    </max-cache-size>
    </entity-cache>
    </ejb>
    </weblogic_application>

    Use the entity-cache element to define a named application level cache that will be used to cache entity bean instances at runtime. There are no restrictions on the number of different entity beans that may reference an individual cache.

    The sub elements of entity-cache have the same basic meaning as they do in the weblogic-ejb-jar.xml deployment descriptor file.

  3. Specify an entity-descriptor element in weblogic-ejb-jar.xml file.

    Use the entity-descriptor element to configure an entity bean to use an application level cache.

For instructions on specifying deployment descriptors, see Specifying and Editing the EJB Deployment Descriptors.

The weblogic-application.xml deployment descriptor is documented in full in the "Application.xml Deployment Descriptor Elements" section of Developing WebLogic Server Applications.

 


Caching Between Transactions

Use caching between transactions or long tern caching to enable the EJB container to cache an entity bean's persistent data between transactions. You can enable caching between transactions if the entity bean's concurrency strategy is set to either Exclusive, ReadOnly, or Optimistic. See Specifying the Concurrency Strategy for instructions on setting an entity bean's concurrency strategy.

Caching Between Transactions with Exclusive Concurrency

When you enable long term caching for an entity bean with an Exclusive concurrency strategy the EJB container must have exclusive update access to the underlying data. This means that another application outside of the EJB container must not be updating the data. If you deploy an EJB with an Exclusive concurrency strategy in a cluster, long term caching is disabled automatically because any node in the cluster may update the data. This would make long term caching impossible.

In previous versions of WebLogic Server, this feature was controlled by the db-is-shared element of weblogic-ejb-jar.xml.

Note: Exclusive concurrency is a single-server feature. Do not attempt to use it with clustered servers.

Caching Between Transactions with ReadOnly Concurrency

When you disable long term caching for an entity bean with a ReadOnly concurrency strategy it ignores the value of the caching-between-transactions setting because the EJB container always performs long term caching of read-only data.

Caching Between Transactions with Optimistic Concurrency

When you enable long term caching for an entity bean with an Optimistic concurrency strategy the EJB container reuses the cached values from previous transactions. The container ensures that the updates are transactionally consistent by checking for optimistic conflicts at the end of the transaction. See Optimistic Concurrency Strategy for instructions on setting optimistic checking.

In addition, notifications for updates of optimistic data are broadcast to other cluster members to help avoid optimistic conflicts.

Enabling Caching Between Transactions

To enable caching between transactions:

  1. Set the caching-between-transactions element in the weblogic-ejb-jar.xml file by choosing one of the following options:
  2. For instructions on specifying deployment descriptors, see Specifying and Editing the EJB Deployment Descriptors.

Using cache-between-transactions to Limit Calls to ejbLoad()

WebLogic Server's default behavior of calling ejbLoad() at the start of each transaction works well for environments where multiple sources may update the datastore. Because multiple clients (including WebLogic Server) may be modifying an EJB's underlying data, an initial call to ejbLoad() notifies the bean that it needs to refresh its cached data and ensures that it works against the most current version of the data.

In the special circumstance where only a single WebLogic Server transaction ever accesses a particular EJB concurrently, such as when you use exclusive concurrency for a single server; not a cluster, calling ejbLoad() by default is unnecessary. Because no other clients or systems update the EJB's underlying data, WebLogic Server's cached version of the EJB data is always up-to-date. Calling ejbLoad() in this case simply creates extra overhead for WebLogic Server clients that access the bean.

To avoid unnecessary calls to ejbLoad() in the case of a single WebLogic Server transaction accessing a particular EJB, WebLogic Server provides the cache-between-transactions deployment parameter. By default, cache-between-transactions is set to "false" for each EJB in the bean's weblogic-ejb-jar.xml file, which ensures that ejbLoad() is called at the start of each transaction. Where only a single WebLogic Server transaction ever accesses an EJB's underlying data concurrently, you can set d to "true" in the bean's weblogic-ejb-jar.xml file. When you deploy an EJB with cache-between-transactions set to "true," the single instance of WebLogic Server calls ejbLoad() for the bean only when:

Restrictions and Warnings for cache-between-transactions

Setting cache-between-transactions to "true" overrides WebLogic Server's default ejbLoad() container-managed-persistence (behavior, regardless of whether the EJB's underlying data is updated by one WebLogic Server instance or multiple clients. If you incorrectly set cache-between-transactions to "true" and multiple clients (database clients, other WebLogic Server instances, and so forth) update the bean data, you run the risk of losing data integrity.

Do not set cache-between-transactions to "true" if you set the entity bean's concurrency strategy to the "Database" option. Weblogic Server ignores this setting because with database concurrency specified, the EJB container continues to cache instances of entity bean classes. However, the container does not cache the state of the EJB instance between transactions. Instead, WebLogic Server calls ejbLoad() for each instance at the beginning of a transaction to obtain the latest EJB data. This means that setting cache-between-transactions to "true" which prevents WebLogic Server from calling ejbload() at the beginning of each transaction is invalid.

Also, due to the limitations of exclusive concurrency, you cannot set cache-between-transactions to "true" in a WebLogic Server cluster when using exclusive concurrency. However, you can set this element to true when using either optimistic or readonly concurrency.

 


ejbLoad() and ejbStore() Behavior for Entity EJBs

WebLogic Server reads and writes the persistent fields of entity EJBs using calls to ejbLoad() and ejbStore(). By default, WebLogic Server calls ejbLoad() and ejbStore() in the following manner:

  1. A transaction is initiated for the entity EJB. The client may explicitly initiate a new transaction and invoke the bean, or WebLogic Server may initiate a new transaction in accordance with the bean's method transaction attributes.
  2. WebLogic Server calls ejbLoad() to read the most current version of the bean's persistent data from the underlying datastore.
  3. When the transaction commits, WebLogic Server calls ejbStore() to write persistent fields back to the underlying datastore.

This simple process of calling ejbLoad() and ejbStore() ensures that new transactions always use the latest version of the EJB's persistent data, and always write the data back to the datastore upon committing. In certain circumstances, however, you may want to limit calls to ejbLoad() and ejbStore() for performance reasons. Alternately, you may want to call ejbStore() more frequently to view the intermediate results of uncommitted transactions.

WebLogic Server provides several deployment descriptor elements in the weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml files that enable you to configure ejbLoad() and ejbStore() behavior.

Warning for is-modified-method-name

Using the is-modified-method-name element can improve performance by avoiding unnecessary calls to ejbStore(). However, it places a greater burden on the EJB developer to identify correctly when updates have occurred. If the specified is-modified-method-name returns an incorrect flag to WebLogic Server, data integrity problems can occur, and they may be difficult to track down.

If entity EJB updates appear "lost" in your system, start by ensuring that the value for all is-modified-method-name elements return "true" under every circumstance. In this way, you can revert to WebLogic Server's default ejbStore() behavior and possibly correct the problem.

Using delay-updates-until-end-of-tx to Change ejbStore() Behavior

By default, WebLogic Server updates the persistent store of all beans in a transaction only at the completion (commit) of the transaction. This generally improves performance by avoiding unnecessary updates and repeated calls to ejbStore().

If your datastore uses an isolation level of READ_UNCOMMITTED, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, the default WebLogic Server behavior of updating the datastore only at transaction completion may be unacceptable.

You can disable the default behavior by using the delay-updates-until-end-of-tx deployment descriptor element. This element is set in the weblogic-ejb-jar.xml file. When you set this element to "false," WebLogic Server calls ejbStore() after each method call, rather than at the conclusion of the transaction.

Setting delay-updates-until-end-of-tx to false does not cause database updates to be "committed" to the database after each method invoke; they are only sent to the database. Updates are committed or rolled back in the database only at the conclusion of the transaction.

 


Groups

In container-managed persistence, you use groups to specify certain persistent attributes of an entity bean. A field-group represents a subset of the cmp and CMR-fields of a bean. You can put related fields in a bean into groups that are faulted into memory together as a unit. You can associate a group with a query or relationship, so that when a bean is loaded as the result of executing a query or following a relationship, only the fields mentioned in the group are loaded.

A special group named "default" is used for queries and relationships that have no group specified. By default, the default group contains all of a bean's CMP-fields and any CMR-fields that add a foreign key to the persistent state of the bean.

A field can belong to multiple groups. In this case, the getXXX() method for the field will fault in the first group that contains the field.

Specifying Field Groups

Field groups are specified in the weblogic-rdbms-cmp-jar.xml file as follows:

<weblogic-rdbms-bean>
<ejb-name>XXXBean</ejb-name>
<field-group>
<group-name>medical-data</group-name>
<cmp-field>insurance</cmp-field>
<cmr-field>doctors</cmr-fields>
</field-group>
</weblogic-rdbms-bean>

You use field groups when you want to access a subset of fields.

Using Groups

The field group is an optimizing element that should be used with care because it is possible to corrupt the database.

For example,

You have the following CMP fields: A, B, and C.

A and B belong to the same group.

You set up the following scenario:

getA() // loads A and B
modify A
// then an external process modifies the row getC()

Because C is not in the group, there are two possibilities:

 


Automatic Primary Key Generation

WebLogic Server supports an automatic primary key generation feature for container-managed persistence (CMP).

Note: This feature is supported for the EJB 2.0 CMP container only, there is no automatic primary key generation support for EJB 1.1 CMP. For 1.1 beans, you must use bean-managed-persistence (BMP.)

Generated key support is provided in two ways:

Note: For instructions on creating a table in Oracle, use the Oracle database documentation.

In the weblogic-cmp-rdbms-jar.xml file, set the key_cache_size element to specify how many primary key values a database SELECT and UPDATE will fetch at one time. The default value of key_cache_size is 1. BEA recommends that you set this element to a value of >1, to minimize database accesses and to improve performance. For more information in this feature, see Specifying Primary Key Named Sequence Table Support.

At this time, WebLogic Server only provides DBMS primary key generation support for Oracle and Microsoft SQL Server. However, you can use named sequence tables with other unsupported databases. Also, this feature is intended for use with simple (non-compound) primary keys.

Valid Key Field Types

In the abstract `get' and `set' methods of the bean, you can declare the field to be either of these two types:

Specifying Primary Key Support for Oracle

Generated primary key support for Oracle databases uses Oracle's SEQUENCE feature. This feature works with a Sequence entity in the Oracle database to generate unique primary keys. The Oracle SEQUENCE is called when a new number is needed.

Once the SEQUENCE already exists in the database, you specify automatic key generation in the XML deployment descriptors. In the weblogic-cmp-rdbms-jar.xml file, you specify automatic key generation as follows:

Figure 6-3 Specifying automatic key generation for Oracle

<automatic-key-generation>
<generator-type>Oracle</generator-type>
<generator_name>test_sequence</generator-name>
<key-cache-size>10</key-cache-size>
</automatic-key-generator>

Specify the name of the Oracle SEQUENCE to be used, using the generator-name element. If the Oracle SEQUENCE was created with a SEQUENCE INCREMENT value, then you must specify a key-cache-size. This value must match the Oracle SEQUENCE INCREMENT value. If these two values are different, then you will most likely have duplicate key problems.

Warning: Do not use the generator type USER_DESIGNATED_TABLE with Oracle, as doing so can cause the following exception:

javax.ejb.EJBException: nested exception is: java.sql.SQLException: Automatic Key Generation Error: attempted to UPDATE or QUERY NAMED SEQUENCE TABLE NamedSequenceTable, but encountered SQLException java.sql.SQLException: ORA-08177: can't serialize access for this transaction.

USER_DESIGNATED_TABLE mode sets the TX ISOLATION LEVEL to SERIALIZABLE which can cause problems with Oracle.

Instead, use the AutoKey option Oracle.

Specifying Primary Key Support for Microsoft SQL Server

Generated primary key support for Microsoft SQL Server databases uses SQL Server's IDENTITY column. When the bean is created and a new row is inserted in the database table, SQL Server automatically inserts the next primary key value into the column that was specified as an IDENTITY column.

Note: For instructions on creating a table in Microsoft SQL Server, see the Microsoft SQL Server database documentation.

Once the IDENTITY column is created in the database table, you specify automatic key generation in the XML deployment descriptors. In the weblogic-cmp-rdbms-jar.xml file, you specify automatic key generation as follows:

Figure 6-4 Specifying automatic key generation for Microsoft SQL

<automatic-key-generation>
<generator-type>SQLServer</generator-type>
</automatic-key-generator>

The generator-type element lets you specify the primary key generation method that you want to use.

Specifying Primary Key Named Sequence Table Support

Generated primary key support for unsupported databases uses a Named SEQUENCE TABLE to hold key values. The table must contain a single row with a single column that is an integer, SEQUENCE INT. This column will hold the current sequence value.

Note: For instructions on creating the table, see the documentation for the specific database product.

To use Named Sequence Table support, make sure that the underlying database supports the transaction isolation level, TransactionSerializable. You specify this option for the isolation-level element, in the weblogic-ejb.xml file. The TransactionSerializable option specifies that simultaneously executing a transaction multiple times has the same effect as executing the transaction multiple times in a serial fashion. If the database doesn't support the transaction isolation level, TransactionSerializable, then you cannot use Named Sequence Table support.

Note: See the documentation for the underlying database to determine the type of isolation level support it provides and see Specifying and Editing the EJB Deployment Descriptors for instructions on setting the isolation level.

Once the NamedSequenceTable exists in the database, you specify automatic key generation by using the XML deployment descriptors in the weblogic-cmp-rdbms-jar.xml file, as follows:

Figure 6-5 Specifying automatic key generation for named sequence table support

<automatic-key-generation>
<generator-type>NamedSequenceTable</generator-type>
<generator_name>MY_SEQUENCE_TABLE_NAME</generator-name>
<key-cache-size>100</key-cache-size>
</automatic-key-generator>

Specify the name of the SEQUENCE TABLE to be used, with the generator-name element. Using the key-cache-size element, specify the optional size of the key cache that tells you how many keys the container will fetch in a single DBMS call.

For improved performance, BEA recommends that you set this value to >1, a number greater than one. This setting reduces the number of calls to the database to fetch the next key value.

Also, it is recommended that you define one NAMED SEQUENCE table per bean type. Beans of different types should not share a common NAMED SEQUENCE table. This reduces contention for the key table.

 


Automatic Table Creation

You can specify that WebLogic Server automatically create tables based on the descriptions in the XML deployment descriptor files and the bean class, if the table does not already exist. Tables are created for all beans and relationship join tables, if the relationships in the JAR files have joins. You explicitly turn on this feature by defining it in the deployment descriptors per each RDBMS deployment, for all beans in the JAR file.

If you enable automatic table creation, WebLogic Serve examines the value of the database-type element in weblogic-cmp-rdbms-jar.xml to determine the correct syntax and datatype conversions to use to create a table in your database. WebLogic Server uses the vendor-specific CREATE TABLE syntax and datatype conversions for the following databases and vendors:

For all other database systems, WebLogic Server makes a best attempt to create the new table using a basic syntax and the datatype conversions shown in the following table:

Table 6-1 Generic Java Field to DBMS Column Type Conversion

Java Type

DBMS Column Type

boolean

INTEGER

byte

INTEGER

char

CHAR

double

DOUBLE PRECISION

float

FLOAT

int

INTEGER

long

INTEGER

short

INTEGER

java.lang.string

VARCHAR (150)

java.lang.BigDecimal

DECIMAL (38, 19)

java.lang.Boolean

INTEGER

java.lang.Byte

INTEGER

java.lang.Character

CHAR (1)

java.lang.Double

DOUBLE PRECISION

java.lang.Float

FLOAT

java.lang.Integer

INTEGER

java.lang.Long

INTEGER

java.lang.Short

INTEGER

java.sql.Date

DATE

java.sql.Time

DATE

java.sql.Timestamp

DATETIME

byte[ ]

RAW (1000)

Any serializable Class that is not a valid SQL type:

RAW (1000)

If, based on the descriptions in the deployment files, a field cannot be successfully mapped to an appropriate column type in the database, the CREATE TABLE fails, an error is thrown, and you must create the table yourself.

Automatic table creation is not recommended for use in a production environment. It is better suited for the development phase of design and prototype work. A production environment may require the use of more precise table schema definitions, for example; the declaration of foreign key constraints.

To define automatic table creation:

  1. In the weblogic-cmp-rdbms-jar.xml file, set the create-default-dbms-tables element to True to explicitly turn on automatic table creation for all beans in the JAR file. Use the following syntax:

    <create-default-dbms-tables>True</create-default-dbms-tables>

  2. Specify the correct database system or database vendor name in the database-type element of weblogic-cmp-rdbms-jar.xml. CREATE TABLE syntax and datatype mapping is provide for the following database-type values: Informix, Oracle, POINTBASE, SQLServer, and Sybase. All other DBMS systems use a basic syntax and the datatype conversions shown in the table above.

Automatic Database Detection

As application developers develop their entity beans, the underlying table schema must change. With the automatic database detection feature enabled, the WebLogic Server EJB container automatically changes the underlying table schema as entity beans change, ensuring that tables always reflect the most recent value of deployment descriptor values.

Even if a table already exists, if any container-managed persistence fields have been added or deleted for that table, the container will recreate the table during deployment. To ensure that the container only changes tables it created, container-created tables include an extra column, called wls_temp.

Note: Use this feature during development only, not during production.

Enabling Automatic Database Detection

Enable this feature using the create-default-dbms-tables element in weblogic-cmp-rdbms-jar.xml. The precise behavior of this feature varies, depending on the value of the element. The following table summarizes how behavior varies depending on the value:

Table 6-2 Automatic Database Detection values for <create-default-dbms-tables>

Setting <create-default-dbms-tables> to this value

Results in this behavior:

DropAndCreate

The container drops and creates the table during deployment if columns have changed. Data is not saved.

DropAndCreateAlways

The container drops and creates the table during deployment whether or not columns have changed. Data is not saved.

CreateOrAlterTable

The container creates the table if it does not yet exist. If the table does exist, the container alters the table schema. Data is saved.

Note: Do not choose this option if either of the following is true:

  • A new column is specified as a primary key

  • A column with null values is specified as the new primary key column

Behavior When Type Conflict Detected

If the database type WebLogic Server detects differs from the database type defined in the deployment descriptor, WebLogic Server will issue a warning and give preference to the type defined in the deployment descriptor.

 


Using Oracle SELECT HINTS

WebLogic Server supports an EJB QL extension that allows you to pass INDEX usage hints to the Oracle Query optimizer. With this extension, you can provide a hint to the database engine. For example, if you know that the database you are searching can benefit from an ORACLE_SELECT_HINT, you can define an ORACLE_SELECT_HINT clause that will take ANY string value and then insert that String value after the SQL SELECT statement as a hint to the database.

To use this option, declare a query that uses this feature in the weblogic-ql element. This element is found in the weblogic-cmp-rdbms-jar.xml file. The weblogic-ql element specifies a query that contains a WebLogic specific extension to the EJB-QL language.

The WebLogic QL keyword and usage is as follows:

SELECT OBJECT(a) FROM BeanA AS a WHERE a.field > 2 ORDERBY a.field SELECT_HINT '/*+ INDEX_ASC(myindex) */'

This statement generates the following SQL with the optimizer hint for Oracle:

SELECT /*+ INDEX_ASC(myindex) */ column1 FROM .... (etc)

In the WebLogic QL ORACLE_SELECT_HINT clause, whatever is between the single quotes (' ') is what gets inserted after the SQL SELECT. It is the query writer's responsibility to make sure that the data within the quotes makes sense to the Oracle database."get" and "set" Method Restrictions

WebLogic Server uses a series of accessor methods. The names of these methods begin with set and get. WebLogic Server uses these methods to read and modify container-managed fields. These container-generated classes must begin with "get" or "set" and use the actual name of a persistent field defined in ejb-jar.xml. The methods are also declared as public, protected, and abstract.

 


Multiple Table Mapping

Multiple table mapping allows you to map a single EJB to multiple DBMS tables within a single database for EJB 2.0 CMP beans. You configure this feature by mapping multiple DBMS tables and columns to the EJB and its fields in the EJB's weblogic-cmp-rdbms-xml file. This includes the following types of mappings:

When enabling multiple table mappings, the following requirements apply:

Previously, you could associate an EJB with a single table and a list of fields and columns. Now, you can associate sets of fields and columns for as many tables as the EJB maps to.

Restrictions for multiple mapped tables on a single bean

Tables that are mapped to a single entity bean must not have referential integrity constraints declared between their primary keys. Doing so may result in a runtime error upon bean removal.

Multiple Table Mappings for cmp-fields

Configure multiple table mappings for cmp-fields, in a weblogic-rdbms-bean stanza of the EJB's weblogic-cmp-rdbms-xml file, as follows:

  1. Specify the following elements in the weblogic-cmp-rdbms-jar.xml file:
    • table-field-map element
    • table-name element
    • field-map element
  2. For instructions on specifying deployment descriptors, see Specifying and Editing the EJB Deployment Descriptors.

The following sample XML shows an EJB that maps to a single DBMS table:

Figure 6-6 Mapping a single DBMS table

<table-name>TableName</table-name>
<field-map>
<cmp-field>name</cmp-field>
<dbms-column>name_in_tablename</dbms-column>
</field-map>
	<field-map>
<cmp-field>street_address</cmp-field>
<dbms-column>street_address_in_tablename
</dbms_column>
</field-map>
<field-map>
<cmp-field>phone</cmp-field>
<dbms-column>phone_in_tablename</dbms-column>
</field-map>

The following sample XML shows an EJB that maps to two different tables:

Figure 6-7 Mapping to two DBMS tables

<table-map>
<table-name>TableName_1</table-name>
<field-map>
<!--Note `name'is the primary key field of this EJB -->
<cmp-field>name</cmp-field>
<dbms-column>name_in_tablename_1</dbms-column>
</field-map>
	<field-map>
<cmp-field>street_address</cmp-field>
<dbms-column>street_address_in_tablename_1
</dbms-column>
</field-map>
</table-map>
<table-map>
<table-name>TableName_2</table-name>
<field-map>
<!--Note `name'is the primary key field of this EJB -->
<cmp-field>name</cmp-field>
<dbms-column>name_in_tablename_2</dbms-column>
</field-map>
<field-map>
<cmp-field>phone</cmp-field>
<dbms-column>phone_in_tablename_2</dbms-column>
</field-map>
</table-map>

Note: As shown in the above XML sample for a table mapping, you must map the primary key field to each table's primary key column.

Multiple Table Mappings for cmr-fields

Configure multiple table mappings for cmr-fields, in a weblogic-relationship-role stanza of the EJB's weblogic-cmp-rdbms-xml file, as follows:

  1. Specify the following elements in the weblogic-cmp-rdbms-jar.xml file:
    • column-map element
    • foreign-key-column element
    • key-column element
    • foreign-key-table element
    • primary-key-table element
  2. For instructions on specifying deployment descriptors, see Specifying and Editing the EJB Deployment Descriptors.

Note: Multiple table mappings for cmr-fields require that the foreign key needed to maintain a relationship be only one of the tables that constitutes the EJB.

In previous versions, the name of the DBMS table that contains the foreign keys is implicit and uniquely determined; with multiple table mappings the table that contains the foreign keys must be explicitly specified. For example, a foreign key to key column mappings that is required for a one-to-one or many-to-one relationship.

The following sample XML shows multiple table mapping for cmr-fields for an EJB with an one-to-one relationship with another EJB:

Figure 6-8 Mapping EJBs with an one-to-one relationship

<column-map>
<foreign-key-column>forfeign_key_1</foreign-key-column>
<key-column>key_1</key-column>
</column-map>
<foreign-key-column>foreign_key_2</foreign-key-column>
<key-column>key_2</key-column>
</column-map>

The following sample XML shows the multiple table mapping for cmr-fields for an EJB with explicitly named foreign key columns:

Figure 6-9 Mapping foreign key columns in a relationship-role-name stanza

<relationship-role-map>
<foreign-key-table>
<table-name>TableName_2</table-name>
</foreign-key-table>
<column-map>
<foreign-key-column>foreign_key_1
</foreign-key-column>
<key-column>key_11</key-column>
</column-map>
<column-map
<foreign-key-column>foreign_key_2
</foreign-key-column>
<key-column>key_12</key-column>
</column-map>
<column-map
<foreign-key-column>foreign_key_1
</foreign-key-column>
<key-column>key_21</key-column>
</column-map>
<column-map
<foreign-key-column>foreign_key_2
</foreign-key-column>
<key-column>key_22</key-column>
</column-map>
</relationship-role-map>

When mapping many-to-many relationships, consider the following:

 

Back to Top Previous Next