Specifying an Embedded GlassFish Server File System

Specifying an embedded file system for an embedded GlassFish Server is optional. What you don't specify is created automatically and used transparently by the server. An embedded file system enables you to do the following:

• To use the configuration information of an existing installation of GlassFish Server

• To control where embedded GlassFish Server creates its configuration directories

• To specify a configuration file, which controls how embedded GlassFish Server functions

To specify an embedded file system for embedded GlassFish Server, perform these tasks:

1. Instantiate the org.glassfish.api.embedded.EmbeddedFileSystem.Builder class.

2. Invoke any methods for configuration settings that you require. This is optional.

3. Invoke the build method to create an EmbeddedFileSystem object.

If you are including the glassfish-embedded-static-shell.jar file in your class path, the methods of the EmbeddedFileSystem.Builder class can only point to the referenced installation. These methods cannot create or delete any directories or files.

The methods of the EmbeddedFileSystem.Builder class for setting the embedded file system configuration are listed in the following table. The default value of each configuration setting is also listed.

Purpose	Method	Default Value
Creates an embedded file system builder	EmbeddedFileSystem.Builder()	None
Deletes embedded file system files when the server is stopped  Caution – Do not set autoDelete to true if you are using installRoot to refer to a preexisting GlassFish Server installation.	autoDelete(boolean enabled)	false
Creates a new or references an existing Installation Root Directory	installRoot(java.io.File install-root)	In order of precedence:  glassfish.embedded.tmpdir system property value user.dir system property value Current directory
Creates or references an Installation Root Directory in which the embedded server and file system use different class loaders if cooked-mode is false	installRoot(java.io.File install-root, boolean cooked-mode)	Same as the other installRoot method, cooked-mode is true
Creates a new or references an existing Instance Root Directory	instanceRoot(java.io.File instance-root)	as-install/domains/domain1
Creates a new or references an existing configuration file	configurationFile(java.io.File config-file)	domain-dir/config/domain.xml
Creates or references a configuration file that is read-only if read-only is true	configurationFile(java.io.File config-file boolean read-only)	domain-dir/config/domain.xml, read-only is false
Creates an embedded file system	build()	None

Example 2 Creating an Embedded File System

This example shows code for creating an embedded file system whose configuration information is stored in the file C:\samples\test\applicationserver\domains\domain1\config\domain.xml. This example also includes the code from Example 1 for creating Server.Builder and Server objects.

...
import java.io.File;
...
import org.glassfish.api.embedded.*;
...
    File installDir = new File("c:\\samples\\testapp\\applicationserver");
    File domainDir = new File(installDir, "domains\\domain1");
        ...
    File domainConfig = new File(domainDir, "config");
    File domainXml = new File(domainConfig, "domain.xml");
    ...
    Server.Builder builder = new Server.Builder("test");
    ...
    EmbeddedFileSystem.Builder efsb = new EmbeddedFileSystem.Builder();
    efsb.installRoot(installDir);
    efsb.instanceRoot(domainDir);
    efsb.configurationFile(domainXml);
    EmbeddedFileSystem efs = efsb.build();
    builder.embeddedFileSystem(efs);
    ...
    Server server = builder.build();
...

Installation Root Directory

The installation root directory, represented as as-install, is the parent of the directory that embedded Oracle GlassFish Server uses for configuration files. This directory corresponds to the base directory for an installation of GlassFish Server. Configuration files are contained in the following directories in the base directory for an installation of GlassFish Server:

• domains

• lib

Specify the installation root directory if any of the following conditions applies:

• You require Oracle GlassFish Server to create the directory for configuration files at a specific location.

• You are using an existing domain that is at the default location, that is contained in the domains subdirectory of the installation root directory. The domains subdirectory must contain only one domain directory. This domain can be part of a nonembedded installation of Oracle GlassFish Server.

  If the domains subdirectory contains multiple directories, or if you are using a domain at a non-default location, you must also specify the instance root directory.

If the instance root directory is also specified, configuration files for the domain are obtained from the instance root directory, not the domains directory under the installation root directory.

How embedded Oracle GlassFish Server uses the installation root directory depends on the content of this directory:

• If the installation root directory contains domain configuration files, embedded Oracle GlassFish Server reads the configuration files.

• If the installation root directory does not contain domain configuration files, embedded Oracle GlassFish Server copies configuration files into this directory.

• If the installation root directory does not exist, embedded Oracle GlassFish Server creates the directory and copies configuration files into the directory.

If the installation root directory is not specified, embedded Oracle GlassFish Server creates a directory named gfembedrandom-numbertmp in the current working directory, where random-number is a randomly generated 19-digit number. Embedded Oracle GlassFish Server then copies configuration files into this directory.

Instance Root Directory

The instance root directory, represented as domain-dir, is the parent directory of a server instance directory. Embedded Oracle GlassFish Server uses the server instance directory for domain configuration files.

Specify the instance root directory if any of the following conditions applies:

• You are using a domain directory that is at a non-default location, that is not contained in the domains subdirectory of the installation root directory.

  For example, if your domain directory is at /tmp/domain1, specify the instance root directory as /tmp/domain1.

• The domains subdirectory of your installation root directory contains multiple domain directories.

  For example, the domains subdirectory of the /home/gfuser/glassfish installation root directory might contain the domain directories domain1 and domain2. To use the domain directory domain2, specify the instance root directory as /home/gfuser/glassfish/domains/domain2.

How embedded Oracle GlassFish Server uses the instance root directory depends on the content of this directory:

• If the instance root directory contains domain configuration files, embedded Oracle GlassFish Server reads the configuration files.

• If the instance root directory does not contain domain configuration files, embedded Oracle GlassFish Server copies configuration files into this directory.

• If the instance root directory does not exist, embedded Oracle GlassFish Server creates the directory and copies configuration files into the directory.

If the instance root directory is not specified, embedded Oracle GlassFish Server uses the domains subdirectory of the installation root directory for domain configuration files.

Using an Existing domain.xml File

Using an existing domain.xml file avoids the need to configure embedded GlassFish Server programmatically in your application. Your application obtains domain configuration data from an existing domain.xml file. You can create this file by using the administrative interfaces of an installation of nonembedded GlassFish Server. To specify an existing domain.xml file, invoke the installRoot, instanceRoot, or configurationFile method of the EmbeddedFileSystem.Builder class or a combination of these methods.