Oracle® GlassFish Server 3.0.1 Embedded Server Guide
Part No: 821–1754–10 June 2010 Copyright © 2010, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related software documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are “commercial computer software” or “commercial technical data” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms setforth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. UNIX is a registered trademark licensed through X/Open Company, Ltd. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, andservices.Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products,orservices.
100616@24378 Contents
Preface ...... 5
Oracle GlassFish Server 3.0.1 Embedded Server Guide ...... 11 Introduction to Embedded GlassFish Server ...... 11 Including the GlassFish Server Embedded Server API in Applications ...... 12 Setting the Class Path ...... 12 Creating, Starting, and Stopping Embedded GlassFish Server ...... 13 Deploying and Undeploying an Application in an Embedded GlassFish Server ...... 20 Running asadmin Commands Using the GlassFish Server Embedded Server API ...... 23 Sample Applications ...... 24 ▼ To Run Embedded GlassFish Server from the Command Line ...... 25 Testing Applications with the Maven Plug-in for Embedded GlassFish Server ...... 26 ▼ To Set Up Your Maven Environment ...... 27 ▼ To Build and Start an Application From Maven ...... 30 ▼ To Stop Embedded GlassFish Server ...... 30 ▼ To Redeploy an Application That Was Built and Started From Maven ...... 31 Maven Goals for Embedded GlassFish Server ...... 31 Using the EJB 3.1 Embeddable API with Embedded GlassFish Server ...... 35 ▼ To Use the EJB 3.1 Embeddable API with Embedded GlassFish Server ...... 35 Using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server ...... 36 Changing Log Levels in Embedded GlassFish Server ...... 37 ▼ To Change Log Levels in Embedded GlassFish Server ...... 37 Restrictions for Embedded GlassFish Server ...... 38
Index ...... 41
3 4 Preface
This document explains how to use embedded Oracle GlassFish Server to run applications in embedded GlassFish Server and to develop applications in which GlassFish Server is embedded. This document is for software developers who are developing applications to run in embedded GlassFish Server. The ability to program in the Java language is assumed.
This preface contains information about and conventions for the entire Oracle GlassFish Server (GlassFish Server) documentation set.
GlassFish Server 3.0.1 is developed through the GlassFish project open-source community at https://glassfish.dev.java.net/. The GlassFish project provides a structured process for developing the GlassFish Server platform that makes the new features of the Java EE platform available faster, while maintaining the most important feature of Java EE: compatibility. It enables Java developers to access the GlassFish Server source code and to contribute to the development of the GlassFish Server. The GlassFish project is designed to encourage communication between Oracle engineers and the community.
■ “GlassFish Server Documentation Set” on page 5 ■ “Related Documentation” on page 7 ■ “Typographic Conventions” on page 8 ■ “Symbol Conventions” on page 8 ■ “Default Paths and File Names” on page 9 ■ “Documentation, Support, and Training” on page 10 ■ “Searching Oracle Product Documentation” on page 10 ■ “Third-Party Web Site References” on page 10
GlassFish Server Documentation Set
The GlassFish Server documentation set describes deployment planning and system installation. The Uniform Resource Locator (URL) for GlassFish Server documentation is http://docs.sun.com/coll/1343.13. For an introduction to GlassFish Server, refer to the books in the order in which they are listed in the following table.
5 Preface
TABLE P–1 Books in the GlassFish Server Documentation Set
BookTitle Description
Release Notes Provides late-breaking information about the software and the documentation. Includes a comprehensive, table-based summary of the supported hardware, operating system, Java Development Kit (JDK), and database drivers.
Quick Start Guide Explains how to get started with the GlassFish Server product.
Installation Guide Explains how to install the software and its components.
Upgrade Guide Explains how to upgrade to the latest version of GlassFish Server. This guide also describes differences between adjacent product releases and configuration options that can result in incompatibility with the product specifications.
Administration Guide Explains how to configure, monitor, and manage GlassFish Server subsystems and components from the command line by using the asadmin(1M) utility. Instructions for performing these tasks from the Administration Console are provided in the Administration Console online help.
Application Deployment Guide Explains how to assemble and deploy applications to the GlassFish Server and provides information about deployment descriptors.
Your First Cup: An Introduction Provides a short tutorial for beginning Java EE programmers that explains to the Java EE Platform the entire process for developing a simple enterprise application. The sample application is a web application that consists of a component that is based on the Enterprise JavaBeans specification, a JAX-RS web service, and a JavaServer Faces component for the web front end.
Application Development Guide Explains how to create and implement Java Platform, Enterprise Edition (Java EE platform) applications that are intended to run on the GlassFish Server. These applications follow the open Java standards model for Java EE components and APIs. This guide provides information about developer tools, security, and debugging.
Add-On Component Explains how to use published interfaces of GlassFish Server to develop Development Guide add-on components for GlassFish Server. This document explains how to perform only those tasks that ensure that the add-on component is suitable for GlassFish Server.
Embedded Server Guide Explains how to run applications in embedded GlassFish Server and to develop applications in which GlassFish Server is embedded.
Scripting Framework Guide Explains how to develop scripting applications in languages such as Ruby on Rails and Groovy on Grails for deployment to GlassFish Server.
Troubleshooting Guide Describes common problems that you might encounter when using GlassFish Server and how to solve them.
6 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Preface
TABLE P–1 Books in the GlassFish Server Documentation Set (Continued) BookTitle Description
Error Message Reference Describes error messages that you might encounter when using GlassFish Server.
Reference Manual Provides reference information in man page format for GlassFish Server administration commands, utility commands, and related concepts.
Domain File Format Reference Describes the format of the GlassFish Server configuration file, domain.xml.
Java EE 6 Tutorial Explains how to use Java EE 6 platform technologies and APIs to develop Java EE applications.
Message Queue Release Notes Describes new features, compatibility issues, and existing bugs for GlassFish Message Queue.
Message Queue Administration Explains how to set up and manage a Message Queue messaging system. Guide
Message Queue Developer's Describes the application programming interface in Message Queue for Guide for JMX Clients programmatically configuring and monitoring Message Queue resources in conformance with the Java Management Extensions (JMX).
Related Documentation Javadoc tool reference documentation for packages that are provided with GlassFish Server is available as follows: ■ The API specification for version 6 of Java EE is located at http://download.oracle.com/ docs/cd/E17410_01/javaee/6/api/. ■ The API specification for GlassFish Server 3.0.1, including Java EE 6 platform packages and nonplatform packages that are specific to the GlassFish Server product, is located at: https://glassfish.dev.java.net/nonav/docs/v3/api/. Additionally, the following resources might be useful: ■ The Java EE Specifications (http://java.sun.com/javaee/technologies/index.jsp) ■ The Java EE Blueprints (http://java.sun.com/reference/blueprints/) For information about creating enterprise applications in the NetBeans Integrated Development Environment (IDE), see http://www.netbeans.org/kb/. For information about the Java DB for use with the GlassFish Server, see http://developers.sun.com/javadb/. The GlassFish Samples project is a collection of sample applications that demonstrate a broad range of Java EE technologies. The GlassFish Samples are bundled with the Java EE Software Development Kit (SDK), and are also available from the GlassFish Samples project page at https://glassfish-samples.dev.java.net/.
7 Preface
Typographic Conventions
The following table describes the typographic changes that are used in this book.
TABLE P–2 Typographic Conventions
Typeface Meaning Example
AaBbCc123 The names of commands, files, and Edit your .login file. directories, and onscreen computer Use ls -a to list all files. output machine_name% you have mail.
AaBbCc123 What you type, contrasted with onscreen machine_name% su computer output Password:
AaBbCc123 A placeholder to be replaced with a real The command to remove a file is rm filename. name or value
AaBbCc123 Book titles, new terms, and terms to be Read Chapter 6 in the User's Guide. emphasized (note that some emphasized A cache is a copy that is stored locally. items appear bold online) Do not save the file.
Symbol Conventions
The following table explains symbols that might be used in this book.
TABLE P–3 Symbol Conventions
Symbol Description Example Meaning
[] Contains optional arguments ls [-l] The -l option is not required. and command options.
{|} Contains a set of choices for a -d {y|n} The -d option requires that you use required command option. either the y argument or the n argument.
${ } Indicates a variable ${com.sun.javaRoot} References the value of the reference. com.sun.javaRoot variable.
- Joins simultaneous multiple Control-A Press the Control key while you press keystrokes. the A key.
+ Joins consecutive multiple Ctrl+A+N Press the Control key, release it, and keystrokes. then press the subsequent keys.
8 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Preface
TABLE P–3 Symbol Conventions (Continued) Symbol Description Example Meaning
→ Indicates menu item File → New → Templates From the File menu, choose New. selection in a graphical user From the New submenu, choose interface. Templates.
Default Paths and File Names The following table describes the default paths and file names that are used in this book.
TABLE P–4 Default Paths and File Names
Placeholder Description DefaultValue
as-install Represents the base installation directory for Installations on the Oracle Solaris operating system, Linux GlassFish Server. operating system, and Mac operating system: In configuration files, as-install is represented user’s-home-directory/glassfishv3/glassfish as follows: Windows, all installations: ${com.sun.aas.installRoot} SystemDrive:\glassfishv3\glassfish
as-install-parent Represents the parent of the base installation Installations on the Oracle Solaris operating system, Linux directory for GlassFish Server. operating system, and Mac operating system: user’s-home-directory/glassfishv3 Windows, all installations: SystemDrive:\glassfishv3
domain-root-dir Represents the directory in which a domain is as-install/domains/ created by default.
domain-dir Represents the directory in which a domain's domain-root-dir/domain-name configuration is stored. In configuration files, domain-dir is represented as follows: ${com.sun.aas.instanceRoot}
9 Preface
Documentation, Support, andTraining The Oracle web site provides information about the following additional resources:
■ Documentation (http://docs.sun.com/) ■ Support (http://www.sun.com/support/) ■ Training (http://education.oracle.com/)
Searching Oracle Product Documentation Besides searching Oracle product documentation from the docs.sun.com web site, you can use a search engine by typing the following syntax in the search field:
search-term site:docs.sun.com
For example, to search for “broker,”type the following:
broker site:docs.sun.com
To include other Oracle web sites in your search (for example, java.sun.com, www.sun.com, and developers.sun.com), use sun.com in place of docs.sun.com in the search field.
Third-PartyWeb Site References Third-party URLs are referenced in this document and provide additional, related information.
Note – Oracle is not responsible for the availability of third-party web sites mentioned in this document. Oracle does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Oracle will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.
10 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Oracle GlassFish Server 3.0.1 Embedded Server Guide
This document explains how to use embedded Oracle GlassFish Server to run applications in embedded GlassFish Server and to develop applications in which GlassFish Server is embedded. This document is for software developers who are developing applications to run in embedded GlassFish Server. The ability to program in the Java language is assumed.
This document addresses the following topics:
■ “Introduction to Embedded GlassFish Server” on page 11 ■ “Including the GlassFish Server Embedded Server API in Applications” on page 12 ■ “Testing Applications with the Maven Plug-in for Embedded GlassFish Server” on page 26 ■ “Using the EJB 3.1 Embeddable API with Embedded GlassFish Server” on page 35 ■ “Changing Log Levels in Embedded GlassFish Server” on page 37 ■ “Restrictions for Embedded GlassFish Server” on page 38
Introduction to Embedded GlassFish Server
Embedded Oracle GlassFish Server enables you to use GlassFish Server as a library. Embedded GlassFish Server also enables you to run GlassFish Server inside any Virtual Machine for the Java platform (Java Virtual Machine or JVMmachine).
No installation or configuration of embedded GlassFish Server is required. The ability torun GlassFish Server inside applications without installation or configuration simplifies the process of bundling GlassFish Server with applications.
Note – Embedded GlassFish Server does not run on the Java Platform, Micro Edition (Java ME platform).
11 Including the GlassFish Server Embedded Server API in Applications
You can use embedded GlassFish Server in the following ways:
■ With the Embedded Server API ■ With the Maven Plug-in ■ With the EJB 3.1 Embeddable API
Embedded GlassFish Server provides a plug-in for Apache Maven. This plug-in simplifies the testing of applications by enabling you to build an application and run it with GlassFish Server on a single system. Testing and debugging are simplified because the need for an installed and configured GlassFish Server is eliminated. Therefore, you can run unit tests automatically in every build.
Note – Using Embedded GlassFish Server does not involve any use of OSGi technology.
Including the GlassFish Server Embedded Server API in Applications Oracle GlassFish Server provides an application programming interface (API) for developing applications in which GlassFish 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 GlassFish Server is embedded is explained in the following topics:
■ “Setting the Class Path” on page 12 ■ “Creating, Starting, and Stopping Embedded GlassFish Server” on page 13 ■ “Deploying and Undeploying an Application in an Embedded GlassFish Server” on page 20 ■ “Running asadmin Commands Using the GlassFish Server Embedded Server API” on page 23 ■ “Sample Applications” on page 24 ■ “To Run Embedded GlassFish Server from the Command Line” on page 25
Setting the Class Path To enable your applications to locate the class libraries for embedded GlassFish Server, add one of the following JAR files to your class path: glassfish-embedded-web.jar Contains classes needed for deploying Java EE web applications. Download this file from http://download.java.net/maven/glassfish/org/glassfish/extras/.
12 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Including the GlassFish Server Embedded Server API in Applications glassfish-embedded-all.jar Contains classes needed for deploying all Java EE application types. Download this file from http://download.java.net/maven/glassfish/org/glassfish/extras/. glassfish-embedded-static-shell.jar Contains references to classes needed for deploying all Java EE application types. Must be used with a nonembedded installation of GlassFish Server. Obtain this file from the as-install/glassfish/lib/embedded directory of a nonembedded GlassFish 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 (JDBC) driver JAR files in the class path.
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” on page13 ■ “Specifying an Embedded GlassFish Server File System” on page 14 ■ “Running an Embedded GlassFish Server” on page 18
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 DefaultValue
Creates a server builder Server.Builder(java.lang.String id) None and names the server
References an embedded embeddedFileSystem(EmbeddedFileSystem file-system) None file system
Enables verbose mode verbose(boolean enabled) true
Oracle GlassFish Server 3.0.1 Embedded Server Guide 13 Including the GlassFish Server Embedded Server API in Applications
TABLE 1 Constructor and Methods of the Server.Builder Class (Continued) Purpose Method DefaultValue
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 build(Properties properties) None properties
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. Whatyou 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.
14 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Including the GlassFish Server Embedded Server API in Applications
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 settingis also listed.
TABLE 2 Constructor and Methods of the EmbeddedFileSystem.Builder Class
Purpose Method DefaultValue
Creates an embedded file EmbeddedFileSystem.Builder() None system builder
Deletes embedded file autoDelete(boolean enabled) false 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.
Creates a new or installRoot(java.io.File install-root) In order of precedence: references an existing ■ glassfish.embedded. Installation Root tmpdir system property Directory value ■ user.dir system property value ■ Current directory
Creates or references an installRoot(java.io.File install-root, Same as the other installRoot Installation Root boolean cooked-mode) method, cooked-mode is true Directory in which the embedded server and file system use different class loaders if cooked-mode is false
Creates a new or instanceRoot(java.io.File instance-root) as-install/domains/domain1 references an existing Instance Root Directory
Creates a new or configurationFile(java.io.File config-file) domain-dir/config/domain.xml references an existing configuration file
Creates or references a configurationFile(java.io.File config-file domain-dir/config/domain.xml, configuration file that is boolean read-only) read-only is false read-only if read-only is true
Oracle GlassFish Server 3.0.1 Embedded Server Guide 15 Including the GlassFish Server Embedded Server API in Applications
TABLE 2 Constructor and Methods of the EmbeddedFileSystem.Builder Class (Continued) Purpose Method DefaultValue
Creates an embedded file build() None system
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:
16 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Including the GlassFish Server Embedded Server API in Applications
■ You require Oracle GlassFish Server to create the directory for configuration files ata 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.
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 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.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 17 Including the GlassFish Server Embedded Server API in Applications
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,orconfigurationFile 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” on page 13, you can perform operations such as:
■ Setting the Port ■ Starting the server ■ Stopping the server
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.
■ 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 GlassFish Server File System” on page 14 and “Using an Existing domain.xml File” on page 18.
18 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Including the GlassFish Server Embedded Server API in Applications
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:
■ Undeploying deployed applications ■ Releasing any resources that your application uses
To stop an embedded GlassFish Server, invoke the stop method of an existing Server object.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 19 Including the GlassFish Server Embedded Server API in Applications
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” on page 22. 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 and Undeploying an Application in an Embedded GlassFish Server Deploying an application installs the files that comprise the application into Embedded GlassFish Server and makes the application ready to run. By default, an application is enabled when it is deployed. You can perform operations such as:
■ “To Deploy an Application From an Archive File or a Directory” on page 20 ■ “Undeploying an Application” on page 22
For general information about deploying applications in GlassFish Server, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.
▼ To Deploy an Application From an Archive File or a Directory 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 Oracle GlassFish Server 3.0.1 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 GlassFish Server. The directory
20 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Including the GlassFish Server Embedded Server API in Applications
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 Oracle GlassFish Server 3.0.1 Application Deployment Guide.
1 Invoke the addContainer method of the Server object to get an instance of the org.glassfish.api.embedded.ContainerBuilder class. Instantiate ContainerBuilder.Type.web, ContainerBuilder.Type.ejb,or ContainerBuilder.Type.all.
2 Instantiate the java.io.File class to represent the archive file or directory.
3 Invoke the getDeployer method of the Server object to get an instance of the org.glassfish.api.embedded.EmbeddedDeployer class.
4 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 ofthe equivalent deploy(1) command parameters.
5 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.
Example 6 Deploying an Application From an Archive File 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.addContainer(ContainerBuilder.Type.web); server.createPort(8080);
Oracle GlassFish Server 3.0.1 Embedded Server Guide 21 Including the GlassFish Server Embedded Server API in Applications
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); ...
Undeploying an Application Undeploy an application when the application is no longer required to run in GlassFish Server. For example, before stopping GlassFish Server, undeploy all applications that are running in GlassFish Server.
Note – If you reference a nonembedded GlassFish Server installation using the glassfish-embedded-static-shell.jar file and do not undeploy your applications inthe same server life cycle in which you deployed them, expanded archives for these applications remain under the domain-dir/applications directory.
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.
EXAMPLE 7 Undeploying an Application
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); ...
22 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Including the GlassFish Server Embedded Server API in Applications
Running asadmin Commands Using the GlassFish Server Embedded Server API Running asadmin(1M) commands from an application enables the application to configure the embedded GlassFish 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 GlassFish Server, see the Oracle GlassFish Server 3.0.1 Administration Guide. For detailed information about asadmin commands, see Section 1 of the Oracle GlassFish Server 3.0.1 Reference Manual.
Note – Ensure that your application has started an embedded GlassFish Server before the application attempts to run asadmin commands. For more information, see “Running an Embedded GlassFish Server” on page 18.
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.
EXAMPLE 8 Running an asadmin create-jdbc-resource Command 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(); ...
EXAMPLE 9 Running an asadmin set-log-level Command
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.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 23 Including the GlassFish Server Embedded Server API in Applications
EXAMPLE 9 Running an asadmin set-log-level Command (Continued)
... 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 GlassFish Server” on page 37.
Sample Applications
EXAMPLE 10 Using an Existing domain.xml File and Deploying an Application From an Archive File 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) {
24 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Including the GlassFish Server Embedded Server API in Applications
EXAMPLE 10 Using an Existing domain.xml File and Deploying an Application From an Archive File (Continued)
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.addContainer(ContainerBuilder.Type.web); 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(); } } }
▼ To Run Embedded GlassFish Server from the Command Line After you have written a class that uses the GlassFish ServerEmbedded Server API to start the server, deploy your applications, and stop the server, you can run this class at the command line.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 25 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
BeforeYou Begin Ensure that the following prerequisites are met:
■ A distribution of embedded GlassFish 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 GlassFish Server in the Java application launcher, specifying the applications to deploy. java -jar glassfish-embedded-jar embedded-class glassfish-embedded-jar The full path to the file that contains your distribution of embedded GlassFish Server: glassfish-embedded-web.jar, glassfish-embedded-all.jar,or glassfish-embedded-static-shell.jar. embedded-class 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 GlassFish Server until embedded GlassFish Server is stopped.
Example 11 Running Embedded GlassFish Server This example shows the command for running embedded GlassFish Server as follows:
■ The embedded GlassFish Server JAR file is glassfish-embedded-all.jar. ■ The user class file is myembed.class.
java -jar glassfish-embedded-all.jar myembed.class
Testing Applications with the Maven Plug-in for Embedded GlassFish Server If you are using Apache Maven, the plug-in for embedded GlassFish Server simplifies the testing of applications. This plug-in enables you to build and start an unpackaged application with a single Maven goal.
Testing applications with the Maven plug-in involves the following tasks:
■ “To Set Up Your Maven Environment” on page 27 ■ “To Build and Start an Application From Maven” on page 30 ■ “To Stop Embedded GlassFish Server” on page 30 ■ “To Redeploy an Application That Was Built and Started From Maven” on page 31
26 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
Predefined Maven goals for embedded GlassFish Server are described in “Maven Goals for Embedded GlassFish Server” on page 31.
To use Maven with Embedded GlassFish Server and the EJB 3.1 Embeddable API, see “Using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server” on page 36.
▼ To Set UpYourMaven Environment Setting up your Maven environment enables Maven to download the required embedded GlassFish Server distribution file when you build your project. Setting up your Maven environment also identifies the plug-in that enables you to build and start an unpackaged application with a single Maven goal.
BeforeYou Begin Ensure that Apache Maven is installed.
1 Identify the Maven plug-in for embedded GlassFish Server. Add the following plugin element to your POM file: ......
2 Configure the embedded-glassfish goal prefix, the application name, and other standard settings. Add the following configuration element to your POM file: ...
Oracle GlassFish Server 3.0.1 Embedded Server Guide 27 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
3 Configure Maven goals. Add execution elements to your POM file: ...
4 Configure the repository. Add the following repository element to your POM file:
28 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
Example 12 POM File for Configuring Maven to Use Embedded GlassFish Server This example shows a POM file for configuring Maven to use embedded GlassFish Server.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 29 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
▼ To Build and Start an Application From Maven If you are using Maven to manage the development of your application, you can use a Maven goal to build and start the application in embedded GlassFish Server.
BeforeYou Begin Ensure that your Maven environment is configured.
1 Include the path to the Maven executable file mvn in your path statement.
2 Ensure that the JAVA_HOME environment variable is defined.
3 Create a directory for the Maven project for your application.
4 Copy to your project directory the POM file that you created in “To Set UpYour Maven Environment”on page 27.
5 Run the following command in your project directory: mvn install This command performs the following actions:
■ Installs the Maven repository in a directory named .m2 under your home directory. ■ Starts embedded GlassFish Server. ■ Deploys your application. The application continues to run in embedded GlassFish Server until embedded GlassFish Server is stopped.
▼ To Stop Embedded GlassFish Server
1 Change to the root directory of the Maven project for your application.
2 Run the Maven goal to stop the application in embedded GlassFish Server. mvn embedded-glassfish:stop
30 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
This runs the stop method of the Server object and any other methods that are required to shut down the server in an orderly fashion. See “Stopping an Embedded GlassFish Server From an Application” on page 19.
▼ To Redeploy an ApplicationThatWas Built and Started From Maven An application that was built and started from Maven continues to run in embedded GlassFish Server until embedded GlassFish Server is stopped. While the application is running, you can test changes to the application by redeploying it.
● In the window from where the application was built and started from Maven, press Enter.
Maven Goals for Embedded GlassFish Server You can use the following Maven goals to test your applications with embedded GlassFish Server:
■ “embedded-glassfish:run Goal” on page 31 ■ “embedded-glassfish:start Goal” on page 32 ■ “embedded-glassfish:deploy Goal” on page 33 ■ “embedded-glassfish:undeploy Goal” on page 34 ■ “embedded-glassfish:stop Goal” on page 35
embedded-glassfish:run Goal This goal starts the server and deploys an application. You can redeploy if you change the application. The application can be a packaged archive or a directory that contains an exploded application. You can set the parameters described in the following table.
TABLE 3 embedded-glassfish:run Parameters
Parameter Default Description
serverID maven (optional) The ID of the server to start.
containerType all (optional) The container to start: web, ejb, jpa,orall.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 31 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
TABLE 3 embedded-glassfish:run Parameters (Continued) Parameter Default Description
installRoot In order of precedence: (optional) The Installation Root ■ glassfish.embedded.tmpdir system Directory. property value ■ user.dir system property value ■ Current directory
instanceRoot as-install/domains/domain1 (optional) The Instance Root Directory
configFile domain-dir/config/domain.xml (optional) The configuration file.
port None. Must be set explicitly or defined in the (optional) The HTTP port. configuration file.
app None. The archive file or directory for the application to be deployed.
name In order of precedence: (optional) The name of the application. ■ The application-name or module-name in the deployment descriptor. ■ The name of the archive file without the extension or the directory name.
For more information, see “Naming Standards” in Oracle GlassFish Server 3.0.1 Application Deployment Guide.
contextRoot The name of the application. (optional) The context root of the application.
precompileJsp false (optional) If true, JSP pages are precompiled during deployment.
createTables Value of the create-tables-at-deploy (optional) If true, creates database tables attribute in sun-ejb-jar.xml. during deployment for beans that are automatically mapped by the EJB container.
autoDelete false (optional) If true, deletes the contents of the Instance Root Directory 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.
embedded-glassfish:start Goal This goal starts the server. You can set the parameters described in the following table.
32 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
TABLE 4 embedded-glassfish:start Parameters
Parameter Default Description
serverID maven (optional) The ID of the server to start.
containerType all (optional) The container to start: web, ejb, jpa,or all.
installRoot In order of precedence: (optional) The Installation Root Directory. ■ glassfish.embedded.tmpdir system property value ■ user.dir system property value ■ Current directory
instanceRoot as-install/domains/domain1 (optional) The Instance Root Directory
configFile domain-dir/config/domain.xml (optional) The configuration file.
port None. Must be set explicitly or (optional) The HTTP port. defined in the configuration file.
autoDelete false (optional) If true, deletes the contents of the Instance Root Directory 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. embedded-glassfish:deploy Goal This goal deploys an application. You can redeploy if you change the application. The application can be a packaged archive or a directory that contains an exploded application. You can set the parameters described in the following table.
TABLE 5 embedded-glassfish:deploy Parameters
Parameter Default Description
app None. The archive file or directory for the application to be deployed.
name In order of precedence: (optional) The name of the application. ■ The application-name or module-name in the deployment descriptor. ■ The name of the archive file without the extension or the directory name. For more information, see “Naming Standards” in Oracle GlassFish Server 3.0.1 Application Deployment Guide.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 33 Testing Applications with the Maven Plug-in for Embedded GlassFish Server
TABLE 5 embedded-glassfish:deploy Parameters (Continued) Parameter Default Description
contextRoot The name of the application. (optional) The context root of the application.
precompileJsp false (optional) If true, JSP pages are precompiled during deployment.
createTables Value of the create-tables-at-deploy (optional) If true, creates database tables attribute in sun-ejb-jar.xml. during deployment for beans that are automatically mapped by the EJB container.
embedded-glassfish:undeploy Goal
Note – If you reference a nonembedded GlassFish Server installation using the glassfish-embedded-static-shell.jar file and do not undeploy your applications inthe same server life cycle in which you deployed them, expanded archives for these applications remain under the domain-dir/applications directory.
This goal undeploys an application. You can set the parameters described in the following table.
TABLE 6 embedded-glassfish:undeploy Parameters
Parameter Default Description
name If the name is omitted, all The name of the application. applications are undeployed.
dropTables Value of the (optional) If true, and deployment and undeployment occur drop-tables-at-undeploy in the same JVM session, database tables that were attribute in automatically created when the bean(s) were deployed are sun-ejb-jar.xml. dropped when the bean(s) are undeployed. If true, the name parameter must be specified or tables may not be dropped.
cascade false (optional) If true, deletes all connection pools and connector resources associated with the resource adapter being undeployed. If false, undeployment fails if any pools or resources are still associated with the resource adapter. This attribute is applicable to connectors (resource adapters) and applications with connector modules.
34 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Using the EJB 3.1 Embeddable API with Embedded GlassFish Server
embedded-glassfish:stop Goal This goal stops the server. You can set the parameters described in the following table.
TABLE 7 embedded-glassfish:stop Parameters
Parameter Default Description
serverID maven (optional) The ID of the server to stop.
Using the EJB 3.1 Embeddable API with Embedded GlassFish Server
The EJB 3.1 Embeddable API is designed for unit testing of EJB modules. You must use this API with a pre-installed, nonembedded GlassFish Server instance. However, you can take advantage of the embedded GlassFish Server's ease of use by referencing the nonembedded GlassFish Server instance with the glassfish-embedded-static-shell.jar file.
Embedded GlassFish Server is not related to the EJB 3.1 Embeddable API, but you can use these APIs together.
The Maven plug-in does not apply to embeddable EJB applications. However, you can use Maven with the POM file shown in “Using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server” on page 36.
The EJB 3.1 Embeddable API is described in Java Specification Request (JSR) 318 (http://jcp.org/en/jsr/detail?id=318).Anejb-embedded sample is included in the samples available at Java EE 6 Downloads (http://java.sun.com/javaee/downloads/ index.jsp) or Code Samples (http://java.sun.com/javaee/reference/code/index.jsp).
▼ To Use the EJB 3.1 Embeddable API with Embedded GlassFish Server
1 To specify GlassFish Server as the Container Provider, include glassfish-embedded-static-shell.jar in the class path of your embeddable EJB application. See “Setting the Class Path” on page 12 and Section 22.3.3 of the EJB 3.1 Specification, Embeddable Container Bootstrapping.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 35 Using the EJB 3.1 Embeddable API with Embedded GlassFish Server
2 Configure any required resources. For more information about configuring resources, see the Administration Console Online Help or Part III, “Resources and Services Administration,”in Oracle GlassFish Server 3.0.1 Administration Guide. The jdbc/__default Java DB database is preconfigured with all distributions of GlassFish Server.
3 Invoke one of the createEJBContainer methods.
Note – Do not deploy your embeddable EJB application or any of its dependent Java EE modules before invoking one of the createEJBContainer methods. These methods perform deployment in the background and do not load previously deployed applications or modules.
4 To change the Instance Root Directory, set the org.glassfish.ejb.embedded.glassfish. instance.root system property value by using the createEJBContainer(Map properties) method. The default Instance Root Directory location is as-install/domains/domain1. This system property applies only to embeddable EJB applications used with nonembedded GlassFish Server.
5 Close the EJB container properly to release all acquired resources and threads.
Using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server When using Maven with the EJB 3.1 Embeddable API and Embedded GlassFish Server, you cannot use the features of the Maven plug-in. You must start and stop Embedded GlassFish Server manually or programmatically outside of Maven.
EXAMPLE 13 Maven POM File for Using the EJB 3.1 Embeddable API with Embedded GlassFish Server This example shows a POM file for configuring Maven to use the EJB 3.1 Embeddable APIwith Embedded GlassFish Server.
36 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Changing Log Levels in Embedded GlassFish Server
EXAMPLE 13 Maven POM File for Using the EJB 3.1 Embeddable API with Embedded GlassFish Server (Continued)
Changing Log Levels in Embedded GlassFish Server To change log levels in Embedded GlassFish Server, you can follow the steps in this section or you can use the Embedded Server API as shown in Example 9. For more information about GlassFish Server logging, see Chapter 7, “Administering the Logging Service,”in Oracle GlassFish Server 3.0.1 Administration Guide.
▼ To Change Log Levels in Embedded GlassFish Server
1 Ensure that you have write permission access to the $JAVA_HOME/jre/lib/logging.properties file.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 37 Restrictions for Embedded GlassFish Server
2 Use a text editor to edit the $JAVA_HOME/jre/lib/logging.properties file.
3 Change the java.util.logging.ConsoleHandler.level log level to FINE or FINEST.
4 Add GlassFish Server log levels to the end of the file and adjust them as necessary. For example, add javax.enterprise.system.tools.deployment.level=FINE.
Restrictions for Embedded GlassFish Server The glassfish-embedded-web.jar file for embedded GlassFish Server supports only these features of nonembedded GlassFish Server:
■ The following web technologies of the Java EE platform: ■ Java Servlet API 2.5 ■ JavaServer Pages (JSP) technology 2.1 ■ JavaServer Faces technology 1.0 ■ JDBC-technology connection pooling ■ Java Persistence API 1.0 ■ Java Transaction API ■ Java Transaction Service
The other embedded GlassFish Server JAR files, glassfish-embedded-all.jar and glassfish-embedded-static-shell.jar, support all features of nonembedded GlassFish Server with these exceptions:
■ Installers ■ Administration Console ■ Update Tool ■ Apache Felix OSGi framework ■ EJB Timer Service ■ The Maven plug-in for embedded GlassFish Server does not support application clients. ■ Applications that require ports for communication, such as remote EJB components, do not work with the EJB 3.1 Embeddable API running with embedded GlassFish Server if a nonembedded GlassFish Server is running in parallel.
Embedded GlassFish Server requires no installation or configuration. As a result, the following files and directories are absent from the file system until embedded GlassFish Server isstarted:
■ default-web.xml file ■ domain.xml file ■ Applications directory
38 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010 Restrictions for Embedded GlassFish Server
■ Instance root directory
When embedded GlassFish Server is started, the base installation directory that GlassFish Server uses depends on the options with which GlassFish Server is started. For more information, see “Specifying an Embedded GlassFish Server File System” on page 14.If necessary, embedded GlassFish Server creates a base installation directory. Embedded GlassFish Server then copies the following directories and their contents from the Java archive (JAR) file in which embedded GlassFish Server is distributed:
■ domains ■ lib
If necessary, GlassFish Server also creates an instance root directory.
Oracle GlassFish Server 3.0.1 Embedded Server Guide 39 40 Index
A deploy goal, 33-34 addContainer method, 21 deploy method, 21 app parameter, 32, 33 DeployCommandParameters class, 21 asadmin commands, 23-24 deployment, 20-22 autoDelete method, 15 domain.xml file, 18 autoDelete parameter, 32, 33 dropTables parameter, 34
B E build method EJB 3.1 Embeddable API, 35-37 EmbeddedFileSystem.Builder class, 16 and Maven, 36-37 Server.Builder class, 14 Embedded GlassFish Server about, 11-12 and EJB 3.1 Embeddable API, 35-37 API, 12-26 C changing log levels, 23-24, 37-38 cascade parameter, 34 class path, 12-13 configFile parameter, 32, 33 creating and configuring, 13-14 configurationFile method, 15 deployment, 20-22 ContainerBuilder class, 21 containerType parameter, 31, 33 file system, 14-18 contextRoot parameter, 32, 34 JAR files, 12-13 createEJBContainer methods, 36 Maven plug-in, 26-35 createPort method, 18 restrictions, 38-39 createTables parameter, 32, 34 running asadmin commands, 23-24 running from the command line, 25-26 running the server, 18-20 sample applications, 24-25 D EmbeddedDeployer class, 21, 22 database tables EmbeddedFileSystem.Builder class, 14 creating at deployment, 32, 34 EmbeddedFileSystem.Builder constructor, 15 dropping at undeployment, 34 embeddedFileSystem method, 13
41 Index
G P getDeployer method, 21 POM file, 29-30, 36-37 glassfish-embedded-all.jar,12 port, setting, 18-19 glassfish-embedded-static-shell.jar,13 port parameter, 32, 33 glassfish-embedded-web.jar,12 precompileJsp parameter, 32, 34
I R installation root directory, 16-17 run goal, 31-32 installRoot method, 15 installRoot parameter, 32, 33 instance root directory, 17-18 S instanceRoot method, 15 Server.Builder class, 13 instanceRoot parameter, 32, 33 Server.Builder constructor, 13 Server class addContainer method, 21 J createPort method, 18 JSP pages getDeployer method, 21 start precompiling, 32, 34 method, 19 stop method, 19 serverID parameter, 31, 33, 35 start goal, 32-33 L start method, 19 log levels, 23-24, 37-38 stop goal, 35 logFile method, 14 stop method, 19 logger method, 14 logging.properties file, 37 U undeploy goal, 34-35 M undeploy method, 22 undeployAll Maven, and EJB 3.1 Embeddable API, 36-37 method, 22 Maven plug-in, 26-35 building and starting an application, 30 goals, 31-35 V POM file, 29-30 verbose method, 13 setting up, 27-30
N name parameter, 32, 33, 34
42 Oracle GlassFish Server 3.0.1 Embedded Server Guide • June 2010