Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation
BEA WebLogic Server Enterprise JavaBeans:   Previous Topic   |   Next Topic   |   Contents

Overview

ejbc

Syntax

Arguments

Options

Examples

DDConverter

Syntax

Arguments

Options

Examples

deploy

Syntax

Arguments

Options

Examples

XML deployment properties

Manually editing XML deployment files

Basic conventions

DOCTYPE header information

Document Type Definitions (DTDs) for validation

weblogic-ejb-jar.xml Properties

Caching properties

Persistence properties

Clustering properties

Transaction properties

EJB references

Security role assignments

weblogic-cmp-rdbms-jar.xml Properties

RDBMS definition elements

EJB field-mapping elements

Finder elements

Persistence options

options

This section provides a complete reference to the utilities and support files supplied with WebLogic Server EJB. It contains reference information for:

• ejbc (weblogic.ejbc)

• DDConverter (weblogic.ejb.utils.DDConverter)

• deploy (weblogic.deploy)

• XML deployment properties

ejbc

Using the XML deployment descriptors present in the input .jar file, weblogic.ejbc creates wrapper classes for the corresponding EJB classes. It then runs these through the RMI compiler, which generates a client-side stub and a server-side skeleton. If you specify an output .jar file, ejbc inserts these files into the .jar.

By default, ejbc uses javac as a compiler. For faster performance, specify a different compiler (such as Symantec's sj) using the -compiler flag.

 $ java weblogic.ejbc [options] <source jar file>

  <target directory or jar file>

Note: If you output to a .jar file, the output .jar name must be different from the input .jar name.

Argument	Description
<source jar file>	Specifies the .jar file containing the compiled EJB classes, interfaces, and XML deployment files.
<target directory or jar file>	Specifies the destination .jar file or deployment directory in which ejbc places the output .jar. If you specify an output .jar file, ejbc places the original EJB classes, interfaces, and XML deployment files in the .jar, as well as the new container classes that ejbc generates.

Option	Description
-help	Prints a list of all options available for the compiler.
-version	Prints ejbc version information.
-idl	Generates CORBA Interface Definition Language for remote interfaces.
-idlOverwrite	Overwrites existing IDL files.
-idlVerbose	Displays verbose information while generating IDL.
-idlDirectory <dir>	Specifies the directory where ejbc creates IDL files. By default, ejbc uses the current directory.
-keepgenerated	Saves the intermediate Java files generated during compilation.
-compiler <javac>	Sets the compiler for ejbc to use.
-normi	Passed through to Symantec's sj to stop generation of RMI stubs. Otherwise sj creates its own RMI stubs, which are unnecessary for the EJB.
-classpath <path>	Sets a CLASSPATH used during compilation. This overrides the system or shell CLASSPATH.

The following example uses the javac compiler against an input .jar file in c:\weblogic\examples\ejb\basic\containerManaged\build. The output .jar is placed in c:\weblogic\myserver.

$ java weblogic.ejbc -compiler javac c:\weblogic\examples\ejb\basic\containerManaged\build\std_ejb_basic_containerManaged.jar c:\weblogic\myserver\ejb_basic_containerManaged.jar

Given one or more EJB 1.0-compliant text deployment descriptors, DDConverter generates EJB 1.1-compliant XML descriptor files.

$ java weblogic.ejb.utils.DDConverter [options] oldDDFile
  [oldDDFile2 ...]

DDConverter takes one or more arguments of oldDDFile. Each oldDDFile specifies a text file containing an EJB 1.0-compliant deployment descriptor.

DDConverter uses the beanHomeName property of EJBs in the text deployment descriptor files to define new ejb-name elements in the resultant ejb-jar.xml file. If you specify more than one oldDDFile, you must ensure that no two EJBs in the collection of files share the same beanHomeName property.

Option	Description
-d targetDir	Sets the destination directory for the generated XML files. This directory must exist before you run DDConverter. If you do not specify -d, DDConverter uses the current directory.

The following example converts two EJB 1.0-compliant WebLogic Server DeploymentDescriptor.txt files into a collection of EJB 1.1-compliant XML files. The XML files are created in the META-INF subdirectory:

$ java weblogic.ejb.utils.DDConverter -d META-INF DeploymentDescriptor.txt DeploymentDescriptor2.txt

Given an EJB 1.1-compliant .jar file, the deploy utility deploys the .jar's EJBs into a running WebLogic Server.

$ java weblogic.deploy [options] [list|deploy|undeploy|update] password {name} {source}

Argument	Description
list	Lists all EJB deployment units in the specified WebLogic Server.
deploy	Deploys an EJB .jar to the specified server.
undeploy	Removes an existing EJB deployment unit from the specified server.
update	Redeploys an EJB deployment unit in the specified server.
password	Specifies the system password for the WebLogic Server.
{name}	Identifies the name of the EJB deployment unit. This name can be specified at deployment time, either with the deploy or console utilities.
{source}	Specifies the exact location of the EJB .jar file, or the path to the top level of an EJB deployment directory.

Option	Description
-help	Prints a list of all options available for the deploy utility.
-version	Prints the version of the utility.
-port <port>	Specifies the port number of the WebLogic Server to use for deploying the .jar. If you do not specify this option, the deploy utility attempts to connect using port number 7001.
-host <host>	Specifies the host name of the WebLogic Server to use for deploying the .jar. If you do not specify this option, the deploy utility attempts to connect using host name "localhost."
-debug	Prints detailed debugging information during the deployment process.

See Deploying EJBs in a running WebLogic Server (Hot Deployment) for examples of using deploy at the command shell.

This section describes the XML elements used to define WebLogic Server EJB deployment properties.

Note: The WebLogic Server DeployerTool utility provides a graphical way to set these elements without having to manually edit and validate XML files.

If you choose to edit XML elements manually:

• Make sure that you use an ASCII text editor that does not reformat the XML or insert additional characters that could invalidate the file

• Use the correct case for file and directory names, even if your operating system ignores the case

• To use the default value for an optional element, you can either omit the entire element definition or specify a blank value, as in:

  <max-beans-in-cache></max-beans-in-cache>

DOCTYPE header information

When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose. The correct text for the PUBLIC element for each XML deployment file is as follows:

XML file	PUBLIC element string
ejb-jar.xml	`-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN'
weblogic-ejb-jar.xml	`-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN'
weblogicmp-rdbms -jar.xml	`-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB RDBMS Persistence//EN'

For example, the entire DOCTYPE header for a weblogic-ejb-jar.xml file is as follows:

<!DOCTYPE weblogic-ejb-jar PUBLIC 
'-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB//EN' 'http://www.beasys.com/j2ee/dtds/weblogic-ejb-jar.dtd'>

XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as ejbc or DeployerTool):

SAXException: This document may not have the identifier `identifier_name'

identifier_name generally includes the invalid text from the PUBLIC element.

The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server utilities ignore the DTDs embedded within the DOCTYPE header of XML deployment files, and instead use the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.

The following links provide the public DTD locations for XML deployment files used with WebLogic Server:

• ejb-jar.dtd contains the DTD for the standard ejb-jar.xml deployment file, required for all EJBs. This DTD is maintained as part of the JavaSoft EJB 1.1 specification; refer to the JavaSoft specification for information about the elements used in ejb-jar.dtd.

• weblogic-ejb-jar.dtd contains the DTD used for creating weblogic-ejb-jar.xml, which defines EJB properties used for deployment to WebLogic Server. This file is located at http://www.bea.com/servers/wls510/dtd/weblogic-ejb-jar.dtd

• weblogic-rdbms-persistence.dtd contains the DTD that defines container-managed persistence properties for entity EJBs. This DTD is used to create the weblogic-rdbms-persistence.xml file for using WebLogic Server persistence services. Third-party persistence vendors may also create XML deployment files that conform to this DTD. This file is located at http://www.bea.com/servers/wls510/dtd/weblogic-rdbms-persistence.dtd

  Note: Most browsers do not display the contents of files having the .dtd extension. To view the DTD file contents in your browser, save the links as text files and view them with a text editor.

weblogic-ejb-jar.xml Properties

weblogic-ejb-jar.xml defines EJB deployment properties unique to WebLogic Server. The top level elements in weblogic-ejb-jar.xml are as follows:

• description

• weblogic-version

• weblogic-enterprise-bean

  • ejb-name

  • caching-descriptor

  • persistence-descriptor

  • clustering-descriptor

  • transaction-descriptor

  • reference-descriptor

  • enable-call-by-reference

  • jndi-name

• security-role-assignment

Caching properties

The caching-descriptor stanza affects the number of EJBs in the WebLogic Server cache as well as the length of time before EJBs are passivated or pooled. The entire stanza, as well as each of its elements, is optional. WebLogic Server uses default values where no elements are defined.

The following is a sample caching-descriptor stanza that shows the caching elements described in this section:

<caching-descriptor>

    <max-beans-in-free-pool>500</max-beans-in-free-pool>

    <initial-beans-in-free-pool>50</initial-beans-in-free-pool>

    <max-beans-in-cache>1000</max-beans-in-cache>

    <idle-timeout-seconds>20</idle-timeout-seconds>

    <cache-strategy>Read-Write</cache-strategy>

    <read-timeout-seconds>0</read-timeout-seconds>

</caching-descriptor>

Note: This element is valid only for stateless session EJBs.

WebLogic Server maintains a free pool of EJBs for every bean class. This optional element defines the size of the pool. By default, max-beans-in-free-pool has no limit; the maximum number of beans in the free pool is limited only by the available memory. See Initializing and using EJB instances in The WebLogic Server EJB Container for more information.

Note: This element is valid only for stateless session EJBs.

If you specify a value for initial-bean-in-free-pool, WebLogic Server populates the free pool with the specified number of bean instances at startup. Populating the free pool in this way improves initial response time for the EJB, since initial requests for the bean can be satisfied without generating a new instance.

initial-bean-in-free-pool defaults to 0 if the element is not defined.

Note: This element is valid only for stateful session EJBs and entity EJBs.

This element specifies the maximum number of objects of this class that are allowed in memory. When max-bean-in-cache is reached, WebLogic Server passivates some EJBs that have not been recently used by a client. max-beans-in-cache also affects when EJBs are removed from the WebLogic Server cache, as described in Removing stateful session EJB instances.

The default value of max-beans-in-cache is 100.

idle-timeout-seconds defines the maximum length of time a stateful EJB should remain in the cache. After this time has elapsed, WebLogic Server may remove the bean instance if the number of beans in cache approaches the limit of max-beans-in-cache. See EJB Lifecycle in WebLogic Server for more information.

idle-timeout-seconds defaults to 600 if you do not define the element.

The cache-strategy element can be one of the following:

• Read-Write

• Read-Only

The default value is Read-Write. See Setting the cache strategy for entity EJBs for more information.

The read-timeout-seconds element specifies the number of seconds between ejbLoad() calls on a Read-Only entity bean. By default, read-timeout-seconds is set to 600 seconds. If you set this value to 0, WebLogic Server calls ejbLoad only when the bean is brought into the cache.

The persistence-descriptor stanza specifies persistence options for entity EJBs. The following shows all elements contained in the persistence-descriptor stanza:

<persistence-descriptor>

    <is-modified-method-name>. . .</is-modified-method-name>

    <delay-updates-until-end-of-tx>. . .</delay-updates-until-end-of-tx>

    <find-by-primary-key-calls-ejbload>. . .</find-by-primary-key-calls-ejbload>

    <persistence-type>

       <type-identifier>. . .</type-identifier>

       <type-version>. . .</type-version>

       <type-storage>. . .</type-storage>

    </persistence-type>

    <db-is-shared>. . .</db-is-shared>

    <stateful-session-persistent-store-dir>

       . . .

    </stateful-session-persistent-store-dir>

    <persistence-use>. . .</persistence-use>

</persistence-descriptor>

is-modified-method-name specifies a method that WebLogic Server calls when the EJB is stored. The specified method must return a boolean value. If no method is specified, WebLogic Server always assumes that the EJB has been modified and always saves it.

Providing a method and setting it as appropriate can improve performance. However, any errors in the method's return value can cause data inconsistency problems. See Using is-modified-method-name to limit calls to ejbStore() for more information.

Set this property to "true" (the default), to update the persistent store of all beans in a transaction at the completion of the transaction. This generally improves performance by avoiding unnecessary updates. However, it does not preserve the ordering of database updates within a database transaction.

If your datastore uses an isolation level of TRANSACTION_READ_UNCOMMITTED, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set delay-updates-until-end-of-tx to "false" to update the bean's persistent store at the conclusion of each method invoke. See ejbLoad() and ejbStore() behavior for entity EJBs for more information.

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

This property is applicable only to entity EJBs. find-by-primary-key-calls-ejbload determines whether the bean is loaded immediately into the cache (followed by invoke of ejbLoad) after a call to findByPrimaryKey returns a reference to the bean.

If this property is set to "true," WebLogic Server immediately loads the bean into the cache if a reference to a bean is returned by findByPrimaryKey. If it is set to "false," the bean will not be loaded into the cache until the first invoke of the bean.

The default value of find-by-primary-key-calls-ejbload is "false."

A persistence-type defines a persistence service that can be used by an EJB. You can define multiple persistence-type entries in weblogic-ejb-jar.xml for testing with multiple persistence services. Only the persistence type defined in persistence-use (described below) is used during deployment.

persistence-type includes several elements that define the properties of a service:

• type-identifier contains text that identifies the specified persistence type. For example, WebLogic Server RDBMS persistence uses the identifier, WebLogic_CMP_RDBMS.

• type-version identifies the version of the specified persistence type.

  Note: The specified version must exactly match the RDBMS persistence version for the WebLogic Server release. Specifying an incorrect version results in the error:

  weblogic.ejb.persistence.PersistenceSetupException: Error initializing the CMP Persistence Type for your bean: No installed Persistence Type matches the signature of (identifier `Weblogic_CMP_RDBMS', version `version_number').

• type-storage defines the full path of the file that stores data for this persistence type. The path must specify the file's location relative to the top level of the EJB's .jar deployment file or deployment directory.

  WebLogic Server RDBMS-based persistence generally uses an XML file named weblogic-cmp-rdbms-jar.xml to store persistence data for a bean. This file is stored in the META-INF subdirectory of the .jar file.

The following shows an example persistence-type stanza with values appropriate for WebLogic Server RDBMS persistence:

<persistence-type>

      <type-identifier>WebLogic_CMP_RDBMS</type-identifier>

      <type-version>5.1.0</type-version>

      <type-storage>META-INF\weblogic-cmp-rdbms-jar.xml</type-storage>

</persistence-type>

The db-is-shared element applies only to entity beans. When set to "true" (the default value) WebLogic Server assumes that EJB data could be modified between transactions and reloads data at the beginning of each transaction. When set to "false" WebLogic Server assumes that it has exclusive access to the EJB data in the persistent store. See Using db-is-shared to limit calls to ejbLoad() for more information.

stateful-session-persistent-store-dir specifies the file system directory where WebLogic Server stores the state of passivated stateful session bean instances.

The persistence-use property is similar to persistence-type, but it defines the persistence service actually used during deployment. persistence-use uses the type-identifier and type-version elements defined in a persistence-type to identify the service.

For example, to actually deploy an EJB using the WebLogic Server RDBMS-based persistence service defined in persistence-type, the persistence-use stanza would resemble:

<persistence-use>

    <type-identifier>WebLogic_CMP_RDBMS</type-identifier>

    <type-version>5.1.0</type-version>

</persistence-use>

The clustering-descriptor stanza defines the replication properties and behavior for EJBs deployed in a WebLogic Server cluster. The clustering-descriptor stanza and each of its elements are optional, and are not applicable to single-server systems.

The following shows all elements contained in the clustering-descriptor stanza:

<clustering-descriptor>

    <home-is-clusterable>. . .</home-is-clusterable>

    <home-load-algorithm>. . .</home-load-algorithm>

    <home-call-router-class-name>. . .</home-call-router-class-name>

    <stateless-bean-is-clusterable>. . .</stateless-bean-is-clusterable>

    <stateless-bean-load-algorithm>. . .</stateless-bean-load-algorithm>

    <stateless-bean-call-router-class-name>. . .</stateless-bean-call-router-class-name>

    <stateless-bean-methods-are-idempotent>. . .</stateless-bean-methods-are-idempotent>

</clustering-descriptor>

You can set this element to either "true" or "false." When home-is-clusterable is true, the EJB can be deployed from multiple WebLogic Servers in a cluster. Calls to the home stub are load-balanced between the servers on which this bean is deployed, and if a server hosting the bean is unreachable, the call automatically fails over to another server hosting the bean.

home-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, weblogic.cluster.defaultLoadAlgorithm.

You can define home-load-algorithm as one of the following values:

• round-robin: Load balancing is performed in a sequential fashion among the servers hosting the bean.

• random: Replicas of the EJB home are deployed randomly among the servers hosting the bean.

• weight-based: Replicas of the EJB home are deployed on host servers according to the servers' current workload.

home-call-router-class-name

home-call-router-class-name specifies the custom class to use for routing bean method calls. This class must implement weblogic.rmi.extensions.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.

This property is similar to home-is-clusterable, but it is applicable only to stateless session EJBs.

This property is similar to home-load-algorithm, but it is applicable only to stateless session EJBs.

This property is similar to home-call-router-class-name, but it is applicable only to stateless session EJBs.

You can set this element to either "true" or "false." Set stateless-bean-methods-are-idempotent to true only if the bean is written such that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually completed on the failed server. Setting this property to "true" makes it possible for the bean stub to automatically recover from any failure as long as another server hosting the bean can be reached.

Note: This property is applicable only to stateless session EJBs.

The transaction-descriptor stanza contains elements that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element:

<transaction-descriptor>

    <trans-timeout-seconds>20</trans-timeout-seconds>

<transaction-descriptor>

The trans-timeout-seconds element specifies the maximum duration for the EJB's container-initiated transactions. If a transaction lasts longer than trans-timeout-seconds, WebLogic Server rolls back the transaction.

If you specify no value for trans-timeout-seconds, container-initiated transactions timeout after five minutes, by default.

The reference-descriptor stanza maps references in the ejb-jar.xml file to the JNDI names of actual resource factories and EJBs available in WebLogic Server. The DeployerTool utility simplifies the process of mapping EJB references. You can use DeployerTool to connect to a WebLogic Server and assign available resources before deploying. See Mapping EJB references in Deploying EJBs with DeployerTool for more information.

The reference-descriptor stanza contains one or more additional stanzas to define resource factory references and EJB references. The following shows the organization of these elements:

<reference-descriptor>

    <resource-description>

       <res-ref-name>. . .</res-ref-name>

       <jndi-name>. . .</jndi-name>

    </resource-description>

    <ejb-reference-description>

       <ejb-ref-name>. . .</ejb-ref-name>

       <jndi-name>. . .</jndi-name>

    </ejb-reference-description>

</reference-descriptor>

The following elements define an individual resource-description:

• res-ref-name specifies a resource reference name. This is the reference that the EJB provider places within the ejb-jar.xml deployment file.

• jndi-name specifies the JNDI name of an actual resource factory available in WebLogic Server. This is the value that DeployerTool assigns when you map resource references using the instructions in Mapping resource factory references

ejb-reference-description

The following elements define an individual ejb-reference-description:

• res-ref-name specifies an EJB reference name. This is the reference that the EJB provider places within the ejb-jar.xml deployment file.

• jndi-name specifies the JNDI name of an actual EJB available in WebLogic Server. This is the value that DeployerTool assigns when you map EJB references using the instructions in Mapping EJB references

Security role assignments

The security-role-assignment stanza maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server. As with EJB and resource references, the DeployerTool utility simplifies the process of mapping application roles to principals. You can use DeployerTool to connect to a WebLogic Server and assign principal names before deploying. See Mapping application roles to WebLogic Server principals in Deploying EJBs with DeployerTool for more information.

security-role-assignment can contain one or more pairs of the following elements:

• role-name is the application role name that the EJB provider placed in the ejb-jar.xml deployment file.

• principal-name specifies the name of an actual WebLogic Server principal. This is the value that DeployerTool assigns when you map EJB references using the instructions in Mapping application roles to WebLogic Server principals.

enable-call-by-reference

By default, EJB methods called from within the same server pass arguments by reference. This increases the performance of method invocation since parameters are not copied.

If you set enable-call-by-reference to "false," parameters to EJB methods are copied (pass by value) in accordance with the EJB 1.1 specification. Pass by value is always necessary when the EJB is called remotely (not from within the server).

weblogic-cmp-rdbms-jar.xml defines deployment properties for a single entity EJB that uses WebLogic Server RDBMS-based persistence services. See Persistence Services for more information.

The top-level element of weblogic-cmp-rdbms-jar.xml consists of a weblogic-enterprise-bean stanza:

<weblogic-enterprise-bean>

    <pool-name>finance_pool</pool-name>

    <schema-name>FINANCE_APP</schema-name>

    <table-name>ACCOUNT</table-name>

    <attribute-map>

       <object-link>

          <bean-field>accountID</bean-field>

          <dbms-column>ACCOUNT_NUMBER</dbms-column>

       </object-link>

       <object-link>

          <bean-field>balance</bean-field>

          <dbms-column>BALANCE</dbms-column>

       </object-link>

    </attribute-map>

    <finder-list>

       <finder>

          <method-name>findBigAccounts</method-name>

          <method-params>

             <method-param>double</method-param>

          </method-params>

       <finder-query><![CDATA[(> balance $0)]]></finder-query>

       <finder-expression>. . .</finder-expression>

       </finder>

    </finder-list>

    <options>

       <transaction-isolation>TRANSACTION_SERIALIZABLE</transaction-isolation>

    </options>

</weblogic-enterprise-bean>

pool-name specifies name of the WebLogic Server connection pool to use for this EJB's database connectivity. See Using connection pools for more information.

schema-name specifies the schema where the source table is located in the database. This element is required only if you want to use a schema that is not the default schema for the user defined in the EJB's connection pool.

Note: This field is case sensitive, although many SQL implementations ignore case.

table-name specifies the source table in the database. This element is required in all cases.

Note: The user defined in the EJB's connection pool must have read and write privileges to the specified table, though not necessarily schema modification privileges. This field is case sensitive, although many SQL implementations ignore case.

The attribute-map stanza links a single field in the EJB instance to a particular column in the database table. The attribute-map must have exactly one entry for each field of an EJB that uses WebLogic Server RDBMS-based persistence.

Each attribute-map entry consists of an object-link stanza, which represents a link between a column in the database and a field in the EJB instance.

bean-field specifies the field in the EJB instance that should be populated from the database. This element is case sensitive and must precisely match the name of the field in the bean instance.

The field referenced in this tag must also have a cmp-field element defined in the ejb-jar.xml file for the bean.

dbms-column specifies the database column to which the EJB field is mapped. This tag is case sensitive, although many databases ignore the case.

Note: WebLogic Server does not support quoted RDBMS keywords as entries to dbms-column. For example, you cannot create an attribute map for column names such as "create" or "select" if those names are reserved in the underlying datastore.

The finder-list stanza defines the set of all finders that are generated to locate sets of beans. See Writing Finders for RDBMS Persistence for more information.

finder-list must contain exactly one entry for each finder method defined in the home interface, except for findByPrimarykey. If an entry is not provided for findByPrimaryKey, one is generated at compilation time.

Note: If you do provide an entry for findByPrimaryKey, WebLogic Server uses that entry without validating it for correctness. In most cases, you should omit an entry for findByPrimaryKey and accept the default, generated method.

The finder stanza describes a finder method defined in the home interface. The elements contained in the finder stanza enable WebLogic Server to identify which method in the home interface is being described, and to perform required database operations.

method-name defines the name of the finder method in the home interface. This tag must contain the exact name of the method.

The method-params stanza defines the list of parameters to the finder method being specified in method-name.

Note: WebLogic Server compares this list against the parameter types for the finder method in the EJB's home interface; the order and type for the parameter list must exactly match the order and type defined in the home interface.

method-param defines the fully-qualified name for the parameter's type. The type name is evaluated into a java.lang.Class object, and the resultant object must precisely match the respective parameter in the EJB's finder method.

You can specify primitive parameters using their primitive names (such as "double" or "int"). If you use a non-primitive data type in a method-param element, you must specify a fully qualified name. For example, use java.sql.Timestamp rather than Timestamp. If you do not use a qualified name, ejbc generates an error message when you compile the deployment unit.

finder-query specifies the WebLogic Query Language (WLQL) string that is used to retrieve values from the database for this finder. See Using WebLogic Query Language (WLQL) for more information.

Note: Always define the text of the finder-query value using the XML CDATA attribute. Using CDATA ensures that any special characters in the WLQL string do not cause errors when the finder is compiled.

finder-expression specifies a Java language expression to use as a variable in the database query for this finder. See Using Java Expressions in WLQL for more information.

The options stanza defines optional behavior for EJBs using WebLogic Server RDBMS-based persistence. WebLogic Server currently supports only one optional element, transaction-isolation.

transaction-isolation specifies the isolation level for all of the EJB's database operations. The following are possible values for transaction-isolation:

• TRANSACTION_READ_UNCOMMITTED: The transaction can view uncommitted updates from other transactions.

• TRANSACTION_READ_COMMITTED: The transaction can view only committed updates from other transactions.

• TRANSACTION_REPEATABLE_READ: Once the transaction reads a subset of data, repeated reads of the same data return the same values, even if other transactions have subsequently modified the data.

• TRANSACTION_SERIALIZABLE: Simultaneously executing this transaction multiple times has the same effect as executing the transaction multiple times in a serial fashion.

Refer to your database documentation for more information on the implications and support for different isolation levels.