This chapter teaches you how to write XML deployment descriptors for your beans. You may never need to write a deployment descriptor by hand: most vendors of integrated development tools and EJB servers provide tools for creating the descriptor automatically. Even if you have such a tool available, however, you must be familiar with deployment descriptors: the ability to read a deployment descriptor is an essential skill. This chapter does not attempt to teach you how to read or write correct XML. There are many books on the subject: XML Pocket Reference by Bob Eckstein (O’Reilly) is a good quick reference; XML in a Nutshell, by Elliotte Rusty Harold and W. Scott Means (O’Reilly), provides a more detailed treatment.
Very briefly,
XML looks like HTML, but with different tag
names and attributes inside the tags. You won’t see
<h1> and <p> inside
a deployment descriptor; instead, you’ll see tags
like <ejb-jar>. But if
you’re familiar with the structure of HTML,
you’re most of the way towards reading XML. The tag
names and attribute names for an XML document are defined by a
special document called an XML Schema Definition (XSD). (EJB 2.0 used
an older kind of definition document called a
Document Type Definition (DTD)). An XSD or
DTD defines the tags and attributes that can be used in a deployment
descriptor, as well; the XSDs for deployment
descriptors in EJB 2.1 and the DTDs for EJB 2.0 are available online
at http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd
(EJB 2.1) and http://java.sun.com/dtd/ejb-jar_2_0.dtd (EJB
2.0).
There are other important differences between XML and HTML. XML is
much more strict; many things that are acceptable in HTML are errors
in XML. This should not make a difference if you’re
just reading a deployment descriptor, but if you’re
writing one, be careful. Two differences are particularly important.
First, XML is case-sensitive: you cannot mix uppercase and lowercase
in your tag names. HTML does not care about the difference between
<h1> and <H1>, but
XML does. All the tags and attributes used in deployment descriptors
are lowercase. Second, XML will not forgive you if you fail to supply
closing tags. In HTML, you can write
<p>...<p> without ever putting in a
</p> to end the first paragraph. But XML
never allows you to be sloppy. Whenever you have an opening tag, you
must also supply a closing tag.
That’s about it. These few paragraphs don’t qualify as a real introduction to XML, but the basic ideas are very simple, and they are all you need to get going.
The JAR file format is a platform-independent format for compressing, packaging, and delivering several files together. Based on the Zip file format and the ZLIB compression standards, the JAR (Java archive) packages and tool were originally developed to make downloads of Java applets more efficient. As a packaging mechanism, however, the JAR file format is a convenient way to “shrink-wrap” components and other software for delivery to third parties. The original JavaBeans component architecture depends on JAR files for packaging, as does Enterprise JavaBeans. The goal in using the JAR file format is to package all the classes and interfaces associated with one or more beans, including the deployment descriptor, into one file.
The JAR file is created using a vendor-specific tool, or using the jar utility that is part of the Java 2, Standard Edition development kit. An ejb-jar file contains:
The XML deployment descriptors
The bean classes
The remote and home interfaces
The primary key class
Dependent classes and interfaces
All of the XML deployment descriptors
(ejb-jar.xml,
webservices.xml, WSDL, JAX-RPC Mapping) should
be located in the META-INF directory and must
contain all the deployment information for all the beans in the
ejb-jar file. For each bean declared in the XML
deployment descriptor, the ejb-jar file must
contain its bean class, remote and home interfaces, and dependent
classes and interfaces. Dependent classes and interfaces are usually
things like application-specific exceptions, business interfaces, and
other supertypes, and dependent objects that are used by the bean. In
the ejb-jar file for the TravelAgent bean, for
example, we would include the
IncompleteConversationalState application
exception and the Ticket and
CreditCard classes, as well as the remote and home
interfaces to other beans referenced by the TravelAgent bean, such as
the Customer and ProcessPayment beans.[53]
You can use the jar utility from the command line to package a bean in a JAR file. Here’s an example of how the jar utility was used to package the Cabin EJB in Chapter 4:
dev % jar cf cabin.jar com/titan/cabin/*.class META-INF/ejb-jar.xml F:..dev>jar cf cabin.jar com itancabin*.class META-INFejb-jar.xml
You might have to create the
META-INF
directory first, and copy ejb-jar.xml into that
directory. The c option tells the
jar utility to create a new JAR file that
contains the files indicated in subsequent parameters. It also tells
the jar utility to stream the resulting JAR file
to standard output. The f option tells
jar to redirect the standard output to a new
file named in the second parameter (cabin.jar).
It is important to get the order of the option letters and the
command-line parameters to match. You can learn more about the
jar utility and the
java.util.zip package in Java in a
Nutshell by David Flanagan or Learning
Java by Pat Niemeyer and Jonathan Knudsen, both published
by O’Reilly.
The jar utility creates the file
cabin.jar in the dev
directory. If you are interested in looking at the contents of the
JAR file, you can use any standard ZIP application (WinZip, PKZIP,
etc.) or the command jar tvf cabin.jar.
[53] The EJB 1.1
specification also allows remote and home interfaces of referenced
beans to be named in the manifest’s
Class-Path attribute, instead of including them in
the JAR file. Use of the Class-Path entry in the
JAR’s manifest is addressed in more detail in the
Java 2, Standard Edition specification.