Before you can successfully run your enterprise beans at
1.1, 2.0, or 2.1 specification-level on either a test or production
server, you need to generate deployment code for the enterprise beans.
See
Tolerating
Enterprise JavaBeans™ at
3.0 specification-level section on how the ejbdeploy command
handles enterprise beans at 3.0 specification-level. This reference
topic describes what is the syntax, expected behavior, and descriptions
of each of the parameters for running the ejbdeploy command from a
command line.
This topic is divided
into the following sections:
Syntax
Use the following
command and the optional parameters, when the schema and map are provided
in the input EAR or JAR file:
ejbdeploy input_EAR_name|input_JAR_name working_directory output_EAR_name|output_JAR_name [-bindear "options"]
[-cp classpath] [-codegen] [-debug]
[-keep] [-ignoreErrors] [-quiet]
[-nowarn] [-noinform] [-rmic "options"][-trace]
[-sqlj] [-outer] [-complianceLevel "1.4"|"5.0"]
[-DgenInheritancePerfEnhancement=true]
Use the following command and the optional
parameters, when the schema and map are not available in the input
EAR or JAR file, and a top-down mapping approach is needed:
ejbdeploy input_EAR_name|input_JAR_name working_directory output_EAR_name|output_JAR_name [-bindear "options"]
[-cp classpath] [-codegen] [-dbname "name"]
[-dbschema "name"] [-dbvendor name]
[-debug] [-keep] [-ignoreErrors]
[-quiet] [-nowarn] [-noinform] [-rmic "options"][-trace]
[-sqlj][-OCCColumn] [-outer] [-complianceLevel "1.4"|"5.0"]
[-DgenInheritancePerfEnhancement=true] The
-dbschema, -dbname, -dbvendor, and -OCCColumn options are only used
when creating a database definition in the top-down mode of operation.
The database information is then saved in the schema document in the
JAR or EAR file, which means that the options do not need to be specified
again. It also means that when a JAR or EAR is generated, the correct
database must be defined at that point because it cannot be changed
later.
Behavior
If your input
JAR or EAR file contains CMP beans, the EJB deployment tool looks
for an existing schema and map to use when generating deployment code.
If no existing schema and map are found, a schema and map are created
using top-down mapping rules.
In the top-down mapping approach,
you already have existing enterprise beans and their design determines
the database design. The generated schema contains one table for each
CMP entity bean. In these tables, each column corresponds to a CMP
field of the enterprise bean, and the generated mapping maps the field
to the column.
If the -dbvendor option is not set, the default
database back end is DB2UDB_V82. If you want to set a different
database back end, use the -dbname, -dbschema,
and -dbvendor options to specify your choice. A
data definition language (DDL) file, Table.ddl, is created for the
database back end set in the -dbvendor option, when you run the ejbdeploy command.
However, you can specify only one back end at a time using the -dbvendor
option.
If the -dbvendor option is specified
for mapped jars, for example the JAR file already contains a DB2® back end and you specify -dbvendor ORACLE
on the command line; in previous releases of the product, rather than
getting a second back end, the database vendor specification was ignored.
Starting in WebSphere® Application
Server v6.0.2, the following changes were made for the scenario where
the -dbvendor option is specified for a mapped
jar:
For 2.x CMP beans where multiple mappings to different
database vendors are supported:
For 1.1 CMP beans that can only be mapped once:
- If the value for the -dbvendor option is the
same as the existing map, then the following message is issued and
deployment continues:
A mapping to the database vendor, database_vendor, already exists. Using the existing map to continue the generation of EJB deployment code.
- If the value for the -dbvendor option is different
as the existing map, the following exception is thrown and deployment
stops:
A mapping already exists for a different database vendor.
Action: If you want to generate deployment code against this existing map, for the -dbvendor argument of the ejbDeploy command, try verifying and matching the backend id to the existing map.
Another general behavior of the ejbdeploy command is if
the abstract fields or bean name for CMP entity beans use any SQL
reserved keywords, the top-down mapping adds a numeric suffix to the
column name when generating the data definition language file (Table.ddl).
This is to avoid SQL command conflicts when SQL reserved words are
used as column names. For a list of SQL reserved words, see the topic SQL reserved keywords.
Tolerating Enterprise JavaBeans at 3.0 specification-level
When
you install the WebSphere Application
Server V6.1 with Feature Pack for Enterprise JavaBeans (EJB) 3.0 or WebSphere Application Server v7.0, the ejbdeploy command-line tool tolerates
artifacts at Java™ Platform,
Enterprise Edition (Java EE)
5, such as EJB 3.0. In terms of tolerance, the ejbdeploy tool allows
the presence, but does not generate deployment code for artifacts
at Java EE 5 specification-level.
For
EJB 3.0 specification-level, you no longer need to generate the EJB
deployment code. The runtime of the server automatically handles generating
the required deployment code.
The following lists the general
behavior of the ejbdeploy command when issued with the presence of Java EE 5 artifacts:
- Tolerates EAR 5.0 files and EJB 3.0 JAR files
- Tolerates EAR files with Java 2
Platform Enterprise Edition (J2EE) 1.4 deployment descriptors that
contains EJB 3.0 JAR files Deployment code is generated only for EJB
at 1.1, 2.0, or 2.1 specification-level, such as Container-Managed
Persistence (CMP) entity beans. However, deployment code is not generated
for EJB beans at 3.0 specification-level, such as Session beans, Message-Driven
Beans (MDB) or Bean-Managed Persistence (BMP)
- If the -complianceLevel option for the ejbdeploy
command is not specified, in any of the following cases the default -complianceLevel setting
is Java developer kit V5.0, "5.0":
- An EAR or JAR file that contains Java EE
5 or EJB 3.0 deployment descriptor files
- An EAR file without any deployment descriptor files
All other cases, the -complianceLevel setting
defaults to Java developer kit
V1.4, "1.4"
If you are generating deployment code for J2EE 1.4 EAR or JAR
files that contain source code files which makes use of the new language
features in Java developer kit
5.0, you must specify the following parameter when running the ejbdeploy
command:
-complianceLevel "5.0"
Parameters
- ejbdeploy
- The command to generate deployment code. If run without any arguments,
the ejbdeploy command displays a list
of arguments that can be run with the command.
- input_JAR_name or input_EAR_name
- The fully qualified name of the input JAR or EAR file that contains
the enterprise beans for which you want to generate deployment code;
for example, c:\ejb\inputJARs\myEJBs.jar. (This
argument is required.)
The ejbdeploy command
no longer uses what is specified on the system class path. Instead,
the dependent classes need to be contained in a JAR file or included
in the command processing using the -cp option.
You must ensure that the .class files of each enterprise bean's home
and remote classes are packaged in the input JAR or EAR file.
You
should not include source files in the input JAR or EAR file. If there
are source files in the input JAR or EAR file, the EJBDeploy tools
runs a rebuild before generating the deployment code. Recommendation:
Either remove the source files, or include all dependent classes and
resource files on the class path. Otherwise, this might cause problems
during rebuild of your application on the server.
- working_directory
- The name of the directory where temporary files that are required
for code generation are stored. (This argument is required.) If the
working directory that you specify already exists prior to running
the ejbdeploy command, the temporary files
are generated into the working directory (as an Eclipse workspace).
However, if the working directory does not already exist prior to
running the command, the directory is created and the Eclipse workspace
is generated into it. In both cases, the workspace and all of its
files are automatically removed when the deployment code generation
is complete unless you specify the -keep option.
(Retaining the workspace is useful for problem determination.)
- output_JAR_name or output_EAR_name
- The fully qualified name of the output JAR or EAR file that is
created by the ejbdeploy command and that contains
the generated classes required for deployment; for example: c:\ejb\outputJARs\myEJBs.jar.
(This argument is required.) The directories specified in the fully-qualified
name must already exist before you run the ejbdeploy command.
(Note that when you specify a name for the output JAR or EAR file
and then run the ejbdeploy command, any existing
output JAR or EAR file of the same name will be overwritten without
warning.)
- -cp classpath
- If you intend to run the ejbdeploy command
against JAR or EAR files that have dependencies on other zipped or
JAR files, you can use the -cp option to specify
the class path of the other JAR or zipped files. Using the -cp option,
you can specify multiple zipped and JAR files as arguments. However,
the zipped and JAR file names must be fully qualified, separated by
path separators, and enclosed in double quotation marks. The path
separator depends on the operating system you are using. On Windows®, use semi-colons (;)
as the path separator. On UNIX® platforms,
use colons (:) as the path separator. For example:
-cp "path\myJar1.jar;path\myJar2.jar;path\myJar3.jar"
-cp "path\myJar1.jar:path\myJar2.jar:path\myJar3.jar"
Tip: If you specfied the -sqlj option, you need to
specify the location of the SQLJ translator classes, sqlj.zip.
The default path for this file is x:\java,
where x is the installation directory of DB2, for example, d:\sqllib\java\sqlj.zip on Windows.
- -codegen
- Restricts the ejbdeploy command to just (a)
importing code from the input JAR or EAR file (b) generating the
deployment code, and (c) exporting code to the output JAR or EAR
file. It will not compile the generated deployment code or run remote
method invocation compiler (RMIC). Since Java source
code is not usually exported in the output EAR or JAR, this is the
only way to save the generated code.
- -bindear "options"
- Enables you to populate an EAR file with bindings. This argument
applies only to EAR files. You can also use this command without specifying
any options. The options must be separated by a space and enclosed
in double quotation marks. For example: -bindear "xx
yy zz" For more information on these options,
see the WebSphere Application
Server documentation.
- -dbname "name"
- The name of the database you want to define in the data definition
language (DDL) file that gets generated. If the name of the database
contains any spaces, the entire name must be enclosed in double quotes.
For example: -dbname "my database"
- -dbschema "name"
- The name of the schema you want to create. If the name of the
schema contains any spaces, the entire name must be enclosed in double
quotes. For example: -dbschema "my schema"
- -dbvendor name
- The name of the database vendor, which is used to determine database
column types, mapping information, Table.ddl, and other information.
The valid database vendor names are:
- DB2UDB_V81
- DB2 V8.1 for Linux®, UNIX,
and Windows
- DB2UDB_V82
- DB2 V8.2 for Linux, UNIX,
and Windows
- DB2UDB_V91
- DB2 V9.1 for Linux, UNIX,
and Windows
- DB2UDB_V95
- DB2 V9.5 for Linux, UNIX,
and Windows
- DB2UDBOS390_V8
- DB2 V8 for z/OS®
- DB2UDBOS390_NEWFN_V8
- DB2 V8 for z/OS
- Additional to the DB2UDBOS390_V8 option, this
option includes the generated data model that has all the new catalog
features of DB2 V8 for z/OS specified in the new function
mode. Use this option if you plan to work with the generated data
model available in the IBM® Rational® Software Development
Platform products.
- DB2UDBOS390_V9
- DB2 V9 for z/OS
- This option includes the generated data
model that has all the new catalog features of DB2 V9 for z/OS specified
in the new function mode. It enables the option to work with the
generated data model available in the IBM Rational Software Development
Platform products.
- DB2UDBISERIES_V53
- DB2 V5R3 for iSeries®
- DB2UDBISERIES_V54
- DB2 V5R4 for iSeries
- DERBY_V10
- Apache Derby V10
- DERBY_V101
- Apache Derby V10.1
- ORACLE_V10G
- Oracle, V10g
- ORACLE_V11G
- Oracle, V11g
- INFORMIX_V100
- Informix
Dynamic Server, V10
- INFORMIX_V110
- Informix Dynamic Server,
V11
- SYBASE_V1250
- Sybase Adaptive Server Enterprise, V12.5
- SYBASE_V15
- Sybase Adaptive Server Enterprise, V15.0
- MSSQLSERVER_2005
- Microsoft® SQL Server
2005
The SQL92 and SQL99 options are obsolete and no
longer available. See the topic EJB
query to SQL syntax to help determine what back end you should
use now that the SQL92 and SQL99 back ends are no longer supported.
In addition, if you want to use an unsupported database, see this
same topic to help choose a valid database vendor back-end id that
matches closely to your unsupported deployment environment.
Note: - The default is DB2UDB_V82 (DB2 V8.2
for Linux, UNIX, and Windows)
- If -sqlj is specified, it supports DB2UDB_V95 (DB2 V9.1 for Linux, UNIX,
and Windows),DB2UDB_V91 (DB2 V9.1 for Linux, UNIX,
and Windows), DB2UDB_V82 (DB2 V8.2 for Linux, UNIX,
and Windows), DB2UDB_V81
(DB2 V8.1 for Linux, UNIX,
and Windows), DB2UDBOS390_V9 (DB2 V9 for z/OS), and DB2UDBOS390_V8 (DB2 V8 for z/OS).
- -debug
- Specifies that deployment code will be compiled with debug information.
- -keep
- Controls the disposition of the temporary files that are created
(that is, the Eclipse workspace) when the ejbdeploy command
has run. Without this option, the Eclipse workspace is deleted when
the command has completed.
- -ignoreErrors
- Specifies that processing should continue even if validation errors
are detected.
- -quiet
- During validation, suppresses status messages (but does not suppress
error messages).
- -nowarn
- During validation, suppresses warning and informational messages.
- -noinform
- During validation, suppresses informational messages.
- -rmic "options"
- Enables you to pass RMIC options to RMIC. The options, which are
described in Sun's RMI Tools documentation, must be separated by a
space and enclosed in double quotation marks. For example: -rmic "-nowarn
-verbose"
- -trace
- Generates additional progress messages to the console.
- -sqlj
Note: This option is valid only on enterprise beans compliant
with the 2.0 specification.
Enables you to use SQLJ instead
of JDBC to make calls to a DB2 database.
With the -sqlj option specified, the EJB
deployment tool generates SQLJ code for your CMP beans to use SQLJ
to access the database. It also automatically invokes the SQLJ translator
to translate the SQLJ source files. Finally, an Ant script will be
created by the EJB deployment tool to help you to customize the SQLJ
profiles easily. You can run the Ant script against the profile to
produce a DB2 package. These DB2 packages can be used at runtime
to avoid extensive runtime checking. Once you have generated the deployment
code for SQLJ using the EJB deployment tool, you will need to run
the DB2 SQLJ profile customizer, db2sqljcustomize,
against the generated .ser file, which is found in the subfolder
of the websphere_deploy folder associated with
the DB2 back end. Consult the DB2 documentation for more information
on running the DB2 SQLJ profile
customizer, or visit www7b.boulder.ibm.com/dmdd/zones/java/bigpicture.html (section SQLJ
support).
- -OCCColumn
Note: This option is valid only on EJB 2.x CMP entity beans when
generating top-down mapping.
Enables you to add a column to
your relational database table for collision detection. The collision
detection column is the additional database column reserved to
determine if a record has been updated. Adding a column for collision
detection is an alternative optimistic concurrency control scheme
of including attributes in a predicate for optimistic access intents.
To manage the collision detection column, you will need to provide
your own database trigger implementation. The following are the result
of adding a column for collision detection:- The data type of the collision detection column is a 64 bit integer.
- The naming convention of the collision detection column has the
following format: OCC_bean_name
- The top-down mapping generates an extra relational column. This
column can not be mapped to the enterprise bean.
- -outer
- This is an optional parameter and is only supported for deploying
J2EE 1.3 applications. It specifies to use OUTER semantics
for path expressions in EJB query language queries. If this parameter
is not specified, the default setting is INNER semantics.
Note: If you specify this parameter for deploying a J2EE 1.4 application,
this option is ignored because the specification for J2EE 1.4 defines
the INNER semantics be used for J2EE 1.4 applications.
- -complianceLevel "1.4 " | "5.0" | "6.0"
- Specify the Java developer
kit (JDK) compiler compliance level to either 1.4, 5.0 or 6.0, if
you have included application source files for compilation.
- If this parameter is not specified, in any of the following cases
the default -complianceLevel setting is Java developer kit V5.0, "5.0":
- An EAR or JAR file that contains Java EE
5 or EJB 3.0 deployment descriptor files
- An EAR file without any deployment descriptor files
All other cases, the -complianceLevel setting
defaults to Java developer kit
V1.4, "1.4"
- If you are generating deployment code for J2EE 1.4 EAR or JAR
files that contain source code files which makes use of the new language
features in Java developer kit
5.0, you must specify the parameter value, "5.0".
- -DgenInheritancePerfEnhancement true or false
- For EJB 1.x CMP beans using inheritance, use this parameter to
optimize the amount of SQL queries that the EJB container will execute
at runtime during bean hydration to improve the runtime performance
of the application.
- Previously, in an EJB 1.1 inheritance scenario, a result set is
produced by a finder containing all columns visible from the owning
bean and all of its child beans. As a result of each child bean not
knowing the columns from other child beans in this hierarchy, the findByPrimaryKey method
is called for each row (using the primary key of that row) to prevent
data corruption during hydration of the child beans. The original
result set does contain all of the information needed to build the
bean, but because the hydrate method may receive columns in the incorrect
order, then all of these extra findByPrimaryKey queries
need to be executed, rather than just extracting the right columns
from the original result set.
- Now, you can select an enhancement to make the retrieval of the
result set more efficient. The EJB deployment code for EJB 1.1 produces
an enhanced result set that allows EJBDeploy to provide the EJB container
with the correct result set to use for bean hydration. The EJBDeploy
code also generates a flag to tell the EJB container to use the new
enhanced SQL result set at runtime so that the default behaviour does
not change if the flag is not present. This EJB deploy functionality
is not enabled by default but rather enabled via the specified custom
property.
- Modify the $WAS_HOME/deploytool/itp/ejbdeploy.bat (windows)
or $WAS_HOME/deploytool/itp/ejbdeploy.sh script
and add the DgenInheritancePerfEnhancement=true system
property to the Java call. For example:
%JAVA_HOME%\bin\java" -DgenInheritancePerfEnhancement=true -Ditp.loc="%ITP_LOC%" -Dorg.osgi.framework.bootdelegation=* -Dwas.install.root="%WAS_HOME%" -Dwebsphere.lib.dir="%WAS_HOME%\lib" -Dws.ext.dirs="%WAS_HOME%\eclipse\plugins\j2ee.javax_1.4.0";"%WAS_HOME%\eclipse\plugins\com.ibm.ws.runtime.eclipse_1.0.0";"%WAS_EXT_DIRS%" -Dcom.ibm.sse.model.structuredbuilder="off" -cp "%ejbd_cp%" -Xbootclasspath/a:"%bootpath%" -Xj9 -Xquickstart -Xverify:none -Xms256M -Xmx256M %WAS_DEBUG% com.ibm.etools.ejbdeploy.EJBDeploy %*
$JAVA_CMD -Xbootclasspath/a:$ejbd_bootpath -Xms256m -Xmx256m -DgenInheritancePerfEnhancement=true
-Dws.ext.dirs=$WAS_HOME/eclipse/plugins/j2ee.javax_1.4.0:$WAS_HOME/eclipse/plugins/com.ibm.ws.runtime.eclipse_1.0.0:$WAS_EXT_DIRS -Dwebsphere.lib.dir=$WAS_HOME/lib -Dwas.install.root=$WAS_HOME -Ditp.loc=$ITP_LOC -Dorg.osgi.framework.bootdelegation=* -Dejbdeploy.user.install.root=$USER_INSTALL_ROOT/ejbdeploy $USER_INSTALL_PROP -Dcom.ibm.sse.model.structuredbuilder="off" -cp $ejbd_cp $EJBDEPLOY_JVM_OPTIONS $WAS_DEBUG com.ibm.etools.ejbdeploy.EJBDeploy "$@"
ejbdeploy AccessEmployee.ear d:\deploydir AccessEmployee_sqlj.ear -dbvendor DB2UDB_V82 -keep -sqlj -cp "e:\sqllib\java\sqlj.zip"
Explanation: We have DB2 V8.2
for Windows, Linux and UNIX installed
in e:\sqllib.
The ejbdeploy command takes
the AccessEmployee.ear file (which has enterprise beans that are compliant
with the EJB 2.0 specification) as input and produces the AccessEmployee_sqlj.ear
as output. Since the -sqlj option is used,
SQLJ is used instead of JDBC in the generated code to make calls to DB2.
When ejbdeploy runs,
it creates an Eclipse workspace in the directory that you specify
as the working directory: d:\deploydir.
When it has completed running, it deletes this workspace. However,
the -keep option causes ejbdeploy to
end without deleting the workspace.