Creates WebLogic-specific deployment descriptors (weblogic-ejb-jar.xml and
weblogic-cmp-rdbms-jar.xml files) for EJB beans.
Only WebLogic 6.0 and 6.1 is supported.
Most comments have been copied from the WebLogic DTDs:
http://www.bea.com/servers/wls600/dtd/weblogic-rdbms20-persistence-600.dtd
http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd
Aslak Hellesøy (aslak.hellesoy@netcom.no)
| Attribute | Description | Required |
| xmlencoding | The encoding of the ejb-jar.xml file. | No, default is "UTF-8" |
| version | The version of WLS. | No, default is "6.1". Legal values are "6.0" and "6.1" |
| createtables | Indicates whether or not WLS should attempt to generate tables. | No. Legal values are "True" or "False". If version is < 6.1, this parameter will be ignored. |
| destdir | Destination directory for output WebLogic-specific deployment descriptor files. | No, default is destdir parameter of ejbdoclet task |
| mergedir | Merge directory where ejbdoclet looks for files to be merged with generated files. | No, required, if the merge feature used |
| datasource | Overrides the values of @weblogic:data-source-name for Entity Beans. | No. Only if at least one of the Entity Beans have not specified the @weblogic:data-source-name. |
| validateXml | Validates the generated xml file according to the DTD file contained inside xdoclet.jar. | No, default is false |
| Merge File Name | Description | Required |
|---|---|---|
| weblogic-security-role-assignment.xml | The file where security role mappings are defined. Should comply with the security-role-assignment element's DTD in weblogic-ejb-jar.xml | No, but nothing automatically generated |
Used to specify various options for instance pooling. Applicable to all bean types.
| Parameter | Usage | Applies to | Mandatory |
| [max-beans-in-free-pool]: Integer | WebLogic EJB maintains a free pool of beans for every bean class. This property decides the maximum size of the pool. |
All bean types | No |
| [initial-beans-in-free-pool]: Integer | WebLogic EJB maintains a free pool of beans for every bean class. This property decides the initial size of the pool. |
All bean types | No |
Used to specify various options for the caching. Applicable to Entity Beans and Stateless Session Beans.
| Parameter | Usage | Applies to | Mandatory |
| [max-beans-in-cache]: Integer | Maximum number of objects of this class that are allowed in memory. Objects are kept in an LRU chain, and the ones dropped from the end of the chain are passivated. |
Entity Beans, Stateless Session Beans | No |
| [idle-timeout-seconds]: Integer | The cache (see "max-beans-in-cache" above) is scrubbed of inactive objects after at least this many seconds. Objects scrubbed are passivated. |
Entity Beans, Stateless Session Beans | No |
| [read-timeout-seconds]: Integer | The read-timeout-seconds is the number of seconds between ejbLoad calls
on a Read-Only entity bean. If read-timeout-seconds is 0, ejbLoad will only be called when the bean is brought into the cache. |
Entity Beans | No |
| [concurrency-strategy]: String | The concurrency-strategy specifies how the container should manage
concurrent access to an entity bean. The concurrent-strategy can be one of the following values:
|
Entity Beans | No |
| [cache-type]: String | The cache-type can be one of "NRU" or "LRU". The
default is "NRU". Used in: stateful-session-cache |
Stateless Session Beans (WLS 6.1) | No |
The lifecycle element is used to specify various options for the management of the lifecycle of stateful beans. Applicable to Entity Beans and Stateful Session Beans.
| Parameter | Usage | Applies to | Mandatory |
| [passivation-strategy]: String | The passivation-strategy can be either "default" or
"transaction". With the default setting the container will attempt to keep a working set of beans in the cache. With the "transaction" setting, the container will passivate the bean after every transaction (or method call for a non-transactional invocation). |
Entity Beans, Stateful Session Beans | No |
The persistence element is used to specify persistence options
| Parameter | Usage | Applies to | Mandatory |
| [is-modified-method-name]: String | Applies to bean managed persistence or EJB 1.1 container-managed persistence entity EJBs. EJB 2.0 entity EJBs do not need to implement an is-modified-method. The EJB container can automatically detect which fields were modified in a transaction. This parameter declares the name of an EJBean method that tells the container whether the bean data has been modified. The method is called when the bean managed EJBean is stored. If a method is not specified, WebLogic always assumes that the EJBean has been modified and always saves it. Providing a method and setting it as appropriate will improve performance. |
Entity Beans | No |
| [delay-updates-until-end-of-tx]: Boolean | Applicable to entity beans only (both container- and bean-managed). This optional optimization affects when changes to a bean's state propogated to the persistent store. If this is set to "True" (which is the default) updates of the persistent store of all beans in the transaction will be performed just before the end of the transaction. If this is set to "False" the pstore update of a bean will be performed at the conclusion of each method invoke. |
Entity Beans | No |
| [finders-load-bean]: Boolean | Applicable to CMP entity beans only. This optional optimization affects whether the beans returned by a finder (or ejbSelect method) are loaded immediately into the cache before the finder method returns. If this is set to "True", the beans will immediately be loaded into the cache by the finder. If this is set to "False", the beans will not be loaded into the cache until the first invoke of the bean. The default value is "True", which generally provides the best performance. |
Entity Beans | No |
| [db-is-shared]: Boolean | The value of db-is-shared must be "True" or "False". This parameter applies only to entity beans. If the value is set to "False" the container will assume that it has exclusive access to the bean data in the persistence store. If it is set to "True" the bean will assume that the bean data could be modified between transactions and will therefore reload data at the beginning of each transaction. |
Entity Beans | No |
The stateful-session-clustering element is used to specify various options for how a bean will be replicated in a WebLogic cluster. Applicable to Entity Beans, Stateless Session Beans and Stateful SessionBeans
| Parameter | Usage | Applies to | Mandatory |
| [home-is-clusterable]: Boolean | The valid values of the home-is-clusterable parameter are "True" or "False." If "True," this bean can be deployed from multiple servers in a cluster. Calls to the home stub will be load-balanced between the servers on which this bean is deployed, and if a server hosting the bean is unreachable, the call will automatically failover to another server hosting the bean. The valid values of the stateless-bean-is-clusterable parameter |
Entity Beans, Stateful Session Beans | No |
| [home-load-algorithm]: String | The home-load-algorithm specifies the algorithm to use for
load-balancing between replicas of this home. If this property is not specified, the algorithm specified by the server property weblogic.cluster.defaultLoadAlgorithm will be used. The value of this element must be one of the following: RoundRobin Random WeightBased |
Entity Beans, Stateful Session Beans | No |
| [home-call-router-class-name]: String | The home-call-router-class-name specifies a custom class to be used for routing home method calls. This class must implement weblogic.rmi.cluster.CallRouter. If specified, an instance of this class will be called before each method call and be given the opportunity to choose a server to route to based on the method parameters. It either returns a server name or null indicating that the current load algorithm should be used to pick the server. |
Entity Beans, Stateful Session Beans | No |
| [replication-type]: String | The replication-type element describes how to replicate stateful session beans in a cluster. The legal values are: "InMemory": The bean will be replicated in memory across the cluster "None": The bean will not be replicated. |
Stateful Session Beans | No |
| [stateless-bean-is-clusterable]: Boolean | The valid values of the stateless-bean-is-clusterable parameter are "True" or "False." The parameter is applicable only to session EJBeans with a session-type value of "Stateless" (see ejb-jar.dtd). If home-is-clusterable is "True" and this parameter is also "true", calls to this bean stub will be load-balanced between all the the servers on which this bean is deployed, and if a server hosting the bean becomes unreachable, the call will automatically failover to another server hosting the bean. |
Stateless Session Beans | No |
| [stateless-bean-load-algorithm]: String | The stateless-bean-load-algorithm specifies the algorithm to use for load-balancing between replicas of this bean. If this property is not specified, the algorithm specified by the server property weblogic.cluster.defaultLoadAlgorithm will be used. The legal values of stateless-bean-load-algorithm are: RoundRobin Random WeightBased |
Stateless Session Beans | No |
| [stateless-bean-call-router-class-name]: String | The stateless-bean-call-router-class-name specifies a custom class to be used for routing bean method calls. This class must implement weblogic.rmi.cluster.CallRouter. If specified, an instance of this class will be called before each method call and be given the opportunity to choose a server to route to based on the method parameters. It either returns a server name or null indicating that the current load algorithm should be used to pick the server. |
Stateless Session Beans | No |
| [stateless-bean-methods-are-idempotent]: Boolean | The value of the stateless-bean-methods-are-idempotent must be either "True" or "False." This parameter is applicable only to session EJBeans with a session-type of "Stateless" (see ejb-jar.dtd). The value should be set 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. |
Stateless Session Beans | No |
The invalidation-target element specifies a Read-Only Entity EJB which should
be invalidated when this Container-Managed Persistence Entity EJB has been
modified.
Note that the target ejb-name must be a Read-Only Entity EJB, and this tag may
only be specified in an EJB 2.0 Container-Managed Persistence Entity
EJB.
| Parameter | Usage | Applies to | Mandatory |
| [ejb-name]: String | Name of the EJB to be invalidated | Entity Beans (WLS 6.1) | No |
The allow-concurrent-calls specifies whether a stateful session bean instance will allow concurrent method calls. The value of this element may be either "True" or "False". The default value is "False". When a stateful session bean instance is currently in a method call and another (concurrent) method call arrives on the server, the EJB specification requires that the server throw a RemoteException. By default, allow-concurrent-calls is false, and the EJB container will follow the EJB specification. When this value is set to true, the EJB container will block the concurrent method call and allow it to proceed when the previous call has completed.
Various settings for Message Driven Beans.
| Parameter | Usage | Applies to | Mandatory |
| [destination-jndi-name]: String | The destination-jndi-name element is used to associate a message-driven
bean with a JMS Queue or Topic that has been deployed in the WebLogic JNDI tree. |
Message Driven Beans | No |
| [initial-context-factory]: String | This element specifies the URL provider to be put in the Properties used by the InitialContext. It is typically host:port and used in conjunction with initial-context-factory and connection-factory-jndi-name. |
Message Driven Beans | No |
| [connection-factory-jndi-name]: String | This parameter specifies the JNDI name of the JMS ConnectionFactory that the MessageDriven Bean should look up to create its Queues and Topics. If not specified, it will default to weblogic.jms.MessageDrivenBeanConnectionFactory, which must have been declared in config.xml. |
Message Driven Beans | No |
| [jms-polling-interval-seconds]: Integer | Each Message-Driven EJB listens on an associated JMS destination. If the JMS destination is located on another WebLogic Server instance or a foreign JMS provider, it is possible that the JMS destination will become unreachable. In this case, the EJB container automatically attempts to reconnect to the JMS Server. Once the JMS Server is up again, the Message-Driven EJB can again receive JMS messages. The jms-polling-interval-seconds determines the number of seconds between each attempt to reconnect to the JMS destination. The default value is 10 seconds. |
Message Driven Beans (WLS 6.1) | No |
| [jms-polling-interval-seconds]: Integer | The JMS specification allows JMS consumers to specify an associated id. This id is necessary for durable subscriptions to JMS topics. A Message-Driven EJB with a durable subscription needs an associated client id. If a separate connection factory is used, the client id can be set on the connection factory. In this case, the Message-Driven EJB uses this client id. If the associated connection factory does not have a client id (or you are using the default connection factory), the Message-Driven EJB uses the jms-client-id value as its client id. |
Message Driven Beans (WLS 6.1) | No |
The transaction-descriptor specifies properties relating to transactions. Applicable to all bean types
| Parameter | Usage | Applies to | Mandatory |
| [destination-jndi-name]: String | Sets the default timeout for container-initiated transactions for this bean. If a transaction's duration is longer than this value, it will be rolled back. |
All bean types | No |
The resource-description element is used to map a resource-ref, declared in the ejb-jar.xml deployment descriptor, to the JNDI name of the server resource factory it represents.
| Parameter | Usage | Applies to | Mandatory |
| [res-ref-name]: String | The res-ref-name element specifies the name of a resource factory reference. |
All bean types | No |
| [jndi-name]: String | This jndi-name for the resource. | All bean types | No |
The resource-env-description element is used to map a resource-env-ref, declared in the ejb-jar.xml deployment descriptor, to the JNDI name of the server resource it represents.
| Parameter | Usage | Applies to | Mandatory |
| [res-env-ref-name]: String | The res-env-ref-name element specifies the name of a resource
environment reference. |
All bean types | No |
| [jndi-name]: String | This jndi-name for the resource. | All bean types | No |
The ejb-reference-description is used to map the JNDI name in the WebLogic server of an EJB that is referenced by the bean in an ejb-reference.
| Parameter | Usage | Applies to | Mandatory |
| ejb-ref-name: String | The ejb-ref-name element contains the name of an EJB reference. The EJB reference is an entry in the enterprise bean's environment. |
All bean types | Yes |
| jndi-name: String | This jndi-name for the ejb. | All bean types | Yes |
The ejb-local-reference-description is used to map the JNDI name in the WebLogic server of an EJB that is referenced by the bean in an ejb-local-ref.
| Parameter | Usage | Applies to | Mandatory |
| ejb-ref-name: String | The ejb-ref-name element contains the name of an EJB reference. The EJB reference is an entry in the enterprise bean's environment. |
All bean types | Yes |
| jndi-name: String | This jndi-name for the ejb. | All bean types | Yes |
Pass by value is always necessary when the EJB is called remotely (not
from within the server). By setting enable-call-by-reference to
"True", EJB methods called from within the same server will pass
arguments by reference. This increases the performance of method
invocation since parameters are not copied.
The value of enable-call-by-reference must be "True" or
"False".
The run-as-identity-principal element specifies which security principal is
to be used for the run-as identity. This tag is necessary if the role
specified in the run-as element of the ejb-jar.xml descriptor does not map to
a single security principal representing a User in the security realm. This
could be true in two cases. One case is where the role maps to multiple
security principals (see security-role-assignment element). In this case,
the run-as-identity-principal element must be used to specify which of the
security principals you would like to be used. The other case is where the
role maps to a single security principal that represents a Group in the
security realm. In this case the run-as-identity-principal element must be
used to specify a particular User in the security realm.
(Applicable to CMP Entity Beans)
The JNDI name of the WebLogic data source which should be used for all
database connectivity for this particular bean. This data source must
be defined in the standard way for WebLogic JDBC data sources. If you
do not know how to do this please consult the WebLogic Server
Documentation.
(Applicable to CMP Entity Beans)
The fully qualified SQL name of the source table in the database. Note
that this needs to be set in all cases. The user defined for the data
source for this bean must have read and write privileges on this
table, though not necessarily schema modification privileges.
(Applicable to CMP Entity Beans)
The delay-database-insert-until element is used to specify the
precise time at which a new bean that uses RDBMS CMP is inserted into
the database. By default, the database insert is done after ejbPostCreate.
Delaying the database insert until after ejbPostCreate is required
when a cmr-field is mapped to a foreign-key column that doesn't allow
null values. In this case, the cmr-field must be set to a non-null value
in ejbPostCreate before the bean is inserted into the database. Note that
cmr-fields may not be set during ejbCreate, before the primary key of the
bean is known.
It is also generally advisable to delay the database insert until after
ejbPostCreate if the ejbPostCreate method modifies the persistent
fields of the bean. This can yield better performance by avoiding an
unnecessary store operation.
For maximum flexibility, developers should avoid creating related
beans in their ejbPostCreate method. This may make delaying the
database insert impossible if database constraints prevent related
beans from referring to a bean that has not yet been created.
Allowed values:
ejbCreate - perform database insert immediately after ejbCreate
ejbPostCreate - perform insert immediately after ejbPostCreate (default)
(Applicable to CMP Entity Beans) (WLS 6.1)
| Parameter | Usage | Applies to | Mandatory |
| [generator-type]: String | Specifies the Key Generation Method that will be employed
|
CMP Entity Beans (WLS 6.1) | Yes |
| [generator-name]: String | If this is DBMS Key Generation, then this may be used to
specify the Name of the Generator, e.g. for generator-type ORACLE generator-name would be the name of the ORACLE SEQUENCE to use. The SEQUENCE is assumed to already exist in the Database. If this is generator-type NAMED_SEQUENCE_TABLE Key Generation, Then this would be used to specify the name of the SEQUENCE TABLE to use. The NAMED_SEQUENCE_TABLE is assumed to already exist in the Database with 1 row. |
CMP Entity Beans (WLS 6.1) | No |
| [key-cache-size]: Integer | Optional size of key cache. For generator-type ORACLE , this
value MUST match the Oracle SEQUENCE INCREMENT value. If there is a
mismatch between this value and the Oracle SEQUENCE INCREMENT value, then
there will likely be duplicate key problems. For generator-type NAMED_SEQUENCE_TABLE, this tells how many keys the Container will fetch in a single DBMS call For generator-type SQL_SERVER, this value is ignored |
CMP Entity Beans (WLS 6.1) | No |
(Applicable to CMP Entity Beans)
The database column to which the given field should be mapped. This element is case maintaining, though not all databases are case sensitive.
(Applicable to CMP Entity Beans) (WLS 6.1)
The dbms-column-type can be either OracleBlob or OracleClob. This will map the current field to a Blob or Clob in Oracle database.
(Applicable to CMP Entity Beans)
A field-group represents a subset of the cmp and cmr-fields of a bean.
Related fields in a bean can be put into groups which are faulted
into memory together as a unit. A group can be associated 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 may belong to multiple groups. In this case, the getXXX() method
for the field will fault in the first group (lexically speaking) that
contains the field.
(Applicable to CMP Entity Beans with CMR)
Used in conjunction with the @ejb:relation
tag.
| Parameter | Usage | Applies to | Mandatory |
| [join-table-name]: String | Specifies the join table of a m:n relationship | M:N relationships. (Bidirectional and unidirectional). | Only for m:n relationships |
| [group-name]: String | Specifies the group name of the corresponding weblogic-relationship-role | All relationships. (Bidirectional and unidirectional). | No |
| [target-group-name]: String | Specifies the group name of the corresponding weblogic-relationship-role | (Unidirectional m:n relationships). | No |
| [db-cascade-delete]: String | The db-cascade-delete tag specifies that a cascade delete
will use the builtin cascade delete facilities of the underlying DBMS. (Not implemented yet) |
All relationships, but only if @ejb:relation cascade-delete="true" | No |
| [target-db-cascade-delete]: String | The db-cascade-delete tag specifies that a cascade delete
will use the builtin cascade delete facilities of the underlying DBMS. (Not implemented yet) |
All relationships, but only if @ejb:relation target-cascade-delete="true" and relation is unidirectional | No |
(Applicable to CMP Entity Beans with CMR)
Used in conjunction with the @ejb:relation
tag.
| Parameter | Usage | Applies to | Mandatory |
| foreign-key-column: String | Represents a mapping from a foreign key column in one table in the database to a corresponding primary key column. The two columns may or may not be in the same table. The tables to which the column belong are implicit from the context in which the column-map element appears in the deployment descriptor. | All relationships. Should only be specified on Entity Beans where the foreign key is on the other side of the relation. | Yes |
| [key-column]: String | The key-column element is not specified if the
foreign-key-column refers to a 'remote' bean. |
All relationships. Should only be specified on Entity Beans where the foreign key is on the other side of the relation. | No |
(Applicable to CMP Entity Beans with CMR)
Used in conjunction with the @ejb:relation
tag. This tag only applies to unidirectional m:n relationships.
| Parameter | Usage | Applies to | Mandatory |
| foreign-key-column: String | unidirectional m:n relationships | Yes | |
| [key-column]: String | unidirectional m:n relationships | No |
(Applicable to CMP 1.1 Entity Beans)
| Parameter | Usage | Applies to |
| [finder-query]: String | A raw SQL string that will be used instead of the standard
EJB QL query to retrieve values from the database for this finder. Any amount of vendor specific SQL may be used. |
CMP 1.1 Entity Beans |
| [find-for-update]: String | The optional find-for-update element can contain a value of
'true' or 'false'. The default value is 'false'. When find-for-update is true, a SELECT...FOR UPDATE statement is generated for the finder method. This option should only be used with a database that supports SELECT...FOR UPDATE, such as Oracle. The purpose of find-for-update is to cause the finder method to acquire a write lock on the database row. |
CMP 1.1 Entity Beans |