jBoss 2.0: Deploying EJBs in

jBoss

In order to make an EJB available through jBoss, you need to package

it into a JAR file, and then put that JAR file in the deploy directory.

This section has the details on what needs to go into the JAR file, how
to prepare it, what to do if something goes wrong, and some advanced

deployment topics.

Preparing Your EJB JAR

The first question you need to answer is how you want to package

multiple EJBs. You can package them all separately, with one JAR file

per bean, or you can package them all together, with one JAR file per
"application." Both approaches have their advantages.

If you package all your beans together, any EJB-EJB references will

perform faster since the server gathers them all together into one
application. You'll save a little work on the configuration since there

are a number of settings that you must make once per JAR. The
packaging process is simpler since you just include all your classes in

one JAR. But if you unload one bean, you unload them all. Additionally,
you cannot deploy individual beans within one EJB JAR - when you

deploy the JAR, all EJBs in the JAR are deployed.

The advantage to packaging everything separately is that you have
finer-grained control; You can update individual EJBs while leaving the

rest running. But this is definitely more complex to configure and
deploy.

Required Classes

The JAR file for an EJB requires all the EJB classes and interfaces, plus
any other required classes that are not available on the server

classpath. Any JARs or ZIPs in the lib or lib/ext directories are

available on the server classpath. But other EJB JARs are not available
on the server classpath. So if your EJB uses any helper or utility

classes, those are probably required. If your EJB uses another EJB that
is not packaged in the same JAR, then you need to package the Home

and Remote interfaces (and Primary Key, for entities) of the other EJB
in the current JAR. You do not need the implementation class for the

other EJB, or any helper or utility classes it uses, unless they are used

in the home or remote interfaces or primary key class.

Deployment Descriptors

In addition to the EJB classes, you need one or more deployment

descriptors. In previous versions of the EJB specification, this was
often a serialized Java class, with other vendor-specific files or classes.

In the EJB 1.1 specification, the EJB deployment descriptor is an XML
file. Any vendor-specific extensions may use any format, but in the

case of jBoss, they are also XML files. So to deploy in jBoss, you need
the one standard EJB 1.1 deployment descriptor, and then up to two

other jBoss-specific XML deployment descriptors, depending on the

type of EJB and the features it will use.

The three possible deployment descriptors are described next. If you

need specific details, you can refer to the

DTDs

section in the

Appendix.

The EJB 1.1 Deployment Descriptor

The EJB 1.1 Deployment Descriptor (

ejb-jar.xml

) declares your EJBs. It

indicates what the various classes are (home + remote interfaces,

primary key, implementation class). It defines any environment
settings, EJB references, and data source references. It defines

security and transaction settings for each bean or method. It gives
each bean a name, which becomes the default JNDI name for the

bean. For each CMP Entity Bean, it lists which fields are container-

managed persistent fields. All of this information should be the same
no matter what EJB server you deploy in.

The jBoss Deployment Descriptor

The jBoss Deployment Descriptor (

jboss.xml

) is optional. There are

default settings, and you only need to include this file if you want to
override the defaults. Further, you only need to include any sections

within this file that differ from the defaults, so you do not need a new

complete configuration file for every JAR.

The jBoss deployment descriptor handle the following settings:

•

The JNDI name for the EJBs in the JAR

•

Any data sources or other resources used by the EJBs in the JAR (declared in

ejb-jar.xml

)

•

How to resolve EJB references (declared in

ejb-jar.xml

) when the EJBs in this

JAR refer to other EJBs (in this JAR or elsewhere)

•

The RMI configuration for each EJB in the JAR, which determines the client JDK
version compatibility

•

The instance pool characteristics for each EJB in the JAR

•

The transaction manager for each EJB in the JAR

•

The persistence manager for each CMP Entity Bean in the JAR

•

Whether to optimize calls between beans in the same JAR for additional
performance

•

Whether to log information on every bean invocation

The structure of this file is broken into container configurations,
resource managers, and EJB declarations. All the settings above

except the JNDI name and data sources are configured once in a
named "container configuration". Then any EJBs declare which

container configuration they use, so you can easily use the same

configuration for a number of EJBs within the same JAR.

You can also set up resource managers for the JAR. The most common

resource manager type is JDBC, though there are others available.

These resource managers are visible to all EJBs in the JAR, though you
must also indicate in the EJB declaration section which EJBs use which

resource managers. With JDBC resources, you link the JNDI name of
the database pool or pools you set up in the configuration section (see

Data Sources

) to a resource manager name.

In the EJB declaration section, you indicate which container
configuration each EJB uses. You may also override the default JNDI

name for the bean. If you defined any EJB references in the EJB 1.1
deployment descriptor, you define here what the JNDI name of the

referenced bean is, so those references can be resolved. If you defined
any data source references in the EJB 1.1 deployment descriptor, you

link the data source reference name from the EJB 1.1 deployment

descriptor to a resource manager you configured above for the JAR.

The JAWS Deployment Descriptor

The JAWS Deployment Descriptor (

jaws.xml

) is used by the default

jBoss Container-Managed Persistence engine. So this file is only used

for CMP Entity Beans. Again, there are default settings, and you only
need to include this file if you want to override the defaults. Further,

you only need to include any sections within this file that differ from

the defaults, so you do not need a new complete configuration file for
every JAR.

The JAWS deployment descriptor handles the following settings:

•

The table to use for each CMP bean

•

The column that each CMP field corresponds to

•

The database product you are using, and how to map JDBC types to native
database types

•

Whether the table should be created when the bean is deployed

•

Whether the table should be dropped when the bean is undeployed

•

Whether updates should include only the changed columns or all columns

•

Whether the EJBs should be treated as read-only

The JAWS deployment descriptor is split into two sections. In the first,

you provide JDBC to SQL type mappings for your DBMS. In the
second, you provide the EJB-specific configuration for each CMP Entity

Bean that uses JAWS.

Editing Deployment Descriptors with EJX

jBoss includes a graphical tool to edit deployment descriptors, called
EJX (Enterprise Java XML-editor). You can edit all three types of

deployment descriptors with EJX. EJX can either read and write XML
files on disk, or read and write XML files in an EJB JAR. We recommend

that you package all the required class files into a JAR, and edit the
deployment descriptors there, so EJX can validate your entries against

the available classes.

After you have created your deployment descriptors, you may want to
extract them from the JAR so subsequent builds can use the existing

deployment descriptors instead of forcing you to go through the entire
editing process again. If you only have minor changes to make later,

you can edit the file on disk using EJX, or if you're comfortable with

XML you can just edit them by hand.

You may also want to browse the

EJX Walkthrough

in the Appendix for

a step-by-step overview of creating deployment descriptors in EJX.

Editing Deployment Descriptors By Hand

If you have an XML editor or text editor, you can simply compose the
required deployment descriptors by hand. It's often helpful to get a

start in EJX and then tweak the output files as necessary, but you can
use whichever method you're most comfortable with. You should refer

to the

DTDs Section

of the Appendix for the exact syntax for

deployment descriptors.

The Manifest File

You don't typically need a custom manifest file for an EJB 1.1 JAR. The
JAR tool will create a manifest for you, if you don't provide one

yourself. One case where you may want a manifest file is to add other
JARs to your classpath. You may choose to package utility classes in a

separate JAR rather than including them in all the necessary EJB JARs,
and adding that separate JAR to the classpath in the manifest file

would be the best way to accomplish that.

Deploying Your EJB JAR

Deploying an EJB JAR in jBoss is simple. Once you have packaged the
classes and deployment descriptors in a JAR, copy that JAR to the

deploy directory. If jBoss is running, it will deploy the JAR
automatically. If not, it will deploy the JAR the next time you start it.

You can use the management interface (see

Managing a Live jBoss

Server

) to manually deploy JARs from different locations, but copying

the JARs to the deploy directory is the recommended way to deploy.
No matter how you deploy, all the EJBs in an EJB JAR are deployed

when you deploy the JAR - you cannot select specific EJBs within the

JAR to deploy.

Deployment Failures

There are a number of reasons a deployment might fail, but the most

common include leaving required classes out of a JAR, making
mistakes in the deployment descriptors, and using the wrong JNDI

names in your beans. If the tips here do not help you resolve your
deployment problem, see the

Troubleshooting

section.

Strange File Names

You may notice that the jBoss server refers to an EJB JAR by a cryptic
name. The reason is the jBoss does not want to lock files in the

deployment directory and prevent you from updating them, so it

makes copies in a temporary directory with cryptic names. This is not
the cause of a deployment failure.

Verifying EJBs During Deployment

If your EJB JAR fails to deploy, the first thing to do is to turn on the
verifier and try again. The verifier will run a number of tests on each

EJB in an EJB JAR before the JAR is deployed. No matter what the

results of the verification are, the deployer will attempt to deploy the
EJBs, but the verifier may give you helpful error messages ahead of

time. To enable the verifier, edit the

jboss.jcml

file in the conf

directory. Look for a section like the following:

<mbean name="EJB:service=ContainerFactory">
<attribute name="VerifyDeployments">false</attribute>
</mbean>

If there is no such section, simply add it. In either case, make sure the

attribute value is set to

true

to enable the verifier.

JNDI Problems

If your bean gets NamingExceptions, that indicates a JNDI problem.
Typically, this means the bean implementation used an invalid JNDI

name when it looked up an environment setting, a data source, or

another EJB. Review the naming syntax in the

Writing EJBs

section, for

Environment Settings

,

Data Sources

, or

EJBs

. Remember that your

EJBs should not attempt to look up any of those unless they have been
declared and named in the

ejb-jar.xml

file (see

The EJB 1.1

Deployment Descriptor

). Also, note that you must define the target

data source or EJB in the

jboss.xml

file (see

The jBoss Deployment

Descriptor

).

Undeploying EJBs

To undeploy an EJB, delete the EJB JAR file in the deploy directory.

You can also undeploy JARs using the management interface, and that
is the only option if you manually deployed a JAR in a different location

(see

Managing a Live jBoss Server

).

Redeploying Existing EJBs

To redeploy an EJB, copy a new EJB JAR file to the deploy directory,
replacing the old one. The EJBs in the JAR will automatically be

undeployed and the new versions deployed. You can also undeploy
JARs using the management interface, and that is the only option if

you manually deployed a JAR in a different location (see

Managing a

Live jBoss Server

).

Hot Deployment

jBoss always hot deploys and EJB JARs copied into the deploy
directory, so there are not special procedures for hot deployment. If

you want a strictly manual deploy and undeploy process, use the
management interface (see

Managing a Live jBoss Server

).