|
|
|
|
|
|
For more information about deploying EJBs in the WLE environment, see Building and Deploying Enterprise JavaBeans (EJBs).
Sun's Enterprise JavaBeans Specification 1.1 (Public Release 2 dated October 18, 1999) specification defines a standard DTD for describing EJB deployment information. For a list of the standard XML elements, see EJB Deployment Descriptor Reference.
WLE extends the ability to configure EJBs by providing additional, optional XML elements that can be associated with EJBs. The Enterprise JavaBeans Specification 1.1 mandates that these extensions must be specified in a separate file. The WebLogic EJB Extensions reside in a file name weblogic-ejb-extensions.xml
, which is included in an ejb-jar file.
The Bean Developer is responsible for creating this file, if needed, and the Application Assembler is responsible for including it in a deployable ejb-jar file. To add this extensions file to an ejb-jar file, an Application Assembler uses the ejbc
command line tool, specifying the -x
parameter and passing this file name (weblogic-ejb-extensions.xml
). For more information about the ejbc
command line tool, see the Command Reference.
About the WebLogic EJB Extensions
Summary of WebLogic EJB Extensions
Synopsis
Specifies an attribute map containing one or more attribute map entries, which define a mapping between an EJB field (a container-managed attribute) and a table column name.
Syntax
<!ELEMENT attribute-map (description?, attribute-map-entry+)>
EJB Role
Bean Provider
Used In
Synopsis
Specifies the mapping between an EJB field and a table column.
Syntax
<!ELEMENT attribute-map-entry (bean-field-name, table-column-name)>
Description
No automatic type conversion between types is performed on primary key columns, and therefore the specified mapping must be between equivalent types.
EJB Role
Bean Provider
Used In
Synopsis
Specifies the name of an EJB field in an attribute map entry.
Syntax
<!ELEMENT bean-field-name (#PCDATA)>
EJB Role
Bean Provider
Used In
Synopsis
Specifies the finder descriptor for finding one or more EJBs.
Syntax
<!ELEMENT finder-descriptor (description?, method?, query-grammar?)>
Valid Values
- Method names must always start with the prefix find .
- If you use a nonprimitive data type in a finder descriptor, you must specify a fully qualified name, such as java.sql.Timestamp .
- Finder descriptors always use EJB field names, not column names, except for the ordering of the returned beans (the OrderBy expression).
Description
Finder descriptors are WLE's implementation of the EJB find methods. If an EJB uses container-managed JDBC persistence, you can specify finder methods of the form findMethod() to find either an individual or collection of EJBs.
The finder-descriptor elements are pairs of method signatures and expressions. You specify a method signature in the EJBHome interface and specify the method's expression in the deployment descriptor using the query-grammar element. Expressions contain method parameters and EJB attributes. The EJB Container automatically maps the attributes to the appropriate columns in the persistent store.
For complex SQL lookups, such as a dynamically set WHERE clause, you need to use bean-managed persistence and write custom finders.
EJB Role
Bean Provider
Used In
Example
The findBigAccounts method has the following interface:
public interface AccountHome extends EJBHome {
// ...
public Enumeration findBigAccounts(double balanceGreaterThan)
throws FinderException, RemoteException;
// ...
}The following sample expression associated with the findBigAccounts method is defined in the deployment descriptor:
(> balance $balanceGreaterThan)
where balance is an attribute (field) of the EJB and $balanceGreaterThan is the symbol for the method parameter balanceGreaterThan .
A call in the client application, such as myEJBean.findBigAccounts(amount) , will return a list of all EJBs whose balance attribute is greater than the value of amount .
Synopsis
Specifies the name for the EJB home that is registered in the Global WLE JNDI namespace.
Syntax
<!ELEMENT jndi-name (#PCDATA)>
Description
To allow Java clients to perform a lookup on the JNDI name for the EJB home and gain access to the object, the name of the EJB home must be registered in the Global WLE JNDI namespace.
This name can differ from the ejb-name element specified in the standard EJB XML. Whereas the ejb-name element must be unique only among the names of the EJBs in the same ejb-jar file, however, the JNDI name must be unique among all global factory names in a WLE domain, including EJB homes, CORBA factories, and RMI-named objects.
EJB Role
Bean Provider
Used In
Example
<weblogic-ejb-extensions>
<weblogic-enterprise-bean>
<ejb-name>Trader</ejb-name>
<weblogic-deployment-params>
<jndi-name>EJB_TraderHome</jndi-name>
</weblogic-deployment-params>
</weblogic-enterprise-bean>
</weblogic-ejb-extensions>
Synopsis
Specifies the server implementation class for handling the initialize and release methods.
Syntax
<!ELEMENT module-initializer-class (module-initializer-class-name)>
Description
The syntax for specifying a Server implementation class for handling the initialize and release methods is specified in the EJB XML deployment descriptor extensions. These XML elements are processed by the ejbc command. The WLE EJB framework parses the XML at run time and performs the startup/shutdown processing.
For a complete description of startup and shutdown handling in WLE, see Starting and Shutting Down Applications.
EJB Role
Bean Provider
Used In
Synopsis
Specifies the fully qualified name of the server implementation class for handling the initialize and release methods.
Syntax
<!ELEMENT module-initializer-class-name (#PCDATA)>
EJB Role
Bean Provider
Used In
Example
<weblogic-ejb-extensions>
...
<module-initializer-class>
<moduleinitializer-class-name>ServerImpl
</moduleinitializer-class-name>
</module-initializer-class>
</weblogic-ejb-extensions>
Synopsis
Specifies the type of persistence storage (in a flat file or a JDBC-managed database) for container-managed persistence.
Syntax
<!ELEMENT persistence-store-descriptor (description?, (persistence-store-file | persistence-store-jdbc)?)>
Description
For container-managed persistence, WLE EJB Container supports storing an EJB in either of the following formats:
- a flat file (the persistence-store-file element)
- a database that is managed with a WLE JDBC connection pool (the persistence-store-jdbc element)
Note: Database persistence is required for an EJB to fully cooperate in a WLE global transaction. File persistence is intended primarily for development and prototyping.
The standard EJB XML descriptor provides XML elements for specifying which fields in the entity bean are to be persisted (the cmp-field element), and information about the primary key. The WebLogic XML extensions provide additional information for mapping to the persistent store.
The code for implementing the persistence is generated by the EJB compiler, based on the bean's deployment descriptors.
EJB Role
Bean Provider
Used In
Example
Using JDBC persistence, the following sample XML code shows how to define the automatic saving of two fields (accountId , balance ) in an entity bean to a database table (ejbAccounts ) using a connection pool (ejbPool ):
<weblogic-ejb-extensions>
<weblogic-enterprise-bean>
<ejb-name>Account</ejb-name>
<weblogic-deployment-params>
<jndi-name>EJB_AccountHome</jndi-name>
<persistence-store-descriptor>
<persistence-store-jdbc>
<pool-name>ejbPool</pool-name>
<table-name>ejbAccounts</table-name>
<attribute-map>
<attribute-map-entry>
<bean-field-name>accountId</bean-field-name>
<table-column-name>id</table-column-name>
</attribute-map-entry>
<attribute-map-entry>
<bean-field-name>balance</bean-field-name>
<table-column-name>bal</table-column-name>
</attribute-map-entry>
</attribute-map>
</persistence-store-jdbc>
</persistence-store-descriptor>
</weblogic-deployment-params>
</weblogic-enterprise-bean>
</weblogic-ejb-extensions>
Synopsis
If persistent storage is kept in a flat file, specifies the directory root for storing all instances of an EJB. Each ejb-name element is converted to a directory name.
Syntax
<!ELEMENT persistence-store-directory-root (#PCDATA)>
Description
For EJBs with container-managed persistence, stateful session beans are stored using file persistence when they are passivated. The persistence-store-directory-root element defines the storage location for these instances. By default, the root directory is pstore , which WLE creates in the directory where the JavaServer is run.
The default file name for a passivated instance is the fully qualified name of the bean, with underscores replacing the periods, plus additional information to ensure uniqueness. For example, if persistence-store-directory-root is c:\weblogic\mystore , all instances of the EJB examples.ejb.AccountBean might be stored in:
c:\weblogic\mystore\examples_ejb_AccountBean\SRVGRP_GROUPX_SRVID_Y_Z_examples.ejb.AccountBean_someBigNumber.db
EJB Role
Bean Provider
Used In
Synopsis
Specifies persistent storage in a flat file.
Syntax
<!ELEMENT persistence-store-file (description?, persistence-store-directory-root)>
Description
File persistence for EJBs is intended primarily for development and prototyping. For an EJB to fully cooperate in a WLE global transaction, use persistence-store-jdbc instead.
EJB Role
Bean Provider
Used In
Synopsis
Specifies persistent storage in a database that is managed by a WLE JDBC connection pool.
Syntax
<!ELEMENT persistence-store-jdbc (description?, pool-name, table-name, attribute-map, finder-descriptor*)>
Description
EJB instances are stored in a database that has been previously set up with the JDBC connection pool specified in the pool-name element. The table-name and attribute-map elements map the EJB fields to the appropriate table columns in the database.
EJB Role
Bean Provider
Used In
Synopsis
Specifies the name of the JDBC connection pool associated with the database used to store EJB state information.
Syntax
<!ELEMENT pool-name (#PCDATA)>
EJB Role
Bean Provider
Used In
Synopsis
Specifies the query expression for a finder method.
Syntax
<!ELEMENT query-grammar (#PCDATA)>
Description
The query grammar syntax has an expression prefix notation of:
[operator operand1 operand2]
Valid operators include:
- ( ) = < > <= >= / ! & |
- like
- isNull
- isNotNull
- orderBy
- ! is the Boolean not
- & is the Boolean and
- | is the Boolean or
- another expression
- an EJB field
- a finder method parameter (when preceded by $ )
EJB Role
Bean Provider
Examples
The following examples show sample query expressions in finder methods.
The following expression determines whether balance exceeds amount.
"(> balance $amount)"
The following example shows the use of compound expressions. Note that single quotes are used to denote strings.
"(& (> bal $amount) (! (= accountType 'checking')))"
The following example is a method signature and an expression that is converted to a findBigAccounts method in the generated persistent storage class. The method returns an enumeration of beans of this class that satisfy this expression.
"findBigAccounts(double amount)" "(> balance $amount)"
The following example finds all the EJBs in a table.
"findAll()" "(= 1 1)"
The following example finds all EJBs whose lastName fields starts with M .
"findNamesStartingWithM()" "(like lastName M%)"
The following example finds all EJBs whose firstName field is null .
"findNullFirstNames()" "(isNull firstName)"
The following example finds all EJBs whose firstName field is not null .
"findNullFirstNames()" "(isNotNull firstName)"
The following expression finds all EJBs in which the value of the balance field exceeds balanceGreaterThan and returns the beans ordered by the id database column. Notice that this expression should all contained in a single line and that no column mapping is performed. The database column must be specified directly.
"findOrderedAccounts(double balanceGreaterThan)"
"(orderBy 'id' (> balance $balanceGreaterThan))"The following expression is identical to the previous one except that it returns the beans in descending order:
"findOrderedAccounts(double balanceGreaterThan)"
"(orderBy 'id desc' (> balance $balanceGreaterThan))"Used In
Synopsis
Specifies the name of a table column in an attribute map entry.
Syntax
<!ELEMENT table-column-name (#PCDATA)>
EJB Role
Bean Provider
Used In
Synopsis
Specifies the name of the table used to store EJB state information.
Syntax
<!ELEMENT table-name (#PCDATA)>
EJB Role
Bean Provider
Used In
Synopsis
Sets the default timeout, in seconds, for container-initiated transactions for this bean. If a transaction duration exceeds this value, the transaction will be rolled back.
Syntax
<!ELEMENT trans-timeout-seconds (#PCDATA)>
EJB Role
Bean Provider
Used In
Synopsis
Specifies deployment options for the WebLogic Server.
Syntax
<!ELEMENT weblogic-deployment-params (trans-timeout-seconds?, jndi-name?, persistence-store-descriptor?)>
EJB Role
Bean Provider
Used In
Synopsis
Root element of the WLE XML extensions to the deployment descriptor.
Syntax
<!ELEMENT weblogic-ejb-extensions (description?, weblogic-version?, weblogic-enterprise-bean*, module-initializer-class*)>
EJB Role
Bean Provider
Synopsis
Specifies deployment information for a bean that is specific to WLE.
Syntax
<!ELEMENT weblogic-enterprise-bean (ejb-name, weblogic-deployment-params?)>
EJB Role
Bean Provider
Used In
Synopsis
Specifies the WLE version.
Syntax
<!ELEMENT weblogic-version (#PCDATA)>
EJB Role
Bean Provider
Used In
Copyright © 1999 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.