Oracle GlassFish Server 3.0.1 Embedded Server Guide

Creating, Starting, and Stopping Embedded GlassFish Server

Before you can run applications, you must set up and run the embedded GlassFish Server. This section includes the following topics:

Creating and Configuring an Embedded GlassFish Server

To create and configure an embedded GlassFish Server, perform these tasks:

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

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

  3. Invoke one of the build methods to create a Server object.

The methods of this class for setting the server configuration are listed in the following table. The default value of each configuration setting is also listed.

Table 1 Constructor and Methods of the Server.Builder Class

Purpose 

Method 

Default Value 

Creates a server builder and names the server 


Server.Builder(java.lang.String id)

None 

References an embedded file system 


embeddedFileSystem(EmbeddedFileSystem file-system)

None 

Enables verbose mode 


verbose(boolean enabled)

true

Enables logging 


logger(boolean enabled)

true

Specifies a log file 


logFile(File log-file)

domain-dir/logs/server.log (see Instance Root Directory)

Creates a server 


build()

None 

Creates a server with properties 


build(Properties properties)

None 


Example 1 Creating an Embedded GlassFish Server

This example shows code for creating a server and enabling logging.

...
import org.glassfish.api.embedded.*;
...
    Server.Builder builder = new Server.Builder("test");
    builder.logger(true);
    ...
    Server server = builder.build();
...

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 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.

Table 2 Constructor and Methods of the EmbeddedFileSystem.Builder Class

Purpose 

Method 

Default Value 

Creates an embedded file system builder 


EmbeddedFileSystem.Builder()

None 

Deletes embedded file system files when the server is stopped 


Caution – 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:

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


Note –

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 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:

How embedded Oracle GlassFish Server uses the instance root directory depends on the content of this 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.

Running an Embedded GlassFish Server

After you create an embedded GlassFish Server as described in Creating and Configuring an Embedded GlassFish Server, you can perform operations such as:

Setting the Port of an Embedded GlassFish Server From an Application

You must set the server's HTTP port. If you do not set the port, your application fails to start and throws an exception. You can set the port directly or indirectly.


Example 3 Starting an Embedded GlassFish Server

This example shows code for setting the port of an embedded GlassFish Server. This example also includes the code from Example 1 for creating Server.Builder and Server objects.

...
import org.glassfish.api.embedded.*;
...
    Server.Builder builder = new Server.Builder("test");
    ...
    Server server = builder.build();
    server.createPort(8080);
...

Starting an Embedded GlassFish Server From an Application

To start an embedded GlassFish Server, invoke the start method of the Server object.


Example 4 Starting an Embedded GlassFish Server

This example shows code for setting the port and starting an embedded GlassFish Server. This example also includes the code from Example 1 for creating Server.Builder and Server objects.

...
import org.glassfish.api.embedded.*;
...
    Server.Builder builder = new Server.Builder("test");
    ...
    Server server = builder.build();
    server.createPort(8080);
    server.start();
...

Stopping an Embedded GlassFish Server From an Application

The API for embedded GlassFish Server provides a method for stopping an embedded server. Using this method enables your application to stop the server in an orderly fashion by performing any necessary cleanup steps before stopping the server, for example:

To stop an embedded GlassFish Server, invoke the stop method of an existing Server object.


Example 5 Stopping an Embedded GlassFish Server

This example shows code for prompting the user to press the Enter key to stop an embedded GlassFish Server. When a user presses Enter, the application undeploys any deployed applications before stopping the server. For more information about undeploying applications, see Undeploying an Application. Code for creating a Server object is not shown in this example. For an example of code for creating a Server object, see Example 1.

...
import java.io.BufferedReader;
...
import org.glassfish.api.embedded.*;
...
    EmbeddedDeployer deployer = server.getDeployer();
    ...
    System.out.println("Press Enter to stop server");
        // wait for Enter
    new BufferedReader(new java.io.InputStreamReader(System.in)).readLine();
    deployer.undeployAll();
    server.stop();
...