Tools

Enterprise JavaBean Tools

Instead of loadjava and publish, Enterprise JavaBean developers use the deployejb tool, which performs equivalent operations, as well as generating and compiling infrastructure code for the EJB. The ejbdescriptor tool is a utility for translating between the text and serialized object forms of EJB deployment descriptors.

deployejb

From a deployment descriptor and a JAR containing interfaces and classes, the deployejb tool makes an EJB implementation ready for test or production clients to invoke. deployejb converts the text descriptor to a serialized object, generates and compiles classes that effect client-bean communication, loads compiled classes into the database, and publishes the bean's home interface name in the session namespace so clients can look it up with JNDI. The BeanHomeName must refer to a PublishingContext for which the deployejb invoker has the write right; see "publish" for the rights required to publish.

Before deploying, verify that you add the appropriate JDK JAR, library, and binary information in the following environment variables:

Environment Variable Addition Required

JAVA_HOME

Set to the location where the JDK is installed.

CLASSPATH

Include the appropriate JDK JAR file in your CLASSPATH, as follows:

For JDK 1.1, include $JAVA_HOME/lib/classes.zip

For JDK 1.2, include the JDK's tools.jar and dt.jar file

Also, include the remote and home interface files and the JAR generated by deployejb.

PATH

Add the JDK binary path: $JAVA_HOME/bin

LD_LIBRARY_PATH

Add the JDK library path: $JAVA_HOME/lib

Environment Variable	Addition Required
`JAVA_HOME`	Set to the location where the JDK is installed.
`CLASSPATH`	Include the appropriate JDK JAR file in your CLASSPATH, as follows: For JDK 1.1, include `$JAVA_HOME/lib/classes.zip` For JDK 1.2, include the JDK's `tools.jar` and `dt.jar` file Also, include the remote and home interface files and the JAR generated by `deployejb`.
`PATH`	Add the JDK binary path: `$JAVA_HOME/bin`
`LD_LIBRARY_PATH`	Add the JDK library path: `$JAVA_HOME/lib`

To specify a different encoding for multibyte support, modify the encoding element in the XML deployment descriptor heading. The deployejb tool recognizes the proper encoding from the header.

Syntax

deployejb {-user | -u} <username> {-password | -p} <password> 
  {-service | -s} <serviceURL> -descriptor <file> -temp <work_dir> <beanjar>
  [-addclasspath <dirlist>]  
  [-beanonly]
  [-credsFile <credentials>]
  [-describe | -d]
  [-generated <clientjar>] 
  [-help | -h] 
  [-iiop]
  [-keep]
  [-oracledescriptor <file>]
  [-republish]
  [-resolver "resolver_spec"]
  [-role <role>] 
  [-ssl]
  [-useServiceName]
  [-verbose]
  [-version | -v]

Argument Summary

Table 1-54 summarizes the deployejb arguments.

Note:
Any value provided within the argument options is case insensitive. All values are uppercased.

Table 1-54 deployejb Argument Summary

Argument	Description and Values
`-user`	Specifies the schema into which the EJB classes will be loaded.
`-password`	Specifies the password for `<username>`.
`-service`	URL identifying database in whose session namespace the EJB is to be published. The serviceURL has the form: `sess_iiop://<``host>:<lport>:<sid>` `<host>` is the computer that hosts the target database; `<lport>` is the listener port configured to listen for session IIOP; `<sid>` is the database instance identifier. Example: `sess_iiop://localhost:2481:orcl` which matches the default installation on the invoker's machine.
`-credsFile`	Supply a text file with credentials instead of a username and password for the connect. You create this file by exporting a wallet into a text version.
`-descriptor`	Specifies the text file containing the EJB deployment descriptor.
`-temp`	Specifies a temporary directory to hold intermediate files `deployejb` creates. Unless you specify `-keep`, `deployejb` removes the files and the directory when it completes.
`<beanjar>`	Specifies the name of the JAR containing the bean interface and implementation files.
`-addclasspath`	Specifies directories containing interface and/or implementation dependency classes not contained in `<beanjar>`. Format of `<dirlist>` is the same as `javac`'s `CLASSPATH` argument. Required for `-beanonly`.
`-beanonly`	Skips generation of interface files. Basically, this option enables you to reload the bean implementation if none of the interfaces have changed.
`-describe`	Summarizes the tool's operation.
`-generated`	Specifies the name of the output (generated) JAR file, which contains communication files bean clients need. If you do not specify, the output JAR file has the name of the input JAR file with `_generated` appended.
`-help`	Summarizes the tool's syntax.
`-iiop`	Connects to the target database with IIOP instead of the default session IIOP. Use this option when deploying to a database server that has been configured without session IIOP.
`-keep`	Do not remove the temporary files generated by the tool. This option may be useful for debugging because it provides access to the source files `deployejb` generates.
`-oracledescriptor`	Specifies the text file containing the Oracle-specific deployment descriptor.
`-republish`	Replaces the published BeanHomeName attributes if the BeanHomeName has already been published, otherwise publishes it.
`-resolver`	Specifies an explicit resolver spec, which is bound to the newly loaded classes. If -resolver is not specified, the default resolver spec, which includes current user's schema and PUBLIC, is used. For more information, see the discussion on -resolve and -resolver in "loadjava".
`-role`	Specifies role to assume when connecting to the database; no default.
`-ssl`	Connects to the database with SSL authentication and encryption.
`-useServiceName`	If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID.
`-verbose`	Emits detailed status information while running.
`-version`	Shows the tool's version.

Argument Details

addclasspath

deployejb needs the classes the home and remote interfaces depend on and the classes the bean implementation depends on. These dependency classes can either be included in the <beanjar> file or directories containing them or can be specified in the -addclasspath argument. The first approach is less prone to error, the second can substantially reduce deployejb's run time. If you use -addclasspath, then you must ensure that the classes have been loaded before you run a client that activates the EJB.

Here is a deployejb example.

Basic invocation specifying the name of the generated client JAR file:

deployejb -user SCOTT -password TIGER -service sess_iiop://dbserver:2481:orcl \
  -descriptor myBeanDescriptor.xml -temp /tmp/ejb \ 
  -generated myBeanClient.jar myBean.jar

ejbdescriptor

Each EJB implementation includes a serialized Java object known as a deployment descriptor. The values in a deployment descriptor are not readable by people, yet people must create them and might sometimes have to read them. The ejbdescriptor tool transforms a serialized deployment descriptor to text and converse. Developers are most likely to use ejbdescriptor to extract the deployment descriptor data from an EJB developed for a non-Oracle environment. The deployejb tool calls ejbdescriptor to build a deployment descriptor from the text file you specify in the -descriptor argument.

Syntax

ejbdescriptor [-options] <infile> <outfile>  
  [-parse]
  [-parsexml]
  [-dump
  [-dumpxml]
  [-encoding]

Argument Summary

Table 1-55 describes the ejbdescriptor arguments.

Table 1-55 ejbdescriptor Argument Summary

Option	Description
`-parse`	Creates serialized deployment descriptor `<outfile>` from a Release 8.1.6 and previous .ejb text deployment descriptor specified in `<infile>`.
`-parsexml`	Creates the Release 8.1.6 .ejb text deployment descriptor `<outfile>` from and XML deployment descriptor specified in `<infile>`.
`-dump`	Creates a Release 8.1.6 .ejb deployment descriptor text file `<outfile>` from serialized deployment descriptor `<infile>`.
`-dumpxml`	Creates the Release 8.1.7 XML deployment descriptor file `<outfile>` from a Release 8.1.6 text deployment descriptor `<infile>`.
`-encoding`	Identifies the source file encoding for the compiler, overriding the matching value, if any, in the `JAVA$OPTIONS` table. Values are the same as for the `javac` `-encoding` option. If you do not specify an encoding on the command line or in a `JAVA$OPTIONS` table, the encoding is assumed to be `latin1`. The `-encoding` option is relevant only when loading a source file.
`infile`	Name of the file to parse or read. The default is standard in. The conventional suffix for a deployment descriptor file is .ejb or .xml; for a serialized descriptor it is .ser.
`outfile`	Name of file to `dump` or write. The default is standard out. The conventional suffix for a deployment descriptor file is .ejb or .xml; for a serialized descriptor it is .ser.

Here are examples of the ejbdescriptor tool.

Create a Release 8.1.7 XML deployment descriptor from a Release 8.1.6 .ejb deployment descriptor:

ejbdescriptor -dumpxml beandescriptor.ejb beandescriptor.xml

Create a Release 8.1.6 deployment descriptor from an XML deployment descriptor:

ejbdescriptor -parsexml beandescriptor.xml beandescriptor.ser

Create a text file representation of a Release 8.1.6 deployment descriptor:

ejbdescriptor -dump beandescriptor.ser beandescriptor.ejb

Create a serialized deployment descriptor from a Release 8.1.6 deployment descriptor file:

ejbdescriptor -parse beandescriptor.ejb beandescriptor.ser

Display the contents of a Release 8.1.6 deployment descriptor:

ejbdescriptor -dump beandescriptor.ser