Programming WebLogic Enterprise JavaBeans
|
WebLogic Server EJB Utilities
The following sections provide a complete reference to the utilities and support files supplied with WebLogic Server that are used with EJBs:
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.
If you have installed BEA WebLogic 7.0 examples, see SAMPLES_HOME\server\src\examples\ejb20\ejbgen for an example application called Bands that uses EJBGen.
EJBGen Syntax
javadoc -docletpath weblogic.jar -doclet weblogic.tools.ejbgen.EJBGen (YourBean).java
If you do not have weblogic.jar in your classpath, add the path to weblogic.jar as follows:
javadoc -docletpath <path_to_weblogic.jar> weblogic.jar -doclet weblogic.tools.ejbgen.EJBGen (YourBean).java
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:
javadoc -docletpath weblogic.jar -doclet weblogic.tools.ejbgen.EJBGen (YourBean).java (RelatedBean).java
EJBGen uses the following options.
Option
|
Definition
|
-d [directory]
|
The directory under which all the files will be created.
|
-ignorePackage
|
If this flag is set, EJBGen will ignore the package name of the Java files it generates and will create 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
|
Print 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 generate an HTML document.
|
-propertyFile [fileName]
|
The name of a property file that EJBGen will read to define substitution variables. See the substitution variable documentation
|
-valueBaseClass [className]
|
Removed. Use the variable value.baseClass.
|
-noValueClasses
|
If specified, value classes will not be generated.
|
Surround Attributes that Contain Spaces With Double Quotes
When you specify an attribute that contains spaces, surround the attribute value with double quotes. For example:
group-names = "group1, group2"
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
When javadoc exits, it will have generated the following files for you:
- 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 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
|
@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 have this attribute to a distinct numeric value.
|
No
|
@ejbgen:cmr-field
Where:Method
Applicable on: Entity
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
|
@ejbgen:create-default-rdbms-tables
Where: Class
Applicable on: Entity bean
@ejbgen:ejb-client-jar
Where: Class
Applicable on: All
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 will be included in the deployment descriptor.
|
Yes
|
types of beans
@ejbgen:ejb-local-ref
Where: Class
Applicable on: All
Attribute
|
Description
|
Required
|
home
|
Local class of the bean.
|
No
|
jndi-name
|
The JNDI name of the reference.
|
No
|
link
|
Link of the bean.
|
No
|
local
|
Home class of the bean.
|
No
|
name
|
Name of the reference.
|
No
|
type
|
(Entity|Session)
|
No
|
types of beans
@ejbgen:ejb-ref
Where: Class
Applicable on: All
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
|
types of beans
@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
|
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).
|
No
|
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
|
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
|
persistence-type
|
(cmp|bmp) The type of this Entity bean (default: cmp).
|
No
|
prim-key-class-nogen
|
(True|False). If this keyword is specified, EJBGen will 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 will be 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
|
@ejbgen:env-entry
Where:Class
Applicable on: All
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
|
types of beans
@ejbgen:finder
Where: Class
Applicable on: Entity
Attribute
|
Description
|
Required
|
ejb-ql
|
The EJB QL request as it will appear in the deployment descriptor.
|
Yes
|
signature
|
It must match exactly the signature as you want it generated on the Home class. EJBGen will add the conformant exceptions, but you must make sure that you specify the fully qualified type of each parameter, even if it belongs to java.lang.
|
Yes
|
isolation-level
|
The type of transaction isolation for 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 will be generated on the Local class.
|
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 EJBQL and Weblogic EJBQL within double quotes.
|
No
|
beans
@ejbgen:jndi-name
Where: Class
Applicable on: All
Attribute
|
Description
|
Required
|
local
|
The local JNDI name of this EJB. It not specified, no local interfaces will be generated.
|
No
|
remote
|
The remote JNDI name of this EJB. It not specified, no remote interfaces will be generated.
|
No
|
types of beans
@ejbgen:local-home-method
Where: Method
Applicable on: Entity and Session beans
Attribute
|
Description
|
Required
|
transaction-attribute
|
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:local-method
Where: Method
Applicable on: Entity and Session beans
Attribute
|
Description
|
Required
|
isolation-level
|
The type of transaction isolation for 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 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
|
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
|
destination-type
|
(javax.jms.Queue|javax.jms.Topic).
|
No
|
durable
|
(True|False) If the destination-type is "Topic", setting this attribute to True will make the subscription durable.
|
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:primkey-field
Where: Method
Applicable on: Entity beans
@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
|
target-ejb
|
The EJB name of the target of this relationship.
|
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
|
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
|
joint-table
|
Only needed in a Many-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
|
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
|
@ejbgen:remote-home-method
Where: Method
Applicable on: Entity and Session beans
Attribute
|
Description
|
Required
|
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
|
isolation-level
|
The type of transaction isolation for 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:resource-env-ref
Where: Class
Applicable on: All types of beans
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
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
|
types of beans
@ejbgen:role-mapping
Where: Class
Applicable on: All
Attribute
|
Description
|
Required
|
principals
|
The names of the principals in this role (separated by commas).
|
Yes
|
role-name
|
The name of the role
|
Yes
|
types of beans
@ejbgen:select
Where: Method
Applicable on: Entity
Attribute
|
Description
|
Required
|
ejb-ql
|
The EJB-QL defining this select method. Note: the method name must start with ejbSelect.
|
Yes
|
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 EJBQL and Weblogic EJBQL within double quotes.
|
No
|
beans
@ejbgen:session
Where: Class
Applicable on: Session
Attribute
|
Description
|
Required
|
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
|
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
|
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
|
type
|
(Stateless|Stateful) The type of the Session bean. If this attribute is not specified, EJBGen will guess 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
|
beans
@ejbgen:value-object
Where: Class
Applicable on: All
Attribute
|
Description
|
Required
|
reference
|
(Local|Value) Specify what objects the value object class should reference when accessing other EJB's.
|
Yes
|
types of beans
ejbc
Use the weblogic.ejbc utility for generating and compiling EJB 2.0 and 1.1 container classes. If you compile JAR files for deployment into the EJB container, you must use weblogic.ejbc to generate the container classes.
weblogic.ejbc does the following:
- Places the EJB classes, interfaces, and XML deployment descriptor files in a specified JAR file.
- Checks all EJB classes and interfaces for compliance with the EJB specification.
- Generates WebLogic Server container classes for the EJBs.
- Runs each EJB container class through the RMI compiler to create client-side dynamic proxies and server-side byte code.
Note: ejbc accepts both JAR files and exploded directories as input.
If you specify an output JAR file, ejbc places all generated files into the JAR file.
By default, ejbc uses javac as a compiler. For faster performance, specify a different compiler (such as Symantec's sj) using the -compiler flag.
Although versions of the WebLogic-specific XML deployment descriptor files are published on or web site for your convience, an internal version is shipped with the product for use by weblogic.ejbc.
For the location of the public version of weblogic-ejb-jar.xml, see DOCTYPE Header Information; for the location of the public version of weblogic-cmp-rdbms-jar.xml, see DOCTYPE Header Information.
Advantages of Using ejbc
The ejbc utility offers the following benefits:
- It is easy to identify and correct errors ejbc produces.
If an error occurs while running ejbc from the command line, ejbc exits with an error message.
By contrast, if you defer compilation to the time of deployment and a compilation error occurs, the server fails the deployment and goes on with its work. To determine why deployment failed, you must examine the server output, fix the problem and then redeploy.
- By running ejbc prior to deployment, you potentially reduce the number of time a bean is compiled.
For example, if you deploy a .jar file to a cluster of 3 servers, the .jar file is copied to each of the three servers for deployment. If the .jar file wasn't precompiled, each of the three servers will have to compile the file during deployment.
ejbc Syntax
prompt> java weblogic.ejbc [options] <source directory or jar file>
<target directory or jar file>
Note: If you output to a JAR file, the output JAR name must be different from the input JAR name.
ejbc Arguments
Argument
|
Description
|
<source directory or jar file>
|
Specifies the exploded source directory or JAR file containing the compiled EJB classes, interfaces, and XML deployment files.
|
<target directory or jar file>
|
Specifies the destination JAR file or deployment directory in which ejbc places the output JAR. If you specify an output JAR file, ejbc places the original EJB classes, interfaces, and XML deployment files in the JAR, as well as the new container classes that ejbc generates.
|
ejbc Options
Option
|
Description
|
-help
|
Prints a list of all options available for the compiler.
|
-version
|
Prints ejbc version information.
|
-basicClientJar
|
Does not include deployment descriptors in client JARs generated for EJBs.
|
-dispatchPolicy <queueName>
|
Specifies a configured execute queue that the EJB should use for obtaining execute threads in WebLogic Server. For more information, see Using Execute Queues to Control Thread Usage.
|
-forceGeneration
|
Forces generation of EJB classes. Without this flag, the classes may not be regenerated (if determined to be unnecessary).
|
-idl
|
Generates CORBA Interface Definition Language for remote interfaces.
|
-idlNoValueTypes
|
Does not generate valuetypes and the methods/attributes that contain them.
|
-idlFactories
|
Generates factory methods for valuetypes.
|
-idlVisibroker
|
Generates IDL somewhat compatible with Visibroker 4.5 C++.
|
-idlOrbix
|
Generates IDL somewhat compatible with Orbix 2000 2.0 C++.
|
-idlOverwrite
|
Overwrites existing IDL files.
|
-idlVerbose
|
Displays verbose information while generating IDL.
|
-idlDirectory <dir>
|
Specifies the directory where ejbc creates IDL files. By default, ejbc uses the current directory.
|
-idlMethodSignatures <>
|
Specifies the method signatures used to trigger IDL code generation.
|
-iiop
|
Generates CORBA stubs for EJBs.
|
-iiopDirectory <dir>
|
Specifies the directory where IIOP stub files will be written (default: target directory or JAR)
|
-J
|
Specifies the heap size for weblogic.ejbc. Use as follows: java weblogic.ejbc -J-mx256m input.jar output.jar
|
-keepgenerated
|
Saves the intermediate Java files generated during compilation.
|
-compiler <compiler name>
|
Sets the compiler for ejbc to use.
|
-normi
|
Passed through to Symantec's java compiler, sj, to stop generation of RMI stubs. Otherwise sj creates its own RMI stubs, which are unnecessary for the EJB.
|
-classpath <path>
|
Sets a CLASSPATH used during compilation. This augments the system or shell CLASSPATH.
|
-convertDD
|
Attempts to update deployment descriptors to the latest version.
|
ejbc Examples
The following example uses the javac compiler against an input JAR file in c:\%SAMPLES_HOME%\server\src\examples\ejb\basic\containerManaged\build. The output JAR file is placed in c:\%SAMPLES_HOME%\server\config\examples\applications.
prompt> java weblogic.ejbc -compiler javac c:\%SAMPLES_HOME%\server\samples\src\examples\ejb\basic\containerManaged\build\std_ejb_basic_containerManaged.jar c:%SAMPLES_HOME%\server\config\examples\ejb_basic_containerManaged.jar
The following example checks a JAR file for compliance with the EJB 1.1 specification and generates WebLogic Server container classes, but does not generate RMI stubs:
prompt> java weblogic.ejbc -normi c:%SAMMPLES_HOME%\server\src\examples\ejb\basic\containerManaged\build\std_ejb_basic_containerManaged.jar
DDConverter
The DDConverter is a command line utility that converts earlier versions EJB deployment descriptors into EJB deployment descriptors that conform to this version of WebLogic Server. The WebLogic Server EJB container supports both the EJB 1.1 and EJB 2.0 specifications including the EJB 1.1 and EJB 2.0 document type definitions (DTD). Each WebLogic Server EJB deployment includes standard deployment descriptors in the following files:
- ejb-jar.xml
This XML file contains the J2EE-specific EJB deployment descriptors.
- weblogic-ejb-jar-.xml
This XML file contains the WebLogic-specific EJB deployment descriptors.
- weblogic-cmp-rdbms-jar.xml
This XML file contains the WebLogic-specific container-managed persistence (CMP) deployment descriptors.
Conversion Options Available with DDConverter
The DDConverter command line utility includes the following conversion options:
- Converting beans from earlier versions of WebLogic Server (WLS).
- Converting CMP and non-CMP beans from earlier version of the EJB specification.
The following table lists the various conversion options for the DDconverter:
Table 8-1
Conversion Options for the DDConverter Utility
|
WLS
|
EJB non-CMP
|
EJB CMP
|
From To
|
From To
|
From To
|
WLS 4.5 - WLS 7.0
|
See Note 1
|
EJB CMP 1.0 - EJB CMP 1.1
See Note 2
|
WLS 4.5 - WLS 7.0
|
EJB 1.1 - EJB 2.0
|
EJB CMP 1.0 - EJB CMP 2.0
|
WLS 5.x - WLS 7.0
|
EJB 1.1 - EJB 2.0
|
See Note 3
|
WLS 6.x - WLS 7.0
|
EJB 1.1 - EJB 2.0
|
EJB CMP 1.1 - EJB CMP 2.0
|
Note: Converting non-CMP EJB 1.0 beans to non-CMP EJB 1.1 beans is not necessary because the EJB 1.1 non-CMP deployment descriptors are the same as the EJB 2.0 non-CMP deployment descriptors.
Note: Use the DDConverter command line option -EJBVer for converting EJB CMP 1.0 to EJB CMP 1.1. See DDConverter Options for a description of this option.
Note: Even though WLS 5.x CMP 1.1 beans and WLS 7.0 CMP 1.1 beans are different, WLS 5.1 CMP 1.1 beans can run in WebLogic Server 7.0 without any changes to the source code.
You should always recompile the beans after you use the DDConverter. We recommend that you use weblogic.ejbc and then deploy the new generated JAR file. Recompiling the bean makes sure that the code is compliant with the EJB Specifications and saves you time because you can skip the recompile process during server startup.
- When converting WLS 4.5 EJB 1.0 beans to WLS 7.0 EJB 1.1 beans, the input to DDConverter is the WebLogic 4.5 deployment descriptor text. The output is a JAR file that only includes the WebLogic 7.0 deployment descriptors. Run weblogic-ejbc to see if you need to make any additional changes to the source code following the steps in Using DDConverter to Convert EJBs. See the first row in the Conversion Options for the DDConverter Utility table.
- When converting WLS 4.5 EJB 1.1 beans to WLS 7.0 EJB 2.0 beans, the input to DDConverter is the WebLogic Server 4.5 deployment descriptor text. The output is a JAR file that only includes the WebLogic 7.0 deployment descriptors. Run weblogic-ejbc to see if you need to make any additional changes to the source code, follow the steps in Using DDConverter to Convert EJBs. See the second row in the Conversion Options for the DDConverter Utility table.
- You can deploy WLS 5.x EJB 1.1 beans to WLS 7.0 without any making changes to the source code because WLS 7.0 is backward compatible. WLS 7.0 detects, recompiles, and then deploys beans from previous versions of WLS. However, we recommend that you use the DDConverter to upgrade the WLS 5.x EJB 1.1 beans to WLS 7.0 EJB 2.0 beans.
When converting WLS 5.x EJB 1.1 beans to WLS 7.0 EJB 2.0 beans, the input to DDConverter is the WebLogic 5.1 JAR file. This file contains the deployment descriptor files and class files. The output goes to a JAR file that includes the WebLogic 7.0 deployment descriptor files and all necessary class files. See the third row in the Conversion Options for the DDConverter Utility table.
You can convert non-CMP beans to EJB 2.0 beans with little or no changes to the source code. To do this, run weblogic.ejbc on the output.jar file and then deploy the generated JAR file. With CMP beans, you must make changes to the source code using the steps in Using DDConverter to Convert EJBs.
Using DDConverter to Convert EJBs
To convert earlier versions of EJBs for use in WebLogic Server:
- Input the EJB's deployment descriptor file into the DDConverter using the command line format shown in DDConverter Syntax.
The output is a JAR file.
- Extract the XML deployment descriptors from the JAR file.
- Modify the source code according to the JavaSoft EJB Specification.
- Compile the modified java file with the extracted XML deployment descriptors, using weblogic.ejbc to create a JAR file.
- Deploy the JAR file.
DDConverter Syntax
prompt> java weblogic.ejb20.utils.DDConverter [options] file1 [file2...]
DDConverter Arguments
DDConverter takes the argument file1 [file2...], where file is one of the following:
- A text file containing EJB 1.0-compliant deployment descriptors.
- A JAR file containing EJB 1.1 compliant deployment descriptors.
DDConverter uses the beanHomeName property of EJBs in the text deployment descriptor to define new ejb-name elements in the resultant ejb-jar.xml file.
DDConverter Options
The following table lists the DDConverter command-line options:
Option
|
Description
|
-d destDir
|
Specifies the destination directory for the output of the JAR files.
This is a required option.
|
-c jar name
|
Specifies a JAR file in which you combine all beans in the source files.
|
-EJBVer output EJB version
|
Specifies the output EJB version number, such as 2.0 or 1.1. The default is 2.0.
|
-log log file
|
Specifies a file into which the log information can be placed instead of the ddconverter.log.
|
-verboseLog
|
Specifies that extra information on the conversion be placed in the ddconverter.log.
|
-help
|
Prints a list of all options available for the DDConverter utility.
|
DDConverter Examples
The following example converts a WLS 5.x EJB 1.1 bean into a WLS 7.0 EJB 2.0 bean.
The JAR file is created in the destDir subdirectory:
prompt> java weblogic.ejb20.utils.DDConverter -d destDir Employee.jar
Where the Employee bean is a WLS 5.x EJB 1.1 JAR file.
weblogic.Deployer
The weblogic.Deployer command-line utility is new in WebLogic Server 7.0 and replaces the earlier weblogic.deploy utility, which has been deprecated. The weblogic.Deployer utility is a Java-based deployment tool that provides a command line interface to the WebLogic Server deployment API. This utility was developed for administrators and developers who need to initiate deployment from the command line, a shell script, or any automated environment other than Java.
For instructions on using weblogic.Deployer and a list of the commands, see Deploying Using weblogic.Deployer.
weblogic.deploy
Note: This tool is being deprecated in this release. We strongly encourage you to use the command-line tool weblogic.Deployer. It provides more sophisticated deployment options.
Use the weblogic.deploy command-line utility tool to deploy EJBs. Given an EJB-compliant JAR file, the JAR's EJBs are deployed into a running WebLogic Server.
deploy Syntax
prompt> java weblogic.deploy [options] [list|deploy|undeploy|update] password {name} {source}
deploy Arguments
Argument
|
Description
|
list
|
Lists all EJB deployment units in the specified WebLogic Server.
|
deploy
|
Deploys an EJB JAR to the specified server.
|
undeploy
|
Removes an existing EJB deployment unit from the specified server.
|
update
|
Redeploys an EJB deployment unit in the specified server.
|
password
|
Specifies the system password for the WebLogic Server.
|
{name}
|
Identifies the name of the EJB deployment unit. This name can be specified at deployment time, either with the deploy or console utilities.
|
{source}
|
Specifies the exact location of the EJB JAR file, or the path to the top level of an EJB deployment directory.
|
deploy Options
Option
|
Description
|
-help
|
Prints a list of all options available for the deploy utility.
|
-version
|
Prints the version of the utility.
|
-port <port>
|
Specifies the port number of the WebLogic Server to use for deploying the JAR file. If you do not specify this option, the deploy utility attempts to connect using port number 7001.
|
-host <host>
|
Specifies the host name of the WebLogic Server to use for deploying the JAR file. If you do not specify this option, the deploy utility attempts to connect using host name localhost.
|
-user
|
Specifies the system username of the WebLogic Server to be used to deploy the JAR file. If you do not specify this option, deploy attempts to make a connection using the system username system. You use the weblogic.system.user property to define the system username.
|
-debug
|
Prints detailed debugging information during the deployment process.
|