Table of Contents
This chapter describes configuration of modules and applications, their components, and how to configure the components. It also explains JEUS functions for application deployment.
A Java EE application consists of one or more modules. A Java EE module consists of one or more Java EE components (EJB web applications, application clients, and connectors) of a type and deployment descriptors (DD).
There are two types of deployment descriptors: Java EE standard DD (application.xml) and JEUS DD (jeus-application-dd.xml). For Java EE 5 and later, most configurations in the standard DD can be replaced with annotations.
The following figure shows configurations of Java EE modules and applications:
There are four types of Java EE modules as follows:
-
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".
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.
The following describes each directory:
- 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.
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:
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 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".
-
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".
-
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".
-
Classloading Settings
The sequence of loading the libraries included in an EAR application can be configured. By default, classes are loaded from the parent class loader in the Java class loader. However, there may be a situation that the libraries included in an application need to be loaded before the parent library depending on the application setting. In such case, the sequence of loading classes can be changed.
This section describes how to add and use the application library (lib/application), and a shared library. It also describes library deployment, which is a new feature added to JEUS 8.
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 life cycle, 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.
Note
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 life cycle 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.
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.
Installing 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.
Note
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 and later versions, 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>
<value>2.0</value>
</specification-version>
<implementation-version>
<value>2.0</value>
</implementation-version>
</library-ref>
The following example uses an exact version:
<library-ref>
<library-name>myLibrary</library-name>
<specification-version>
<value>2.0</value>
<exact-match>true</exact-match>
</specification-version>
<implementation-version>
<value>2.0</value>
<exact-match>true</exact-match>
</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>
<value>2.0</value>
<exact-match>true</exact-match>
</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>
<library-name>myLibrary</library-name>
<failon-error>true</failon-error>
</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 "1.4. Class Loader Structure" in "JEUS Server Guide."
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
JEUS 8 provides the library deployment feature that allows users to manage libraries by using DAS.
Users can deploy a library to a domain by using a console tool or WebAdmin and then configure an application to reference the library. This deployment and reference function minimizes class conflicts that can occur when multiple applications reference different versions of one library.
The advantages of library deployment are as follows.
-
Users do not need to have a library included in each application for packaging. This resolves inconvenience that users must perform packaging for all applications that use the same library. It also resolves resource usage problems that are caused when the same class is loaded by multiple applications.
-
Users can specify a library to use when deploying an application. To deploy the same library to multiple applications, the library can be set with different versions for each application.
Major Functions
Installation and deployment are required to use a library in applications. The functions provided to deploy a library are as follows.
-
Library Installation
Install a library to deploy in the domain directory of the server in which DAS is installed. Installation is performed through a console command or WebAdmin. The information required for installation are as follows.
Information Description Library Identifier (ID) Name of a library to deploy, delete, or reference. This must be unique in a domain. If this option is not set, installation is not proceeded. Library Version Version of library to install. If not set, the version is deemed to be 1.0. Library Path Path to the library to install. If not set, installation is not proceeded. After the installation completes, the library files are located under DOMAIN_HOME/.libraries/LIBRARY_ID/VERSION.
Note
The information about the installed libraries are not stored in domain.xml. DAS will search the directories of DOMAIN_HOME/.libraries if library installation status needs to be identified. It is not recommended to change the directory.
-
Library Deployment
An installed library can be deployed using console commands or WebAdmin. Specify a server or cluster to use the library. All servers can be specified. When deployment completes successfully, DAS saves the changes in domain.xml to maintain library installation status when it is restarted.
-
Library Undeployment
A library can be undeployed using console commands or WebAdmin when it is no longer used. When undeployment completes, DAS removes the information about the undeployed library from domain.xml. The library file itself is maintained.
-
Library Uninstallation
A library file can be deleted using console commands or WebAdmin.
This section describes how to install and delete a library using WebAdmin and a console tool.
Using WebAdmin
Click [Applications] on the left of WebAdmin to navigate to the screen in order to manage applications and libraries. A library can be installed and deleted in this screen.
Using the Console Tool
The following describes how to install and delete a library using a console tool jeusadmin.
-
Checking the information about installed libraries
View the list of installed and deployed libraries using the library-info command.
[DAS]domain1.adminServer>library-info Library information ================================================================================ +-----------+--------+-------+---------------+-------------------+-------------+ | Library ID| Version| State | Target Servers| Target Clusters | Applications| +-----------+--------+-------+---------------+-------------------+-------------+ (No data available) ================================================================================ [DAS]domain1.adminServer> -
Installing a library
Install a library using the install-library command. Library ID and path must be entered. Otherwise, installation is not proceeded.
[DAS]domain1.adminServer>install-library log4j -path /usr/lib/apache-log4j-1.2.17/log4j-1.2.17.jar -version 1.2.17 Successfully installed the library [log4j] version [1.2.17]. [DAS]domain1.adminServer>library-info Library information ================================================================================ +-----------+--------+----------+--------------+------------------+------------+ | Library ID| Version| State | Target | Target Clusters | Applicatio | | | | | Servers | | ns | +-----------+--------+----------+--------------+------------------+------------+ | log4j | 1.2.17 | INSTALLED| | | | +-----------+--------+----------+--------------+------------------+------------+ ================================================================================ [DAS]domain1.adminServer>
-
Deploying a library
Deploy a library using the deploy-library command. Specify a server, cluster, or all servers to use the library for deployment.
[DAS]domain1.adminServer>deploy-library log4j -servers adminServer deploy the library [log4j] succeeded. [DAS]domain1.adminServer>library-info Library information ================================================================================ +-----------+--------+--------+---------------+------------------+-------------+ | Library ID| Version| State | Target Servers| Target Clusters | Applications| +-----------+--------+--------+---------------+------------------+-------------+ | log4j | 1.2.17 | RUNNING| adminServer | | | +-----------+--------+--------+---------------+------------------+-------------+ ================================================================================ [DAS]domain1.adminServer>
-
Undeploying a library
Undeploy a library using the undeploy-library command if it is no longer used. Undeployment does not cause any functional issue of the server. However, it may require unnecessary tasks such as library synchronization when the server is restarted.
[DAS]domain1.adminServer>undeploy-library log4j undeploy the library [log4j] succeeded. [DAS]domain1.adminServer>library-info Library information ================================================================================ +-----------+--------+----------+--------------+------------------+------------+ | Library ID| Version| State | Target | Target Clusters | Applicatio | | | | | Servers | | ns | +-----------+--------+----------+--------------+------------------+------------+ | log4j | 1.2.17 | INSTALLED| | | | +-----------+--------+----------+--------------+------------------+------------+ ================================================================================ [DAS]domain1.adminServer>
-
Deleting a library
Remove a library from the domain using the uninstall-library command. A deployed library cannot be deleted. Undeployment must be performed first to delete a library.
[DAS]domain1.adminServer>uninstall-library log4j uninstall the library [log4j] succeeded. : Successfully deleted [log4j]. [DAS]domain1.adminServer>library-info Library information ================================================================================ +-----------+--------+-------+---------------+-------------------+-------------+ | Library ID| Version| State | Target Servers| Target Clusters | Applications| +-----------+--------+-------+---------------+-------------------+-------------+ (No data available) ================================================================================ [DAS]domain1.adminServer>
When deploying an application, a library to reference can be specified. Specify the ID and version of a library to deploy it through WebAdmin. If a version is not set, it is deemed to use the latest version of the library.
A deployer performs tasks that enable applications to reference a library based on the specified information. The information about the library referenced by applications is saved in domain.xml, same as other deployment information.
Using WebAdmin
Specify a library to use in a deployment setting window.
Using the Console Tool
Specify the identifier and version of a library to reference when executing the deploy-application command.
[DAS]domain1.adminServer>deploy-application sample -lib log4j -version 1.2.17 -servers adminServer deploy the application for the application [sample] succeeded. [DAS]domain1.adminServer>library-info Library information ================================================================================ +-----------+--------+--------+---------------+------------------+-------------+ | Library ID| Version| State | Target Servers| Target Clusters | Applications| +-----------+--------+--------+---------------+------------------+-------------+ | log4j | 1.2.17 | RUNNING| adminServer | | sample | +-----------+--------+--------+---------------+------------------+-------------+ ================================================================================