<a href="../../../wls81/docs/ejb/EJB_tools.html#1096697">WebLogic Server EJB Tools</a>

BEA provides several tools you can use to help you create and configure EJBs. They are discussed in the following sections:

EJBGen

EJBGen is an Enterprise JavaBeans 2.0 code generator. You can annotate your Bean class file with javadoc tags and then use EJBGen to generate the Remote and Home classes and the deployment descriptor files for an EJB application, reducing to one the number of EJB files you need to edit and maintain.

BEA recommends that you use EJBGen to generate deployment descriptors ; this is a BEA best practice which allows for easier and simpler maintenance of EJBs. When you use EJBGen, you have to write and annotate only one bean class file, which simplifies writing, debugging and maintenance. Moreover, if you use WebLogic Workshop to as a development environment, WebLogic Workshop automatically inserts EJBGen tags for you.

If you have installed BEA WebLogic 8.1 examples, see WL_HOME\samples\server\examples\src\examples\ejb20\ejbgen for an example application called Bands that uses EJBGen.

EJBGen Syntax

If you do not have weblogic.jar in your classpath, add the path to weblogic.jar as follows:

If you are invoking EJBGen for an EJB that has relationships with other EJBs, invoke the related EJBs by naming them, following your EJB, in the invocation, as follows:

Option Definition
-d [directory] The directory under which all the files will be created.
-descriptorDir [directory] The directory under which all the descriptor files will be created.
-ignorePackage
If this flag is set, EJBGen ignores the package name of the Java files it generates and creates those in the output directory as specified by the -d flag (or in the current directory if no -d was specified).
-pfd1
If this flag is set, EJBGen will generate deployment descriptors compatible with the Public Final Draft 1 of the EJB 2.0 specification. You should use this flag if you are using any version anterior to Weblogic 6.1.
-ejbPrefix [string] (default: "")
The prefix to use when generating the EJB class.
-ejbSuffix [string] (default: "Bean" or "EJB")
The suffix to use when generating the EJB class.
-localHomePrefix [string] (default: "")
The prefix to use when generating the local EJB class.
-localHomeSuffix [string] (default: "LocalHome")
The suffix to use when generating the local EJB class.
-remoteHomePrefix [string] (default: "")
The prefix to use when generating the remote EJB home class.
-remoteHomeSuffix [string] (default: "Home")
The suffix to use when generating the remote EJB home class.
-remotePrefix [string] (default: "")
The prefix to use when generating the remote EJB class.
-remoteSuffix [string] (default: "")
The suffix to use when generating the remote EJB class.
-localPrefix [string] (default: "")
The prefix to use when generating the local EJB class.
-localSuffix [string] (default: "Local")
The suffix to use when generating the local EJB class.
-valueObjectPrefix [string] (default: "")
The prefix to use when generating the value object class.
-valueObjectSuffix [string] (default: "Value")
The suffix to use when generating the value object class.
-jndiPrefix [string] (default: "")
The prefix to use for @remote-jndi-name and @local-jndi-name
-jndiSuffix [string] (default: "")
The suffix to use for @remote-jndi-name and @local-jndi-name
-checkTags
If invoked with this option, EJBGen will not generate any classes but will search the classes supplied on the command line for tags that are not valid EJBGen tags.
-docTags
Print out all the tags known by EJBGen. Note that even though this option does not need any source file, you still need to specify an existing .java class on the command line, or Javadoc will emit an error message even though it recognized the flag.
-docTag tagName
If specified, EJBGen prints out the detailed documentation for this tag, including all the recognized attributes. Note that even though this option does not need any source file, you still need to specify an existing .java class on the command line, or Javadoc will emit an error message even though it recognized the flag.
-docTagsHtml
Same as -docTags, but generates an HTML document.
-propertyFile [fileName]
The name of a property file that EJBGen reads to define substitution variables.
-noValueClasses
If specified, value classes will not be generated.
-noRemoteInterfaces If specified, remote interfaces are not generated.
-noLocalInterfaces If specified, local interfaces are not generated.
-wls7 Use this flag to specify that EJBGen generate WebLogic Server 7.0 deployment descriptors.
-toStringForPrimitivesOnly If specified, the toString () methods of value objects only display container-managed persistence fields that are primitives. This flag fixes the problem of circular references between value objects (AValue.toString() invoking BValue.toString() invoking AValue.toString(), etcetera).

Option	Definition
-d [directory]	The directory under which all the files will be created.
-descriptorDir [directory]	The directory under which all the descriptor files will be created.
-ignorePackage	If this flag is set, EJBGen ignores the package name of the Java files it generates and creates those in the output directory as specified by the -d flag (or in the current directory if no -d was specified).
-pfd1	If this flag is set, EJBGen will generate deployment descriptors compatible with the Public Final Draft 1 of the EJB 2.0 specification. You should use this flag if you are using any version anterior to Weblogic 6.1.
-ejbPrefix [string] (default: "")	The prefix to use when generating the EJB class.
-ejbSuffix [string] (default: "Bean" or "EJB")	The suffix to use when generating the EJB class.
-localHomePrefix [string] (default: "")	The prefix to use when generating the local EJB class.
-localHomeSuffix [string] (default: "LocalHome")	The suffix to use when generating the local EJB class.
-remoteHomePrefix [string] (default: "")	The prefix to use when generating the remote EJB home class.
-remoteHomeSuffix [string] (default: "Home")	The suffix to use when generating the remote EJB home class.
-remotePrefix [string] (default: "")	The prefix to use when generating the remote EJB class.
-remoteSuffix [string] (default: "")	The suffix to use when generating the remote EJB class.
-localPrefix [string] (default: "")	The prefix to use when generating the local EJB class.
-localSuffix [string] (default: "Local")	The suffix to use when generating the local EJB class.
-valueObjectPrefix [string] (default: "")	The prefix to use when generating the value object class.
-valueObjectSuffix [string] (default: "Value")	The suffix to use when generating the value object class.
-jndiPrefix [string] (default: "")	The prefix to use for @remote-jndi-name and @local-jndi-name
-jndiSuffix [string] (default: "")	The suffix to use for @remote-jndi-name and @local-jndi-name
-checkTags	If invoked with this option, EJBGen will not generate any classes but will search the classes supplied on the command line for tags that are not valid EJBGen tags.
-docTags	Print out all the tags known by EJBGen. Note that even though this option does not need any source file, you still need to specify an existing .java class on the command line, or Javadoc will emit an error message even though it recognized the flag.
-docTag tagName	If specified, EJBGen prints out the detailed documentation for this tag, including all the recognized attributes. Note that even though this option does not need any source file, you still need to specify an existing .java class on the command line, or Javadoc will emit an error message even though it recognized the flag.
-docTagsHtml	Same as -docTags, but generates an HTML document.
-propertyFile [fileName]	The name of a property file that EJBGen reads to define substitution variables.
-noValueClasses	If specified, value classes will not be generated.
-noRemoteInterfaces	If specified, remote interfaces are not generated.
-noLocalInterfaces	If specified, local interfaces are not generated.
-wls7	Use this flag to specify that EJBGen generate WebLogic Server 7.0 deployment descriptors.
-toStringForPrimitivesOnly	If specified, the toString () methods of value objects only display container-managed persistence fields that are primitives. This flag fixes the problem of circular references between value objects (AValue.toString() invoking BValue.toString() invoking AValue.toString(), etcetera).

EJBGen Example

This example shows a Bean file annotated so that EJBGen will generate the Remote and Home interfaces and the deployment descriptor files. AccountBean.java is the main bean class. It is a CMP EJB 2.0 Entity bean:

/**


 * @ejbgen:entity



*   ejb-name  = AccountEJB-OneToMany



*   data-source-name  = examples-dataSource-demoPool



*   table-name = Accounts



*   prim-key-class = java.lang.String


 * @ejbgen:jndi-name


 *   local = one2many.AccountHome

 


 * @ejbgen:finder


 *   signature = "Account findAccount(double balanceEqual)"



*   ejb-ql  = "WHERE balance = ?1"


 * @ejbgen:finder


 *   signature = "Collection findBigAccounts(double balanceGreaterThan)"


 *   ejb-ql  = "WHERE balance > ?1"


 * @ejbgen:relation


 *   name = Customer-Account



*   target-ejb  = CustomerEJB-OneToMany



*   multiplicity  = many



*   cmr-field  = customer

*/


abstract public class AccountBean implements EntityBean {

/**


   * @ejbgen:cmp-field column = acct_id


   * @ejbgen:primkey-field


   * @ejbgen:remote-method transaction-attribute  = Required

*/


  abstract public String getAccountId();


  abstract public void setAccountId(String val);


  // ....

As you can see from this example, there are two types of tags: class tags and method tags, depending on where you can use them.

Once you finish editing your file, you invoke EJBGen through the following Javadoc command:


javadoc -docletpath weblogic.jar -doclet weblogic.tools.ejbgen.EJBGen AccountBean.java

The Javadoc command generates the following files:

Account.java
AccountHome.java
ejb-jar.xml
weblogic-ejb-jar.xml
weblog-cmp-rdbms-jar.xml

EJBGen Tags

Use the following tags to annotate your bean class file.

@ejbgen:automatic-key-generation

Where: Class

Applicable on: Entity bean

Attribute Description Required
cache-size The size of the key cache. Yes
name The name of the generator. Yes
type The type of the generator. Yes

Attribute	Description	Required
cache-size	The size of the key cache.	Yes
name	The name of the generator.	Yes
type	The type of the generator.	Yes

@ejbgen:cmp-field

Where: Method

Applicable on: Entity bean

Attribute Description Required
column The column where this CMP field will be mapped. Yes
column-type The type of this column. (OracleClob|OracleBlob) No
ordering-number (0..n) The number where this field must appear in signatures and constructors. For this ordering to work, all cmr and cmp fields must set this attribute to a distinct numeric value. No
exclude-from-value-object (True|False) If True, this field will not be generated in the value object. No
group-names Comma-delimited names of the groups this field belongs to. No
primkey-field (True|False) Whether this field is part of the compound primary key. No
table-name The table(s) where this field should be mapped. Mapping an Entity Bean to Several Tables. No

Attribute	Description	Required
column	The column where this CMP field will be mapped.	Yes
column-type	The type of this column. (OracleClob\|OracleBlob)	No
ordering-number (0..n)	The number where this field must appear in signatures and constructors. For this ordering to work, all cmr and cmp fields must set this attribute to a distinct numeric value.	No
exclude-from-value-object	(True\|False) If True, this field will not be generated in the value object.	No
group-names	Comma-delimited names of the groups this field belongs to.	No
primkey-field	(True\|False) Whether this field is part of the compound primary key.	No
table-name	The table(s) where this field should be mapped. Mapping an Entity Bean to Several Tables.	No

@ejbgen:cmr-field

Where:Method

Applicable on: Entity bean

Attribute Description Required
ordering-number (0..n) The number where this field must appear in signatures and constructors. For this ordering to work, all cmr and cmp fields must have this attribute to a distinct numeric value. No
exclude-from-value-object (True|False) If True, this field will not be generated in the value object. No
group-names Comma-delimited names of the groups this field belongs to. No

Attribute	Description	Required
ordering-number (0..n)	The number where this field must appear in signatures and constructors. For this ordering to work, all cmr and cmp fields must have this attribute to a distinct numeric value.	No
exclude-from-value-object	(True\|False) If True, this field will not be generated in the value object.	No
group-names	Comma-delimited names of the groups this field belongs to.	No

@ejbgen:create-default-rdbms-tables

Where: Class

Applicable on: Entity bean

Attribute Description Required
value (CreateOnly|Disabled|DropAndCreate|DropAndCreateAlways|AlterOrCreate) No

Attribute	Description	Required
value	(CreateOnly\|Disabled\|DropAndCreate\|DropAndCreateAlways\|AlterOrCreate)	No

@ejbgen:ejb-client-jar

Where: Class

Applicable on: All bean types

Attribute Description Required
file-name The name of the client JAR to generate. If more than one EJB's have this tag, only one of the specified JAR files is included in the deployment descriptor. Yes

Attribute	Description	Required
file-name	The name of the client JAR to generate. If more than one EJB's have this tag, only one of the specified JAR files is included in the deployment descriptor.	Yes

@ejbgen:ejb-local-ref

Where: Class

Applicable on: Session and entity beans

Attribute Description Required
home Local class of the bean. No
jndi-name The JNDI name of the reference. No
link Link to the bean. No
local Home class of the bean. No
name Name of the reference. No
type (Entity | Session) No

Attribute	Description	Required
home	Local class of the bean.	No
jndi-name	The JNDI name of the reference.	No
link	Link to the bean.	No
local	Home class of the bean.	No
name	Name of the reference.	No
type	(Entity \| Session)	No

@ejbgen:ejb-ref

Where: Class

Applicable on: All bean types

Attribute Description Required
home Remote class of the bean. No
jndi-name The JNDI name of the reference. No
link Link of the bean. No
name Name of the reference. No
remote Home class of the bean. No
type (Entity|Session) No

Attribute	Description	Required
home	Remote class of the bean.	No
jndi-name	The JNDI name of the reference.	No
link	Link of the bean.	No
name	Name of the reference.	No
remote	Home class of the bean.	No
type	(Entity\|Session)	No

@ejbgen:entity

Where: Class

Applicable on: Entity beans

Attribute Description Required
ejb-name The name of this entity bean. Yes
prim-key-class null Yes
abstract-schema-name The abstract schema name for this EJB. If not specified, the ejb-name value will be used. No
cache-between-transactions (True|False) Whether to cache the persistent data of an entity bean across (between) transactions. No
check-exists-on-method (True|False) Whether the container checks for the existence of a bean for each method call. No
concurrency-strategy (Optimistic|ReadOnly|Exclusive|Database) Defines the concurrency strategy for this bean. No
data-source-name The name of the DataSource (as it was declared in your config.xml file). No
database-type The type of the database.

db-is-shared (True|False) No
default-transaction The transaction attribute to be applied to all methods that do not have a more specific transaction attribute setting. No
delay-database-insert-until (ejbCreate|ejbPostCreate) No
delay-updates-until-end-of-tx (True|False) Whether updates will be sent after the transaction has committed. No
dispatch-policy The JMS dispatch policy queue for this bean No
enable-call-by-reference (True|False) Whether the container will call this EJB by reference No
enable-dynamic-queries (True|False) Whether dynamic queries are enabled. No
finders-load-bean (True|False) If this is set to True, the beans will immediately be loaded into the cache by the finder. No
home-call-router-class-name Class to be used for routing home method calls. No
home-is-clusterable (True|False) Whether this bean can be deployed from multiple servers in a cluster. No
home-load-algorithm (RoundRobin|Random|WeightBased) The algorithm to use for load-balancing between replicas of this home. No
idle-timeout-seconds Maximum duration an EJB should stay in the cache. No
invalidation-target The ejb-name of a read-only entity bean that should be invalidated when this container-managed persistence entity EJB has been modified. No
max-beans-in-cache The maximum number of beans in the cache. No
optimistic-column The column that holds the timestamp for optimistic concurrency No
persistence-type (CMP|BMP) Whether this bean's persistence is container managed or bean-managed. No
prim-key-class-nogen (True|False). If this keyword is specified, EJBGen does not generate the primary key class - it is assumed that you are providing it yourself. No
read-timeout-seconds The number of seconds between each ejbLoad() call on a read-only entity bean. No
reentrant (True|False) No
run-as Specifies the role-name for this EJB. No
run-as-identity-principal The name of the principal in case the role maps to several principals. No
table-name The Java class of the primary key. In case of a compound primary key, this class is generated by EJBGen. No
trans-timeout-seconds The transaction timeout, in seconds. No
use-caller-identity (True|False) Whether this EJB uses caller's identity. No
use-select-for-update (True|False) Causes SELECT ... FOR UPDATE to be used whenever the bean is loaded from the database. No
validate-db-schema-with (MetaData|TableQuery) The method used to validate the tables created by the EJB container. No
verify-columns (Read|Modified|Version|Timestamp) How optimistic concurrency verifies that the columns modified during the transactions have not been modified. No

Attribute	Description	Required
ejb-name	The name of this entity bean.	Yes
prim-key-class	null	Yes
abstract-schema-name	The abstract schema name for this EJB. If not specified, the ejb-name value will be used.	No
cache-between-transactions	(True\|False) Whether to cache the persistent data of an entity bean across (between) transactions.	No
check-exists-on-method	(True\|False) Whether the container checks for the existence of a bean for each method call.	No
concurrency-strategy	(Optimistic\|ReadOnly\|Exclusive\|Database) Defines the concurrency strategy for this bean.	No
data-source-name	The name of the DataSource (as it was declared in your config.xml file).	No
database-type	The type of the database.
db-is-shared	(True\|False)	No
default-transaction	The transaction attribute to be applied to all methods that do not have a more specific transaction attribute setting.	No
delay-database-insert-until	(ejbCreate\|ejbPostCreate)	No
delay-updates-until-end-of-tx	(True\|False) Whether updates will be sent after the transaction has committed.	No
dispatch-policy	The JMS dispatch policy queue for this bean	No
enable-call-by-reference	(True\|False) Whether the container will call this EJB by reference	No
enable-dynamic-queries	(True\|False) Whether dynamic queries are enabled.	No
finders-load-bean	(True\|False) If this is set to True, the beans will immediately be loaded into the cache by the finder.	No
home-call-router-class-name	Class to be used for routing home method calls.	No
home-is-clusterable	(True\|False) Whether this bean can be deployed from multiple servers in a cluster.	No
home-load-algorithm	(RoundRobin\|Random\|WeightBased) The algorithm to use for load-balancing between replicas of this home.	No
idle-timeout-seconds	Maximum duration an EJB should stay in the cache.	No
invalidation-target	The ejb-name of a read-only entity bean that should be invalidated when this container-managed persistence entity EJB has been modified.	No
max-beans-in-cache	The maximum number of beans in the cache.	No
optimistic-column	The column that holds the timestamp for optimistic concurrency	No
persistence-type	(CMP\|BMP) Whether this bean's persistence is container managed or bean-managed.	No
prim-key-class-nogen	(True\|False). If this keyword is specified, EJBGen does not generate the primary key class - it is assumed that you are providing it yourself.	No
read-timeout-seconds	The number of seconds between each ejbLoad() call on a read-only entity bean.	No
reentrant	(True\|False)	No
run-as	Specifies the role-name for this EJB.	No
run-as-identity-principal	The name of the principal in case the role maps to several principals.	No
table-name	The Java class of the primary key. In case of a compound primary key, this class is generated by EJBGen.	No
trans-timeout-seconds	The transaction timeout, in seconds.	No
use-caller-identity	(True\|False) Whether this EJB uses caller's identity.	No
use-select-for-update	(True\|False) Causes SELECT ... FOR UPDATE to be used whenever the bean is loaded from the database.	No
validate-db-schema-with	(MetaData\|TableQuery) The method used to validate the tables created by the EJB container.	No
verify-columns	(Read\|Modified\|Version\|Timestamp) How optimistic concurrency verifies that the columns modified during the transactions have not been modified.	No

@ejbgen:entity-cache-ref

Where: Class

Applicable on: Entity beans

Attribute Description Required
cache-between-transactions (True|False) Whether to cache the persistent data of an entity bean across (between) transactions. No
concurrency-strategy (Optimistic|ReadOnly|Exclusive|Database) Defines the concurrency strategy for this bean. No
name The name of the cache. No
estimated-bean-size The estimated average size of the instances of an entity bean in bytes. No

Attribute	Description	Required
cache-between-transactions	(True\|False) Whether to cache the persistent data of an entity bean across (between) transactions.	No
concurrency-strategy	(Optimistic\|ReadOnly\|Exclusive\|Database) Defines the concurrency strategy for this bean.	No
name	The name of the cache.	No
estimated-bean-size	The estimated average size of the instances of an entity bean in bytes.	No

@ejbgen:env-entry

Where:Class

Applicable on: All bean types

Attribute Description Required
name The name of this environment entry. Yes
type The Java type for this environment entry (must be fully qualified, even if java.lang). Yes
value The value for this environment entry. Yes

Attribute	Description	Required
name	The name of this environment entry.	Yes
type	The Java type for this environment entry (must be fully qualified, even if java.lang).	Yes
value	The value for this environment entry.	Yes

@ejbgen:file-generation

Where:Class

Applicable on: All bean types

Attribute Description Required
local-class (True|False) Whether to generate the local interface for this EJB. No
local-home (True|False) Whether to generate the local home interface for this EJB. No
pk-class (True|False) Whether to generate the primary key class for this EJB. No
remote-class (True|False) Whether to generate the remote interface for this EJB. No
remote-home (True|False) Whether to generate the remote home interface for this EJB. No
value-class (True|False) Whether to generate the value class for this EJB. No

Attribute	Description	Required
local-class	(True\|False) Whether to generate the local interface for this EJB.	No
local-home	(True\|False) Whether to generate the local home interface for this EJB.	No
pk-class	(True\|False) Whether to generate the primary key class for this EJB.	No
remote-class	(True\|False) Whether to generate the remote interface for this EJB.	No
remote-home	(True\|False) Whether to generate the remote home interface for this EJB.	No
value-class	(True\|False) Whether to generate the value class for this EJB.	No

@ejbgen:finder

Where: Class Applicable on: Entity beans

Attribute Description Required
caching-name The name of an eager relationship caching. No
comment A comment that will be reproduced above the generated finder Java method. No
ejb-ql The EJB QL request as it will appear in the deployment descriptor. No
generate-on (Local|Remote) On which home this finder will be generated (if unspecified, both) No
group-name Name of the group for the WebLogic query. No
include-updates (True|False) Whether updates made during the current transaction must be reflected in the result of a query. No
isolation-level The type of transaction isolation for this method. No
max-elements The maximum number of elements that should be returned by a multi-valued query. No
signature It must match exactly the signature as you want it generated on the Home class. EJBGen adds the conformant exceptions, but make sure that you specify the fully qualified type of each parameter, even if it belongs to java.lang. No
sql-select-distinct (True|False) Whether the generated SQL 'SELECT' contains a 'DISTINCT' qualifier. No
transaction-attribute (NotSupported|Supports|Required|RequiresNew|Mandatory|Never) The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag will are generated on the Local class. No
weblogic-ejb-ql The Weblogic EJB Query Language (QL) request as it will appear in the deployment descriptor. Note: if this request is needed, you need to enclose both EJB QL and Weblogic EJB QL within double quotes. No

Attribute	Description	Required
caching-name	The name of an eager relationship caching.	No
comment	A comment that will be reproduced above the generated finder Java method.	No
ejb-ql	The EJB QL request as it will appear in the deployment descriptor.	No
generate-on	(Local\|Remote) On which home this finder will be generated (if unspecified, both)	No
group-name	Name of the group for the WebLogic query.	No
include-updates	(True\|False) Whether updates made during the current transaction must be reflected in the result of a query.	No
isolation-level	The type of transaction isolation for this method.	No
max-elements	The maximum number of elements that should be returned by a multi-valued query.	No
signature	It must match exactly the signature as you want it generated on the Home class. EJBGen adds the conformant exceptions, but make sure that you specify the fully qualified type of each parameter, even if it belongs to java.lang.	No
sql-select-distinct	(True\|False) Whether the generated SQL 'SELECT' contains a 'DISTINCT' qualifier.	No
transaction-attribute	(NotSupported\|Supports\|Required\|RequiresNew\|Mandatory\|Never) The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag will are generated on the Local class.	No
weblogic-ejb-ql	The Weblogic EJB Query Language (QL) request as it will appear in the deployment descriptor. Note: if this request is needed, you need to enclose both EJB QL and Weblogic EJB QL within double quotes.	No

@ejbgen:foreign-jms-provider

Where: Class

Applicable on: Message-driven beans

Attribute Description Required
provider-url The URL of the foreign JMS provider. Yes
connection-factory-jndi-name The JNDI name for the connection factory. No
initial-context-factory The initial JNDI context factory. No

Attribute	Description	Required
provider-url	The URL of the foreign JMS provider.	Yes
connection-factory-jndi-name	The JNDI name for the connection factory.	No
initial-context-factory	The initial JNDI context factory.	No

@ejbgen:jndi-name

Where: Class

Applicable on: All bean types

Attribute Description Required
local The local JNDI name of this EJB. It not specified, no local interfaces is generated. No
remote The remote JNDI name of this EJB. It not specified, no remote interfaces is generated. No

Attribute	Description	Required
local	The local JNDI name of this EJB. It not specified, no local interfaces is generated.	No
remote	The remote JNDI name of this EJB. It not specified, no remote interfaces is generated.	No

@ejbgen:local-home-method

Where: Method

Applicable on: Entity and Session beans

Attribute Description Required
roles Comma-delimited list of roles that are allowed to invoke this method. No
transaction-attribute The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag are generated on the Local class. No

Attribute	Description	Required
roles	Comma-delimited list of roles that are allowed to invoke this method.	No
transaction-attribute	The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag are generated on the Local class.	No

@ejbgen:local-method

Where: Method

Applicable on: Entity and Session beans

Attribute Description Required
is-idempotent (True|False) Whether this method is idempotent. No
isolation-level The type of transaction isolation for this method. No
ordering-number (0..n) The number where this method must appear in the generated class. No
roles Comma-delimited list of roles that are allowed to invoke this method. No
transaction-attribute (NotSupported|Supports|Required|RequiresNew|Mandatory|Never) The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag will be generated on the Local class. No

Attribute	Description	Required
is-idempotent	(True\|False) Whether this method is idempotent.	No
isolation-level	The type of transaction isolation for this method.	No
ordering-number	(0..n) The number where this method must appear in the generated class.	No
roles	Comma-delimited list of roles that are allowed to invoke this method.	No
transaction-attribute	(NotSupported\|Supports\|Required\|RequiresNew\|Mandatory\|Never) The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag will be generated on the Local class.	No

@ejbgen:message-driven

Where: Class

Applicable on: Message-Driven beans

Attribute Description Required
destination-jndi-name The JNDI name of the destination. Yes
destination-type (javax.jms.Queue|javax.jms.Topic)The JMS destination type. Yes
ejb-name The name of this message-driven bean. Yes
acknowledge-mode (auto-acknowledge|dups-ok-acknowledge) The acknowledgement mode. No
default-transaction The transaction attribute to be applied to all methods that do not have a more specific transaction attribute setting. No
durable (True|False) If the destination-type is Topic, setting this attribute to True will make the subscription durable. No
enable-call-by-reference (True|False) Whether the container will call this EJB by reference No
initial-beans-in-free-pool The initial number of beans in the free pool. No
max-beans-in-free-pool The maximum number of beans in the free pool. No
message-selector The JMS message selector. No
run-as Specifies the role-name for this EJB. No
run-as-identity-principal The name of the principal in case the role maps to several principals. No
trans-timeout-seconds The transaction timeout (in seconds). No
use-caller-identity (True|False) Whether this EJB uses caller's identity. No

Attribute	Description	Required
destination-jndi-name	The JNDI name of the destination.	Yes
destination-type	(javax.jms.Queue\|javax.jms.Topic)The JMS destination type.	Yes
ejb-name	The name of this message-driven bean.	Yes
acknowledge-mode	(auto-acknowledge\|dups-ok-acknowledge) The acknowledgement mode.	No
default-transaction	The transaction attribute to be applied to all methods that do not have a more specific transaction attribute setting.	No
durable	(True\|False) If the destination-type is Topic, setting this attribute to True will make the subscription durable.	No
enable-call-by-reference	(True\|False) Whether the container will call this EJB by reference	No
initial-beans-in-free-pool	The initial number of beans in the free pool.	No
max-beans-in-free-pool	The maximum number of beans in the free pool.	No
message-selector	The JMS message selector.	No
run-as	Specifies the role-name for this EJB.	No
run-as-identity-principal	The name of the principal in case the role maps to several principals.	No
trans-timeout-seconds	The transaction timeout (in seconds).	No
use-caller-identity	(True\|False) Whether this EJB uses caller's identity.	No

@ejbgen:method-isolation-level-pattern

Where: Class

Applicable on: All beans

Attribute Description Required
isolation-level The isolation level for the methods specified in the pattern tag. Yes
pattern The pattern that matches all methods that will receive this isolation level (for example, "*"). Yes

Attribute	Description	Required
isolation-level	The isolation level for the methods specified in the pattern tag.	Yes
pattern	The pattern that matches all methods that will receive this isolation level (for example, "*").	Yes

@ejbgen:method-permission-pattern

Where: Class

Applicable on: All beans

Attribute Description Required
pattern The pattern that matches all methods that will receive this isolation level (for example, "*"). Yes
roles Comma-delimited list of roles for the methods specified in the pattern tag. Yes
interface (Home|Remote|LocalHome|Local) The interface where this permission pattern applies. No

Attribute	Description	Required
pattern	The pattern that matches all methods that will receive this isolation level (for example, "*").	Yes
roles	Comma-delimited list of roles for the methods specified in the pattern tag.	Yes
interface	(Home\|Remote\|LocalHome\|Local) The interface where this permission pattern applies.	No

@ejbgen:relation

Where: Class

Applicable on: Entity beans

Attribute Description Required
multiplicity (One|Many) Yes
name The name of the relationship. Make sure you use the same name on both ends of a relationship for the roles to be generated properly (note that this constraint applies to unidirectional as well). Yes
cascade-delete (True|False) No
cmr-field The cmr field where this relationship will be kept. This field is optional. If it not present, the relationship is unidirectional. If it is present, the attribute fk-column must be specified as well. No
db-cascade-delete (True|False) Whether a cascade delete will use the built-in cascade delete facilities of the underlying DBMS. No
fk-column Only needed in a relationship having at least one One side. In that case, the non-One side EJB must declare a column that it will use to store the primary key of its counterpart. No
foreign-key-table The name of a DBMS table that contains a foreign-key. No
joint-table Only needed in a many-to-many relationship. It must be the name of an existing table that will be used to hold the joint table containing the relationships. In case you are using a compound primary key, you need to specify a set of corresponding foreign keys separated by a comma. No
primary-key-table The name of a DBMS table that contains a primary-key. No
role-name The name of this role (such as ParentHasChildren). If no role name is given, EJBGen will generate one for you. Note that you have to specify a role-name if you are going to inherit relations. No
target-ejb The EJB name of the target of this relationship. Yes

Attribute	Description	Required
multiplicity	(One\|Many)	Yes
name	The name of the relationship. Make sure you use the same name on both ends of a relationship for the roles to be generated properly (note that this constraint applies to unidirectional as well).	Yes
cascade-delete	(True\|False)	No
cmr-field	The cmr field where this relationship will be kept. This field is optional. If it not present, the relationship is unidirectional. If it is present, the attribute fk-column must be specified as well.	No
db-cascade-delete	(True\|False) Whether a cascade delete will use the built-in cascade delete facilities of the underlying DBMS.	No
fk-column	Only needed in a relationship having at least one One side. In that case, the non-One side EJB must declare a column that it will use to store the primary key of its counterpart.	No
foreign-key-table	The name of a DBMS table that contains a foreign-key.	No
joint-table	Only needed in a many-to-many relationship. It must be the name of an existing table that will be used to hold the joint table containing the relationships. In case you are using a compound primary key, you need to specify a set of corresponding foreign keys separated by a comma.	No
primary-key-table	The name of a DBMS table that contains a primary-key.	No
role-name	The name of this role (such as ParentHasChildren). If no role name is given, EJBGen will generate one for you. Note that you have to specify a role-name if you are going to inherit relations.	No
target-ejb	The EJB name of the target of this relationship.	Yes

@ejbgen:relationship-caching-element

Where: Method

Applicable on: Entity beans

Attribute Description Required
caching-name The name of an eager relationship caching. Yes
cmr-field A comma-delimited list of CMR field names. Yes
group-name The name of the group to be loaded for the CMR field. No
id An id that allows a child to use this element as a parent. No
parent-id The parent id of this element. No

Attribute	Description	Required
caching-name	The name of an eager relationship caching.	Yes
cmr-field	A comma-delimited list of CMR field names.	Yes
group-name	The name of the group to be loaded for the CMR field.	No
id	An id that allows a child to use this element as a parent.	No
parent-id	The parent id of this element.	No

@ejbgen:remote-home-method

Where: Method

Applicable on: Entity and Session beans

Attribute Description Required
roles Comma-delimited list of roles that are allowed to invoke this method. No
transaction-attribute The transaction attribute for this remote method. If not specified, the default transaction attribute will be used. Methods with this tag will be generated on the Remote class. No

Attribute	Description	Required
roles	Comma-delimited list of roles that are allowed to invoke this method.	No
transaction-attribute	The transaction attribute for this remote method. If not specified, the default transaction attribute will be used. Methods with this tag will be generated on the Remote class.	No

@ejbgen:remote-method

Where: Method

Applicable on: Entity and Session beans

Attribute Description Required
is-idempotent (True|False) Whether this method is idempotent. No
isolation-level The type of transaction isolation for this method. No
ordering-number (0..n) The number where this method must appear in the generated class. No
roles Comma-delimited list of roles that are allowed to invoke this method. No
transaction-attribute (NotSupported|Supports|Required|RequiresNew|Mandatory|Never) The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag will be generated on the Local class. No

Attribute	Description	Required
is-idempotent	(True\|False) Whether this method is idempotent.	No
isolation-level	The type of transaction isolation for this method.	No
ordering-number	(0..n) The number where this method must appear in the generated class.	No
roles	Comma-delimited list of roles that are allowed to invoke this method.	No
transaction-attribute	(NotSupported\|Supports\|Required\|RequiresNew\|Mandatory\|Never) The transaction attribute for this local method. If not specified, the default transaction attribute will be used. Methods with this tag will be generated on the Local class.	No

@ejbgen:resource-env-ref

Where: Class

Applicable on: All bean types

Attribute Description Required
name Name of the resource environment reference. Yes
type Type of the environment resource references (e.g. javax.jms.Queue). Yes
jndi-name JNDI name of the resource. No

Attribute	Description	Required
name	Name of the resource environment reference.	Yes
type	Type of the environment resource references (e.g. javax.jms.Queue).	Yes
jndi-name	JNDI name of the resource.	No

@ejbgen:resource-ref

Where: Class

Applicable on: All bean types

Attribute Description Required
auth (Application|Container) Yes
jndi-name JNDI name of the resource. Yes
name Name of the resource. Yes
type Type of the resource (e.g. javax.sql.DataSource). Yes
sharing-scope (Shareable|Unshareable) No

Attribute	Description	Required
auth	(Application\|Container)	Yes
jndi-name	JNDI name of the resource.	Yes
name	Name of the resource.	Yes
type	Type of the resource (e.g. javax.sql.DataSource).	Yes
sharing-scope	(Shareable\|Unshareable)	No

@ejbgen:role-mapping

Where: Class

Applicable on: All bean types

Attribute Description Required
global-role (True|False) True if this role is global. No
principals The names of the principals in this role (separated by commas). No
role-name The name of the role. Yes

Attribute	Description	Required
global-role	(True\|False) True if this role is global.	No
principals	The names of the principals in this role (separated by commas).	No
role-name	The name of the role.	Yes

@ejbgen:security-role-ref

Where: Method

Applicable on: Entity and session beans

Attribute Description Required
role-name The name of the security role. Yes
role-link A reference to a defined security role. No

Attribute	Description	Required
role-name	The name of the security role.	Yes
role-link	A reference to a defined security role.	No

@ejbgen:select

Where: Method

Applicable on: Entity beans

Attribute Description Required
caching-name The name of an eager relationship caching. No
ejb-ql The EJB-QL defining this select method. The method name must start with ejbSelect. Yes
group-name Name of the group for the query. No
include-updates (True|False) Whether updates made during the current transaction must be reflected in the result of a query. No
max-elements The maximum number of elements that should be returned by a multi-valued query. No
ordering-number (0..n) The number where this method must appear in the generated class. No
result-type-mapping (Remote|Local) Whether the returned objects are mapped to EJBLocalObject or EJBObject. No
weblogic-ejb-ql The Weblogic EJB QL request as it will appear in the deployment descriptor. Note: If this request is needed, you need to enclose both EJB QL and Weblogic EJB QL within double quotes. No

Attribute	Description	Required
caching-name	The name of an eager relationship caching.	No
ejb-ql	The EJB-QL defining this select method. The method name must start with ejbSelect.	Yes
group-name	Name of the group for the query.	No
include-updates	(True\|False) Whether updates made during the current transaction must be reflected in the result of a query.	No
max-elements	The maximum number of elements that should be returned by a multi-valued query.	No
ordering-number	(0..n) The number where this method must appear in the generated class.	No
result-type-mapping	(Remote\|Local) Whether the returned objects are mapped to EJBLocalObject or EJBObject.	No
weblogic-ejb-ql	The Weblogic EJB QL request as it will appear in the deployment descriptor. Note: If this request is needed, you need to enclose both EJB QL and Weblogic EJB QL within double quotes.	No

@ejbgen:session

Where: Class

Applicable on: Session beans

Attribute Description Required
allow-concurrent-calls (True|False) Whether to allow concurrent calls on that EJB. No
bean-load-algorithm The algorithm to use for load-balancing between replicas of this bean. No
ejb-name The name of this session bean. Yes
call-router-class-name Class name to be used for routing home method calls. No
default-transaction The transaction attribute to be applied to all methods that do not have a more specific transaction attribute setting. No
dispatch-policy The JMS dispatch policy queue for this bean No
enable-call-by-reference (True|False) Whether the container will call this EJB by reference No
home-call-router-class-name Class to be used for routing home method calls. No
home-is-clusterable (True|False) Whether this bean can be deployed from multiple servers in a cluster. No
home-load-algorithm (RoundRobin|Random|WeightBased) The algorithm to use for load-balancing between replicas of this home. No
idle-timeout-seconds Maximum duration an EJB should stay in the cache. No
initial-beans-in-free-pool The initial number of beans in the free pool. No
is-clusterable (True|False) Whether this bean is clusterable No
load-algorithm (RoundRobin|Random|WeightBased) The name of the algorithm used to balance replicas of this home No
max-beans-in-cache The maximum number of beans in the cache. No
max-beans-in-free-pool The maximum number of beans in the free pool. No
methods-are-idempotent (True|False) Whether the methods for this stateless session bean are idempotent or not. No
persistent-store-dir The directory in which to store the passivated beans. No
replication-type (InMemory|None) How to replicate stateful session beans in a cluster. No
run-as Specifies the role-name for this EJB. No
run-as-identity-principal The name of the principal in case the role maps to several principals. No
trans-timeout-seconds The transaction timeout, in seconds. No
transaction-type (Bean|Container) Whether transactions for this EJB are bean- managed or container-managed. No
type (Stateless | Stateful) The type of the session bean. If this attribute is not specified, EJBGen guesses the right type by looking at the ejbCreate() methods on your class. No
use-caller-identity (True | False) Whether this EJB uses caller's identity. No

Attribute	Description	Required
allow-concurrent-calls	(True\|False) Whether to allow concurrent calls on that EJB.	No
bean-load-algorithm	The algorithm to use for load-balancing between replicas of this bean.	No
ejb-name	The name of this session bean.	Yes
call-router-class-name	Class name to be used for routing home method calls.	No
default-transaction	The transaction attribute to be applied to all methods that do not have a more specific transaction attribute setting.	No
dispatch-policy	The JMS dispatch policy queue for this bean	No
enable-call-by-reference	(True\|False) Whether the container will call this EJB by reference	No
home-call-router-class-name	Class to be used for routing home method calls.	No
home-is-clusterable	(True\|False) Whether this bean can be deployed from multiple servers in a cluster.	No
home-load-algorithm	(RoundRobin\|Random\|WeightBased) The algorithm to use for load-balancing between replicas of this home.	No
idle-timeout-seconds	Maximum duration an EJB should stay in the cache.	No
initial-beans-in-free-pool	The initial number of beans in the free pool.	No
is-clusterable	(True\|False) Whether this bean is clusterable	No
load-algorithm	(RoundRobin\|Random\|WeightBased) The name of the algorithm used to balance replicas of this home	No
max-beans-in-cache	The maximum number of beans in the cache.	No
max-beans-in-free-pool	The maximum number of beans in the free pool.	No
methods-are-idempotent	(True\|False) Whether the methods for this stateless session bean are idempotent or not.	No
persistent-store-dir	The directory in which to store the passivated beans.	No
replication-type	(InMemory\|None) How to replicate stateful session beans in a cluster.	No
run-as	Specifies the role-name for this EJB.	No
run-as-identity-principal	The name of the principal in case the role maps to several principals.	No
trans-timeout-seconds	The transaction timeout, in seconds.	No
transaction-type	(Bean\|Container) Whether transactions for this EJB are bean- managed or container-managed.	No
type	(Stateless \| Stateful) The type of the session bean. If this attribute is not specified, EJBGen guesses the right type by looking at the ejbCreate() methods on your class.	No
use-caller-identity	(True \| False) Whether this EJB uses caller's identity.	No

@ejbgen:value-object

Where: Class

Applicable on: All bean types

Attribute Description Required
reference (Local|Value) Specifies which objects the value object class should reference when accessing other EJB's. Yes

Attribute	Description	Required
reference	(Local\|Value) Specifies which objects the value object class should reference when accessing other EJB's.	Yes

Controlling File Generation

By default, EJBGen generates the following files:

Remote bean and home interfaces (if @ejbgen:jndi-name with "remote" was specified)
Local bean and home interfaces (if @ejbgen:jndi-name with "local" was specified)
Value object classes
Primary key classes (if applicable)

You can selectively disable the generation of these files by using the @ejbgen:file-generation tag. This can be done on a per-bean basis. The following code sample suppresses value class generation: /** * @ejbgen:file-generation * value-class = False

Note: The -noValueClasses, -noRemoteInterfaces or -noLocalInterfaces, these command-line options override any tag found on the beans.

Javadoc Warnings with Uncompiled Value Type Classes

If an EJBGen class contains value types (e.g., parameter values, return values) that are Java classes that have not been compiled, then Javadoc will output what appear to be javac compilation errors, as in Figure 10-1 :Figure 10-1 Sample Javadoc output when value type classes are uncompiled


[javadoc]



C:\toddk\dev\issues\cr100528\src\test\po\PurchaseOrderBean.java:29: cannot resolve symbol [javadoc] symbol : class PurchaseOrder [javadoc] location: class test.po.PurchaseOrderBean [javadoc] public boolean submitPO(PurchaseOrder po) throws SubmitException {


[javadoc]



[javadoc] C:\toddk\dev\issues\cr100528\src\test\po\PurchaseOrderBean.java:29: cannot resolve symbol [javadoc] symbol : class SubmitException [javadoc] location: class test.po.PurchaseOrderBean [javadoc] public boolean submitPO(PurchaseOrder po) throws SubmitException {

These are Javadoc warnings, not errors. Because the error messages resemble javac compiler errors, it is easy to interpret them incorrectly as errors. Javadoc returns with an exit status that indicates success; therefore the Ant EJBGen task does not cause the build to fail.

Mapping an Entity Bean to Several Tables

By default, entity beans are mapped to one table, with the attribute table-name on the tag @ejbgen:entity. If you want to map your entity bean to more than one table, you can use the table-name attribute on individual @ejbgen:cmp-fields. All the container-managed persistence fields that do not have a table-name attribute will use the table specified on @ejbgen:entity (which can therefore be considered as the "default" table).

If you want to map an entity bean to several tables, you need to specify a comma-separated list of tables in the table-name attribute (and also on a column). For example:

Make sure that the number of tables matches the number of columns, and that the columns exist in the corresponding table.

Property Files

EJBGen can gather information for generation from property files, as discussed in this section.

Use the -propertyFile option to tell EJBGen to parse a properties file. Figure 10-2 illustrates a sample property file.Figure 10-2 Sample EJBGen Property File


# property-file



#



remote-jndi-name = Account

Use the following syntax to invoke EJBGen with the -propertyFile option:


javadoc -docletpath ejbgen.jar -doclet EJBGen  -propertyFile property-file AccountBean.java

EJBGen recognizes two kinds of variables in a properties file: user variables and predefined variables.

User Variables

EJBGen tags can use variables instead of strings. These variables must be enclosed with "${" and "}", as in Figure 10-3. Figure 10-3 User variables in place of strings


@ejbgen:jndi-name


remote = ${remote-jndi-name}

Variables can be used anywhere after an EJBGen tag, so they can contain whole tag definitions, as in Figure 10-4. Figure 10-4 User variables as a whole tag definition


@ejbgen:jndi-name


  ${jndi-name-tag}


#



#



# property-file


#



jndi-name -tag = remote = RemoteAccount local = LocalAccount

Predefined Variables

EJBGen recognizes a number of predefined variables. These variables are not supposed to be used in tags but EJBGen will use them at various places depending on their role. Here is the list of recognized variables:

remote.baseClass

If specified, the value of this variable will be used as the base class for all generated remote classes.
home.baseClass

If specified, the value of this variable will be used as the base class for all generated remote home classes.
local.baseClass

If specified, the value of this variable will be used as the base class for all generated local classes.
localHome.baseClass

If specified, the value of this variable will be used as the base class for all generated local home classes.
value.baseClass

If specified, the value of this variable will be used as the base class for all generated value classes.
value.package

If specified, the value of this variable will be used as the package for all generated value classes.
value.interfaces

If specified, the value of this variable will be used as the interfaces the value class should implement. This variable can be a list of interfaces separated by commas.

You can make these variables more specific by prefixing them with an EJBName. For example, consider the following property file:


# property-file


Account.home.baseClass = BaseAccountHome


home.baseClass = BaseHome


value.package = value


containerManaged.value.package=valuePackageForContainerManaged

All homes generated by EJBGen extend the class BaseHome except the home of EJB "Account", which extends BaseAccountHome.

Relationship Caching

You can specify relationship caching elements with the @ejbgen:relationship-caching tag. This XML element can be nested (recursive). In other words, you can specify a tree representing all the relationship elements that you want to see cached.

In order to support this tree structure, @ejbgen:relationship-caching has two attributes, id and parent-id. These attributes do not correspond to any XML, they simply allow you to specify your tree structure.

For example, if a caching-element A needs to have two children elements B and C, all you need to specify is an id for A (say "root0") and a parent-id for B and C equal to that name.

Figure 10-5 illustrates specifying relationship caching. Figure 10-5 Specifying relationship caching * @ejbgen:relationship-caching-element * caching-name = cacheMoreBeans * cmr-field = employee * group-name = emp-group * id = A * * @ejbgen:relationship-caching-element * caching-name = cacheMoreBeans * cmr-field = employee_ssn * group-name = emp-group * parent-id = A