EAR layout
1. A brief overview of J2EE
========================
The specification for the Java 2 Enterprise Edition (J2EE) not only
addresses topics which are related to application development but also
covers the area of application deployment. With regard to the latter,
J2EE defines the Enterprise Archive (EAR), a JAR file with a fixed
format through which all application resources (configuration files,
application code, static web pages and images) are provided. The EAR
file collects together as a single entity the collection of J2EE
components (EJB's, Web Archives) from which a specific application may
be built. As such the EAR file is itself a complex object containing
other JAR files whose contents and layout conform to the further J2EE
specifications relevant for the specific module type.
1.1 J2EE's Enterprise Archive (EAR)
-------------------------------
A fuller discussion of the J2EE specification lies outside of the
scope of this document, however the following example may provide a
useful illustration into the composition of a EAR file. The example
presented represents an application which contains an EJB module and a
Web Archive (WAR) module:
myApp.ear
|
|--- META-INF
| `---application.xml
|
|--- myEjbModule.jar
`--- myWebModule.war
In the above, the file myApp.ear is a JAR file whose contents observe
the requirements for a EAR file, i.e.
- the top level of the .ear file contains a folder with the fixed
name 'META-INF';
- the top level META-INF folder in turn contains an XML file with
the fixed name 'application.xml', whose contents conform to the
"J2EE Application 1.2" Document Type Declaration (DTD);
Other than meeting the above requirements, the myApp.ear file contains
two further items 'myEjbModule.jar' and 'myWebModule.war' which are
complex entities in their own right, each conforming to the
requirements for their respective module types.
Although in our example application the myApp.ear file contains only
two additional modules, the EAR file can contain an arbitrary number
of files for various module types and the filename portion of these do
not have to comply any fixed naming scheme (although the extension
does have to be .jar or .war respectively).
In place of using a fixed naming scheme the names of the various .jar
or .war files are instead listed within the application.xml file, as
shown below:
Application 1.2//EN"
"http://java.sun.com/j2ee/dtds/application_1_2.dtd">
myApp
myEjbModule
myWebModule
/
NOTE:
- the value inside the
tags must be a relative path
(relative to the top of the EAR file) to the .jar file which
contains the corresponding modules implementation;
- the value inside the
tags must be a relative
path (relative to the top of the EAR file) to the .war file
which contains the corresponding modules implementation;
Having now explained the layout of the EAR file we will next explore
the layout of the other compound objects it contains.
1.2 The layout of an EJB-JAR file
-----------------------------
We will first consider the structure of the JAR file used to provide
the implementation of EJB related modules.
Essentially, the user developed portions of each EJB are presented to
the EJB container as three java class files.
- remote interface class;
- home interface class;
- bean class;
The naming of these classes typically follows a naming convention
which so that it is easier to determine to which of the above
categories any particular ejb .class file corresponds. This
convention adds a 'Home' suffix to the name of the home interface
class or a 'Bean' suffix to the name of the bean class. For example,
if we implement model an 'Employee' as an entity bean and follow the
naming convention we would have the following class names:
- employee.class (remote interface)
- employeeHome.class (home interface)
- employeeBean.class (bean)
Collections of the above classes are combined together in a JAR file
to provide the implementation of an ejb related module. The list of
these files together with additional configuration information is
presented in a further XML file referred to as the 'deployment
descriptor'.
To present the above files to the container for processing, they are
first combined together as a single JAR file with the following
layout:
myEjbModule.jar
|
|-------META-INF
| `-------ejb-jar.xml
|
|-------bean1.class
|-------bean1Home.class
|-------bean1Bean.class
|
|-------bean2.class
|-------bean2Home.class
|-------bean2Bean.class
| :
| :
`-------beanNBean.class
In a similar fashion to that observed by the EAR file, the EJB-JAR
file is a JAR file whose layout observes the following requirements:
- the top level of the .jar file contains a folder with the fixed
name 'META-INF';
- the top level META-INF folder contains the XML deployment
descriptor 'ejb-jar.xml', which describes the configuration and
lists the names of beans and the classes that implement them;
- the class files implementing the beans are located in a nested
class directory structure directly beneath the top of the JAR
file;
NOTE:
The root directory of the .jar file represents the start of a
search path for classes. As a result, classes belonging to
packages are expected to be located in a nested directory
structure beneath this point. For example, if the bean 'bean1'
belonged to a package class 'myapp.ejb' then the layout of the jar
file would look as follows:
1.3 The layout of an WAR file
-------------------------
Another commonly used module type is the Web module, which contains
those items which are invoked through the HTTP mechanism. The
following types of resources are therefore provided by the WAR file:
- files containing static web content, such as html pages,
gif images etc.
- Java Server Pages (JSP's), which are similar to static html
except for the fact that they contain embedded java code and
therefore need to be processed dynamically;
- Java Servlets, java classes implementing content which is
produced dynamically;
The above files are collected together and presented to the J2EE
container as a .war file, which is essentially a standard JAR file
that conforms to the following layout:
myWebModule
|
|-------WEB-INF
| |
| |----web.xml
| |
| `----classes
| |-------servlet1.class
| |-------servlet2.class
| | :
| `-------servletN.class
|
|-------index.html
|-------page2.jsp
`-------images
`-------bullet.gif
In a similar fashion to that observed by the EAR file, the EJB-JAR
file is a JAR file whose layout observes the following requirements:
- the top level of the .jar file contains a folder with the fixed
name 'WEB-INF';
- the top level WEB-INF folder contains the XML deployment
descriptor 'web.xml', which describes the configuration and
lists the names of servlets, the classes that implement them and
how they should map to URL's;
- unlike the EJB-JAR format, which presents classes starting at
the top of the JAR file, in the WAR file the search path for any
servlet classes starts at the 'classes' folder below the WEB-INF
directory;
- static resources are located at a directory structure starting
at the top of the JAR file, such that the top of the jar file is
in essence a 'virtual' root directory for this web module;
NOTE:
The servlet classes are located below a 'classes' folder within
the 'WEB-INF' folder for reasons of consistency and security.
The resources located immediately below the root folder can be
considered as being PUBLIC, in as much as their contents can be
requested by and delivered to the browser. However, in the case of
dynamic pages such as servlets, the target of the request is not
directly sent back to the browser but is instead executed.
The adopted arrangement ensures that there is nothing below the
WEB-INF directory which truly needs to be sent back to a client
and allows the container to implement safety rules accordingly.
This ensures that java byte code and configuration information is
not returned to the end users browser.
