Before you can successfully run your enterprise beans on either a
test or production server, you need to generate deployment code for the enterprise
beans. 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.
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"]
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"]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.
Behaviour
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 backend is DB2UDB_V82.
If you want to set a different database backend, use the -dbname, -dbschema,
and -dbvendor options to specify your choice. A data definition
language (DDL) file, Table.ddl, is created for the database backend set in
the -dbvendor option, when you run the ejbdeploy command.
However, you can specify only one backend 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® backend and you specify -dbvendor ORACLE
on the command line; in previous releases of the product, rather than getting
a second backend, 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.
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 Universal
database V8.1 for Linux®, UNIX, and Windows
- DB2UDB_V82
- DB2 Universal
database V8.2 for Linux, UNIX, and Windows
- DB2UDB_V91
- DB2 Universal
database V9.1 for Linux, UNIX, and Windows
- DB2UDBOS390_V7
- DB2
Universal Database™ for z/OS®, V7
- DB2UDBOS390_V8
- DB2
Universal Database for z/OS, V8
- DB2UDBOS390_NEWFN_V8
- DB2
Universal Database for z/OS, V8
- Additional to the DB2UDBOS390_V8 option, this option
includes the generated data model that has all the new catalog features of DB2
Universal Database for z/OS v8 specified in the new function mode. Use this
option if you plan to work with the generated data model available in the WebSphere Application
Server Toolkit or IBM® Rational® Software Development Platform products.
- DB2UDBOS390_V9
- DB2
Universal Database for z/OS, V9
- This option includes the generated data model that
has all the new catalog features of DB2 Universal Database for z/OS V9
specified in the new function mode. It enables the option to work with the
generated data model available in the WebSphere Application Server Toolkit
or IBM Rational Software
Development Platform products.
- DB2UDBISERIES_V53
- DB2
Universal Database for iSeries™, V5R3
- DB2UDBISERIES_V54
- DB2
Universal Database for iSeries, V5R4
- DERBY_V10
- IBM Cloudscape™,
V10.1
- ORACLE_V9I
- Oracle, V9i
- ORACLE_V10G
- Oracle, V10g
- INFORMIX_V93
- Informix® Dynamic
Server, V9.3
- INFORMIX_V94
- Informix Dynamic
Server, V9.4
- INFORMIX_V100
- Informix Dynamic
Server, V10.0
- SYBASE_V1250
- Sybase Adaptive Server Enterprise, V12.5
- SYBASE_V15
- Sybase Adaptive Server Enterprise, V15.0
- MSSQLSERVER_2000
- Microsoft® SQL
Server 2000
- MSSQLSERVER_2005
- Microsoft SQL
Server 2005
The following backend ids are deprecated:
- SQL92 (1992 SQL Standard)
- SQL99 (1999 SQL Standard)
Although SQL92 and SQL99 are deprecated, the SQL92 and SQL99 options
remain available. If you choose to use the deprecated SQL92 or SQL99 backend
id, see the topic EJB query to SQL
syntax to help determine what backend you should use, in the near future,
when the deprecated SQL92 and SQL99 backends are no longer available.
If
you want to use an unsupported database, see the topic EJB query to SQL syntax to help choose a valid database
vendor backend id that matches closely to your unsupported deployment environment.
Note: - The default is DB2UDB_V82 (DB2 for Windows, V8.2 and UNIX)
- If -sqlj is specified, it supports DB2UDB_V91 (DB2 for Windows,
V9.1 and UNIX), DB2UDB_V82 (DB2 for Windows,
V8.2 and UNIX), DB2UDB_V81
(DB2 for Windows,
V8.1 and UNIX), DB2UDBOS390_V9 (DB2 for z/OS,
V9), DB2UDBOS390_V8 (DB2 for z/OS, V8) and DB2UDBOS390_V7(DB2 for z/OS, V7).
- -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 backend. 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"
- Specify the Java Development Kit (JDK) compiler compliance level
to either 1.4 or 5.0, if you have included application source files for compilation.
If this parameter is not specified, the default setting is JDK v1.4. If your
application is using new functionality defined in JDK v5.0 or you have included
source files (which is not recommended) then you must specify the parameter
value as "5.0".
Example
ejbdeploy AccessEmployee.ear d:\deploydir AccessEmployee_sqlj.ear -dbvendor DB2UDB_V82 -keep -sqlj -cp "e:\sqllib\java\sqlj.zip"
Explanation: We have DB2 Universal database (version 8.2 for Windows 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.