Sun GlassFish Enterprise Server provides an application programming interface (API) for developing applications in which Enterprise Server is embedded. For details, see the org.glassfish.api.embedded.* packages at https://glassfish.dev.java.net/nonav/docs/v3/api/.
Developing an application in which Enterprise Server is embedded is explained in the following topics:
Deploying and Undeploying an Application in an Embedded Enterprise Server
Running asadmin Commands Using the Sun GlassFish Embedded Server API
To enable your applications to locate the class libraries for embedded Enterprise Server, add one of the following JAR files to your class path:
Contains classes needed for deploying Java EE web applications. Download this file from http://download.java.net/maven/glassfish/org/glassfish/extras/.
Contains classes needed for deploying all Java EE application types. Download this file from http://download.java.net/maven/glassfish/org/glassfish/extras/.
Contains references to classes needed for deploying all Java EE application types. Must be used with a nonembedded installation of Enterprise Server. Obtain this file from the as-installglassfish/lib/embedded directory of a nonembedded Enterprise Server installation. For an explanation of as-install, see Installation Root Directory.
In addition, add to the class path any other JAR files or classes upon which your applications depend. For example, if an application uses a database other than Java DB, include the Java DataBase Connectivity (JDBCTM) driver JAR files in the class path.
Before you can run applications, you must set up and run the embedded Enterprise Server. This section includes the following topics:
To create configure an embedded Enterprise Server, perform these tasks:
Instantiate the org.glassfish.api.embedded.Server.Builder class.
Invoke any methods for configuration settings that you require. This is optional.
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 |
|
None |
|
References an embedded file system |
|
None |
|
Enables verbose mode |
|
true |
|
Enables logging |
|
true |
|
Specifies a log file |
|
instance-dirlogs/server.log (see Instance Root Directory) |
|
Creates a server |
|
None |
|
Creates a server with properties |
|
None |
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 file system for an embedded Enterprise 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 Enterprise Server
To control where embedded Enterprise Server creates its configuration directories
To specify a configuration file, which controls how embedded Enterprise Server functions
To specify an embedded file system for embedded Enterprise Server, perform these tasks:
Instantiate the org.glassfish.api.embedded.EmbeddedFileSystem.Builder class.
Invoke any methods for configuration settings that you require. This is optional.
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 |
|
None |
|
Deletes embedded file system files when the server is stopped ![]() Do not set autoDelete to true if you are using installRoot to refer to a preexisting Enterprise Server installation. |
|
false |
|
Creates a new or references an existing Installation Root Directory |
|
In order of precedence:
|
|
Creates or references an Installation Root Directory in which the embedded server and file system use different class loaders if cooked-mode is false |
|
Same as the other installRoot method, cooked-mode is true |
|
Creates a new or references an existing Instance Root Directory |
|
as-installdomains/domain1 |
|
Creates a new or references an existing configuration file |
|
instance-dirconfig/domain.xml |
|
Creates or references a configuration file that is read-only if read-only is true |
|
instance-dirconfig/domain.xml, read-only is false |
|
Creates an embedded file system |
|
None |
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(); ...
The installation root directory, represented as as-install, is the parent of the directory that embedded Sun GlassFish Enterprise Server uses for configuration files. This directory corresponds to the base directory for an installation of Enterprise Server. Configuration files are contained in the following directories in the base directory for an installation of Enterprise Server:
domains
lib
Specify the installation root directory if any of the following conditions applies:
You require Sun GlassFish Enterprise 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 Sun GlassFish Enterprise 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 Sun GlassFish Enterprise Server uses the installation root directory depends on the content of this directory:
If the installation root directory contains domain configuration files, embedded Sun GlassFish Enterprise Server reads the configuration files.
If the installation root directory does not contain domain configuration files, embedded Sun GlassFish Enterprise Server copies configuration files into this directory.
If the installation root directory does not exist, embedded Sun GlassFish Enterprise Server creates the directory and copies configuration files into the directory.
If the installation root directory is not specified, embedded Sun GlassFish Enterprise Server creates a directory named gfembedrandom-numbertmp in the current working directory, where random-number is a randomly generated 19-digit number. Embedded Sun GlassFish Enterprise Server then copies configuration files into this directory.
The instance root directory, represented as instance-dir, is the parent directory of a server instance directory. Embedded Sun GlassFish Enterprise 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 Sun GlassFish Enterprise Server uses the instance root directory depends on the content of this directory:
If the instance root directory contains domain configuration files, embedded Sun GlassFish Enterprise Server reads the configuration files.
If the instance root directory does not contain domain configuration files, embedded Sun GlassFish Enterprise Server copies configuration files into this directory.
If the instance root directory does not exist, embedded Sun GlassFish Enterprise Server creates the directory and copies configuration files into the directory.
If the instance root directory is not specified, embedded Sun GlassFish Enterprise Server uses the domains subdirectory of the installation root directory for domain configuration files.
Using an existing domain.xml file avoids the need to configure embedded Enterprise 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 Enterprise 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.
After you create an embedded Enterprise Server as described in Creating and Configuring an Embedded Enterprise Server, you can perform operations such as:
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.
To set the port directly, invoke the createPort method of the Server object.
To port indirectly, set up an embedded file system, which includes a domain.xml file that sets the port. For more information, see Specifying an Embedded Enterprise Server File System and Using an Existing domain.xml File.
This example shows code for setting the port of an embedded Enterprise 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); ...
To start an embedded Enterprise Server, invoke the start method of the Server object.
This example shows code for setting the port and starting an embedded Enterprise 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(); ...
The API for embedded Enterprise 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:
Undeploying deployed applications
Releasing any resources that your application uses
To stop an embedded Enterprise Server, invoke the stop method of an existing Server object.
This example shows code for prompting the user to press the Enter key to stop an embedded Enterprise 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(); ...
Deploying an application installs the files that comprise the application into Enterprise Server and makes the application ready to run. By default, an application is enabled when it is deployed.
For general information about deploying applications in Enterprise Server, see Sun GlassFish Enterprise Server v3 Application Deployment Guide.
An archive file contains the resources, deployment descriptor, and classes of an application. The content of the file must be organized in the directory structure that the Java EE specifications define for the type of archive that the file contains. For more information, see Chapter 2, Deploying Applications, in Sun GlassFish Enterprise Server v3 Application Deployment Guide.
Deploying an application from a directory enables you to deploy an application without the need to package the application in an archive file. The contents of the directory must match the contents of the expanded Java EE archive file as laid out by the Enterprise Server. The directory must be accessible to the machine on which the deploying application runs. For more information about the requirements for deploying an application from a directory, see To Deploy an Application or Module in a Directory Format in Sun GlassFish Enterprise Server v3 Application Deployment Guide.
Instantiate the java.io.File class to represent the archive file or directory.
Invoke the getDeployer method of the Server object to get an instance of the org.glassfish.api.embedded.EmbeddedDeployer class.
Instantiate a org.glassfish.api.deployment.DeployCommandParameters class.
To use the default parameter settings, instantiate an empty DeployCommandParameters class. For information about the fields in this class that you can set, see the descriptions of the equivalent deploy(1) command parameters.
Invoke the deploy(File archive, DeployCommandParameters params) method of the instance of the EmbeddedDeployer object.
Specify the java.io.File and DeployCommandParameters class instances you created previously as the method parameters.
This example shows code for deploying an application from the archive file c:\samples\simple.war and setting the contextroot parameter of the DeployCommandParameters class. This example also includes the code from Example 1 for creating Server.Builder and Server objects.
... import java.io.File; ... import org.glassfish.api.deployment.*; ... import org.glassfish.api.embedded.*; ... Server.Builder builder = new Server.Builder("test"); ... Server server = builder.build(); server.createPort(8080); server.start(); File war = new File("c:\\samples\\simple.war"); EmbeddedDeployer deployer = server.getDeployer(); DeployCommandParameters params = new DeployCommandParameters(); params.contextroot = "simple"; deployer.deploy(war, params); ...
Undeploy an application when the application is no longer required to run in Enterprise Server. For example, before stopping Enterprise Server, undeploy all applications that are running in Enterprise Server.
To undeploy an application, invoke the undeploy method of an existing EmbeddedDeployer object. In the method invocation, pass the name of the application and the name of its DeployCommandParameters class as parameters. Both are specified when the application is deployed.
To undeploy all deployed applications, invoke the undeployAll method of an existing EmbeddedDeployer object. This method takes no parameters.
This example shows code for undeploying the application that was deployed in Example 6.
... import org.glassfish.api.deployment.*; ... import org.glassfish.api.embedded.*; ... deployer.undeploy(war, params); ...
Running asadmin(1M) commands from an application enables the application to configure the embedded Enterprise Server to suit the application's requirements. For example, an application can run the required asadmin commands to create a JDBC technology connection to a database.
For more information about configuring embedded Enterprise Server, see the Sun GlassFish Enterprise Server v3 Administration Guide. For detailed information about asadmin commands, see Section 1 of the Sun GlassFish Enterprise Server v3 Reference Manual.
Ensure that your application has started an embedded Enterprise Server before the application attempts to run asadmin commands. For more information, see Running an Embedded Enterprise Server.
The org.glassfish.api.admin package contains classes that you can use to run asadmin commands. Use the following code examples as templates and change the command name, parameter names, and parameter values as needed.
This example shows code for running an asadmin create-jdbc-resource command. Code for creating and starting the server is not shown in this example. For an example of code for creating and starting the server, see Example 4.
... import org.glassfish.api.embedded.*; import org.glassfish.api.admin.*; ... String command = "create-jdbc-resource"; ParameterMap params = new ParameterMap(); params.add("connectionpoolid", "DerbyPool"); params.add("jndi_name", "jdbc/DerbyPool"); CommandRunner runner = server.getHabitat().getComponent(CommandRunner.class); ActionReport report = server.getHabitat().getComponent(ActionReport.class); runner.getCommandInvocation(command, report).parameters(params).execute(); ...
This example shows code for running an asadmin set-log-level command. Code for creating and starting the server is not shown in this example. For an example of code for creating and starting the server, see Example 4.
... import org.glassfish.api.embedded.*; import org.glassfish.api.admin.*; ... String command = "set-log-level"; ParameterMap params = new ParameterMap(); params.add("javax\.enterprise\.system\.container\.web", "FINE"); CommandRunner runner = server.getHabitat().getComponent(CommandRunner.class); ActionReport report = server.getHabitat().getComponent(ActionReport.class); runner.getCommandInvocation(command, report).parameters(params).execute(); ...
For another way to change log levels, see Changing Log Levels in Embedded Enterprise Server.
This example shows code for the following:
Using the existing file c:\myapp\embeddedserver\domains\domain1\config\domain.xml and preserving this file when the application is stopped.
Deploying an application from the archive file c:\samples\simple.war.
The files that this example uses are organized as follows:
c:\myapp\embeddedserver\lib\glassfish-embedded-all.jar
c:\myapp\embeddedserver\domains\domain1\config\domain.xml
c:\myapp\embeddedserver\domains\domain1\logs
c:\myapp\embeddedserver\domains\domain1\docroot
import java.io.File; import java.io.BufferedReader; import org.glassfish.api.deployment.*; import org.glassfish.api.embedded.*; public class Main { /** * @param args the command line arguments */ public static void main(String[] args) { File installDir = new File ("c:\\myapp\\embeddedserver"); File war = new File("c:\\samples\\simple.war"); try { Server.Builder builder = new Server.Builder("test"); ... EmbeddedFileSystem.Builder efsb = new EmbeddedFileSystem.Builder(); efsb.autoDelete(false); efsb.installRoot(installDir); EmbeddedFileSystem efs = efsb.build(); builder.embeddedFileSystem(efs); ... Server server = builder.build(); server.createPort(8080); server.start(); EmbeddedDeployer deployer = server.getDeployer(); DeployCommandParameters params = new DeployCommandParameters(); deployer.deploy(war, params); } catch (Exception e) { e.printStackTrace(); } System.out.println("Press Enter to stop server"); // wait for Enter new BufferedReader(new java.io.InputStreamReader(System.in)).readLine(); try { deployer.undeployAll(); server.stop(); } catch (Exception e) { e.printStackTrace(); } } }
After you have written a class that uses the Sun GlassFish Embedded Server API to start the server, deploy your applications, and stop the server, you can run this class at the command line.
Ensure that the following prerequisites are met:
A distribution of embedded Enterprise Server is downloaded.
A user-created class file that uses the Embedded Server API to start the server, deploy your applications, and stop the server is written.
Run embedded Enterprise Server in the Java application launcher, specifying the applications to deploy.
java -jar glassfish-embedded-jar embedded-class |
The full path to the file that contains your distribution of embedded Enterprise Server: glassfish-embedded-web.jar, glassfish-embedded-all.jar, or glassfish-embedded-static-shell.jar.
A user-created class file with a main method that uses the Embedded Server API to start the server, deploy your applications, and stop the server.
The applications continue to run in embedded Enterprise Server until embedded Enterprise Server is stopped.
This example shows the command for running embedded Enterprise Server as follows:
The embedded Enterprise Server JAR file is glassfish-embedded-all.jar.
The user class file is myembed.class.
java -jar glassfish-embedded-all.jar myembed.class |