Eclipse GlassFish Application Development Guide, Release 7

The asadmin command allows you to configure a local or remote server and perform both administrative and development tasks at the command line. For general information about asadmin, see the Eclipse GlassFish Reference Manual.

The asadmin command is located in the as-install/bin directory. Type asadmin help for a list of subcommands.

The Administration Console lets you configure the server and perform both administrative and development tasks using a web browser. For general information about the Administration Console, click the Help button in the Administration Console. This displays the Eclipse GlassFish online help.

To access the Administration Console, type http://`host:4848` in your browser. The host is the name of the machine on which the Eclipse GlassFish is running. By default, the host is localhost. For example:

The Migration Tool converts and reassembles Jakarta EE applications and modules developed on other application servers. This tool also generates a report listing how many files are successfully and unsuccessfully migrated, with reasons for migration failure. For more information and to download the Migration Tool, see http://java.sun.com/j2ee/tools/migration/index.html.

There is several advanced editors with an integration with GlassFish or generic Jakarta EE servers. Sometimes you have to install additional extensions, sometimes all you need is just some configuration.

You can use several debugging tools with the Eclipse GlassFish. For more information, see Debugging Applications.

You can use several profilers with the Eclipse GlassFish. For more information, see Profiling Tools.

To use the Common class loader, copy the JAR files into the domain-dir/lib or as-install/lib directory, or use the asadmin add-library command with the --type common option, then restart the server. For more information about the asadmin add-library command, see the Eclipse GlassFish Reference Manual.

Using the Common class loader makes an application or module accessible to all applications or modules deployed on servers that share the same configuration. However, this accessibility does not extend to application clients. For more information, see Using Libraries with Application Clients.

For example, using the Common class loader is the recommended way of adding JDBC drivers to the Eclipse GlassFish. For a list of the JDBC drivers currently supported by the Eclipse GlassFish, see the Eclipse GlassFish Release Notes. For configurations of supported and other drivers, see "Configuration Specifics for JDBC Drivers" in Eclipse GlassFish Administration Guide.

To activate custom login modules and realms, place the JAR files in the domain-dir/lib directory, then restart the server.

To share libraries across a specific cluster, copy the JAR files to the domain-dir/config/cluster-config-name/lib directory.

By packaging the client JAR for one application in a second application, you allow an EJB or web component in the second application to call an EJB component in the first (dependent) application, without making either of them accessible to any other application or module.

As an alternative for a production environment, you can have the Common class loader load the client JAR of the dependent application as described in Using the Common Class Loader. Restart the server to make the dependent application accessible to all applications or modules deployed on servers that share the same configuration.

See Also

For details, click the Help button in the Administration Console from the JVM Settings page.

For information on how to use the NetBeans profiler, see http://profiler.netbeans.org/index.html.

The Heap and CPU Profiling Agent (HPROF) is a simple profiler agent shipped with the Java 2 SDK. It is a dynamically linked library that interacts with the Java Virtual Machine Profiler Interface (JVMPI) and writes out profiling information either to a file or to a socket in ASCII or binary format.

HPROF can monitor CPU usage, heap allocation statistics, and contention profiles. In addition, it can also report complete heap dumps and states of all the monitors and threads in the Java virtual machine. For more details on the HPROF profiler, see the technical article at http://java.sun.com/developer/technicalArticles/Programming/HPROF.html.

After HPROF is enabled using the following instructions, its libraries are loaded into the server process.

Information about JProbe from Sitraka is available at http://www.quest.com/jprobe/.

After JProbe is installed using the following instructions, its libraries are loaded into the server process.

Declarative security means that the security mechanism for an application is declared and handled externally to the application. Deployment descriptors describe the Jakarta EE application’s security structure, including security roles, access control, and authentication requirements.

The Eclipse GlassFish supports the deployment descriptors specified by Jakarta EE and has additional security elements included in its own deployment descriptors. Declarative security is the application deployer’s responsibility. For more information about Eclipse GlassFish deployment descriptors, see the Eclipse GlassFish Application Deployment Guide.

There are two levels of declarative security, as follows:

Programmatic security involves an EJB component or servlet using method calls to the security API, as specified by the Jakarta EE security model, to make business logic decisions based on the caller or remote user’s security role. Programmatic security should only be used when declarative security alone is insufficient to meet the application’s security model.

The API for programmatic security consists of methods of the Jakarta EE Security API SecurityContext interface, and methods of the EJB EJBContext interface and the servlet HttpServletRequest interface. The Eclipse GlassFish supports these interfaces as specified in the Java EE specification.

There is also a proprietary Glassfish API for programmatic login. See Programmatic Login Using the ProgrammaticLogin Class.

For more information about programmatic security, see Using Programmatic Security in the The Jakarta EE Tutorial.

The following realms are supported in the current release of the Eclipse GlassFish:

For information about configuring realms, see How to Configure a Realm.

You can configure a realm in one of these ways:

The following deployment descriptor elements have optional realm or realm-name data subelements or attributes that override the domain’s default realm:

If modules within an application specify realms, these are ignored. If present, the realm defined in glassfish-application.xml is used, otherwise the domain’s default realm is used.

For example, a realm is specified in glassfish-application.xml as follows:

For more information about the deployment descriptor files and elements, see "Elements of the Eclipse GlassFish Deployment Descriptors" in Eclipse GlassFish Application Deployment Guide.

You can create a custom realm by providing a custom Java Authentication and Authorization Service (JAAS) login module class and a custom realm class. Note that client-side JAAS login modules are not suitable for use with the Eclipse GlassFish.

To activate the custom login modules and realms, place the JAR files in the domain-dir/lib directory or the class files in the domain-dir`/lib/classes` directory. For more information about class loading in the Eclipse GlassFish, see Class Loaders.

JAAS is a set of APIs that enable services to authenticate and enforce access controls upon users. JAAS provides a pluggable and extensible framework for programmatic user authentication and authorization. JAAS is a core API and an underlying technology for Jakarta EE security mechanisms. For more information about JAAS, refer to the specification, available at https://jakarta.ee/specifications/authentication/ and https://jakarta.ee/specifications/authorization/.

For general information about realms and login modules, see the section about working with realms, users, groups, and roles in Introduction to Security in the Jakarta EE Platform in The Jakarta EE Tutorial.

For Javadoc tool pages relevant to custom realms, see the com.sun.appserv.security package.

Custom login modules must extend the com.sun.appserv.security.AppservPasswordLoginModule class. This class implements javax.security.auth.spi.LoginModule. Custom login modules must not implement LoginModule directly.

Custom login modules must provide an implementation for one abstract method defined in AppservPasswordLoginModule:

This method performs the actual authentication. The custom login module must not implement any of the other methods, such as login, logout, abort, commit, or initialize. Default implementations are provided in AppservPasswordLoginModule which hook into the Eclipse GlassFish infrastructure.

The custom login module can access the following protected object fields, which it inherits from AppservPasswordLoginModule. These contain the user name and password of the user to be authenticated:

The authenticateUser method must end with the following sequence:

Custom realms must extend the com.sun.appserv.security.AppservRealm class and implement the following methods:

This method is invoked during server startup when the realm is initially loaded. The props argument contains the properties defined for this realm. The realm can do any initialization it needs in this method. If the method returns without throwing an exception, the Eclipse GlassFish assumes that the realm is ready to service authentication requests. If an exception is thrown, the realm is disabled.

This method returns a descriptive string representing the type of authentication done by this realm.

This method returns an Enumeration (of String objects) enumerating the groups (if any) to which the given username belongs in this realm.

Custom realms that manage users must implement the following additional methods:

This method returns true if the realm supports user management.

This method returns an Enumeration of all group names.

This method returns an Enumeration of all user names.

This method refreshes the realm data so that new users and groups are visible.

This method persists the realm data to permanent storage.

This method returns the information recorded about a particular named user.

This method adds a new user, who cannot already exist.

This method removes a user, who must exist.

This method updates data for a user, who must exist.

To configure an audit module, you can perform one of the following tasks:

You can create a custom audit module by implementing a class that extends com.sun.enterprise.security.audit.AuditModule.

For Javadoc tool pages relevant to audit modules, see the com.sun.enterprise.security.audit package.

The AuditModule class provides default "no-op" implementations for each of the following methods, which your custom class can override.

The preceding method is invoked during server startup when the audit module is initially loaded. The props argument contains the properties defined for this module. The module can do any initialization it needs in this method. If the method returns without throwing an exception, the Eclipse GlassFish assumes the module realm is ready to service audit requests. If an exception is thrown, the module is disabled.

This method is invoked when an authentication request has been processed by a realm for the given user. The success flag indicates whether the authorization was granted or denied.

This method is invoked when a web container call has been processed by authorization. The success flag indicates whether the authorization was granted or denied. The req object is the standard HttpServletRequest object for this request. The type string is one of hasUserDataPermission or hasResourcePermission (see JSR 115 (http://www.jcp.org/en/jsr/detail?id=115)).

This method is invoked when an EJB container call has been processed by authorization. The success flag indicates whether the authorization was granted or denied. The ejb and method strings describe the EJB component and its method that is being invoked.

This method is invoked during validation of a web service request in which the endpoint is a servlet. The uri is the URL representation of the web service endpoint. The endpoint is the name of the endpoint representation. The success flag indicates whether the authorization was granted or denied.

This method is invoked during validation of a web service request in which the endpoint is a stateless session bean. The endpoint is the name of the endpoint representation. The success flag indicates whether the authorization was granted or denied.

Internal server code is granted all permissions. These are covered by the AllPermission grant blocks to various parts of the server infrastructure code. Do not modify these entries.

Application permissions are granted in the default grant block. These permissions apply to all code not part of the internal server code listed previously. The Eclipse GlassFish does not distinguish between EJB and web module permissions. All code is granted the minimal set of web component permissions (which is a superset of the EJB minimal set). Do not modify these entries.

A few permissions above the minimal set are also granted in the default server.policy file. These are necessary due to various internal dependencies of the server implementation. Jakarta EE application developers must not rely on these additional permissions. In some cases, deleting these permissions might be appropriate. For example, one additional permission is granted specifically for using connectors. If connectors are not used in a particular domain, you should remove this permission, because it is not otherwise necessary.

The following predefined system properties, also called variables, are available for use in the server.policy file. The system property most frequently used in server.policy is ${com.sun.aas.instanceRoot}. For more information about system properties, see the asadmin create-system-properties command in the Eclipse GlassFish Reference Manual.

Table 4-1 Predefined System Properties

The default policy for each domain limits the permissions of Jakarta EE deployed applications to the minimal set of permissions required for these applications to operate correctly. Do not add extra permissions to the default set (the grant block with no codebase, which applies to all code). Instead, add a new grant block with a codebase specific to the applications requiring the extra permissions, and only add the minimally necessary permissions in that block.

If you develop multiple applications that require more than this default set of permissions, you can add the custom permissions that your applications need. The com.sun.aas.instanceRoot variable refers to the domain-dir. For example:

You can add permissions to stub code with the following grant block:

In general, you should add extra permissions only to the applications or modules that require them, not to all applications deployed to a domain. For example:

For a module:

An alternative way to add permissions to a specific application or module is to edit the granted.policy file for that application or module. The granted.policy file is located in the domain-dir`/generated/policy/`app-or-module-name directory. In this case, you add permissions to the default grant block. Do not delete permissions from this file.

When the Eclipse GlassFish policy subsystem determines that a permission should not be granted, it logs a server.policy message specifying the permission that was not granted and the protection domains, with indicated code source and principals that failed the protection check. For example, here is the first part of a typical message:

Granting the following permission eliminates the message:

As noted in the Jakarta EE specification, an application should provide documentation of the additional permissions it needs. If an application requires extra permissions but does not document the set it needs, contact the application author for details.

As a last resort, you can iteratively determine the permission set an application needs by observing AccessControlException occurrences in the server log.

If this is not sufficient, you can add the -Djava.security.debug=failure JVM option to the domain. Use the following asadmin create-jvm-options command, then restart the server:

For more information about the asadmin create-jvm-options command, see the Eclipse GlassFish Reference Manual.

You can use the J2SE standard policytool or any text editor to edit the server.policy file. For more information, see http://docs.oracle.com/javase/tutorial/security/tour2/index.html.

For detailed information about policy file syntax, see http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html.

For information about using system properties in the server.policy file, see http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html.

For detailed information about the permissions you can set in the server.policy file, see http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html.

The Javadoc for the Permission class is at http://docs.oracle.com/javase/8/docs/api/java/security/Permission.html.

The security manager is disabled by default.

In a production environment, you may be able to safely disable the security manager if all of the following are true:

Disabling the security manager may improve performance significantly for some types of applications.

To enable the security manager, do one of the following:

To disable the security manager, uncheck the Security Manager Enabled box or use the corresponding asadmin delete-jvm-options command. For more information about create-jvm-options and delete-jvm-options, see the Eclipse GlassFish Reference Manual.

If the security manager is enabled and you are using the Java Persistence API by calling Persistence.createEMF(), the EclipseLink persistence provider requires that you set the eclipselink.security.usedoprivileged JVM option to true as follows:

If the security manager is enabled and you are using the Java Persistence API by injecting or looking up an entity manager or entity manager factory, the EJB container sets this JVM option for you.

You must grant additional permissions to CDI-enabled Jakarta EE applications that are deployed in a Eclipse GlassFish 7 domain or cluster for which security manager is enabled. These additional permissions are not required when security manager is disabled.

To deploy CDI-enabled Jakarta EE applications in a Eclipse GlassFish 7 domain or cluster for which security manager is enabled, add the following permissions to the applications:

For example, for a CDI application named foo.war, add the following permissions to the server.policy file, restart the domain or cluster, and then deploy and use the application.

For more information about modifying application permissions, see Changing Permissions for an Application.

When you first install the Eclipse GlassFish, the providers XWS_ClientProvider and XWS_ServerProvider are configured but disabled. You can enable them in one of the following ways:

The example described in Understanding and Running the Sample Application uses the ClientProvider and ServerProvider providers, which are enabled when the Ant targets are run. You don’t need to enable these on the Eclipse GlassFish prior to running the example.

If you install the OpenSSO, you have these additional provider choices:

Liberty specifications can be viewed at http://www.projectliberty.org/resources/specifications.php/?f=resources/specifications.php. The WS-I BSP specification can be viewed at http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html.

For more information about the Eclipse GlassFish deployment descriptor files, see the Eclipse GlassFish Application Deployment Guide.

For information about configuring these providers in the Eclipse GlassFish, see the Eclipse GlassFish Security Guide. For additional information about overriding provider settings, see Application-Specific Message Protection.

You can create new message security providers in one of the following ways:

In addition, you can set a few optional provider properties using the asadmin set command. For example:

The following table describes these message security provider properties.

Table 4-2 Message Security Provider Properties

In the Eclipse GlassFish, the system administrator and application deployer roles are expected to take primary responsibility for configuring message security. In some situations, the application developer may also contribute, although in the typical case either of the other roles may secure an existing application without changing its implementation and without involving the developer.

The following topics are addressed here:

When the Eclipse GlassFish provided configuration is insufficient for your security needs, and you want to override the default protection, you can apply application-specific message security to a web service.

Application-specific security is implemented by adding the message security binding to the web service endpoint, whether it is an EJB or servlet web service endpoint. Modify Eclipse GlassFish XML files to add the message binding information.

Message security can also be specified using a WSIT security policy in the WSDL file. For details, see the WSIT page at http://wsit.java.net/.

For more information about message security providers, see Message Security Providers.

For more details on message security binding for EJB web services, servlet web services, and clients, see the XML file descriptions in "Elements of the Eclipse GlassFish Deployment Descriptors" in Eclipse GlassFish Application Deployment Guide.

The following topics are addressed here:

This section discusses the WSS sample application. This sample application is installed on your system only if you installed the J2EE 1.4 samples. If you have not installed these samples, see To Set Up the Sample Application.

The objective of this sample application is to demonstrate how a web service can be secured with WSS. The web service in the xms example is a simple web service implemented using a Jakarta EE EJB endpoint and a web service endpoint implemented using a servlet. In this example, a service endpoint interface is defined with one operation, sayHello, which takes a string then sends a response with Hello prefixed to the given string. You can view the WSDL file for the service endpoint interface at app-dir`/xms-ejb/src/`conf/HelloWorld.wsdl, where app-dir is defined in To Set Up the Sample Application.

In this application, the client looks up the service using the JNDI name java:comp/env/service/HelloWorld and gets the port information using a static stub to invoke the operation using a given name. For the name Duke, the client gets the response Hello Duke!

This example shows how to use message security for web services at the Eclipse GlassFish level. For information about using message security at the application level, see Application-Specific Message Protection. The WSS message security mechanisms implement message-level authentication (for example, XML digital signature and encryption) of SOAP web services invocations using the X.509 and username/password profiles of the OASIS WS-Security standard, which can be viewed from the following URL: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.

The following topics are addressed here:

The Eclipse GlassFish is not involved in how the login information (user, password) is obtained by the deployed application. Programmatic login places the burden on the application developer with respect to assuring that the resulting system meets security requirements. If the application code reads the authentication information across the network, the application determines whether to trust the user.

Programmatic login allows the application developer to bypass the Eclipse GlassFish-supported authentication mechanisms and feed authentication data directly to the security service. While flexible, this capability should not be used without some understanding of security issues.

Since this mechanism bypasses the container-managed authentication process and sequence, the application developer must be very careful in making sure that authentication is established before accessing any restricted resources or methods. It is also the application developer’s responsibility to verify the status of the login attempt and to alter the behavior of the application accordingly.

The programmatic login state does not necessarily persist in sessions or participate in single sign-on.

Lazy authentication is not supported for programmatic login. If an access check is reached and the deployed application has not properly authenticated using the programmatic login method, access is denied immediately and the application might fail if not coded to account for this occurrence. One way to account for this occurrence is to catch the access control or security exception, perform a programmatic login, and repeat the request.

The ProgrammaticLoginPermission permission is required to invoke the programmatic login mechanism for an application if the security manager is enabled. For information about the security manager, see The server.policy File. This permission is not granted by default to deployed applications because this is not a standard Jakarta EE mechanism.

To grant the required permission to the application, add the following to the domain-dir`/config/server.policy` file:

The jar-file-path is the path to the application’s JAR file.

The com.sun.appserv.security.ProgrammaticLogin class enables a user to perform login programmatically.

For Javadoc tool pages relevant to programmatic login, see the com.sun.appserv.security package.

The ProgrammaticLogin class has four login methods, two for servlets or JSP files and two for EJB components.

The login methods for servlets or JSP files have the following signatures:

The login methods for EJB components have the following signatures:

All of these login methods accomplish the following:

The login occurs on the realm specified unless it is null, in which case the domain’s default realm is used. The methods with no realm parameter use the domain’s default realm.

If the errors flag is set to true, any exceptions encountered during the login are propagated to the caller. If set to false, exceptions are thrown.

On the client side, realm and errors parameters are ignored and the actual login does not occur until a resource requiring a login is accessed. A java.rmi.AccessException with COBRA NO_PERMISSION occurs if the actual login fails.

The logout methods for servlets or JSP files have the following signatures:

The logout methods for EJB components have the following signatures:

All of these logout methods return true if logout succeeded, false if logout failed.

If the errors flag is set to true, any exceptions encountered during the logout are propagated to the caller. If set to false, exceptions are thrown.

The Eclipse GlassFish implements JSR-375 to provide built-in support for BASIC, FORM and Custom FORM authentication mechanisms. JSR-375 also defines plug-in interfaces for authentication and identity stores, that is, the HttpAuthenticationMechanism interface and the IdentityStore interface, respectively. Though HttpAuthenticationMechanism implementations can authenticate users in any manner they choose, the IdentityStore interface provides a convenient mechanism. A significant advantage of using HttpAuthenticationMechanism and IdentityStore over the declarative mechanisms defined by the Servlet specification is that it allows an application to control the identity stores that it authenticates against, in a standard, portable way. You can use the built-in implementations of these APIs, or define custom implementations.

Jakarta EE Security API defines several annotations, with names that end with Definition, which when used makes the corresponding built-in mechanism available as a CDI bean. Jakarta EE Security API also supports the use of Expression Language 3.0 in these annotations to allow dynamic configuration.

The Eclipse GlassFish implements the Servlet Container Profile of JSR 196, Java Authentication Service Provider Interface for Containers. JSR 196 defines a standard service provider interface (SPI) that extends the concepts of the Java Authentication and Authorization Service (JAAS) to enable pluggability of message authentication modules in message processing runtimes. The JSR 196 standard defines profiles that establish contracts for the use of the SPI in specific contexts. The Servlet Container Profile of JSR 196 defines the use of the SPI by a Servlet container such that:

The JSR 196 specification defines a simple message processing model composed of four interaction points:

A message processing runtime uses the SPI at these interaction points to delegate the corresponding message security processing to authentication providers, also called authentication modules, integrated into the runtime by way of the SPI.

A compatible server-side message processing runtime, such as the Eclipse GlassFish servlet container, supports the validateRequest and secureResponse interaction points of the message processing model. The servlet container uses the SPI at these interaction points to delegate the corresponding message security processing to a server authentication module (SAM), integrated by the SPI into the container.

A key step in adding an authentication mechanism to a compatible server-side message processing runtime such as the Eclipse GlassFish servlet container is acquiring a SAM that implements the desired authentication mechanism. One way to do that is to write the SAM yourself.

A SAM implements the javax.security.auth.message.module.ServerAuthModule interface as defined by JSR 196. A SAM is invoked indirectly by the message processing runtime at the validateRequest and secureResponse interaction points. A SAM must implement the five methods of the ServerAuthModule interface:

See the Servlet Container Profile section in the JSR 196 specification for additional background and details.

The class MySam.java is a sample SAM implementation. Notice that the sample implements the five methods of the ServerAuthModule interface. This SAM implements an approximation of HTTP basic authentication.

Note that the initialize method looks for the group.name and realm.name properties. The group.name property configures the default group assigned as a result of any successful authentication. The realm.name property defines the realm value sent back to the browser in the WWW-Authenticate challenge.

Before you can use the sample SAM, you need to compile, install, and configure it. Then you can bind it to an application.

To compile the SAM, include the SPI in your classpath. When the Eclipse GlassFish is installed, the JAR file containing the SPI, jmac-api.jar, is installed in the as-install/lib directory. After you compile the SAM, install it by copying a JAR file containing the compiled SAM to the as-install/lib directory.

You can configure a SAM in one of these ways:

After you install and configure the SAM, you can bind it for use by the container on behalf of one or more of your applications. You have two options in how you bind the SAM, depending on whether you are willing to repackage and redeploy your application:

The following annotations are used in automatic schema generation: @AssociationOverride, @AssociationOverrides, @AttributeOverride, @AttributeOverrides, @Column, @DiscriminatorColumn, @DiscriminatorValue, @Embedded, @EmbeddedId, @GeneratedValue, @Id, @IdClass, @JoinColumn, @JoinColumns, @JoinTable, @Lob, @ManyToMany, @ManyToOne, @OneToMany, @OneToOne, @PrimaryKeyJoinColumn, @PrimaryKeyJoinColumns, @SecondaryTable, @SecondaryTables, @SequenceGenerator, @Table, @TableGenerator, @UniqueConstraint, and @Version. For information about these annotations, see the Java Persistence Specification.

For @Column annotations, the insertable and updatable elements are not used in automatic schema generation.

For @OneToMany and @ManyToOne annotations, no ForeignKeyConstraint is created in the resulting DDL files.

Schema generation properties or asadmin command line options can control automatic schema generation by the following:

Optional schema generation properties control the automatic creation of database tables. You can specify them in the persistence.xml file. For more information, see Using EclipseLink JPA Extensions for Schema Generation (http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_(ELUG)#Using_EclipseLink_JPA_Extensions_for_Schema_Generation).

The following options of the asadmin deploy or asadmin deploydir command control the automatic creation of database tables at deployment.

Table 6-1 The asadmin deploy and asadmin deploydir Generation Options

The following options of the asadmin undeploy command control the automatic removal of database tables at undeployment.

Table 6-2 The asadmin undeploy Generation Options

For more information about the asadmin deploy, asadmin deploydir, and asadmin undeploy commands, see the Eclipse GlassFish Reference Manual.

When asadmin deployment options and persistence.xml options are both specified, the asadmin deployment options take precedence.

EclipseLink features a number of enhancements for use with Oracle databases. These enhancements require classes from the Oracle JDBC driver JAR files to be visible to EclipseLink at runtime. If you place the JDBC driver JAR files in domain-dir/lib, the classes are not visible to Eclipse GlassFish components, including EclipseLink.

If you are using an Oracle database, put JDBC driver JAR files in domain-dir/lib/ext instead. This ensures that the JDBC driver classes are visible to EclipseLink.

If you do not want to take advantage of Oracle-specific extensions from EclipseLink or you cannot put JDBC driver JAR files in domain-dir/lib/ext, set the eclipselink.target-database property to the value org.eclipse.persistence.platform.database.OraclePlatform. For more information about the eclipselink.target-database property, see Specifying the Database for an Application.

The Java Persistence API specification does not specify how the container and persistence provider should work together to serialize an extended persistence context. This also prevents successful serialization of a reference to an extended persistence context in a stateful session bean.

Even in a single-instance environment, if a stateful session bean is passivated, its extended persistence context could be lost when the stateful session bean is activated.

Therefore, in Eclipse GlassFish, a stateful session bean with an extended persistence context is never passivated and cannot be failed over.

Setting @OrderBy on a ManyToMany or OneToMany relationship field in which a List represents the Many side doesn’t work if the session cache is shared. Use one of the following workarounds:

To use BLOB or CLOB data types larger than 4 KB for persistence using the Inet Oraxo JDBC Driver for Oracle Databases, you must set the database’s streamstolob property value to true.

Mapping references to column or table names must be in accordance with the expected column or table name case, and ensuring this is the programmer’s responsibility. If column or table names are not explicitly specified for a field or entity, the Eclipse GlassFish uses upper case column names by default, so any mapping references to the column or table names must be in upper case. If column or table names are explicitly specified, the case of all mapping references to the column or table names must be in accordance with the case used in the specified names.

The following are examples of how case sensitivity affects mapping elements that refer to columns or tables. Keep case sensitivity in mind when writing these mappings.

If a finder method with an input greater than 255 characters is executed and the primary key column is mapped to a VARCHAR column, Sybase attempts to convert type VARCHAR to type TEXT and generates the following error:

To avoid this error, make sure the finder method input is less than 255 characters.

The following restrictions apply when you use a MySQL database with the Eclipse GlassFish for persistence.

The Eclipse GlassFish can cache the results of invoking a servlet, a JSP, or any URL pattern to make subsequent invocations of the same servlet, JSP, or URL pattern faster. The Eclipse GlassFish caches the request results for a specific amount of time. In this way, if another data call occurs, the Eclipse GlassFish can return the cached data instead of performing the operation again. For example, if your servlet returns a stock quote that updates every 5 minutes, you set the cache to expire after 300 seconds.

Whether to cache results and how to cache them depends on the data involved. For example, it makes no sense to cache the results of a quiz submission, because the input to the servlet is different each time. However, it makes sense to cache a high level report showing demographic data taken from quiz results that is updated once an hour.

To define how a Eclipse GlassFish web application handles response caching, you edit specific fields in the glassfish-web.xml file.

For Javadoc tool pages relevant to caching servlet results, see the com.sun.appserv.web.cache package.

For information about JSP caching, see JSP Caching.

The following topics are addressed here:

Servlets exist in and are managed by the servlet engine in the Eclipse GlassFish. The servlet engine is an internal object that handles all servlet meta functions. These functions include instantiation, initialization, destruction, access from other components, and configuration management.

The following topics are addressed here:

Eclipse GlassFish supports tag libraries and standard portable tags. For more information, see the JavaServer Pages Standard Tag Library (JSTL) page at https://jakarta.ee/specifications/tags/.

Web applications don’t need to bundle copies of the jsf-impl.jar or appserv-jstl.jar JSP tag libraries (in as-install/lib) to use JavaServer Faces technology or JSTL, respectively. These tag libraries are automatically available to all web applications.

However, the as-install/lib/jspcachtags.jar tag library for JSP caching is not automatically available to web applications. See JSP Caching, next.

JSP caching lets you cache tag invocation results within the Java engine. Each can be cached using different cache criteria. For example, suppose you have invocations to view stock quotes, weather information, and so on. The stock quote result can be cached for 10 minutes, the weather report result for 30 minutes, and so on.

The following topics are addressed here:

For more information about response caching as it pertains to servlets, see Caching Servlet Results.

Eclipse GlassFish provides the following ways of compiling JSP source files into servlets:

The following topics are addressed here:

A session manager automatically creates new session objects whenever a new session starts. In some circumstances, clients do not join the session, for example, if the session manager uses cookies and the client does not accept cookies.

Eclipse GlassFish offers these session management options, determined by the session-manager element’s persistence-type attribute in the glassfish-web.xml file:

For more information, see "session-manager" in Eclipse GlassFish Application Deployment Guide.

Comet is a programming technique that allows a web server to send updates to clients without requiring the clients to explicitly request them.

This kind of programming technique is called server push, which means that the server pushes data to the client. The opposite style is client pull, which means that the client must pull the data from the server, usually through a user-initiated event, such as a button click.

Web applications that use the Comet technique can deliver updates to clients in a more timely manner than those that use the client-pull style while avoiding the latency that results from clients frequently polling the server.

One of the many use cases for Comet is a chat room application. When the server receives a message from one of the chat clients, it needs to send the message to the other clients without requiring them to ask for it. With Comet, the server can deliver messages to the clients as they are posted rather than expecting the clients to poll the server for new messages.

To accomplish this scenario, a Comet application establishes a long-lived HTTP connection. This connection is suspended on the server side, waiting for an event to happen before resuming. This kind of connection remains open, allowing an application that uses the Comet technique to send updates to clients when they are available rather than expecting clients to reopen the connection to poll the server for updates.

For details on using Grizzly Comet including a sample application, refer to the Grizzly Comet documentation.

Grizzly’s support for Comet includes a small set of APIs that make it easy to add Comet functionality to your web applications. The Grizzly Comet APIs that developers use most often are the following:

The way a developer would use this API in a web component is to perform the following tasks:

The Bayeux protocol, often referred to as Cometd, greatly simplifies the use of Comet. No server-side coding is needed for servers such as Eclipse GlassFish that support the Bayeux protocol. Just enable Comet and the Bayeux protocol, then write and deploy the client.

The following topics are addressed here:

The following topics are addressed here: