Understanding the GlassFish deployment structure
In this section, we will get familiar with the GlassFish Server's overall directory structure, and then dive into the administrative domain to explore the GlassFish configuration files.
The directory structure of GlassFish
The essential directory structure of a GlassFish installation is illustrated in the following screenshot. The purpose and content of these directories are discussed in the following section.
The bin directory contains important executable scripts for the GlassFish. For example, the asadmin script is the primary command line (CLI) administrative tools for GlassFish. You have used asadmin to start and stop the GlassFish Server earlier in the chapter, and a detailed discussion of the capability of asadmin will be given in the next chapter.
The config directory contains two configuration scripts that define the GlassFish system environment information. For example, the asenv script captures the GlassFish installation environment, such as the location of the JDK software.
The imq directory contains the server binary of the OpenMQ software. OpenMQ is a high performance JMS provider, and we will discuss OpenMQ later in this book.
The jbi directory contains the Java Business Integration (JBI) runtime environment that is integrated with the GlassFish Server.
The directory javadb contains a distribution of the Java DB Database system based on the Apache Derby project. Java DB provides a small and pure Java implementation of a Relational Database System (RDBMS). It can be used as an embedded persistent and relational data store. In fact, the GlassFish timer service and call flow monitoring feature both use the embedded Java DB for data storage. Java DB is also suitable for prototyping and small scale deployment.
The lib directory contains the system level library files. For example, it contains the GlassFish's runtime library appserver-rt.jar, and the Java EE standard libraries, javaee.jar. These libraries are loaded by the GlassFish's system class loader to provide the core runtime environment of the GlassFish Server. Furthermore, the lib directory also contains a dtds sub directory that stores the XML DTD and schema definitions for Java EE, GlassFish deployment descriptors.
Finally, the updatecenter directory contains the updatetool utility of GlassFish. The other two directories, docs and samples contain some GlassFish quick start documentation and very simple application samples. The complete GlassFish documentation is available at http://docs.sun.com/app/docs/prod/gf.ent.svr, and you can download the Java EE sample and blueprint applications from http://java.sun.com/javaee.
The last, and maybe the most important directory for administrators, domains, is discussed in the following section.
Understanding Glassfish administrative domains
A domain maintains its own collection of configuration files, security settings, deployed applications, and runtime log files.
Multiple domains can be created for a single GlassFish installation. While this approach may not be very common, it can be very helpful in a hosting environment for the following reasons:
- It is easy to maintain and update a single GlassFish Server installation.
- A domain provides a runtime environment that is independent of other domains. For example, when a domain is shut down, other domains are not affected. You can take advantage of this feature by using a domain to host applications for a separate organization.
- Domains do not share administration information. This allows you to delegate the domain administration responsibilities to different administrators.
When you install GlassFish, a default domain, domain1 is created. This domain has a single server instance that provides both administrative and application services. In this section, we examine the structure and configuration information of this domain, and get familiar with some of the most important configuration files of GlassFish.
The directory structure of the default domain, domain1 is illustrated in the following figure.
In the screenshot, the directory domain1 corresponds to the domain root directory for domain1. In GlassFish, each domain corresponds to a directory with the same name as the domain. By default, all the domains are created under the domain root directory $AS_INSTALL/domains, where $AS_INSTALL is the GlassFish installation directory.
The content of each directory under domain1 is as follows:
- The applications directory contains Java EE applications deployed to the GlassFish Server.
- The autodeploy directory allows you to automatically deploy applications by simply copying the application archive file to this directory.
- The lib directory contains directories that contribute to the common classpath of the domain and applications deployed to it. It also contains an embedded Java DB database that is used as the default data store for the EJB timer service.
- The config directory contains all the configuration files for the domain. It is critical to have a good understanding of these files to be able to administer and configure the GlassFish Server.
- The docroot directory contains the default static content. Upon installation, there is only one file,
index.htmlrepresenting the default page for GlassFish. - The logs directory contains the GlassFish Server log files.
We will discuss the applications, autodeploy, and lib directories in detail in the next chapter, because these directories are highly relevant to applications you deploy to the GlassFish Server. Now, let's examine the config directory more closely to get familiar with essential configuration files for the domain.
Exploring essential domain configuration files
The config directory contains the following configuration files:
domain.xml:This is, by far the most important configuration file of the GlassFish Server. It describes the overall configuration structure and information about the domain, and it contains nearly all the settings associated with the domain. Due to this, most of the configuration changes made to the domain will result in an update of this file.default-web.xml:This file specifies the default values for parameters not explicitly configured in deployed applications. This file also defines the default web components shipped with the GlassFish Server, and the Multipurpose Internet Mail Extension (MIME) type mappings for static content served by the server.keyfileandadmin-keyfile:These files store the encrypted user passwords for application users and administrators. They provide the default user authentication realms for the GlassFish Server.login.conf:This file specifies the authentication realms information for the administrative domain.server.policy:This file specifies the security policies for Application Server components.keystore.jksandcacerts.jk:Thekeystore.jksfile stores the server certificate and its private keys, andcacerts.jksstores the certificates that are trusted by the server. These two files are related to enabling SSL/TLS and certificate-based authentication for GlassFish.domain-passwords:This file stores the encrypted passwords used in configuring the domain.
You may see several other files under the config directory. For example, the secure.seed file contains a secure random seed, and the seed value is reset on each server start. Those files are temporary, and it is very unlikely that you need to work with those files.
Now, let's study the primary configuration file, domain.xml.
The domain.xml file captures most of the configuration information about the GlassFish Server. The detailed structure of domain.xml is documented in the GlassFish Server Administration References located at http://docs.sun.com/app/docs/doc/820-4338. This book provides a high-level explanation of essential elements of the domain.xml file to help you get familiar with GlassFish Server quickly.
The structure of the domain.xml is defined by an XML DTD file defined in the $AS_INSTALL/lib/dtds/sun-domain_1_x.dtd. The high level element hierarchy of the domain.xml file is illustrated in the following figure. In this figure, unless explicitly noted, the multiplicity of child elements is many. For example, the application element may contain multiple engine elements. The config element is highlighted, because of its complexity. The rest of this book more or less focuses on working with the GlassFish Server configuration captured in the config element.
The root element of the hierarchy domain defines a GlassFish administrative domain. The top level child elements of domain are described as follows:
- The applications elements describe the applications deployed in the GlassFish Server. Typically, system applications are bundled with the GlassFish Server, such as the Admin Console web application. On the other hand, applications you developed and deployed to GlassFish are typically considered as user applications. Each deployed application is described by a distinct application element. The engine child element of application is used to specify appropriate sniffers to identify the type of the application, and appropriate containers and services that should be used to run the application.
- The resources element describes JDBC resources configured for the domain, including both JDBC connection pools and data sources. We will discuss how you can configure different types of resources later in this book.
- The configs element contains one or multiple config element. Each config element defines a collection of services and other settings. These services together define the behavior of a runtime server instance. The configuration of these services will be covered throughout this book.
- The servers element contains one or multiple server elements. Each server element defines a server instance. Each server element contains an attribute that provides a reference to a config defined in the
domain.xmlfile. Furthermore, the server element uses its resources-ref and application-ref elements to identify necessary applications and resources to be supported by the server instance at runtime. - Finally, the system-property element can be applied to domain, server, and config elements. A system-property essentially defines a variable in the corresponding scope (from high to low levels, domain, server or config), and the value of this property can be referenced using the notation
${prop-name}. Furthermore, a system property defined at a lower level can overwrite the value defined at a higher level.
As the domain.xml file is plain XML, you can edit it using a text editor to make GlassFish Server configuration changes. However, manually modifying the domain.xml file is strongly discouraged, because it is too easy to make a typo, which can potentially render the GlassFish Server corrupted. We will see shortly that GlassFish provides several user-friendly tools which can be used to configure the server.