Sun Microsystems

The following article may contain actual software programs in source code form. This source code is made available for developers to use as needed, pursuant to the terms and conditions of this license.

1. About This Article

This article aims to present a clear, simple and focused understanding of EAR (Enterprise ARchive, or .ear) files, assisting in creation, maintainence and troubleshooting. It incorporates feedback on Manually Creating a Simple Web ARchive (WAR) File.

2. EAR File Overview

This section has been covered well in many of the documents in the Resource section of this article, but as a quick reference, an overview is given here.

Why Use an EAR File?

Quite simply, EAR files are a way of creating a portable collection of logically related Java 2 Platform, Enterprise Edition (J2EE) components.

There are a number of benefits for doing this, including synchronised: security role-names, dependencies, versioning and web context configuration, as well as application-level configuration, including the use of alternate deployment descriptors, which are further explained in the next section. Sun ONE Application Server 7 also creates a separate classloader universe for an EAR, to further enhance classloader separation.

What is in an EAR File?

The deployment descriptors are:

META-INF/application.xml containing:

icons, a description and a name used by tools
the modules contained within, their location within the EAR, the context root for each web application module, and alternative deployment descriptor references
security role names and descriptions

META-INF/sun-application.xml (optional vendor descriptor) containing:

web application context-root overriding
a pass-by reference option for the application scope
security mappings from role-name to user and group
a unique id that is managed during (re)deployment

Enterprise JavaBean (EJB) component modules (.jar)
Deployment descriptors are:

META-INF/ejb-jar.xml
META-INF/sun-ejb-jar.xml- (required - vendor-specific)
.dbschema, schema file for Container Managed Persistance (CMP) entity bean (optional)
sun-cmp-mapping.xml, vendor-specific deployment description for CMP entity bean (optional)

Web application modules (.war)
Deployment descriptors are:

WEB-INF/web.xml
WEB-INF/sun-web.xml - (optional - vendor-specific)

Application client modules (.jar)
Deployment descriptors are:

application-client.xml
sun-application-client.xml - (required - vendor-specific)
sun-acc.xml (vendor specific)

Resource adapter modules (.rar)
Deployment descriptors are:

ra.xml
sun-ra.xml - (required - vendor-specific)

3. Creating an EAR File

Deployment Descriptors

Here we will show here the EAR file's deployment descriptors that contain the full array of elements and sub-elements. Comments are in blue, following the comments syntax of "//", and should be omitted.

For the multiplicity of each element and sub-element, please check the relevent Data Type Definitions (DTDs).

Sample application.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" "http://java.sun.com/dtd/application_1_3.dtd">

<application>

<icon>

            

<small-icon>/small.gif</small-icon>

            

<large-icon>/large.jpg</large-icon>

            

</icon>

<display-name>my-display-name</display-name>

            

<description>Application
description</description>

<module>
<alt-dd>/alt-descriptors/myejb-altdd.xml</alt-dd>// this sub-element can apply to
any module type

            

<ejb>myejb.jar</ejb>

            

</module>

<module>

<java>myappclient.jar</java>

            

</module>

<module>

<connector>myresourceadapter.rar</connector>

            

</module>

            

<module>

<web>

            

<web-uri>mywebapp.war</web-uri>

            

<context-root>helloworld</context-root>

</web>

            

</module>

<security-role>
<description>Just the
Matt's</description> //
overrides the description of the same role-name in a module

<role-name>Matt</role-name>

</security-role>

</application>

Sample corresponding sun-application.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-application PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 J2EE Application 1.3//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-application_ 1_3-0.dtd'>

<sun-application>

<web>

<web-uri>mywebapp.war</web-uri> // maps to application.xml
<context-root>overridden</context-root>

</web>

<pass-by-reference>false</pass-by-reference>

<security-role-mapping>

<role-name>Matt</role-name> // maps to application.xml
<principle-name>mh12345</principle-name>
<group-name>staff</group-name>

</security-role-mapping>

<unique-id>1234567890</unique-id> // automatically generated and maintained

</sun-application>

File Locations

From the preceding deployment descriptors, the structure of the EAR file would be as follows:

/META-INF/MANIFEST.MF
/META-INF/application.xml
/META-INF/sun-application.xml
/alt-descriptors/myejb-altdd.xml
/small.gif
/large.jpg
/mywebapp.war
/myejb.jar
/myresourceadapter.rar
/myappclient.jar

Sample EAR Files

There are samples in the Sun ONE Application Server 7 distribution, under the ${app_server_install}/samples/ directory. You can find information on the samples in the samples/index.html file.

The SampleApplication example built for Sun ONE Application Server 7 below, contains a very simple servlet and a stateless session bean. The output should contain a "hello" message from the servlet. The servlet then calls the EJB, which returns another "hello" message that is output on the screen.

The default URL it deploys the servlet (WebArchive content) to is /suneartest/, so it should be viewable at machine_name/suneartest/myServlet.

SampleApplication.ear
Source.jar

Sun ONE Studio and EAR Files

It is important to note that you cannot start by creating an EAR file, and then create the parts below this node. The components of an EAR file should be standalone modules, and as such you should build them this way. Once you have a web module, for example, you can then add this to the EAR file (as long as it is mounted as a web module) by selecting "Add Module" from the contextual menu.

The completed EAR file should then look like

When browsing the EAR file you will see this hierarchy in the filesystems window. The contextual menu will now allow you to extract the EAR file for processing. Although you will not have access to the sources, you will be able to update the deployment descriptors and browse the contents, including classes, methods and resource files.

Troubleshooting EAR Files With Sun ONE Application Server 7

Can I verify that my EAR file is correct?

The verifier tool validates both J2EE platform-specific and Sun ONE Application Server-specific deployment descriptors against their corresponding DTD files, and gives errors and warnings if a module or application is not J2EE platform or Sun ONE Application Server-compliant. You can verify deployment descriptors in .ear, .war, .rar, and .jar files.

You may verify the EAR file at deploy time in the administration GUI, by selecting the appropriate checkbox. You may also do this at the command line, or by using Ant.

See the Sun ONE Application Server 7 Developer's Guide, The Deployment Descriptor Verifier section.

Can I obtain more detailed deployment error messages?

The message you may receive in the administration GUI may only be the highlighted problem. To see full details you need to view the server.log file, in

{path_to_server_config}/domains/{your_domain}/admin-server/logs/server.log

You may also view the log from the administration GUI by selecting "Admin Server" --> "Logging" --> "View Event Log".

Where does the EAR file get deployed in Sun ONE Application Server 7?

{path_to_server_config}/domains/{your_domain}/{your_server}/applications/j2ee-apps/

The application name will have a number appended for the server to implement version control, as per the J2EE Platform Specification. You will notice that all the files contained within have been extracted.

How can I automate or generate stubs and skeletons without deploying?

Apache's Ant can help here; the samples that come with the Sun ONE Application Server show in practice, how Ant can be used in various ways, and provide 'library-scripts' to simplify creation. The documentation for the samples can be found in {Sun ONE_application_server}/samples/docs/ant.html, or you can consult the Ant online documentation.

How do I deploy my EAR file?

The best place to start is the Sun ONE Application Server 7 Developers Guide, Assembling and Deployment section.

I get errors that refer to my deployment descriptor but it looks fine...

One suggestion is to check that your entries do not contain any 'rogue' characters such as tabs, spaces or unwanted line breaks.

We want to migrate our J2EE platform application to the Sun ONE Application Server?

Take a look at this migration tool; it allows users to migrate from many application servers. It also supports Sun ONE Studio developer tools, Borland's JBuilder, or can be run as a standalone application.

What options are there to create or modify J2EE platform applications with Sun ONE Application Server?

You may want to try the Sun ONE Studio IDE or the purpose-built lightweight Sun ONE Application Server 7 Assembly Tool.

Questions and Answers

Many resources talk about EAR files; each contain there own "value-add". Following are some topics of interest to assist in locating answers.

Where can I find the DTDs for J2EE?

For J2EE 1.2 see http://java.sun.com/j2ee/dtds/.
For J2EE 1.3 see http://java.sun.com/dtd/.

When deploying, the verifier warns that deployment descriptor elements are not found where they should be...

Observe the DTDs for the XML; you should make sure that the elements are in the correct order.

Where can I find a graphical view of the DTDs?

In the J2EE Platform Specification.

We are having classpath/classloader issues or conflicts...

Check out this graphical view of The Classloader Heirarchy.

We also want servlets and JavaServer Pages (JSPs) to be able to access the EJBs...

In this scenario you will need to copy/extract the appropriate, generated client .jar file from the deployed EJB module into the appropriate classloader directory, and if necessary, restart the application server.

I've created a J2EE software application using Sun ONE Studio software, but changes in the added components are not reflected in the application...

You will need to remove and add the component again to ensure that your J2EE software application is updated with the latest changes.


sun.com \| 1-800-123-4000	How To Buy \| My Sun \| Worldwide Sites

Dissecting EARs - Enterprise ARchive (.ear) Files