test

Oracle GlassFish Server 3.0.1 Administration Guide

Part III Resources and Services Administration

Chapter 14 Administering Database Connectivity

This chapter provides procedures for performing database connectivity tasks in the Oracle GlassFish Server 3.0.1 environment by using the asadmin command-line utility.

The following topics are addressed here:

Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.

About Database Connectivity

A database management system (DBMS) provides facilities for storing, organizing, and retrieving data. The information in databases is often described as persistent data because it is saved on disk and exists after the application process ends. Most business applications store data in relational databases. Applications can access database information by using the Java Database Connectivity (JDBC) API.

The key elements of database connectivity are the following:

At runtime, the following sequence occurs when an application connects to a database:

  1. The application gets the JDBC resource associated with the database by making a call through the JNDI API.

    Using the JNDI name of the resource, the naming and directory service locates the JDBC resource. Each JDBC resource specifies a connection pool.

  2. Using the JDBC resource, the application gets a database connection.

    GlassFish Server retrieves a physical connection from the connection pool that corresponds to the database. The pool defines connection attributes such as the database name (URL), user name, and password.

  3. After the database connection is established, the application can read, modify, and add data to the database.

    The application accesses the database by making calls to the JDBC API. The JDBC driver translates the application’s JDBC calls into the protocol of the database server.

  4. When the application is finished accessing the database, the application closes the connection and returns the connection to the connection pool.

Setting Up the Database

Most applications use relational databases to store, organize, and retrieve data. Applications access relational databases through the Java Database Connectivity (JDBC) API.

The following topics are addressed here:

ProcedureTo Install the Database and Database Driver

  1. Install a supported database product.

    To see the current list of database products supported by GlassFish Server, refer to the Oracle GlassFish Server 3.0.1 Release Notes.

  2. Install a supported JDBC driver for the database product.

    For a list of drivers supported by GlassFish Server, see Configuration Specifics for JDBC Drivers.

  3. Make the JDBC driver JAR file accessible to the domain administration server (DAS).

    See Integrating the JDBC Driver.

  4. Create the database.

    The application provider usually delivers scripts for creating and populating the database.

Next Steps

You are now ready to create a connection pool for the database, and a JDBC resource that points to the connection pool. See To Create a JDBC Connection Pool and To Create a JDBC Resource. The final step is to integrate the JDBC driver into an administrative domain as described in Integrating the JDBC Driver.

ProcedureTo Start the Database

GlassFish Server includes an implementation of Java DB (formerly known as Derby), however, you can use any JDBC-compliant database. The database is not started automatically when you start GlassFish Server, so if you have applications that require a database, you need to start Java DB manually by using the local start-database subcommand.

  1. Start the database by using the start-database(1) subcommand.

    When the database server starts, or a client connects to it successfully, the following files are created at the location that is specified by the --dbhome option:

    • The derby.log file contains the database server process log along with its standard output and standard error information.

    • The database files contain your schema (for example, database tables).

Example 14–1 Starting a Database

This example starts Derby on the host host1 and port 5001.


asadmin> start-database --dbhost host1 --dbport 5001 --terse=true
Starting database in the background. 
Log redirected to /opt/SUNWappserver/databases/javadb.log.
Command start-database executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help start-database at the command line.

ProcedureTo Stop the Database

Use the local stop-database subcommand to stop Java DB on a specified port. A single host can have multiple database server processes running on different ports.

  1. If necessary, notify users that the database is being stopped.

  2. Stop the database by using the stop-database(1) subcommand.

Example 14–2 Stopping a Database

This example stops Java DB on port 5001 of localhost.


asadmin> stop-database --dbhost=localhost --dbport=5001
onnection obtained for host: localhost, port number 5001.
Apache Derby Network Server - 10.2.2.1 - (538595) shutdown 
at 2008-10-17 23:34:2 7.218 GMT
Command stop-database executed successfully.
Troubleshooting

For a laptop that roams between networks, you might have trouble shutting down the database. If you start Java DB and then change your IP address, you will not be able to stop Java DB unless you add a specific --dbhost argument. For example, if you run asadmin start-database --dbhost = 0.0.0.0, and then disconnect Ethernet and switch to wifi, you should run a command similar to the following to stop the database:

asadmin stop-database --dbhost localhost

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help stop-database at the command line.

Java DB Utility Scripts

The Java DB configuration that is available for use with GlassFish Server includes scripts that can help you use Java DB. The following scripts are available in the as-install/javadb/frameworks/NetworkServer/bin directory:

startNetworkServer,startNetworkServer.bat

Script to start the network server

stopNetworkServer,stopNetworkServer.bat

Script to stop the network server

ij,ij.bat

Interactive JDBC scripting tool

dblook,dblook.bat

Script to view all or part of the DDL for a database

sysinfo, sysinfo.bat

Script to display versioning information about the Java DB environment

NetworkServerControl,NetworkServerControl.bat

Script to execute commands on the NetworkServerControl API

ProcedureTo Configure Your Environment to Run Java DB Utility Scripts

  1. Ensure that the JAVA_HOME environment variable specifies the directory where the JDK is installed.

  2. Set the JAVADB_HOME environment variable to point to the as-install/derby directory.

See Also

For more information about these utilities, see the following documentation:

Configuring Access to the Database

After establishing the database, you are ready to set up access for GlassFish Server applications. The high-level steps include creating a JDBC connection pool, creating a JDBC resource for the connection pool, and integrating a JDBC driver into an administrative domain.

Instructions for performing these steps are contained in the following sections:

Administering JDBC Connection Pools

A JDBC connection pool is a group of reusable connections for a particular database. Because creating each new physical connection is time consuming, GlassFish Server maintains a pool of available connections. When an application requests a connection, it obtains one from the pool. When an application closes a connection, the connection is returned to the pool.

A JDBC resource is created by specifying the connection pool with which the resource is associated. Multiple JDBC resources can specify a single connection pool. The properties of connection pools can vary with different database vendors. Some common properties are the database name (URL), the user name, and the password.

The following tasks and information are used to administer JDBC connection pools:

ProcedureTo Create a JDBC Connection Pool

Use the create-jdbc-connection-pool subcommand in remote mode to register a new JDBC connection pool with the specified JDBC connection pool name. A JDBC connection pool or a connector connection pool can be created with authentication. You can either use a subcommand option to specify user, password, or other connection information using the asadmin utility, or specify the connection information in the XML descriptor file.

One connection pool is needed for each database, possibly more depending on the application. When you are building the connection pool, certain data specific to the JDBC driver and the database vendor is required. You can find some of the following specifics inConfiguration Specifics for JDBC Drivers:

Creating a JDBC connection pool is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Server Restart.

Before You Begin

Before creating the connection pool, you must first install and integrate the database and its associated JDBC driver. For instructions, see Setting Up the Database.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create the JDBC connection pool by using the create-jdbc-connection-pool(1) subcommand.

  3. (Optional) If needed, restart the server.

    Some parameters require server restart. See Configuration Changes That Require Server Restart.

Example 14–3 Creating a JDBC Connection Pool

This example creates a JDBC connection pool named sample_derby_pool on localhost.


asadmin> create-jdbc-connection-pool 
--datasourceclassname org.apache.derby.jdbc.ClientDataSource 
--restype javax.sql.XADataSource 
--property portNumber=1527:password=APP:user=APP:serverName=
localhost:databaseName=sun-appserv-samples:connectionAttribut
es=\;create\\=true sample_derby_pool
Command create-jdbc-connection-pool executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-jdbc-connection-pool at the command line.

ProcedureTo List JDBC Connection Pools

Use the list-jdbc-connection-pools subcommand in remote mode to list all existing JDBC connection pools.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the JDBC connection pools by using the list-jdbc-connection-pools(1) subcommand.

Example 14–4 Listing JDBC Connection Pools

This example lists the JDBC connection pools that are on localhost.


asadmin> list-jdbc-connection-pools
sample_derby_pool2
poolA
__TimerPool
DerbyPool
sample_derby_pool
Command list-jdbc-connection-pools executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-jdbc-connection-pools at the command line.

ProcedureTo Contact (Ping) a Connection Pool

Use the ping-connection-pool subcommand in remote mode to test if a connection pool is usable. For example, if you create a new JDBC connection pool for an application that is expected to be deployed later, you can test the JDBC pool with this subcommand before the application is deployed. Running a ping will force the creation of the pool if it hasn't already been created.

Before You Begin

Before you can contact a connection pool, the connection pool must be created with authentication, and the server or database must be running.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Ping a connection pool by using the ping-connection-pool(1) subcommand.

Example 14–5 Contacting a Connection Pool

This example tests to see if the DerbyPool connection pool is usable.


asadmin> ping-connection-pool DerbyPool
Command ping-connection-pool executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help ping-connection-pool at the command line.

ProcedureTo Reset (Flush) a Connection Pool

Use the flush-connection-pool in remote mode to reinitialize all connections established in the specified connection pool. The JDBC connection pool or connector connection pool is reset to its initial state. Any existing live connections are destroyed, which means that the transactions associated with these connections are lost. The subcommand then recreates the initial connections for the pool, and restores the pool to its steady pool size.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Reset a connection pool by using theflush-connection-pool(1) subcommand.

Example 14–6 Resetting (Flushing) a Connection Pool

This example resets the JDBC connection pool named __TimerPool to its steady pool size.


asadmin> flush-connection-pool __TimerPool 
Command flush-connection-pool executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help flush-connection-pool at the command line.

ProcedureTo Update a JDBC Connection Pool

You can change all of the settings for an existing pool except its name. Use the get and set subcommands to view and change the values of the JDBC connection pool properties.

  1. List the JDBC connection pools by using the list-jdbc-connection-pools(1) subcommand.

  2. View the attributes of the JDBC connection pool by using the get subcommand.

    For example:


    asadmin get resources.jdbc-connection-pool.DerbyPool.property

  3. Set the attribute of the JDBC connection pool by using the set subcommand.

    For example:


    asadmin set resources.jdbc-connection-pool.DerbyPool.steady-pool-size=9

  4. (Optional) If needed, restart the server.

    Some parameters require server restart. See Configuration Changes That Require Server Restart.

ProcedureTo Delete a JDBC Connection Pool

Use the delete-jdbc-connection-pool subcommand in remote mode to delete an existing JDBC connection pool. Deleting a JDBC connection pool is a dynamic event and does not require server restart.

Before You Begin

Before deleting a JDBC connection pool, all associations to the resource must be removed.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the JDBC connection pools by using the list-jdbc-connection-pools(1) subcommand.

  3. If necessary, notify users that the JDBC connection pool is being deleted.

  4. Delete the connection pool by using the delete-jdbc-connection-pool(1) subcommand.

Example 14–7 Deleting a JDBC Connection Pool

This example deletes the JDBC connection pool named DerbyPool.


asadmin> delete-jdbc-connection-pool jdbc/DerbyPool
Command delete-jdbc-connection-pool executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jdbc-connection-pool at the command line.

Administering JDBC Resources

A JDBC resource, also known as a data source, provides an application with a means of connecting to a database. Typically, you create a JDBC resource for each database that is accessed by the applications deployed in a domain. Multiple JDBC resources can be specified for a database.

A JDBC resource is created by specifying the connection pool with which the resource will be associated . Use a unique Java Naming and Directory Interface (JNDI) name to identify the resource. For example, the JNDI name for the resource of a payroll database might be java:comp/env/jdbc/payrolldb.

The following tasks and information are used to administer JDBC resources:

ProcedureTo Create a JDBC Resource

Use the create-jdbc-resource subcommand in remote mode to create a JDBC resource. Creating a JDBC resource is a dynamic event and does not require server restart.

Because all JNDI names are in the java:comp/env subcontext, when specifying the JNDI name of a JDBC resource in the Administration Console, use only the jdbc/name format. For example, a payroll database might be specified as jdbc/payrolldb.

Before You Begin

Before creating a JDBC resource, you must first create a JDBC connection pool. For instructions, see To Create a JDBC Connection Pool.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a JDBC resource by using the create-jdbc-resource(1) subcommand.

    Information about properties for the subcommand is included in this help page.

  3. If necessary, notify users that the new resource has been created.

Example 14–8 Creating a JDBC Resource

This example creates a JDBC resource named DerbyPool.


asadmin> create-jdbc-resource --connectionpoolid DerbyPool jdbc/DerbyPool
Command create-jdbc-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-jdbc-resource at the command line.

ProcedureTo List JDBC Resources

Use the list-jdbc-resources subcommand in remote mode to list the existing JDBC resources.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List JDBC resources by using the list-jdbc-resources(1) subcommand.

Example 14–9 Listing JDBC Resources

This example lists JDBC resources for localhost.


asadmin> list-jdbc-resources
jdbc/__TimerPool
jdbc/DerbyPool
jdbc/__default
jdbc1
Command list-jdbc-resources executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-jdbc-resources at the command line.

ProcedureTo Update a JDBC Resource

You can enable or disable a JDBC resource by using the set subcommand. The JDBC resource is identified by its dotted name.

  1. List JDBC resources by using the list-jdbc-resources(1) subcommand.

  2. Modify the values for the specified JDBC resource by using the set(1) subcommand.

    For example:

Example 14–10 Updating a JDBC Resource

This example changes the res1 enabled setting to false.


asadmin>set resources.jdbc-resource.res1.enabled=false

ProcedureTo Delete a JDBC Resource

Use the delete-jdbc-resource subcommand in remote mode to delete an existing JDBC resource. Deleting a JDBC resource is a dynamic event and does not require server restart.

Before You Begin

Before deleting a JDBC resource, all associations with this resource must be removed.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List JDBC resources by using the list-jdbc-resources(1) subcommand.

  3. If necessary, notify users that the JDBC resource is being deleted.

  4. Delete a JDBC resource by using the delete-jdbc-resource(1) subcommand.

Example 14–11 Deleting a JDBC Resource

This example deletes a JDBC resource named DerbyPool.


asadmin> delete-jdbc-resource jdbc/DerbyPool
Command delete-jdbc-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jdbc-resource at the command line.

Integrating the JDBC Driver

After setting up the connection pool and resources, integrate the JDBC driver in either of the following ways:

Configuration Specifics for JDBC Drivers

GlassFish Server is designed to support connectivity to any database management system by using a corresponding JDBC driver.

JDBC Drivers, Full Support

The following JDBC driver and database combinations have been tested and are supported for container-managed persistence:

To see the most current list of supported JDBC drivers, refer to the Oracle GlassFish Server 3.0.1 Release Notes.

IBM DB2 Database Type 2 DataDirect JDBC Driver

The JAR file for DataDirect driver is db2.jar. Configure the connection pool using the following settings:

IBM DB2 Database Type 2 JDBC Driver

The JAR files for the DB2 driver are db2jcc.jar, db2jcc_license_cu.jar, and db2java.zip. Set your environment variables . For example:

LD_LIBRARY_PATH=/usr/db2user/sqllib/lib:${Java EE.home}/lib
DB2DIR=/opt/IBM/db2/V8.2
DB2INSTANCE=db2user
INSTHOME=/usr/db2user
VWSPATH=/usr/db2user/sqllib
THREADS_FLAG=native

Configure the connection pool using the following settings:

Java DB/Derby Type 4 JDBC Driver

The JAR file for the Java DB driver is derbyclient.jar. (Java DB is based upon Apache Derby.) Configure the connection pool using the following settings:

Microsoft SQL Server Database Type 4 DataDirect JDBC Driver

The JAR file for the DataDirect driver is sqlserver.jar. Configure the connection pool using the following settings:

MySQL Server Database Type 4 DataDirect JDBC Driver

The JAR file for the DataDirect driver is mysql.jar. Configure the connection pool using the following settings:

MySQL Server Database Type 4 JDBC Driver

The JAR file for the MySQL driver is mysql-connector-java-5.1.7-bin.jar. Configure the connection pool using the following settings:

Oracle 11 Database DataDirect JDBC Driver

The JAR file for the DataDirect driver is oracle.jar.

Note –

To make the Oracle driver behave in a Java EE-compliant manner, you must set this system property as true: oracle.jdbc.J2EE13Compliant=true.

Configure the connection pool using the following settings:

Oracle OCI Type 2 Driver for Oracle Databases

The JAR file for the OCI Oracle driver is ojdbc14.jar. Make sure that the shared library is available through LD_LIBRARY_PATH and that the ORACLE_HOME property is set. Configure the connection pool using the following settings:

Oracle 11 Database Thin Type 4 JDBC Driver

The JAR file for the Oracle driver is ojdbc6.jar.

Note –

When using this driver, keep in mind that you cannot insert more than 2000 bytes of data into a column. To circumvent this problem, use the OCI driver (JDBC type 2).

Note –

To make the Oracle driver behave in a Java EE-compliant manner, you must set this system property as true: oracle.jdbc.J2EE13Compliant=true.

Configure the connection pool using the following settings:

PostgreSQL Type 4 JDBC Driver

The JAR file for the PostgreSQL driver is postgresql-8.4-701.jdbc4.jar. Configure the connection pool using the following settings:

Sybase Database Type 4 DataDirect JDBC Driver

The JAR file for the DataDirect driver is sybase.jar. Configure the connection pool using the following settings:

JDBC Drivers, Limited Support

The following JDBC drivers can also be used with GlassFish Server, but have not been fully tested. Although Oracle offers no product support for these drivers, Oracle does offer limited support for the use of these drivers with GlassFish Server:

IBM Informix Type 4 Driver for DataDirect

Configure the connection pool using the following settings:

Inet Oraxo JDBC Driver for Oracle Databases

The JAR file for the Inet Oracle driver is Oranxo.jar. Configure the connection pool using the following settings:

Inet Merlia JDBC Driver for Microsoft SQL Server Databases

The JAR file for the Inet Microsoft SQL Server driver is Merlia.jar. Configure the connection pool using the following settings:

Inet Sybelux JDBC Driver for Sybase Databases

The JAR file for the Inet Sybase driver is Sybelux.jar. Configure the connection pool using the following settings:

JConnect Type 4 Driver for Sybase ASE 12.5 Databases

The JAR file for the Sybase driver is jconn4.jar. Configure the connection pool using the following settings:

Chapter 15 Administering EIS Connectivity

This chapter provides information and procedures for administering connections to enterprise information system (EIS) data in the Oracle GlassFish Server 3.0.1 environment by using the asadmin command-line utility.

Note –

If you installed the Web Profile, connector modules that use only outbound communication features and work-management that does not involve inbound communication features are supported. Other connector features are supported only in the Full Platform Profile.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

For information about database connectivity, see Chapter 14, Administering Database Connectivity .

About EIS Connectivity

Enterprise information system (EIS) refers to any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. Connection resources are used by applications and modules to access EIS software.)

The key elements of EIS connectivity are the following:

At runtime, the following sequence occurs when an application connects to an EIS:

  1. The application gets the connector resource (data source) associated with the EIS by making a call through the JNDI API.

    Using the JNDI name of the connector resource, the naming and directory service locates the resource. Each EIS resource specifies a connector connection pool.

  2. Using the connector resource, the application gets an EIS connection.

    GlassFish Server retrieves a physical connection from the connection pool that corresponds to the EIS resource. The pool defines connection attributes such as the EIS name, user name, and password.

  3. After the EIS connection is established, the application can read, modify, and add data to the EIS.

    The application accesses the EIS information by making calls to the JMS API.

  4. When the application is finished accessing the EIS, the application closes the connection and returns the connection to the connection pool.

Administering Connector Connection Pools

After a connector module has been deployed, you are ready to create a connector connection pool for it.

The following topics are addressed here:

ProcedureTo Create a Connector Connection Pool

Use the create-connector-connection-pool subcommand in remote mode to create a connector connection pool for a deployed connector module. When you are building the connector connection pool, certain data specific to the EIS will be required. The value in the mandatory --connectiondefintion option provides the EIS info.

Multiple connector resources can specify a single connection pool.

Creating a connector connection pool is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Server Restart.

Before You Begin

Before creating the connector connection pool, the connector must be installed.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create the connector connection pool by using the create-connector-connection-pool(1) subcommand.

    Information about properties for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

  4. (Optional) You can verify that a connection pool is usable by using the ping-connection-pool subcommand.

    For instructions, see To Contact (Ping) a Connection Pool.

Example 15–1 Creating a Connector Connection Pool

This example creates the new jms/qConnPool pool for the javax.jms.QueueConnectionFactory connector module.


asadmin> create-connector-connection-pool --steadypoolsize 20 --maxpoolsize 100 
--poolresize 2 --maxwait 60000 --raname jmsra --connectiondefinition 
javax.jms.QueueConnectionFactory jms/qConnPool  
Command create-connector-connection-pool executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-connection-pool at the command line.

ProcedureTo List Connector Connection Pools

Use the list-connector-connection-pools subcommand in remote mode to list the pools that have been created.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the connector connection pools by using the list-connector-connection-pools(1) subcommand.

Example 15–2 Listing Connector Connection Pools

This example lists the existing connector connection pools.


asadmin> list-connector-connection-pools
jms/qConnPool
Command list-connector-connection-pools executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-connection-pools at the command line.

ProcedureTo Connect to (Ping) or Reset (Flush) a Connector Connection Pool

Use the ping-connection-pool or flush-connection-pool subcommands in remote mode to perform these tasks on a connection pools. See To Contact (Ping) a Connection Pool or To Reset (Flush) a Connection Pool for instructions.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Connect to or reset a connector connection pool by using theflush-connection-pool(1) subcommand or the ping-connection-pool(1) subcommand.

ProcedureTo Update a Connector Connection Pool

Use the get and set subcommands to view and change the values of the connector connection pool properties.

  1. List the connector connection pools by using the list-connector-connection-pools(1) subcommand.

  2. View the properties of the connector connection pool by using the get(1) subcommand.

    For example:


    asadmin> get domain.resources.connector-connection-pool.conectionpoolname.*

  3. Set the property of the connector connection pool by using the set(1) subcommand.

    For example:


    asadmin> set domain.resources.connector-connection-pool
.conectionpoolname.validate-atmost-once-period-in-seconds=3

  4. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

ProcedureTo Delete a Connector Connection Pool

Use the delete-connector-connection-pool subcommand in remote mode to remove a connector connection pool.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the connector connection pools by using the list-connector-connection-pools(1) subcommand.

  3. If necessary, notify users that the connector connection pool is being deleted.

  4. Delete the connector connection pool by using the delete-connector-connection-pool(1) subcommand.

Example 15–3 Deleting a Connector Connection Pool

This example deletes the connection pool named jms/qConnPool.


asadmin> delete-connector-connection-pool --cascade=false jms/qConnPool
Command delete-connector-connection-pool executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-connection-pool at the command line.

Administering Connector Resources

A connector resource provides an application or module with the means of connecting to an EIS. Typically, you create a connector resource for each EIS that is accessed by the applications deployed in the domain.

The following topics are addressed here:

ProcedureTo Create a Connector Resource

Use the create-connector-resource subcommand in remote mode to register a new connector resource with its JNDI name.

Creating a connector resource is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Server Restart.

Before You Begin

Before creating a connector resource, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create the connector resource by using the create-connector-resource(1) subcommand.

    Information about properties for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 15–4 Creating a Connector Resource

This example creates a new resource named jms/qConnFactory for the jms/qConnPool connection pool.


asadmin> create-connector-resource --poolname jms/qConnPool 
--description "creating sample connector resource" jms/qConnFactory
Command create-connector-resource executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-resource at the command line.

ProcedureTo List Connector Resources

Use the list-connector-resources subcommand in remote mode to list the connector resources that have been created.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the connector connection pools by using the list-connector-resources(1) subcommand.

Example 15–5 Listing Connector Resources

This example lists the existing connector resources.


asadmin> list-connector-resources
jms/qConnFactory
Command list-connector-resources executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-resources at the command line.

ProcedureTo Update a Connector Resource

Use the get and set subcommands to view and change the values of the connector resource properties.

  1. List the connector connection pools by using the list-connector-resources(1) subcommand.

  2. View the properties of the connector resource by using the get(1) subcommand.

    For example


    asadmin> get domain.resources.connector-resource.jms/qConnFactory

  3. Set the property of the connector resource by using the set(1) subcommand.

    For example:


    asadmin> set domain.resources.connector-resource.jms/qConnFactory.enabled=true

  4. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

ProcedureTo Delete a Connector Resource

Use the delete-connector-resource subcommand in remote mode to remove a connector resource by specifying the JNDI name.

Before You Begin

Before deleting a resource, all associations with the resource must be removed.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the connector connection pools by using the list-connector-resources(1) subcommand.

  3. If necessary, notify users that the connector resource is being deleted.

  4. Delete the connector resource by using the delete-connector-resource(1) subcommand.

Example 15–6 Deleting a Connector Resource

This example deletes the jms/qConnFactory connector resource.


asadmin> delete-connector-resource jms/qConnFactory 
Command delete-connector-resources executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-resource at the command line.

Administering the Resource Adapter Configuration

The following topics are addressed here:

ProcedureTo Create Configuration Information for a Resource Adapter

Use the create-resource-adapter-config subcommand in remote mode to create configuration information for a resource adapter, also known as a connector module. You can run the subcommand before deploying a resource adapter, so that the configuration information is available at the time of deployment. The resource adapter configuration can also be created after the resource adapter is deployed. In this situation, the resource adapter is restarted with the new configuration.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create configuration information by using the create-resource-adapter-config(1) subcommand.

    Information about properties for the subcommand is included in this help page.

Example 15–7 Creating a Resource Adapter Configuration

This example creates the configuration for resource adapter ra1.


asadmin> create-resource-adapter-config --property foo=bar 
--threadpoolid mycustomerthreadpool ra1
Command create-resource-adapter-config executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-resource-adapter-config at the command line.

ProcedureTo List Resource Adapter Configurations

Use the list-resource-adapter-configs subcommand in remote mode to list the configuration information contained in the domain configuration file (domain.xml) for the specified resource adapter (connector module).

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the configurations for a resource adapter by using the list-resource-adapter-configs(1) subcommand.

Example 15–8 Listing Configurations for a Resource Adapter

This example lists all the resource adapter configurations.


asadmin> list-resource-adapter-configs
ra1
ra2
Command list-resource-adapter-configs executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-resource-adapter-configs at the command line.

ProcedureTo Update a Resource Adapter Configuration

Use the get and set subcommands to view and change the values of the resource adapter configuration properties.

  1. List the configurations for a resource adapter by using the list-resource-adapter-configs(1) subcommand.

  2. View the properties of the connector resource by using the get(1) subcommand.

    For example:


    asadmin> get domain.resources.resource-adapter-config.ra1.*

  3. Set the property of the connector resource by using the set(1) subcommand.

    For example:


    asadmin> set domain.resources.resource-adapter-config.ra1.raSpecificProperty=value

ProcedureTo Delete a Resource Adapter Configuration

Use the delete-resource-adapter-config subcommand in remote mode to delete the configuration information contained in the domain configuration file (domain.xml) for a specified resource adapter (connector module).

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the configurations for a resource adapter by using the list-resource-adapter-configs(1) subcommand.

  3. Delete the configuration for a resource adapter by using the delete-resource-adapter-config(1) subcommand.

Example 15–9 Deleting a Resource Adapter Configuration

This example deletes the configuration for resource adapter ra1.


asadmin> delete-resource-adapter-config ra1
Command delete-resource-adapter-config executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-resource-adapter-config at the command line.

Administering Connector Security Maps

The EIS is any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. The connector security map is used to map the application's credentials to the EIS credentials.

A security map applies to a particular connector connection pool. One or more named security maps can be associated with a connector connection pool.

The following topics are addressed here:

ProcedureTo Create a Connector Security Map

Use the create-connector-security-map subcommand in remote mode to create a security map for the specified connector connection pool. If the security map is not present, a new one is created. You can specify back-end EIS principals or back-end EIS user groups. The connector security map configuration supports the use of the wild card asterisk (*) to indicate all users or all user groups.

You can also use this subcommand to map the caller identity of the application (principal or user group) to a suitable EIS principal in container-managed transaction-based scenarios.

Before You Begin

For this subcommand to succeed, you must have first created a connector connection pool. For instructions, see To Create a Connector Connection Pool.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a connector security map by using the create-connector-security-map(1) subcommand.

    Information about the options for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 15–10 Creating a Connector Security Map

This example creates a connector security map securityMap1 for connection-pool1.


asadmin> create-connector-security-map --poolname connector-pool1 
--principals principal1, principal2 --mappedusername backend-username securityMap1
Command create-connector-security-map executed successfully

ProcedureTo List Connector Security Maps

Use the list-connector-security-maps subcommand in remote mode to list the existing security maps belonging to the specified connector connection pool. You can get a simple listing of the connector security maps for a connector connection pool, or you can get a more comprehensive listing that shows the principals of the map.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List existing connector connection pools by using the list-connector-connection-pools(1) subcommand.

  3. List the security maps for a specific connector connection pool by using the list-connector-security-maps(1) subcommand.

Example 15–11 Listing All Connector Security Maps for a Connector Connection Pool

This example lists the connector security maps associated with connector-Pool1.


asadmin> list-connector-security-maps connector-Pool1
securityMap1 
Command list-connector-security-maps executed successfully.
Example 15–12 Listing Principals for a Specific Security Map for a Connector Connection Pool

This example lists the principals associated with securityMap1.


asadmin> list-connector-security-maps --securitymap securityMap1 connector-Pool1
principal1
principal1
Command list-connector-security-maps executed successfully.
Example 15–13 Listing Principals of All Connector Security Maps for a Connector Connection Pool

This example lists the connector security maps associated with connector-Pool1.


asadmin> list-connector-security-maps --verbose connector-Pool1
securityMap1
principal1
principal1
Command list-connector-security-maps executed successfully.

ProcedureTo Update a Connector Security Map

Use the update-connector-security-map subcommand in remote mode to create or modify a security map for the specified connector connection pool.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List existing connector security maps by using the list-connector-security-maps(1) subcommand.

  3. Modify a security map for a specific connector connection pool by using the update-connector-security-map(1) subcommand.

  4. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 15–14 Updating a Connector Security Map

This example adds principals to securityMap1.


asadmin> update-connector-security-map --poolname connector-pool1 
--addprincipals principal1, principal2 securityMap1
Command update-connector-security-map executed successfully.

ProcedureTo Delete a Connector Security Map

Use the delete-connector-security-map subcommand in remote mode to delete a security map for the specified connector connection pool.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List existing connector connection pools by using the list-connector-connection-pools(1) subcommand.

  3. Delete a security map for a specific connector connection pool by using the delete-connector-security-map(1) subcommand.

    Information about options for this subcommand is included in this help page.

Example 15–15 Deleting a Connector Security Map

This example deletes securityMap1 from connector-pool1.


asadmin> delete-connector-security-map --poolname connector-pool1 securityMap1
Command delete-connector-security-map executed successfully

Administering Connector Work Security Maps

The EIS is any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. The connector work security map is used to is used to map the EIS credentials to the credentials of GlassFish Server security domain.

A security map applies to a particular connector connection pool. One or more named security maps can be associated with a connector connection pool.

The following topics are addressed here:

ProcedureTo Create a Connector Work Security Map

Use the create-connector-work-security-map subcommand in remote mode to map the caller identity of the work submitted by the connector module (resource adapter) EIS principal or EIS user group to a suitable principal or user group in the GlassFish Server security domain. One or more work security maps can be associated with a connector module.

The connector security map configuration supports the use of the wild card asterisk (*) to indicate all users or all user groups.

Before You Begin

Before creating a connector work security map, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create the connector work security map by using the create-connector-work-security-map(1) subcommand.

    Information about properties for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 15–16 Creating Connector Work Security Maps

The following examples create workSecurityMap1 and workSecurityMap2 for my-resource-adapter-name.


asadmin> create-connector-work-security-map --raname my-resource-adapter-name 
--principalsmap eis-principal-1=server-principal-1,eis-principal-2=server-principal-2, 
eis-principal-3=server-principal-1 workSecurityMap1


asadmin> create-connector-work-security-map --raname my-resource-adapter-name
--groupsmap eis-group-1=server-group-1,eis-group-2=server-group-2,
eis-group-3=server-group-1 workSecurityMap2
Command create-connector-work-security-map executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-work-security-map at the command line.

ProcedureTo List Connector Work Security Maps

Use the list-connector-work-security-maps subcommand in remote mode to list the work security maps that belong to a specific connector module.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the connector work security maps by using the list-connector-work-security-maps(1) subcommand.

Example 15–17 Listing the Connector Work Security Maps

This example lists the generic work security maps.


asadmin> list-connector-work-security-maps generic-ra
generic-ra-groups-map: EIS group=eis-group, mapped group=glassfish-group
generic-ra-principals-map: EIS principal=eis-bar, mapped principal=bar
generic-ra-principals-map: EIS principal=eis-foo, mapped principal=foo
Command list-connector-work-security-maps executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-work-security-maps at the command line.

ProcedureTo Update a Connector Work Security Map

Use the update-connector–work-security-map subcommand in remote to modify a work security map that belongs to a specific resource adapter (connector module).

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the connector work security maps by using the list-connector-work-security-maps(1) subcommand.

  3. If necessary, notify users that the connector work security map is being modified.

  4. Update a connector work security map by using the update-connector-work-security-map(1) subcommand.

Example 15–18 Updating a Connector Work Security Map

This example removes a principal from a work security map.


asadmin> update-connector-work-security-map --raname generic-ra 
--removeprincipals eis-foo generic-ra-principals-map
Command update-connector-work-security-map executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help update-connector-work-security-map at the command line.

ProcedureTo Delete a Connector Work Security Map

Use the delete-connector–work-security-map subcommand in remote mode to delete a work security map that belongs to a specific connector module (resource adapter).

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the connector work security maps by using the list-connector-work-security-maps(1) subcommand.

  3. Delete a connector work security map by using the delete-connector-work-security-map(1) subcommand.

Example 15–19 Deleting a Connector Work Security Map

This example deletes the worksecuritymap1 map from the my_ra connector module.


asadmin> delete-connector-work-security-map --raname my_ra worksecuritymap1
Command delete-connector-work-security-map executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-work-security-map at the command line.

Administering Administered Objects

Packaged within a connector module, an administered object provides specialized functionality for an application. For example, an administered object might provide access to a parser that is specific to the connector module and its associated EIS.

The following topics are addressed here:

ProcedureTo Create an Administered Object

Use the create-admin-object subcommand to create an administered object resource. When creating an administered object resource, name-value pairs are created, and the object is associated to a JNDI name.

Before You Begin

The resource adapter must be deployed before running this subcommand (jmsrar.rar).

  1. Create an administered object by using the create-admin-object(1) subcommand.

    Information about properties for the subcommand is included in this help page.

  2. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 15–20 Creating an Administered Object

For this example, the javax.jms.Queue resource type is obtained from the ra.xml file. The JNDI name of the new administered object is jms/samplequeue.


asadmin> create-admin-object --restype javax.jms.Queue --raname jmsra  --description "sample administered object" 
--property Name=sample_jmsqueue jms/samplequeueCommand create-admin-object executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-admin-object at the command line.

ProcedureTo List Administered Objects

Use the list-admin-object subcommand in remote mode to list the existing administered objects.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the administered objects by using the list-admin-objects(1) subcommand.

Example 15–21 Listing Administered Objects

This example lists the existing administered objects.


asadmin> list-admin-objects
jms/samplequeue
Command list-admin-objects executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-admin-object at the command line.

ProcedureTo Update an Administered Object

Use the get and set subcommands to view and change the values of the administered objects properties.

  1. List the administered objects by using the list-admin-objects(1) subcommand.

  2. View the properties of the administered object by using the get(1) subcommand.

    For example:


    asadmin> get domain.resources.admin-object-resource.jms/samplequeue.*

  3. Set the property of the administered object by using the set(1) subcommand.

    For example:


    asadmin> set domain.resources.admin-object-resource.jms/samplequeue.enabled=false

  4. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

ProcedureTo Delete an Administered Object

Use the delete-admin-object subcommand to delete an administered objects.

  1. List the administered objects by using the list-admin-objects(1) subcommand.

  2. If necessary, notify users that the administered object is being deleted.

  3. Delete an administered object by using the delete-admin-object(1) subcommand.

Example 15–22 Deleting an Administered Object

This example deletes the administered object with the JNDI name jms/samplequeue.


asadmin> delete-admin-object jms/samplequeue
Command delete-admin-object executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-admin-object at the command line.

Chapter 16 Administering Internet Connectivity

This chapter provides procedures for performing internet connectivity tasks in the Oracle GlassFish Server 3.0.1 environment by using the asadmin command-line utility.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About Internet Connectivity

The HTTP service provides functionality for deploying web applications and for making deployed web applications accessible by Internet clients. HTTP services are provided by two kinds of related objects: listeners and virtual servers.

The following topics are addressed here:

About HTTP Network Listeners

An HTTP listener, also known as a network listener, is a listen socket that has an Internet Protocol (IP) address, a port number, a server name, and a default virtual server. Each virtual server provides connections between the server and clients through one or more listeners. Each listener must have a unique combination of port number and IP address. For example, an HTTP listener can listen for a host on all configured IP addresses on a given port by specifying the IP address 0.0.0.0. Alternatively, the listener can specify a unique IP address for each listener while using the same port.

Because an HTTP listener is a combination of IP address and port number, you can have multiple HTTP listeners with the same IP address and different port numbers, or with different IP addresses and the same port number (if your host was configured to respond to these addresses). However, if an HTTP listener uses the 0.0.0.0 IP address, which listens on all IP addresses on a port, you cannot create HTTP listeners for additional IP addresses that listen on the same port for a specific IP address. For example, if an HTTP listener uses 0.0.0.0:8080 (all IP addresses on port 8080), another HTTP listener cannot use 1.2.3.4:8080. The host running the GlassFish Server typically has access to only one IP address. HTTP listeners typically use the 0.0.0.0 IP address and different port numbers, with each port number serving a different purpose. However, if the host does have access to more than one IP address, each address can serve a different purpose.

To access a web application deployed on GlassFish Server, use the URL http://localhost:8080/ (or https://localhost:8081/ for a secure application), along with the context root specified for the web application.

To access the Administration Console, use the URL https://localhost:4848/ or http://localhost:4848/asadmin/ (console default context root).

About Virtual Servers

A virtual server, sometimes called a virtual host, is an object that allows the same physical server to host multiple Internet domain names. All virtual servers hosted on the same physical server share the IP address of that physical server. A virtual server associates a domain name for a server (such as www.aaa.com) with the particular server on which GlassFish Server is running. Each virtual server must be registered with the DNS server for your network.

Note –

Do not confuse an Internet domain with the administrative domain of GlassFish Server.

For example, assume that you want to host the following domains on your physical server: www.aaa.com, www.bbb.com, and www.ccc.com. Assume that these domains are respectively associated with web modules web1, web2, and web3. This means that the following URLs are handled by your physical server:

http://www.aaa.com:8080/web1
http://www.bbb.com:8080/web2
http://www.ccc.com:8080/web3

The first URL is mapped to virtual server www.aaa.com, the second URL is mapped to virtual server www.bbb.com, and the third is mapped to virtual server www.ccc.com. For this mapping to work, www.aaa.com, www.bbb.com, and www.ccc.com must all resolve to your physical server’s IP address and each virtual server must be registered with the DNS server for your network. In addition, on a UNIX system, add these domains to your /etc/hosts file (if the setting for hosts in your /etc/nsswitch.conf file includes files).

Administering HTTP Network Listeners

By default, when GlassFish Server starts, the following HTTP listeners are started automatically:

The following table describes the GlassFish Server default ports for the listeners that use ports.

Table 16–1 Default Ports for Listeners

Listener 

Default Port 

Description 

Administrative server 

4848 

A domain’s administrative server is accessed by the Administration Console and the asadmin utility. For the Administration Console, specify the port number in the URL of the browser. When running an asadmin subcommand remotely, specify the port number by using the --port option.

HTTP 

8080 

The web server listens for HTTP requests on a port. To access deployed web applications and services, clients connect to this port. 

HTTPS 

8181 

Web applications configured for secure communications listen on a separate port. 

The following topics are addressed here:

ProcedureTo Create an Internet Connection

Use the subcommands in this procedure to create an internet connection with the full range of listener options. A network listener is created behind the scenes. For the shortcut version of this process , see To Create an HTTP Network Listener.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create an HTTP or HTTPS protocol by using the create-protocol(1) subcommand with the --securityenabled option.

    To use the built-in http-listener-1 HTTP protocol, or http-listener-2 HTTPS protocol, skip this step.

  3. Create an HTTP configuration by using the create-http(1) subcommand.

    To use a built-in protocol, skip this step.

  4. Create a transport by using the create-transport(1) subcommand.

    To use the built-in tcp transport, skip this step.

  5. (Optional) Create a thread pool by using the create-threadpool(1) subcommand.

    To avoid using a thread pool, or to use the built-in http-thread-pool thread pool, skip this step.

    For additional thread pool information, see Chapter 5, Administering Thread Pools.

  6. Create an HTTP listener by using the create-network-listener(1) subcommand.

    Specify a protocol and transport, optionally a thread pool.

  7. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

See Also

You can also view the full syntax and options of the subcommand by typing a command such as asadmin help create-http-listener at the command line.

Administering HTTP Protocols

Each HTTP listener has an HTTP protocol, which is created either by using the create-protocol subcommand or by using the built-in protocols that are applied when you follow the instructions in To Create an HTTP Network Listener.

The following topics are addressed here:

ProcedureTo Create a Protocol

Use the create-protocol subcommand in remote mode to create a protocol.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a protocol by using the create-protocol(1)

    Information about options and properties for the subcommand are included in this help page.

Example 16–1 Creating an HTTP Protocol

This example creates a protocol named http-1 with security enabled.


asadmin> create-protocol --securityenabled=true http-1
Command create-protocol executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-protocol at the command line.

ProcedureTo List Protocols

Use the list-protocols subcommand in remote mode to list the existing HTTP protocols.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing protocols by using the list-protocols(1) subcommand.

Example 16–2 Listing the Protocols

This example lists the existing protocols.


asadmin> list-protocols
admin-listener
http-1
http-listener-1
http-listener-2
Command list-protocols executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-protocols at the command line.

ProcedureTo Delete a Protocol

Use the delete-protocol subcommand in remote mode to remove a protocol.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Delete a protocol by using the delete-protocol(1) subcommand

Example 16–3 Deleting a Protocol

This example deletes the protocol named http-1.


asadmin> delete-protocol http-1
Command delete-protocol executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-protocol at the command line.

Administering HTTP Configurations

Each HTTP listener has an HTTP configuration, which is created either by using the create-http subcommand or by using the built-in configurations that are applied when you follow the instructions in To Create an HTTP Network Listener.

The following topics are addressed here:

ProcedureTo Create an HTTP Configuration

Use the create-http subcommand in remote mode to create a set of HTTP parameters for a protocol. This set of parameters configures one or more network listeners,

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create an HTTP configuration by using the create-http(1) subcommand.

    Information about options and properties for the subcommand are included in this help page.

Example 16–4 Creating an HTTP Configuration

This example creates an HTTP parameter set for the protocol named http-1.


asadmin> create-http --timeout-seconds 60 --default-virtual-server server http-1
Command create-http executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-http at the command line.

ProcedureTo Delete an HTTP Configuration

Use the delete-http subcommand in remote mode to remove HTTP parameters from a protocol.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Delete the HTTP parameters from a protocol by using the delete-http(1) subcommand.

Example 16–5 Deleting an HTTP Configuration

This example deletes the HTTP parameter set from a protocol named http-1.


asadmin> delete-http http-1
Command delete-http executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-http at the command line.

Administering HTTP Transports

Each HTTP listener has an HTTP transport, which is created either by using the create-transport subcommand or by using the built-in transports that are applied when you follow the instructions in To Create an HTTP Network Listener.

The following topics are addressed here:

ProcedureTo Create a Transport

Use the create-transport subcommand in remote mode to create a transport for a network listener,

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a transport by using the create-transport(1) subcommand.

    Information about options and properties for the subcommand are included in this help page.

Example 16–6 Creating a Transport

This example creates a transport named http1-trans that uses a non-default number of acceptor threads.


asadmin> create-transport --acceptorthreads 100 http1-trans
Command create-transport executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-transport at the command line.

ProcedureTo List Transports

Use the list-transports subcommand in remote mode to list the existing HTTP transports.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing transports by using the list-transports(1) subcommand.

Example 16–7 Listing HTTP Transports

This example lists the existing transports.


asadmin> list-transports
http1-trans
tcp
Command list-transports executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-transports at the command line.

ProcedureTo Delete a Transport

Use the delete-transport subcommand in remote mode to remove a transport.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Delete a transport by using the delete-transport(1) subcommand.

Example 16–8 Deleting a Transport

This example deletes he transport named http1-trans.


asadmin> delete-transport http1-trans
Command delete-transport executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-transport at the command line.

Administering HTTP Network Listeners

The following topics are addressed here:

ProcedureTo Create an HTTP Network Listener

Use the create-http-listener subcommand or the create-network-listener subcommand in remote mode to create a listener. These subcommands provide backward compatibility and also provide a shortcut for creating network listeners that use the HTTP protocol. Behind the scenes, a network listener is created as well as its associated protocol, transport, and HTTP configuration. This method is a convenient shortcut, but it gives access to only a limited number of options. If you want to specify the full range of listener options, follow the instructions in To Create an Internet Connection.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create an HTTP network listener by using the create-network-listener(1) subcommand or the create-http-listener(1) subcommand.

  3. If needed, restart the server.

    If you edit the special HTTP network listener named admin-listener, you must restart the server for changes to take effect. See To Restart a Domain.

Example 16–9 Creating an HTTP Listener

This example creates an HTTP listener named sampleListener that uses a non-default number of acceptor threads. Security is not enabled at runtime.


asadmin> create-http-listener --listeneraddress 0.0.0.0 
--listenerport 7272 --defaultvs server --servername host1.sun.com 
--acceptorthreads 100 --securityenabled=false 
--enabled=false sampleListener
Command create-http-listener executed successfully.
Example 16–10 Creating a Network Listener

This example a network listener named sampleListener that is not enabled at runtime:


asadmin> create-network-listener --listenerport 7272 protocol http-1
--enabled=false sampleListener
Command create-network-listener executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-http-listener or asadmin help create-network-listener at the command line.

ProcedureTo List HTTP Network Listeners

Use the list-http-listeners subcommand or the list-network-listeners subcommand in remote mode to list the existing HTTP listeners.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List HTTP listeners by using the list-http-listeners(1) or list-network-listeners(1) subcommand.

Example 16–11 Listing HTTP Listeners

This example lists the HTTP listeners. The same output is given if you use the list-network-listeners subcommand.


asadmin> list-http-listeners
admin-listener
http-listener-2
http-listener-1
Command list-http-listeners executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-http-listeners or asadmin help list-network-listeners at the command line.

ProcedureTo Update an HTTP Network Listener

  1. List HTTP listeners by using the list-http-listeners(1) or list-network-listeners(1) subcommand.

  2. Modify the values for the specified listener by using the set(1) subcommand.

    The listener is identified by its dotted name.

Example 16–12 Updating an HTTP Network Listener

This example changes security-enabled to false.


asadmin> set "server.network-config.protocols.protocol.
http-listener-2.security-enabled=false"server.network-config.
protocols.protocol.http-listener-2.security-enabled=false
Command set executed successfully.

ProcedureTo Delete an HTTP Network Listener

Use the delete-http-listener subcommand or the delete-network-listener subcommand in remote mode to delete an existing HTTP listener. This disables secure communications for the listener.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List HTTP listeners by using the list-http-listeners(1) subcommand.

  3. Delete an HTTP listener by using the delete-http-listener(1) or delete-network-listener(1) subcommand.

  4. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 16–13 Deleting an HTTP Listener

This example deletes the HTTP listener named sampleListener:


asadmin> delete-http-listener sampleListener
Command delete-http-listener executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-http-listener or asadmin help delete-network-listener at the command line.

ProcedureTo Configure an HTTP Listener for SSL

Use the create-ssl subcommand in remote mode to create and configure an SSL element in the specified listener. This enables secure communication for the listener.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Configure an HTTP listener by using the create-ssl(1) subcommand.

  3. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 16–14 Configuring an HTTP Listener for SSL

This example enables the HTTP listener named http-listener-1 for SSL:


asadmin> create-ssl --type http-listener --certname sampleCert http-listener-1
Command create-ssl executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-ssl at the command line.

ProcedureTo Delete SSL From an HTTP Listener

Use the delete-ssl subcommand in remote mode to delete the SSL element in the specified listener. This disables secure communications for the listener.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Delete SSL from an HTTP listener by using the delete-ssl(1) subcommand.

  3. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 16–15 Deleting SSL From an HTTP Listener

This example disables SSL for the HTTP listener named http-listener-1:


asadmin> delete-ssl --type http-listener http-listener-1
Command delete-http-listener executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-ssl at the command line.

ProcedureTo Assign a Default Virtual Server to an HTTP Listener

  1. In the Administration Console, open the HTTP Service component under the relevant configuration.

  2. Open the HTTP Listeners component under the HTTP Service component.

  3. Select or create a new HTTP listener.

  4. Select from the Default Virtual Server drop-down list.

    For more information, see To Assign a Default Web Module to a Virtual Server.

See Also

For details, click the Help button in the Administration Console from the HTTP Listeners page.

Administering Virtual Servers

A virtual server is a virtual web server that serves content targeted for a specific URL. Multiple virtual servers can serve content using the same or different host names, port numbers, or IP addresses. The HTTP service directs incoming web requests to different virtual servers based on the URL.

When you first install GlassFish Server, a default virtual server is created. You can assign a default virtual server to each new HTTP listener you create.

Web applications and Java EE applications containing web components (web modules) can be assigned to virtual servers during deployment. A web module can be assigned to more than one virtual server, and a virtual server can have more than one web module assigned to it. If you deploy a web application and don't specify any assigned virtual servers, the web application is assigned to all currently defined virtual servers. If you then create additional virtual servers and want to assign existing web applications to them, you must redeploy the web applications. For more information about deployment, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

You can define virtual server properties using the asadmin set command. For example:


asadmin> set server-config.http-service.virtual-server.MyVS.property.sso-enabled="true"

Some virtual server properties can be set for a specific web application. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

The following topics are addressed here:

ProcedureTo Create a Virtual Server

By default, when GlassFish Server starts, the following virtual servers are started automatically:

In a production environment, additional virtual servers provide hosting facilities for users and customers so that each appears to have its own web server, even though there is only one physical server.

Use the create-virtual-server subcommand in remote mode to create the named virtual server.

Before You Begin

A virtual server must specify an existing HTTP listener. Because the virtual server cannot specify an HTTP listener that is already being used by another virtual server, create at least one HTTP listener before creating a new virtual server.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a virtual server by using the create-virtual-server(1) subcommand.

    Information about properties for this subcommand is included in this help page.

  3. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 16–16 Creating a Virtual Server

This example creates a virtual server named sampleServer on localhost.


asadmin> create-virtual-server sampleServer
Command create-virtual-server executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-virutal-server at the command line.

ProcedureTo List Virtual Servers

Use the list-virtual-servers subcommand in remote mode to list the existing virtual servers.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List virtual servers by using the list-virtual-servers(1) subcommand.

Example 16–17 Listing Virtual Servers

This example lists the virtual servers for localhost.


asadmin> list-virtual-servers
sampleListener
admin-listener
http-listener-2
http-listener-1
Command list-http-listeners executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-virutal-servers at the command line.

ProcedureTo Update a Virtual Server

  1. List virtual servers by using the list-virtual-servers(1) subcommand.

  2. Modify the values for the specified virtual server by using the set(1) subcommand.

    The virtual server is identified by its dotted name.

ProcedureTo Delete a Virtual Server

Use the delete-virtual-server subcommand in remote mode to delete an existing virtual server.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List virtual servers by using the list-virtual-servers(1) subcommand.

  3. If necessary, notify users that the virtual server is being deleted.

  4. Delete a virtual server by using the delete-virtual-server(1) subcommand.

  5. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 16–18 Deleting a Virtual Server

This example deletes the virtual server named sampleServer from localhost.


asadmin> delete-virtual-server sampleServer
Command delete-virtual-server executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-virutal-server at the command line.

To Assign a Default Web Module to a Virtual Server

A default web module can be assigned to the default virtual server and to each new virtual server. To access the default web module for a virtual server, point the browser to the URL for the virtual server, but do not supply a context root. For example:

http://myvserver:3184/

A virtual server with no default web module assigned serves HTML or JavaServer Pages (JSP) content from its document root, which is usually domain-dir/docroot. To access this HTML or JSP content, point your browser to the URL for the virtual server, do not supply a context root, but specify the target file.

For example:

http://myvserver:3184/hellothere.jsp

ProcedureTo Assign a Virtual Server to an Application or Module

You can assign a virtual server to a deployed application or web module.

Before You Begin

The application or module must already be deployed. For more information, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.

  1. In the Administration Console, open the HTTP Service component under the relevant configuration.

  2. Open the Virtual Servers component under the HTTP Service component.

  3. Select the virtual server to which you want to assign a default web module.

  4. Select the application or web module from the Default Web Module drop-down list.

    For more information, see To Assign a Default Web Module to a Virtual Server.

Chapter 17 Administering the Object Request Broker (ORB)

GlassFish Server supports a standard set of protocols and formats that ensure interoperability. Among these protocols are those defined by CORBA. The Object Request Broker (ORB) is the central component of CORBA. The ORB provides the required infrastructure to identify and locate objects, handle connection management, deliver data, and request communication. This chapter describes how to configure the ORB and the IIOP listeners.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About the ORB

The Common Object Request Broker Architecture (CORBA) model is based on clients requesting services from distributed objects or servers through a well-defined interface by issuing requests to the objects in the form of remote method requests. A remote method request carries information about the operation that needs to be performed, including the object name (called an object reference) of the service provider and parameters, if any, for the invoked method. CORBA automatically handles network programming tasks such as object registration, object location, object activation, request de-multiplexing, error-handling, marshalling, and operation dispatching.

Configuring the ORB

A CORBA object never talks directly with another. Instead, the object makes requests through a remote stub to the Internet Inter-Orb Protocol (IIOP) running on the local host. The local ORB then passes the request to an ORB on the other host using IIOP. The remote ORB then locates the appropriate object, processes the request, and returns the results.

IIOP can be used as a Remote Method Invocation (RMI) protocol by applications or objects using RMI-IIOP. Remote clients of enterprise beans (EJB modules) communicate with GlassFish Server by using RMI-IIOP.

Administering IIOP Listeners

An IIOP listener is a listen socket that accepts incoming connections from the remote clients of enterprise beans and from other CORBA-based clients. Multiple IIOP listeners can be configured for GlassFish Server. For each listener, specify a port number (optional; default 1072), a network address, and security attributes (optional). If you create multiple listeners, you must assign a different port number for each listener.

The following topics are addressed here:

ProcedureTo Create an IIOP Listener

Use the create-iiop-listener subcommand in remote mode to create an IIOP listener.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create an IIOP listener by using the create-iiop-listener(1) subcommand.

    Information about the properties for the subcommand is included in this help page.

  3. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 17–1 Creating an IIOP Listener

This example creates an IIOP listener named sample_iiop_listener.


asadmin> create-iiop-listener --listeneraddress 192.168.1.100
--iiopport 1400 sample_iiop_listener
Command create-iiop-listener executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-iiop-listener at the command line.

ProcedureTo List IIOP Listeners

Use the list-iiop-listeners subcommand in remote mode to list the existing IIOP listeners.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the IIOP listeners by using the list-iiop-listeners(1) subcommand.

Example 17–2 Listing IIOP Listeners

This example lists all the IIOP listeners for the server instance.


asadmin> list-iiop-listeners
orb-listener-1
SSL
SSL_MUTUALAUTH
sample_iiop_listener
Command list-iiop-listeners executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-iiop-listeners at the command line.

ProcedureTo Update an IIOP Listener

  1. List the IIOP listeners by using the list-iiop-listeners(1) subcommand.

  2. Modify the values for the specified IIOP listener by using the set(1) subcommand.

    The listener is identified by its dotted name.

Example 17–3 Updating an IIOP Listener

This example changes SSL from enabled to disabled.


asadmin> set "server.iiop-service.iiop-listener.SSL.enabled"
server.iiop-service.iiop-listener.SSL.enabled=false
Command set executed successfully.

ProcedureTo Delete an IIOP Listener

Use the delete-iiop-listener subcommand in remote mode to delete an IIOP listener.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the IIOP listeners by using the list-iiop-listeners(1) subcommand.

  3. Delete an IIOP listener by using the delete-iiop-listener(1) subcommand.

  4. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 17–4 Deleting an IIOP Listener

This example deletes the IIOP listener named sample_iiop_listener.


asadmin> delete-iiop-listener sample_iiop_listener
 Command delete-iiop-listener executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-iiop-listener at the command line.

Chapter 18 Administering the JavaMail Service

GlassFish Server includes the JavaMail API along with JavaMail service providers that allow an application component to send email notifications over the Internet and to read email from IMAP and POP3 mail servers.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About JavaMail

The JavaMail API is a set of abstract APIs that model a mail system. The JavaMail API provides a platform-independent and protocol-independent framework to build mail and messaging applications and provide facilities for reading and sending electronic messages. Service providers implement particular protocols. Using the API you can add email capabilities to your applications. JavaMail provides access from Java applications to Internet Message Access Protocol (IMAP) and Simple Mail Transfer Protocol (SMTP) capable mail servers on your network or the Internet. The API does not provide mail server functionality; you must have access to a mail server to use JavaMail.

The JavaMail API is implemented as an optional package in the Java platform and is also available as part of the Java EE platform.

To learn more about the JavaMail API, consult the JavaMail web site.

Administering JavaMail Resources

When you create a mail session, the server-side components and applications are enabled to access JavaMail services with JNDI, using the session properties you assign for them. When creating a mail session, you can designate the mail hosts, the transport and store protocols, and the default mail user so that components that use JavaMail do not have to set these properties. Applications that are heavy email users benefit because GlassFish Server creates a single session object and makes the session available to any component that needs it.

JavaMail settings such as the following can be specified:

The following topics are addressed here:

ProcedureTo Create a JavaMail Resource

Use the create-javamail-resource subcommand in remote mode to create a JavaMail session resource. The JNDI name for a JavaMail session resource customarily includes the mail/ naming subcontext, For example: mail/MyMailSession.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a JavaMail resource by using the create-javamail-resource(1) subcommand.

    Information about the properties for the subcommand is included in this help page.

  3. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 18–1 Creating a JavaMail Resource

This example creates a JavaMail resource named mail/MyMailSession. The escape character (\) is used in the --fromaddress option to distinguish the dot (.) and at sign (@).


asadmin> create-javamail-resource --mailhost localhost 
--mailuser sample --fromaddress sample\@sun\.com mail/MyMailSession 
Command create-javamail-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-javamail-resource at the command line.

ProcedureTo List JavaMail Resources

Use the list-javamail-resources subcommand in remote mode to list the existing JavaMail session resources.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the JavaMail resources by using the list-javamail-resources(1) subcommand.

Example 18–2 Listing JavaMail Resources

This example lists the JavaMail resources on localhost.


asadmin> list-javamail-resources 
mail/MyMailSession
Command list-javamail-resources executed successfuly.
See Also

You can also view the full syntax and options of the subcommands by typing asadmin help list-javamail-resources at the command line.

ProcedureTo Update a JavaMail Resource

  1. List the JavaMail resources by using the list-javamail-resources(1) subcommand.

  2. Modify the values for the specified JavaMail source by using the set(1) subcommand.

    The resource is identified by its dotted name.

Example 18–3 Updating a JavaMail Resource

This example changes joeserver to joe.


asadmin> set server.resources.mail-resource.mail/
MyMailSession.user=joeserver.resources.mail-resource.mail/
MyMailSession.user=joe
Command set executed successfully.

ProcedureTo Delete a JavaMail Resource

Use the delete-javamail-resource subcommands in remote mode to delete a JavaMail session resource.

Before You Begin

References to the specified resource must be removed before running the delete-javamail-resource subcommands.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the JavaMail resources by using the list-javamail-resources(1) subcommands.

  3. Delete a JavaMail resource by using the delete-javamail-resource(1) subcommands.

  4. To apply your changes, restart GlassFish Server.

    See To Restart a Domain.

Example 18–4 Deleting a JavaMail Resource

This example deletes the JavaMail session resource named mail/MyMailSession.


asadmin> delete-javamail-resource  mail/MyMailSession 
Command delete-javamail-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-javamail-resource at the command line.

Chapter 19 Administering the Java Message Service (JMS)

Oracle implements the Java Message Service (JMS) API by integrating the OracleGlassFish Message Queue software into GlassFish Server. This chapter provides procedures for administering JMS resources in the GlassFish Server environment by using the asadmin command-line utility.

Note –

JMS resources are supported only in the Full Platform Profile of GlassFish Server, not in the Web Profile.

The following topics are addressed here:

Instructions for accomplishing the task in this chapter by using the Administration Console are contained in the Administration Console online help.

About the JMS

The JMS API is a messaging standard that allows Java EE applications and components to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.

GlassFish Server support for JMS messaging, in general, and for message-driven beans in particular, requires a JMS provider. GlassFish Server uses the Message Queue software as its native JMS provider, providing transparent JMS messaging support. This support is known within GlassFish Server as the JMS Service. JMS requires only minimal administration. When a JMS client accesses a JMS administered object for the first time, the client JVM retrieves the JMS configuration from GlassFish Server.

A JMS resource is a type of connector. Message Queue is integrated with GlassFish Server by means of a connector module, also known as a resource adapter, which is defined by the Java EE Connector Architecture Specification 1.6. Any Java EE components that are deployed to GlassFish Server exchange JMS messages by using the JMS provider that is integrated by the connector module. When a JMS resource is created in GlassFish Server, a connector resource is created in the background. Each JMS operation invokes the connector runtime and uses the Message Queue connector module in the background. GlassFish Server pools JMS connections automatically.

You can configure properties to be used by all JMS connections. If you update these properties at runtime, only those connection factories that are created after the properties are updated will apply the updated values. The existing connection factories will continue to have the original property values. For most values to take effect, GlassFish Server must be restarted. For instructions, see To Restart a Domain. The only property that can be updated without restarting GlassFish Server is the default JMS host.

Message Queue Broker Modes

Message Queue can be integrated with GlassFish Server in LOCAL, REMOTE, or EMBEDDED mode. These modes are represented by the JMS type attribute.

For information about administering Message Queue, see Oracle GlassFish Message Queue 4.4.2 Administration Guide.

Administering JMS Physical Destinations

Messages are delivered for routing and delivery to consumers by using physical destinations in the JMS provider. A physical destination is identified and encapsulated by an administered object (such as a Topic or Queue destination resource) that an application component uses to specify the destination of messages it is producing and the source of messages it is consuming. For instructions on configuring a destination resource, see To Create a Connection Factory or Destination Resource.

If a message-driven bean is deployed and the physical destination it listens to does not exist, GlassFish Server automatically creates the physical destination and sets the value of the maxNumActiveConsumers property to -1. However, it is good practice to create the physical destination beforehand. The first time that an application accesses a destination resource, Message Queue automatically creates the physical destination specified by the Name property of the destination resource. The physical destination is temporary and expires after a period specified by a Message Queue configuration property.

The following topics are addressed here:

ProcedureTo Create a JMS Physical Destination

For production purposes, always create physical destinations. During the development and testing phase, however, this step is not required. Use the create-jmsdest subcommand in remote mode to create a physical destination.

Because a physical destination is actually a Message Queue object rather than a server object, you use Message Queue broker commands to update properties. For information on Message Queue properties, see Oracle GlassFish Message Queue 4.4.2 Administration Guide.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a JMS physical destination by using the create-jmsdest(1) subcommand.

    Information about the properties for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 19–1 Creating a JMS Physical Destination

This example creates a queue named PhysicalQueue.


asadmin> create-jmsdest --desttype queue --property 
User=public:Password=public PhysicalQueue
Command create-jmsdest executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-jmsdest at the command line.

ProcedureTo List JMS Physical Destinations

Use the list-jmsdest subcommand in remote mode to list the existing JMS physical destinations.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.

Example 19–2 Listing JMS Physical Destinations

This example lists the physical destinations for the default server instance.


asadmin> list-jmsdest
PhysicalQueue queue {} 
PhysicalTopic topic {}
Command list-jmsdest executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-jmsdest at the command line.

ProcedureTo Purge Messages From a Physical Destination

Use the flush-jmsdest subcommand in remote mode to purge the messages from a physical destination in the specified target's JMS service configuration.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Purge messages from the a JMS physical destination by using the flush-jmsdest(1) subcommand.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 19–3 Flushing Messages From a JMS Physical Destination

This example purges messages from the queue named PhysicalQueue.


asadmin> flush-jmsdest --desttype queue PhysicalQueue
Command flush-jmsdest executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help flush-jmsdest at the command line.

ProcedureTo Delete a JMS Physical Destination

Use the delete-jmsdest subcommand in remote mode to remove the specified JMS physical destination.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.

  3. Delete the physical resource by using the delete-jmsdest(1) subcommand.

Example 19–4 Deleting a Physical Destination

This example deletes the queue named PhysicalQueue.


asadmin> delete-jmsdest --desttype queue PhysicalQueue
Command delete-jmsdest executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jmsdest at the command line.

Administering JMS Connection Factories and Destinations

The JMS API uses two kinds of administered objects. Connection factory objects allow an application to create other JMS objects programmatically. Destination objects serve as repositories for messages. How these objects are created is specific to each implementation of JMS. In GlassFish Server, JMS is implemented by performing the following tasks:

JMS applications use the Java Naming and Directory Interface (JNDI) API to access the connection factory and destination resources. A JMS application normally uses at least one connection factory and at least one destination. By studying the application or consulting with the application developer, you can determine what resources must be created. The order in which the resources are created does not matter.

GlassFish Server provides the following types of connection factory objects:

GlassFish Server provides the following types of destination objects:

The following topics are addressed here:

The subcommands in this section can be used to administer both the connection factory resources and the destination resources. For instructions on administering physical destinations, see Administering JMS Physical Destinations.

ProcedureTo Create a Connection Factory or Destination Resource

For each JMS connection factory that you create, GlassFish Server creates a connector connection pool and connector resource. For each JMS destination that you create, GlassFish Server creates a connector admin object resource. If you delete a JMS resource, GlassFish Server automatically deletes the connector resources.

Use the create-jms-resource command in remote mode to create a JMS connection factory resource or a destination resource.

Tip –

To specify the addresslist property (in the format host:mqport,host2:mqport,host3:mqport) for the asadmin create-jms-resource command, escape the : by using \\. For example, host1\\:mqport,host2\\:mqport,host3\\:mpqport. For more information about using escape characters, see the asadmin(1M) concepts page.

To update a JMS connection factory, use the set subcommand for the underlying connector connection pool, See To Update a Connector Connection Pool.

To update a destination, use the set subcommand for the admin object resource. See To Update an Administered Object.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a JMS resource by using the create-jms-resource(1) command.

    Information about the properties for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 19–5 Creating a JMS Connection Factory

This example creates a connection factory resource of type javax.jms.ConnectionFactory whose JNDI name is jms/DurableConnectionFactory. The ClientId property sets a client ID on the connection factory so that it can be used for durable subscriptions. The JNDI name for a JMS resource customarily includes the jms/ naming subcontext. 


asadmin> create-jms-resource --restype javax.jms.ConnectionFactory
--description "connection factory for durable subscriptions"
--property ClientId=MyID jms/DurableConnectionFactory
Command create-jms-resource executed successfully.
Example 19–6 Creating a JMS Destination

This example creates a destination resource whose JNDI name is jms/MyQueue.


asadmin> create-jms-resource --restype javax.jms.Queue 
--property Name=PhysicalQueue jms/MyQueue
Command create-jms-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-jms-resource at the command line.

ProcedureTo List JMS Resources

Use the list-jms-resources subcommand in remote mode to list the existing connection factory and destination resources.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing JMS resources by using the list-jms-resources(1) subcommand.

Example 19–7 Listing All JMS Resources

This example lists all the existing JMS connection factory and destination resources.


asadmin> list-jms-resources
jms/Queue
jms/ConnectionFactory
jms/DurableConnectionFactory
jms/Topic
Command list-jms-resources executed successfully
Example 19–8 Listing a JMS Resources of a Specific Type

This example lists the resources for the resource type javax.


asadmin> list-jms-resources --restype javax.jms.TopicConnectionFactory 
jms/DurableTopicConnectionFactory 
jms/TopicConnectionFactory 
Command list-jms-resources executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-jms-resources at the command line.

ProcedureTo Delete a Connection Factory or Destination Resource

Use the delete-jms-resource subcommand in remote mode to remove the specified connection factory or destination resource.

Before You Begin

Ensure that you remove all references to the specified JMS resource before running this subcommand.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing JMS resources by using the list-jms-resources(1) subcommand.

  3. Delete the JMS resource by using the delete-jms-resource(1) subcommand.

Example 19–9 Deleting a JMS Resource

This example deletes the jms/Queue resource.


asadmin> delete-jms-resource jms/Queue
Command delete-jms-resource executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jms-resource at the command line.

Administering JMS Hosts

A JMS host represents a Message Queue broker. JMS contains a JMS hosts list (the AddressList property) that contains all the JMS hosts that are used by GlassFish Server. The JMS hosts list is populated with the hosts and ports of the specified Message Queue brokers and is updated whenever a JMS host configuration changes. When you create JMS resources or deploy message driven beans, the resources or beans inherit the JMS hosts list.

One of the hosts in the JMS hosts list is designated the default JMS host. GlassFish Server starts the default JMS host when the Message Queue broker mode is configured as type LOCAL.

The following topics are addressed here:

ProcedureTo Create a JMS Host

A default JMS host, default_JMS_host, is provided by GlassFish Server. The default JMS host is used by GlassFish Server to perform all Message Queue broker administrative operations, such as creating and deleting JMS destinations.

Creating a new JMS host is not often necessary and is a task for advanced users. Use the create-jms-host subcommand in remote mode to create an additional JMS host.

Because a JMS is actually a Message Queue object rather than a server object, you use Message Queue broker commands to update properties. For information on Message Queue properties, see Oracle GlassFish Message Queue 4.4.2 Administration Guide.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create the JMS host by using the create-jms-host(1) subcommand.

    Information about the properties for this the subcommand is included in this help page.

Example 19–10 Creating a JMS Host

This example creates a JMS host named MyNewHost.


asadmin> create-jms-host --mqhost pigeon --mqport 7677 MyNewHost
Command create-jms-host executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-jms-host at the command line.

ProcedureTo List JMS Hosts

Use the list-jms-hosts subcommand in remote mode to list the existing JMS hosts.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the JMS hosts by using the list-jms-hosts(1) subcommand.

Example 19–11 Listing JMS Hosts

The following subcommand lists the existing JMS hosts.


asadmin> list-jms-hosts
default_JMS_host
MyNewHost
Command list-jmsdest executed successfully

ProcedureTo Update a JMS Host

  1. List the JMS hosts by using the list-jms-hosts(1) subcommand.

  2. Use the set(1) subcommand to modify a JMS host.

Example 19–12 Updating a JMS Host

This example changes the value of the host attribute of the default JMS host. By default this value is localhost.


asadmin>  set server-config.jms-service.jms-host.default_JMS_host.host=
"archie.india.sun.com"
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help set at the command line.

ProcedureTo Delete a JMS Host

Use the delete-jms-host subcommand in remote mode to delete a JMS host from the JMS service. If you delete the only JMS host, you will not be able to start the Message Queue broker until you create a new JMS host.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the JMS hosts by using the list-jms-hosts(1) subcommand.

  3. Delete a JMS host by using the delete-jms-host(1) subcommand.

Example 19–13 Deleting a JMS Host

This example deletes a JMS host named MyNewHost.


asadmin> delete-jms-host MyNewHost
Command delete-jms-host executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jms-host at the command line.

Administering Connection Addressing

Certain JMS resources use the JMS host list (AddressList) configuration, which is populated with the hosts and ports of the JMS hosts defined in GlassFish Server. The JMS host list is updated whenever a JMS host configuration changes. The JMS host list is inherited by any JMS resource when it is created, and by any message-driven bean when it is deployed.

In the Message Queue software, the AddressList property is called imqAddressList.

The following topics are addressed here:

Setting JMS Connection Pooling

GlassFish Server pools JMS connections automatically. When a JMS connection pool is created, there is one ManagedConnectionFactory instance associated with it. If you configure the AddressList property as a ManagedConnectionFactory property, the AddressList configuration in the ManagedConnectionFactory value takes precedence over the value defined in GlassFish Server.

Use the create-connector-connection-pool subcommand to manage an existing pool. For instructions, see Administering Connector Connection Pools.

By default, the addresslist-behavior JMS service attribute is set to random. This means that each physical connection (ManagedConnection) created from the ManagedConnectionFactory selects its primary broker in a random way from the AddressList property.

To specify whether GlassFish Server tries to reconnect to the primary broker if the connection is lost, set the reconnect-enabled attribute in the JMS service by using the set(1) subcommand. To specify the number of retries and the time between retries, set the reconnect-attempts and reconnect-interval-in-seconds attributes, respectively.

If reconnection is enabled and the primary broker fails, GlassFish Server tries to reconnect to another broker in the JMS host list (AddressList). The logic for scanning is decided by two JMS service attributes, addresslist-behavior and addresslist-iterations. You can override these settings by using JMS connection factory settings. The Oracle Message Queue software transparently transfers the load to another broker when the failover occurs. JMS semantics are maintained during failover.

Accessing Remote Servers

Changing the provider and host to a remote system causes all JMS applications to run on the remote server. To use both the local server and one or more remote servers, create a connection factory resource with the AddressList property. This creates connections that access remote servers.

Configuring Resource Adapters for JMS

GlassFish Server implements JMS by using a system resource adapter named jmsra. When you create JMS resources, GlassFish Server automatically creates connector resources. The resource adapter can be configured to indicate whether the JMS provider supports XA or not. It is possible to indicate what mode of integration is possible with the JMS provider.

Two modes of integration are supported by the resource adapter. The first one uses JNDI as the means of integration. In this situation, administered objects are set up in the JMS provider's JNDI tree and will be looked up for use by the generic resource adapter. If that mode is not suitable for integration, it is also possible to use the Java reflection of JMS administered object javabean classes as the mode of integration.

Generic resource adapter 1.6 for JMS is a Java EE connector 2.0 resource adapter that can wrap the JMS client library of external JMS providers such as IBM WebSphere MQ, Tibco EMS, and Sonic MQ among others. This integrates any JMS provider with a Java EE 6 application server, such as GlassFish Server. The adapter is a .rar archive that can be deployed and configured using Java EE 6 application server administration tools.

ProcedureTo Configure the Generic Resource Adapter

Before deploying the generic resource adapter, JMS client libraries must be made available to GlassFish Server. For some JMS providers, client libraries might also include native libraries. In such cases, these native libraries must be made available to any GlassFish Server JVMs.

  1. Deploy the generic resource adapter the same way you would deploy a connector module.

  2. Create a connector connection pool.

    See To Create a Connector Connection Pool.

  3. Create a connector resource.

    See To Create a Connector Resource.

  4. Create an administered object resource.

    See To Create an Administered Object.

  5. Make the following changes to the security GlassFish Server policy files:

    • Modify the sjsas_home/domains/domain1/config/server.policy file to add the following:


      java.util.logging.LoggingPermission "control"

    • Modify the sjsas_home/lib/appclient/client.policy file to add permission:


      javax.security.auth.PrivateCredentialPermission 
"javax.resource.spi.security.PasswordCredential ^ \"^\"","read":

Troubleshooting JMS

When you start GlassFish Server, the JMS service is available but is not loaded until it is needed (for example, when you create a JMS resource). Use the jms-ping(1)subcommand to check if the JMS service is running or, if it is not yet running, to start it. If thejms-ping subcommand is unable to contact a built-in JMS service, an error message is displayed.

If you encounter problems, consider the following:

Chapter 20 Administering the Java Naming and Directory Interface (JNDI) Service

The Java Naming and Directory Interface (JNDI) API is used for accessing different kinds of naming and directory services. Java EE components locate objects by invoking the JNDI lookup method.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About JNDI

By making calls to the JNDI API, applications locate resources and other program objects. A resource is a program object that provides connections to systems, such as database servers and messaging systems. A JDBC resource is sometimes referred to as a data source. Each resource object is identified by a unique, people-friendly name, called the JNDI name. A resource object and its JNDI name are bound together by the naming and directory service, which is included with the GlassFish Server.

When a new name-object binding is entered into the JNDI, a new resource is created.

The following topics are addressed here:

Java EE Naming Environment

JNDI names are bound to their objects by the naming and directory service that is provided by a Java EE server. Because Java EE components access this service through the JNDI API, the object usually uses its JNDI name. For example, the JNDI name of the PointBase database is jdbc/Pointbase. At startup, the GlassFish Server reads information from the configuration file and automatically adds JNDI database names to the name space, one of which is jdbc/Pointbase.

Java EE application clients, enterprise beans, and web components must have access to a JNDI naming environment.

The application component's naming environment is the mechanism that allows customization of the application component's business logic during deployment or assembly. This environment allows you to customize the application component without needing to access or change the source code off the component. A Java EE container implements the provides the environment to the application component instance as a JNDI naming context.

How the Naming Environment and the Container Work Together

The application component's environment is used as follows:

Each application component defines its own set of environment entries. All instances of an application component within the same container share the same environment entries. Application component instances are not allowed to modify the environment at runtime.

Naming References and Binding Information

A resource reference is an element in a deployment descriptor that identifies the component’s coded name for the resource. For example, jdbc/SavingsAccountDB. More specifically, the coded name references a connection factory for the resource.

The JNDI name of a resource and the resource reference name are not the same. This approach to naming requires that you map the two names before deployment, but it also decouples components from resources. Because of this decoupling, if at a later time the component needs to access a different resource, the name does not need to change. This flexibility makes it easier for you to assemble Java EE applications from preexisting components.

The following table lists JNDI lookups and their associated resource references for the Java EE resources used by the GlassFish Server.

Table 20–1 JNDI Lookup Names and Their Associated References

JNDI Lookup Name 

Associated Resource Reference 

java:comp/env

Application environment entries 

java:comp/env/jdbc

JDBC DataSource resource manager connection factories 

java:comp/env/ejb

EJB References 

java:comp/UserTransaction

UserTransaction references 

java:comp/env/mail

JavaMail Session Connection Factories 

java:comp/env/url

URL Connection Factories 

java:comp/env/jms

JMS Connection Factories and Destinations 

java:comp/ORB

ORB instance shared across application components 

Administering JNDI Resources

Within GlassFish Server, you can configure your environment for custom and external JNDI resources. A custom resource accesses a local JNDI repository; an external resource accesses an external JNDI repository. Both types of resources need user-specified factory class elements, JNDI name attributes, and so on.

Administering Custom JNDI Resources

A custom resource specifies a custom server-wide resource object factory that implements the javax.naming.spi.ObjectFactory interface.

The following topics are addressed here:

ProcedureTo Create a Custom JNDI Resource

Use the create-custom-resource subcommand in remote mode to create a custom resource.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a custom resource by using the create-custom-resource(1) subcommand.

    Information on properties for the subcommand is contained in this help page.

  3. Restart GlassFish Server.

    See To Restart a Domain.

Example 20–1 Creating a Custom Resource

This example creates a custom resource named sample-custom-resource.


asadmin> create-custom-resource --restype topic --factoryclass com.imq.topic 
sample_custom_resource
Command create-custom-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-custom-resource at the command line.

ProcedureTo List Custom JNDI Resources

Use the list-custom-resources subcommand in remote mode to list the existing custom resources.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the custom resources by using the list-custom-resources(1) subcommand.

Example 20–2 Listing Custom Resources

This example lists the existing custom resources.


asadmin> list-custom-resources
sample_custom_resource01 
sample_custom_resource02 
Command list-custom-resources executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-custom-resources at the command line.

ProcedureTo Update a Custom JNDI Resource

  1. List the custom resources by using the list-custom-resources(1) subcommand.

  2. Use the set(1) subcommand to modify a custom JNDI resource.

Example 20–3 Updating a Custom JNDI Resource

This example modifies a custom resource.


asadmin> set server.resources.custom-resource.custom
/my-custom-resource.property.value=2010server.resources.custom-resource.custom
/my-custom-resource.property.value=2010

ProcedureTo Delete a Custom JNDI Resource

Use the delete-custom-resource subcommand in remote mode to delete a custom resource.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the custom resources by using the list-custom-resources(1) subcommand.

  3. Delete a custom resource by using the delete-custom-resource(1) subcommand.

Example 20–4 Deleting a Custom Resource

This example deletes a custom resource named sample-custom-resource.


asadmin> delete-custom-resource sample_custom_resource
Command delete-custom-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-custom-resource at the command line.

Administering External JNDI Resources

Applications running on GlassFish Server often require access to resources stored in an external JNDI repository. For example, generic Java objects might be stored in an LDAP server according to the Java schema. External JNDI resource elements let you configure such external resource repositories.

The following topics are addressed here:

ProcedureTo Register an External JNDI Resource

Use the create-jndi-resource subcommand in remote mode to register an external JNDI resource.

Before You Begin

The external JNDI factory must implement the javax.naming.spi.InitialContextFactory interface.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Register an external JNDI resource by using the create-jndi-resource(1) subcommand.

    Information on properties for the subcommand is contained in this help page.

  3. Restart GlassFish Server.

    See To Restart a Domain.

Example 20–5 Registering an External JNDI Resource

In This example sample_jndi_resource is registered.


asadmin> create-jndi-resource --jndilookupname sample_jndi 
--restype queue --factoryclass sampleClass --description "this is a sample jndi 
resource" sample_jndi_resource
Command create-jndi-resource executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-jndi-resource at the command line.

ProcedureTo List External JNDI Resources

Use the list-jndi-resources subcommand in remote mode to list all existing JNDI resources.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing JNDI resources by using thelist-jndi-resources(1) subcommand.

Example 20–6 Listing JNDI Resources

This example lists the JNDI resources.


asadmin> list-jndi-resources
jndi_resource1
jndi_resource2
jndi_resource3
Command list-jndi-resources executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-jndi-resources at the command line.

ProcedureTo List External JNDI Entries

Use the list-jndi-entries subcommand in remote mode to browse and list the entries in the JNDI tree. You can either list all entries, or you can specify the JNDI context or subcontext to list specific entries.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the JNDI entries for a configuration by using the list-jndi-entries(1) subcommand.

Example 20–7 Listing JNDI Entries

This example lists all the JNDI entries for the naming service.


asadmin> list-jndi-entries
jndi_entry03
jndi_entry72
jndi_entry76
Command list-jndi-resources executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-jndi-entries at the command line.

ProcedureTo Update an External JNDI Resource

  1. List the existing JNDI resources by using thelist-jndi-resources(1) subcommand.

  2. Use the set(1) subcommand to modify an external JNDI resource.

Example 20–8 Updating an External JNDI Resource

This example modifies an external resource.


asadmin> set server.resources.external-jndi-resource.my-jndi-resource.
jndi-lookup-name=bar server.resources.external-jndi-resource.my-jndi-resource.jndi-lookup-name=bar

ProcedureTo Delete an External JNDI Resource

Use the delete-jndi-resource subcommand in remote mode to remove a JNDI resource.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Remove an external JNDI entry by using the delete-jndi-resource(1) subcommand.

Example 20–9 Deleting an External JNDI Resource

This example deletes an external JNDI resource:


asadmin> delete-jndi-resource jndi_resource2
Command delete-jndi-resource executed successfully.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jndi-resource at the command line.

Example of Using an External JNDI Resource

<resources>
 <!-- external-jndi-resource element specifies how to access Java EE resources
 -- stored in an external JNDI repository. This example
 -- illustrates how to access a java object stored in LDAP.
 -- factory-class element specifies the JNDI InitialContext factory that
 -- needs to be used to access the resource factory. property element
 -- corresponds to the environment applicable to the external JNDI context
 -- and jndi-lookup-name refers to the JNDI name to lookup to fetch the
 -- designated (in this case the java) object.
 -->
  <external-jndi-resource jndi-name="test/myBean"
      jndi-lookup-name="cn=myBean"
      res-type="test.myBean"
      factory-class="com.sun.jndi.ldap.LdapCtxFactory">
    <property name="PROVIDER-URL" value="ldap://ldapserver:389/o=myObjects" />
    <property name="SECURITY_AUTHENTICATION" value="simple" />
    <property name="SECURITY_PRINCIPAL", value="cn=joeSmith, o=Engineering" />
    <property name="SECURITY_CREDENTIALS" value="changeit" />
  </external-jndi-resource>
</resources>

Chapter 21 Administering Transactions

This chapter discusses how to manage the transaction service for the Oracle GlassFish Server environment by using the asadmin command-line utility. Instructions for manually recovering transactions are also included.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help. For additional information on configuring the transaction service, transaction logging, and distributed transaction recovery, see Chapter 15, Using the Transaction Service, in Oracle GlassFish Server 3.0.1 Application Development Guide.

About Transactions

A transaction is a series of discreet actions in an application that must all complete successfully. By enclosing one or more actions in an indivisible unit of work, a transaction ensures data integrity and consistency. If all actions do not complete, the changes are rolled back.

For example, to transfer funds from a checking account to a savings account, the following steps typically occur:

  1. Check to see if the checking account has enough money to cover the transfer.

  2. Debit the amount from the checking account.

  3. Credit the amount to the savings account.

  4. Record the transfer to the checking account log.

  5. Record the transfer to the savings account log.

These steps together are considered a single transaction.

If all the steps complete successfully, the transaction is committed. If any step fails, all changes from the preceding steps are rolled back, and the checking account and savings account are returned to the states they were in before the transaction started. This type of event is called a rollback. A normal transaction ends in either a committed state or a rolled back state.

The following elements contribute to reliable transaction processing by implementing various APIs and functionalities:

Managing the Transaction Service

You can roll back a single transaction by using the asadmin subcommands described in this section. To do so, the transaction service must be stopped (and later restarted), allowing you to see the active transactions and correctly identify the one that needs to be rolled back.

For instructions on configuring the transaction service and setting up automatic recovery, see Chapter 15, Using the Transaction Service, in Oracle GlassFish Server 3.0.1 Application Development Guide.

The following topics are addressed here:

ProcedureTo Stop the Transaction Service

Use the freeze-transaction-service subcommand in remote mode to stop the transaction service. When the transaction service is stopped, all in-flight transactions are immediately suspended. You must stop the transaction service before rolling back any in-flight transactions.

Running this subcommand on a stopped transaction subsystem has no effect. The transaction service remains suspended until you restart it by using the unfreeze-transaction-service subcommand.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Stop the transaction service by using the freeze-transaction-service(1) subcommand.

Example 21–1 Stopping the Transaction Service

This example stops the transaction service.


asadmin> freeze-transaction-service
Command freeze-transaction-service executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help freeze-transaction-service at the command line.

ProcedureTo Roll Back a Transaction

In some situations, you might want to roll back a particular transaction. Before you can roll back a transaction, you must first stop the transaction service so that transaction operations are suspended. Use the rollback-transaction subcommand in remote mode to roll back a specific transaction.

Before You Begin

Stop the transaction service before rolling back an in-flight transaction.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Identify the ID of the transaction you want to roll back.

    To see a list of IDs of active transactions, use the get subcommand to get the monitoring data for the activeids statistic. See Transaction Service Statistics.

  3. Roll back the transaction by using the rollback-transaction(1) subcommand.

Example 21–2 Rolling Back a Transaction

This example rolls back the transaction with transaction ID 0000000000000001_00.


asadmin> rollback-transaction 0000000000000001_00
Command rollback-transaction executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help rollback-transaction at the command line.

ProcedureTo Restart the Transaction Service

Use the unfreeze-transaction-service subcommand in remote mote to resume all the suspended in-flight transactions. Run this subcommand to restart the transaction service after it has been frozen.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Restart the suspended transaction service by using the unfreeze-transaction-service(1) subcommand.

Example 21–3 Restarting the Transaction Service

This example restarts the transaction service after it has been frozen.


asadmin> unfreeze-transaction-service
Command unfreeze-transaction-service executed successfully
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help unfreeze-transaction-service at the command line.

Recovering Transactions

There are some situations where the commit or rollback operations might be interrupted, typically because the server crashed or a resource manager crashed. Crash situations can leave some transactions stranded between steps. GlassFish Server is designed to recover from these failures and complete the transactions upon server startup. If the failed transaction spans multiple servers, the server that started the transaction can contact the other servers to get the outcome of the transaction. If the other servers are unreachable, the transaction uses heuristic decision information to determine the outcome. The transactions are resolved upon server startup.

ProcedureTo Manually Recover Transactions

Use the recover-transactions subcommand in remote mode to manually recover transactions that were pending when a resource on the server failed.

For a standalone server, do not use manual transaction recovery to recover transactions after a server failure. For a standalone server, manual transaction recovery can recover transactions only when a resource fails, but the server is still running. If a standalone server fails, only the full startup recovery process can recover transactions that were pending when the server failed.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Manually recover transactions by using the recover-transactions(1) subcommand.

Example 21–4 Manually Recovering Transactions

This example performs manual recovery of transactions on sampleserver.


asadmin recover-transactions sampleserver
Transaction recovered.
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help recover-transactions at the command line.