Chapter 3. Applications

Element	Description
<role-permission>	A Principal-role mapping used by an application. This setting is applied to all modules of an application.
<java-security-permission>	Permissions used by an application, if the J2SE security manager is used.

3.1. Modules and Applications

A Java EE application consists of one or more modules. A Java EE module consists of one or more Java EE components (such as EJB web applications, application clients, and connectors) with the same type and deployment descriptors (DD).

There are two types of deployment descriptors: Java EE standard DD, such as application.xml, and JEUS DD, such as jeus-application-dd.xml. Starting with Java EE 5, for most configurations, standard DD can be replaced by annotations that are specified in classes.

The following figure shows configurations of Java EE modules and applications:

[Figure 3.1] Java EE Modules and Applications

3.1.1. Modules

There are four types of Java EE modules as follows:

EJB module (.jar file)

Enterprise JavaBean (EJB) is a standard server side component model, that implements business logic using transactions and security services. The role of an EJB module is to give access to and group the EJBs. In JEUS, EJB is the smallest unit that can be deployed to a JEUS EJB engine.

Therefore, even when only one EJB is deployed, the EJB must be packaged as an EJB module (.jar file). For detailed information about EJB modules, refer to "JEUS EJB Guide".
Web application module (.war file)

A web module consists of static and dynamic contents of web-based services that are executed by a client request. Examples of web-based services are adding a product to a shopping cart, buying a product in the shopping cart through an online shopping site, or browsing products for purchase through a web-based auction site.

For detailed information about web application modules, refer to "JEUS Web Engine Guide".
Application client module (.jar file)

An application client module is a client program executed in a JVM. This module can be executed by calling the main() method, and it ends when the virtual machine terminates.

Like other Java EE application components, an application client module operates in a client container, that provides system services. Client containers use a very small amount of system resources compared to other Java EE containers.

For detailed information about the application client modules, refer to "JEUS Application Client Guide".
Resource adapter module (.rar file)

A resource adapter is the main component of Java EE connector architecture. It is developed for a specific enterprise information system (EIS) and provides the APIs to interact with EIS and system APIs to integrate with Java EE application servers. To accomplish this, a JEUS administrator only needs to set and deploy a resource adapter.

For detailed information about resource adapter modules, refer to "JEUS JCA Guide".

3.1.2. Applications

As shown in [Figure 3.1], a Java EE application consists of one or more Java EE modules and two deployment descriptors, Java EE DD (application.xml) and JEUS DD (jeus-application-dd.xml).

A Java EE application is a JAR archive file with the extension, '.ear'. The following figure shows a simple example of an EAR file. Each module's archive files, the lib directory, and the META-INF directory reside in the root directory.

[Figure 3.2] .ear Archive

Descriptions for each directory are as follows:

lib: The lib directory is a common library directory of EAR applications. Library files with the extension '.jar' are under this directory. The library files can be used, after being automatically added to the class path by a sub-module of an EAR application. This directory can be replaced by configuring a setting to use a different directory.

Starting with Java EE 5, library directory is supported, which can be set with the <library-directory> tag in the application.xml file, which is the standard DD for EAR applications. If the application.xml file does not exist, or the <library-directory> tag is not set in the application.xml file, the lib directory will be used by default.

Note

The APP-INF directory, which is supported starting with JEUS 5, provides functions which are similar to those of the WEB-IF directory for web application modules. Similar to the WEB_INF directory, the APP-INF directory includes the subdirectories, named classes and lib, and they contain classes and '.jar' files, respectively.

The class and '.jar' files can be used as a library by the corresponding application. However, starting with JEUS 6, it is recommended to use a library directory instead of the APP-INF directory.
META-INF: Includes two deployment descriptors: application.xml, Java EE DD, and jeus-application-dd.xml, JEUS DD. These files are optional. Other than the two DDs, this directory contains the MANIFEST.MF file, which can be used to specify information and classpath of the archived EAR file.

3.2. Deployment Descriptor(DD)

A Java EE application is released in the Enterprise ARchive (EAR) file format with the extension .ear.

An EAR file includes an EJB module (.jar), a web application module (.war), an application client module (.jar), a resource adapter module (.rar), and other necessary Java classes. A standalone module, that consists of a single module, is also considered as a type of Java EE application. To start an application for service, the process of uploading the application module files to JEUS and controlling them is called Deployment.

To create a module or an application, to be distributed to an application server, the deployment descriptors, Java EE standard DD and JEUS DD, are required.

Note

Since all settings in standard DD can now be expressed using annotations, standard DD and JEUS DD for EJB modules and EAR files, can be omitted, starting with JEUS 6, which complies with Java EE 5. Standard DD and JEUS DD for the Web application modules can be omitted in JEUS 7, which complies with Java EE 6.

The following table shows deployment descriptors necessary for each module and application:

[Table 3.1] Deployment Descriptors for Each Module

	Java EE Standard DD	JEUS DD
Application	application.xml	jeus-application-dd.xml
EJB module	ejb-jar.xml	jeus-ejb-dd.xml
Web application module	web.xml	jeus-web-dd.xml
Application client module	application-client.xml	jeus-client-dd.xml
Resource adapter module	ra.xml	jeus-connector-dd.xml
Web service	webservices.xml	jeus-webservices-dd.xml

As a module has a separate JEUS DD as well as Java EE standard DD, there exists the jeus-application-dd.xml file for each application descriptor. This file is placed in the META-INF directory of the EAR, and is used to configure additional application settings. If this file does not exist in the EAR or Standalone modules, the application will be deployed using the default settings.

Note

For detailed information about Java EE standard DD, refer to Java EE 7 specifications. For detailed information about JEUS DD, refer to each relevant JEUS guides.

When an application is deployed, information in jeus-application-dd.xml file is used to configure the environment, where the application will run in.

Descriptions of the <application> tag in the jeus-application-dd.xml file are as follows:

Security settings

The following security related settings apply to an application. For detailed information about each element, refer to "JEUS Security Guide".

Element Description
<role-permission> A Principal-role mapping used by an application. This setting is applied to all modules of an application.
<java-security-permission> Permissions used by an application, if the J2SE security manager is used.
Library settings

Using a shared library in an application requires the following setting. For detailed information about each element, see "3.3.2. Shared Library".

Element Description
<library-ref> Shared library used by an application.
Java EE namespace related settings

Information about namespaces to be used by an application can be specified in the application.xml file or in the annotations. Mapping information about the namespaces can be specified in the jeus-application-dd.xml file. The information can be replaced by annotations. For detailed information about the naming convention, refer to Java EE 7 specifications. For detailed information about namespace related settings, refer to "Chapter 23, jeus-application-dd.xml Configuration" in "JEUS XML Reference".

Element	Description
<library-ref>	Shared library used by an application.

3.3. Application Libraries

This section describes how to add and use the application library, lib/application, and a shared library.

3.3.1. The lib/application Directory

The application library, lib/application, is shared among applications. It is distinguished from the system library, JEUS_HOME/lib/system that is added to JEUS system.

The system library includes libraries used by the system. The application library contains libraries, used in classes defined by applications or users. The libraries contain a function to manage the server lifecycle, a user logger, logger filter, logger formatter, etc. The classes do not reference libraries in the application library. The libraries are shared among applications by placing them in the lib/application directory.

Because libraries in lib/application can be shared by applications, a user does not need to include the libraries when packaging applications. Libraries in lib/application are usually used by all the applications in a domain or a server. A library can be a .jar file or .class file.

Caution

If the same libraries with different versions are installed in lib/application, an application may not be able to use the desired library. To prevent this, use shared libraries for which a version to be used by an application can be specified. For more information about shared libraries, see "3.3.2. Shared Library".

The lib/application directory can be placed in both the DOMAIN_HOME and SERVER_HOME directories.

Libraries shared by an entire domain are located in the DOMAIN_HOME/lib/application directory. To transfer an application library installed on a domain to a server on a separate machine, create a domain on a separate machine with the pack-domain command to copy the existing DOMAIN_HOME/lib/application directory to the machine. If the libraries are added or modified after the domain is created, they should be manually synchronized by the user.

Libraries that are used only by a specific server are located in the SERVER_HOME/lib/application directory. The libraries should be manually copied to this directory.

Note

If needed, manually create the SERVER_HOME/lib/application directory to place the libraries, since the directory is not created when installing JEUS.

Class Loading Method

Classes in the application library, lib/application, are loaded by the JEUS root class loader. The classes can be used by all the applications deployed on the server.

Classes in the system library, JEUS_HOME/lib/system, are also loaded by the JEUS root class loader, but the system library resides in a directory that a user cannot access. However, since the application library is a directory meant to be referenced by the user, it can be accessed by the user.

Note

For detailed information about a server's class loader, refer to JEUS Server Guide. "1.4. Class Loader Structure".

Application libraries are placed in the SERVER_HOME and DOMAIN_HOME directories.

The SERVER_HOME/lib/application directory is first added to the classpath of the class loader, and then the DOMAIN_HOME/lib/application directory is added. If a library already exists in both the SERVER_HOME and DOMAIN_HOME directories, the library in the SERVER_HOME directory will be loaded, and the library in the DOMAIN_HOME directory will be ignored.

If a library with a name, that is already used by another library in the class loader, is added, the following warning message will be displayed when the server boots:

Warning [same classpath-name] : [JEUS_HOME/domains/domain1/servers/adminServer
/lib/application/applib.jar] is registered earlier than 
[JEUS_HOME/domains/domain1/lib/application/applib.jar] in JEUSClassLoader.

Note

The previous log message is displayed when lib/application is added to the JEUS root class loader, using a classpath, in the class loader configuration step. This step is the first step in booting a server and is processed before a server logger is configured. Therefore, the message should be checked with the launcher logs.

Application libraries can be used in applications, as well as in all cases when a special class can be configured in the server, including server lifecycle call function, user logger, log message filter class, log message formatter class, etc. Since the special classes do not have reference to the libraries in the application library, they must be placed in the lib/application directory.

3.3.2. Shared Library

Shared libraries are shared among the applications, and are distinguished from the JEUS system library, JEUS_HOME/lib/system, and the application libraries, DOMAIN_HOME/lib/application and SERVER_HOME/lib/application.

Shared libraries do not affect the entire JEUS system. Each application can specify which shared libraries it will use. Shared libraries can be dynamically added, without restarting JEUS, and can be used selectively when different versions of the libraries are installed.

Shared libraries have the following characteristics:

Because a shared library can be shared among applications, the user does not need to consider the library when packaging applications.
A shared library can be dynamically added and removed even when a server is running.
A shared library can be upgraded by adding a new library and redeploying the applications.
Multiple versions of implementation classes, in the shared library, can be registered, and during deployment, one can be selected for use.

Because there can be two versions of a library, a specification version and an implementation version, the user can install multiple versions of the same library. A version, highest, minimum, or exact, required by an application, can be selected dynamically during deployment.

To support the multiple versions of a library, it is recommended to specify a version for use. If a version is not specified, the default version, 0, will be internally used. A version may not be used at all, for simple use cases.

Deploying and Setting Libraries

A library consists of multiple JAR files, which are usually located in the shared library directory, JEUS_HOME/lib/shared. The JAR files are registered in the configuration file, JEUS_HOME/lib/shared/libraries.xml, as follows:

In the following example, myLibrary is registered as the implementation class 2.1, which implements the myLibrary 2.0 specification. This library consists of multiple JAR files: commons-logging.jar, commons-util.jar, and all JAR files under the myLib -2.1 directory.

[Example 3.1] Registering Shared Libraries: <<libraries.xml>>

<library>
     <library-name>myLibrary</library-name>
     <specification-version>2.0</specification-version>
     <implementation-version>2.1</implementation-version>
     <files dir=".">
         <include name="commons-logging.jar"/>
         <include name="commons-util.jar"/>
     </files>
     <files dir="myLib-2.1"/>
</library>

Descriptions for each tag are as follows:

<library-name>, <specification-version>, <implementation-version>

Used when an application references a specific library.
<*-version> fields can be used, when multiple versions of the same library are used.

<files>

Sets a classpath of an actual library in multiple ways as follows:

[Example 3.2] The <files> Tag for Shared Libraries

<files dir="."> <include name="a.jar"/> <include name="b.jar"/> </files> <files dir="testa"/> <files dir="/home/works/lib/testc" /> <files dir="/home/works/lib/testd" mode="classes"/>

dir is a directory, which can be the JAR files directory or the classes directory. A relative or an absolute path can be used. If dir is a relative path, the base directory is JEUS_HOME/lib/shared.

The <include> child tag specifies the JAR files to be included. If this tag is not set, all JAR files in the corresponding directory will be included. JAR files, in the directory, will be searched for during deployment. Therefore, JAR files can be added to this directory without making any changes to the settings. To specify the classes directory, not JAR files, set the mode to 'classes'.

The libraries can be dynamically added while JEUS is running, because if the settings are changed while a new application is deployed, the settings will be read again. Therefore, a new library or an updated library can be added without rebooting JEUS.

Caution

The previously described settings should be modified in the corresponding XML file. In JEUS 6, the settings can be modified using the WebAdmin, but in JEUS 7, the WebAdmin cannot be used to modify these settings.

Referencing Libraries from an Application

Java EE applications and standalone modules can use the registered shared libraries, with entries in jeus-application-dd.xml, jeus-web-dd.xml, and jeus-ejb-dd.xml files.

The following example references the shared library, 'myLibrary':

<library-ref>
     <library-name>myLibrary</library-name>
</library-ref>

In the previous example, when an application is deployed, it searches for the library 'myLibrary' and adds the corresponding classpath to the application classpath. If there are multiple versions of 'myLibrary', the latest version will be selected. If a version of a library to be referenced is not specified, the latest version will be used according to Section 3.3.2, “Version Ordering Rule”.

The following example uses the earliest version:

<library-ref>
     <library-name>myLibrary</library-name>
     <specification-version>2.0</specification-version>
     <implementation-version>2.0</implementation-version>
</library-ref>

The following example uses an exact version:

<library-ref>
     <library-name>myLibrary</library-name>
     <specification-version exact-match="true">2.0</specification-version>
     <implementation-version exact-match="true">2.1</implementation-version>
</library-ref>

To only specify an exact specification version, set as follows. In this case, the application searches for the latest implementation version of the corresponding specification:

<library-ref>
     <library-name>myLibrary</library-name>
     <specification-version exact-match="true">2.0</specification-version>
</library-ref>

If a referenced library is not found during deployment, a WARNING log message will be displayed, but the deployment will continue to be processed. To discontinue the deployment and make it fail, set the 'failonerror' attribute as follows:

<library-ref failonerror="true">
     <library-name>myLibrary</library-name>
</library-ref>

Class Loading Method

Shared library class is loaded by an application class loader or a module class loader, depending on where the library reference is defined.

For example, if 'lib1' is defined in jeus-application-dd.xml as a reference, it will be loaded by an application class loader. If it is defined in jeus-web-dd.xml as a reference, it will be loaded by a web-level class loader.

A class or a library loaded by an application class loader is isolated in the corresponding application. That is, the class instance is not shared with other applications.

Note

For detailed information about a server's class loading methods, refer to JEUS Server Guide. "1.4. Class Loader Structure".

Version Ordering Rule

A version is made up of a fraction part and a non-fraction (string) part. For example, the version "6.2.3-b12" consists of <fraction_part>(6.2.3) and <string(non-fraction)_part>(-b12)

Version ::= <fraction_part> | <string_part> | <fraction_part> <string_part>
fraction_part ::= <integer> | <integer> "." <fraction_part>
string_part ::= <non-numeric> <character>*

The ordering rule of a version is as follows:

Numbers in <fraction part> are compared numerically, in the order of major and minor.
If numbers in <fraction part> are identical, strings in <string part> will be compared.

The following shows the versions that are ordered according to the ordering rule:

6.0 < 6.2.3 < 6.2.3-b12 < 6.2.3-beta < 6.2.4

Prev		Next
Chapter 2. Graceful Undeployment and Redeployment	Home	Chapter 4. Application Implementation and Deployment