The ejbdeploy command

This topic is divided into the following sections:

• Before you begin
• Syntax
• Behavior
• Tolerating Enterprise JavaBeans at 3.0 (or later) specification-level
• Parameters
• Example

Before you begin

Syntax

Use the following command and the optional parameters, when the schema and map are provided in the input EAR or JAR file:

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:

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_V95. If you want to set a different database back end, use the -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:

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 (or later) specification-level

For EJB 3.0 (or later) specification-level, you no longer need to generate the EJB deployment code. The runtime of the server automatically handles generating the required deployment code.

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 home and remote classes of each enterprise bean 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 run 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 exists before running the ejbdeploy command, the temporary files are generated into the working directory (as an Eclipse workspace). However, if the working directory does not exist before 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 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 are overwritten without warning.)

-cp classpath

If you intend to run the ejbdeploy command against JAR or EAR files that have dependencies on other .zip files or JAR files, you can use the -cp option to specify the class path of the other JAR or .zip files. Using the -cp option, you can specify multiple compressed and JAR files as arguments. However, the .zip files 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 specified 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 the following tasks:

1. Importing code from the input JAR or EAR file
2. Generating the deployment code
3. Exporting code to the output JAR or EAR file

It does not compile the generated deployment code or run remote method invocation compiler (RMIC). Since Java source code is not typically 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 about these binding options, see the WebSphere Application Server documentation.

-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 quotation marks. 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

DB2UDB_V97

DB2 V9.7 for Linux, UNIX, and Windows

DB2UDB_V98

DB2 V9.8 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.

DB2UDBOS390_V10

DB2 V10 for z/OS

This option includes the generated data model that has all the catalog features of DB2 V10 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

DB2UDBISERIES_V61

DB2 V6R1 for iSeries

DB2UDBISERIES_V71

DB2 V7R1 for iSeries

DERBY_V10

Apache Derby V10

DERBY_V101

Apache Derby V10.1

DERBY_V105

Apache Derby V10.5

DERBY_V108

Apache Derby V10.8

ORACLE_V10G

Oracle, V10g

ORACLE_V11G

Oracle, V11g

INFORMIX_V100

Informix® Dynamic Server, V10

INFORMIX_V110

Informix Dynamic Server, V11

INFORMIX_V115

Informix Dynamic Server, V11.5

INFORMIX_V117

Informix Dynamic Server, V11.7

SYBASE_V1250

Sybase Adaptive Server Enterprise, V12.5

SYBASE_V15

Sybase Adaptive Server Enterprise, V15.0

SYBASE_V155

Sybase Adaptive Server Enterprise, V15.5

MSSQLSERVER_2005

Microsoft SQL Server 2005

MSSQLSERVER_2008

Microsoft SQL Server 2008

Note:

• The default is DB2UDB_V95 (DB2 V9.5 for Linux, UNIX, and Windows)
• If -sqlj is specified, this argument supports the following database vendors:
  • DB2UDB_V98
  • DB2UDB_V97
  • DB2UDB_V95
  • DB2UDB_V91
  • DB2UDB_V82
  • DB2UDB_V81
  • DB2UDBOS390_V10
  • DB2UDBOS390_V9
  • DB2UDBOS390_V8
  • DB2UDB0S390_NEWFN_V8

-debug

Specifies that deployment code is 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 the Sun 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 is 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 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 about running the DB2 SQLJ profile customizer, or visit http://www.ibm.com/developerworks/data/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 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 cannot 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 later) or EJB 3.0 (or later) 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 uses the new language features in Java developer kit 5.0 (or later), you must specify one of the following parameters when running the ejbdeploy command:

-complianceLevel "5.0"

For Java developer kit 5.0.

-complianceLevel "6.0"

For Java developer kit 6.0.

-DgenInheritancePerfEnhancement true or false

For EJB 1.x CMP beans using inheritance, use this parameter to optimize the number of SQL queries that the EJB container executes 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 the information needed to build the bean, but because the hydrate method can receive columns in the incorrect order, then all 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 behavior 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 "$@"

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 the information needed to build the bean, but because the hydrate method can 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 activation. As a result, the EJB container makes a small modification to allow the EJB deployment code to tell the container how to activate the bean. The EJBDeploy code generates a flag to tell the EJB container which method of activation to use. This EJB deploy functionality is not enabled by default but rather enabled via a custom property.

Example

We have DB2 V9.5 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.