Contents

List of Examples

List of Tables

Title and Copyright Information

Preface

• GlassFish Server Documentation Set
• Related Documentation
• Typographic Conventions
• Symbol Conventions
• Default Paths and File Names
• Documentation, Support, and Training
• Searching Oracle Product Documentation
• Documentation Accessibility

Part I Development Tasks and Tools

1 Setting Up a Development Environment

• Installing and Preparing the Server for Development
• High Availability Features
• Development Tools
  • The asadmin Command
  • The Administration Console
  • The Migration Tool
  • The NetBeans IDE
  • The Eclipse IDE
  • Debugging Tools
  • Profiling Tools
• Sample Applications

2 Class Loaders

• The Class Loader Hierarchy
• Delegation
• Using the Java Optional Package Mechanism
• Using the Endorsed Standards Override Mechanism
• Class Loader Universes
• Application-Specific Class Loading
• Circumventing Class Loader Isolation
  • Using the Common Class Loader
  • Sharing Libraries Across a Cluster
  • Packaging the Client JAR for One Application in Another Application
  • To Package the Client JAR for One Application in Another Application

3 Debugging Applications

• Enabling Debugging
  • To Set the Server to Automatically Start Up in Debug Mode
• JPDA Options
• Generating a Stack Trace for Debugging
• Application Client Debugging
• GlassFish Server Message Queue Debugging
• Enabling Verbose Mode
• Class Loader Debugging
• GlassFish Server Logging
• Profiling Tools
  • The NetBeans Profiler
  • The HPROF Profiler
    • To Use HPROF Profiling on UNIX
  • The JProbe Profiler
    • To Enable Remote Profiling With JProbe

Part II Developing Applications and Application Components

4 Securing Applications

• Security Goals
• GlassFish Server Specific Security Features
• Container Security
  • Declarative Security
    • Application Level Security
    • Component Level Security
  • Programmatic Security
• Roles, Principals, and Principal to Role Mapping
• Realm Configuration
  • Supported Realms
  • How to Configure a Realm
  • How to Set a Realm for an Application or Module
  • Creating a Custom Realm
• JACC Support
• Pluggable Audit Module Support
  • Configuring an Audit Module
  • The AuditModule Class
• The server.policy File
  • Default Permissions
  • System Properties
  • Changing Permissions for an Application
  • Enabling and Disabling the Security Manager
• Configuring Message Security for Web Services
  • Message Security Providers
  • Message Security Responsibilities
    • Application Developer Responsibilities
    • Application Deployer Responsibilities
    • System Administrator Responsibilities
  • Application-Specific Message Protection
    • Using a Signature to Enable Message Protection for All Methods
    • Configuring Message Protection for a Specific Method Based on Digital Signatures
  • Understanding and Running the Sample Application
    • To Set Up the Sample Application
    • To Run the Sample Application
• Programmatic Login
  • Programmatic Login Precautions
  • Granting Programmatic Login Permission
  • The ProgrammaticLogin Class
• User Authentication for Single Sign-on
• Adding Authentication Mechanisms to the Servlet Container
  • The GlassFish Server and JSR 196
  • Writing a Server Authentication Module
  • Sample Server Authentication Module
  • Compiling and Installing a Server Authentication Module
  • Configuring a Server Authentication Module
  • Binding a Server Authentication Module to Your Application

5 Developing Web Services

• Creating Portable Web Service Artifacts
• Deploying a Web Service
• The Web Service URI, WSDL File, and Test Page
• The Databinding Provider
• GlassFish Java EE Service Engine
  • Using the jbi.xml File

6 Configuring the Java Persistence Provider

• Overview of Oracle TopLink
• Using Oracle TopLink in GlassFish Server
• Specifying the Database for an Application
• Specifying the Persistence Provider for an Application
• Primary Key Generation Defaults
• Automatic Schema Generation
  • Annotations
  • Generation Options
• Restrictions and Optimizations
  • Oracle Database Enhancements
  • Extended Persistence Context
  • Using @OrderBy with a Shared Session Cache
  • Using BLOB or CLOB Types with the Inet Oraxo JDBC Driver
  • Database Case Sensitivity
    • Unique Constraints
    • Foreign Key Mapping
    • SQL Result Set Mapping
    • Named Native Queries and JDBC Queries
    • PostgreSQL Case Sensitivity
  • Sybase Finder Limitation
  • MySQL Database Restrictions

7 Developing Web Applications

• Using Servlets
  • Caching Servlet Results
    • Caching Features
    • Default Cache Configuration
    • Caching Example
    • The CacheKeyGenerator Interface
  • About the Servlet Engine
    • Instantiating and Removing Servlets
    • Request Handling
• Using JavaServer Pages
  • JSP Tag Libraries and Standard Portable Tags
  • JSP Caching
    • Enabling JSP Caching
    • Caching Scope
    • The cache Tag
    • The flush Tag
  • Options for Compiling JSP Files
• Creating and Managing Sessions
  • Configuring Sessions
    • HTTP Sessions, Cookies, and URL Rewriting
    • Coordinating Session Access
    • Saving Sessions During Redeployment
    • Logging Session Attributes
    • Distributed Sessions and Persistence
  • Session Managers
    • The memory Persistence Type
    • The file Persistence Type
    • The replicated Persistence Type
    • The coherence-web Persistence Type
• Using Comet
  • Introduction to Comet
    • The Grizzly Implementation of Comet
    • Client Technologies to Use With Comet
    • Types of Comet Connections
  • Grizzly Comet
    • The Grizzly Comet API
    • The Hidden Frame Example
    • Creating a Comet-Enabled Application
    • Developing the Web Component
    • Creating the Client Pages
    • Creating the Deployment Descriptor
    • Deploying and Running a Comet-Enabled Application
  • Bayeux Protocol
    • Enabling Comet
    • To Configure the web.xml File
    • To Write, Deploy, and Run the Client
• Advanced Web Application Features
  • Internationalization Issues
    • The Server's Default Locale
    • Servlet Character Encoding
  • Virtual Server Properties
  • Class Loader Delegation
  • Using the default-web.xml File
    • To Use the default-web.xml File
  • Configuring Logging and Monitoring in the Web Container
  • Configuring Idempotent URL Requests
    • Specifying an Idempotent URL
    • Characteristics of an Idempotent URL
  • Header Management
  • Configuring Valves and Catalina Listeners
  • Alternate Document Roots
  • Using a context.xml File
  • Enabling WebDav
  • Using SSI
  • Using CGI

8 Using Enterprise JavaBeans Technology

• Value Added Features
  • Read-Only Beans
  • The pass-by-reference Element
  • Pooling and Caching
    • Pooling Parameters
    • Caching Parameters
  • Priority Based Scheduling of Remote Bean Invocations
  • Immediate Flushing
• EJB Timer Service
  • To Deploy an EJB Timer to a Cluster
• Using Session Beans
  • About the Session Bean Containers
    • Stateless Container
    • Stateful Container
  • Stateful Session Bean Failover
    • Choosing a Persistence Store
    • Enabling Checkpointing
    • Specifying Methods to Be Checkpointed
  • Session Bean Restrictions and Optimizations
    • Optimizing Session Bean Performance
    • Restricting Transactions
    • EJB Singletons
• Using Read-Only Beans
  • Read-Only Bean Characteristics and Life Cycle
  • Read-Only Bean Good Practices
  • Refreshing Read-Only Beans
    • Invoking a Transactional Method
    • Refreshing Periodically
    • Refreshing Programmatically
  • Deploying Read-Only Beans
• Using Message-Driven Beans
  • Message-Driven Bean Configuration
    • Connection Factory and Destination
    • Message-Driven Bean Pool
    • Domain-Level Settings
  • Message-Driven Bean Restrictions and Optimizations
    • Pool Tuning and Monitoring
    • The onMessage Runtime Exception

9 Using Container-Managed Persistence

• GlassFish Server Support for CMP
• CMP Mapping
  • Mapping Capabilities
  • The Mapping Deployment Descriptor File
  • Mapping Considerations
    • Join Tables and Relationships
    • Automatic Primary Key Generation
    • Fixed Length CHAR Primary Keys
    • Managed Fields
    • BLOB Support
    • CLOB Support
• Automatic Schema Generation for CMP
  • Supported Data Types for CMP
  • Generation Options for CMP
• Schema Capture
  • Automatic Database Schema Capture
  • Using the capture-schema Utility
• Configuring the CMP Resource
• Performance-Related Features
  • Version Column Consistency Checking
    • To Use Version Consistency
  • Relationship Prefetching
  • Read-Only Beans
• Default Fetch Group Flags
• Configuring Queries for 1.1 Finders
  • About JDOQL Queries
  • Query Filter Expression
  • Query Parameters
  • Query Variables
  • JDOQL Examples
    • Example 1
    • Example 2
    • Example 3
• CMP Restrictions and Optimizations
  • Disabling ORDER BY Validation
  • Setting the Heap Size on DB2
  • Eager Loading of Field State
  • Restrictions on Remote Interfaces
  • PostgreSQL Case Insensitivity
  • No Support for lock-when-loaded on Sybase
  • Sybase Finder Limitation
  • Date and Time Fields
  • Set RECURSIVE_TRIGGERS to false on MSSQL
  • MySQL Database Restrictions

10 Developing Java Clients

• Introducing the Application Client Container
  • ACC Security
  • ACC Naming
  • Application Client Annotation
  • Java Web Start
  • Application Client JAR File
• Developing Clients Using the ACC
  • To Access an EJB Component From an Application Client
  • To Access a JMS Resource From an Application Client
  • Using Java Web Start
    • Enabling and Disabling Java Web Start
    • Downloading and Launching an Application Client
    • The Application Client URL
    • Signing JAR Files Used in Java Web Start
    • Error Handling
    • Vendor Icon, Splash Screen, and Text
    • Creating a Custom JNLP File
  • Using the Embeddable ACC
  • Running an Application Client Using the appclient Script
  • Using the package-appclient Script
  • The client.policy File
  • Using RMI/IIOP Over SSL
  • Connecting to a Remote EJB Module Through a Firewall
  • Specifying a Splash Screen
  • Setting Login Retries
  • Using Libraries with Application Clients
• Developing Clients Without the ACC
  • To access an EJB component from a stand-alone client
  • To access an EJB component from a server-side module
  • To access a JMS resource from a stand-alone client

11 Developing Connectors

• Connector Support in the GlassFish Server
  • Connector Architecture for JMS and JDBC
  • Connector Configuration
• Advanced Connector Configuration Options
  • Thread Associations
  • Security Maps
  • Work Security Maps
  • Overriding Configuration Properties
  • Testing a Connector Connection Pool
  • Flushing a Connector Connection Pool
  • Handling Invalid Connections
  • Setting the Shutdown Timeout
  • Specifying the Class Loading Policy
  • Using Last Agent Optimization of Transactions
  • Disabling Pooling for a Connection
  • Using Application-Scoped Connectors
• Inbound Communication Support
• Outbound Communication Support
• Configuring a Message Driven Bean to Use a Resource Adapter

12 Developing Lifecycle Listeners

• Server Life Cycle Events
• The LifecycleListener Interface
• The LifecycleEvent Class
• The Server Lifecycle Event Context
• Deploying a Lifecycle Module
• Considerations for Lifecycle Modules

13 Developing OSGi-enabled Java EE Applications

• Overview of OSGi Application and GlassFish Server
  • Benefits of Using OSGi in Enterprise Java Applications
• Developing OSGi Application Bundles for GlassFish Server
  • Developing Plain OSGi Bundles
    • HTTP Service
    • Transaction Service
    • JDBC Data Source Service
    • JMS Resource Service
  • Developing Web Application Bundles
    • Required WAB Metadata
    • How WABs Consume OSGi Services
    • OSGi CDI Extension for WABs
  • Developing EJB Application Bundles
    • Required EJB Metadata
    • How EJB Bundles Consume OSGi Services
    • Using the OSGi CDI Extension With EJB Bundles
• Deploying OSGi Bundles in GlassFish Server

Part III Using Services and APIs

14 Using the JDBC API for Database Access

• Statements
  • Using an Initialization Statement
  • Setting a Statement Timeout
  • Statement Leak Detection and Leaked Statement Reclamation
  • Statement Caching
  • Statement Tracing
• Connections
  • Transparent Pool Reconfiguration
  • Disabling Pooling
  • Associating Connections with Threads
  • Custom Connection Validation
  • Sharing Connections
  • Marking Bad Connections
  • Handling Invalid Connections
• Connection Wrapping
  • Wrapping Connections
  • Obtaining a Physical Connection From a Wrapped Connection
  • Using the Connection.unwrap() Method
• Allowing Non-Component Callers
• Using Application-Scoped Resources
• Restrictions and Optimizations
  • Disabling Stored Procedure Creation on Sybase

15 Using the Transaction Service

• Handling Transactions with Databases
  • Using JDBC Transaction Isolation Levels
  • Using Non-Transactional Connections
• Handling Transactions with Enterprise Beans
  • Flat Transactions
  • Global and Local Transactions
  • Commit Options
  • Bean-Level Container-Managed Transaction Timeouts
• Handling Transactions with the Java Message Service
  • Transactions and Non-Persistent Messages
  • Using the ConfigurableTransactionSupport Interface
• The Transaction Manager, the Transaction Synchronization Registry, and UserTransaction

16 Using the Java Naming and Directory Interface

• Accessing the Naming Context
  • Portable Global JNDI Names
  • GlassFish Server V2 Vendor-Specific Global JNDI Names
  • Disabling GlassFish Server V2 JNDI Names
  • Accessing EJB Components Using the CosNaming Naming Context
  • Accessing EJB Components in a Remote GlassFish Server
  • Naming Environment for Lifecycle Modules
• Configuring Resources
  • External JNDI Resources
  • Custom Resources
  • Built-in Factories for Custom Resources
    • JavaBeanFactory
    • PropertiesFactory
    • PrimitivesAndStringFactory
    • URLFactory
  • Using Application-Scoped Resources
• Using a Custom jndi.properties File
• Mapping References

17 Using the Java Message Service

• Using Application-Scoped JMS Resources
• Load-Balanced Message Inflow
• Authentication With ConnectionFactory
• Delivering SOAP Messages Using the JMS API
  • To Send SOAP Messages Using the JMS API
  • To Receive SOAP Messages Using the JMS API

18 Using the JavaMail API

• Introducing JavaMail
• Creating a JavaMail Session
• JavaMail Session Properties
• Looking Up a JavaMail Session
• Sending and Reading Messages Using JavaMail
  • To Send a Message Using JavaMail
  • To Read a Message Using JavaMail
• Using Application-Scoped JavaMail Resources