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.
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:
Database. The repository where data is stored for an enterprise. Java EE applications access relational databases through the JDBC API. For administration procedures, see Setting Up the Database.
JDBC Connection Pool. A JDBC connection pool is a group of reusable connections for a particular database. For administration procedures, see Administering JDBC Connection Pools.
JDBC Resource. A JDBC resource (data source) provides applications with a means of connecting to a database. To create a JDBC resource, specify the connection pool with which it is associated. Multiple JDBC resources can specify a single connection pool. A JDBC resource is identified by its Java Naming and Directory Interface (JNDI) name. For administration procedures, see Administering JDBC Resources.
JDBC Driver. A database driver is a software component that enables a Java application to interact with a database connectivity API . Each database requires its own driver. For administration procedures, see Integrating the JDBC Driver.
At runtime, the following sequence occurs when an application connects to a database:
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.
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.
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.
When the application is finished accessing the database, the application closes the connection and returns the connection to the connection pool.
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:
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.
Install a supported JDBC driver for the database product.
For a list of drivers supported by GlassFish Server, see Configuration Specifics for JDBC Drivers.
Make the JDBC driver JAR file accessible to the domain administration server (DAS).
Create the database.
The application provider usually delivers scripts for creating and populating the database.
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.
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.
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).
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help start-database at the command line.
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.
If necessary, notify users that the database is being stopped.
Stop the database by using the stop-database(1) subcommand.
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. |
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
You can also view the full syntax and options of the subcommand by typing asadmin help stop-database at the command line.
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:
Script to start the network server
Script to stop the network server
Interactive JDBC scripting tool
Script to view all or part of the DDL for a database
Script to display versioning information about the Java DB environment
Script to execute commands on the NetworkServerControl API
Ensure that the JAVA_HOME environment variable specifies the directory where the JDK is installed.
Set the JAVADB_HOME environment variable to point to the as-install/derby directory.
For more information about these utilities, see the following documentation:
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:
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:
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:
Database vendor name
Resource type, such as javax.sql.DataSource (local transactions only) javax.sql.XADataSource (global transactions)
Data source class name
Required properties, such as the database name (URL), user name, and password
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 creating the connection pool, you must first install and integrate the database and its associated JDBC driver. For instructions, see Setting Up the Database.
Ensure that the server is running.
Remote subcommands require a running server.
Create the JDBC connection pool by using the create-jdbc-connection-pool(1) subcommand.
(Optional) If needed, restart the server.
Some parameters require server restart. See Configuration Changes That Require Server Restart.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jdbc-connection-pool at the command line.
Use the list-jdbc-connection-pools subcommand in remote mode to list all existing JDBC connection pools.
Ensure that the server is running.
Remote subcommands require a running server.
List the JDBC connection pools by using the list-jdbc-connection-pools(1) subcommand.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jdbc-connection-pools at the command line.
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 can contact a connection pool, the connection pool must be created with authentication, and the server or database must be running.
Ensure that the server is running.
Remote subcommands require a running server.
Ping a connection pool by using the ping-connection-pool(1) subcommand.
This example tests to see if the DerbyPool connection pool is usable.
asadmin> ping-connection-pool DerbyPool Command ping-connection-pool executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help ping-connection-pool at the command line.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Reset a connection pool by using theflush-connection-pool(1) subcommand.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help flush-connection-pool at the command line.
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.
List the JDBC connection pools by using the list-jdbc-connection-pools(1) subcommand.
View the attributes of the JDBC connection pool by using the get subcommand.
For example:
asadmin get resources.jdbc-connection-pool.DerbyPool.property |
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 |
(Optional) If needed, restart the server.
Some parameters require server restart. See Configuration Changes That Require Server Restart.
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 deleting a JDBC connection pool, all associations to the resource must be removed.
Ensure that the server is running.
Remote subcommands require a running server.
List the JDBC connection pools by using the list-jdbc-connection-pools(1) subcommand.
If necessary, notify users that the JDBC connection pool is being deleted.
Delete the connection pool by using the delete-jdbc-connection-pool(1) subcommand.
This example deletes the JDBC connection pool named DerbyPool.
asadmin> delete-jdbc-connection-pool jdbc/DerbyPool Command delete-jdbc-connection-pool executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jdbc-connection-pool at the command line.
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:
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 creating a JDBC resource, you must first create a JDBC connection pool. For instructions, see To Create a JDBC Connection Pool.
Ensure that the server is running.
Remote subcommands require a running server.
Create a JDBC resource by using the create-jdbc-resource(1) subcommand.
Information about properties for the subcommand is included in this help page.
If necessary, notify users that the new resource has been created.
This example creates a JDBC resource named DerbyPool.
asadmin> create-jdbc-resource --connectionpoolid DerbyPool jdbc/DerbyPool Command create-jdbc-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jdbc-resource at the command line.
Use the list-jdbc-resources subcommand in remote mode to list the existing JDBC resources.
Ensure that the server is running.
Remote subcommands require a running server.
List JDBC resources by using the list-jdbc-resources(1) subcommand.
This example lists JDBC resources for localhost.
asadmin> list-jdbc-resources jdbc/__TimerPool jdbc/DerbyPool jdbc/__default jdbc1 Command list-jdbc-resources executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jdbc-resources at the command line.
You can enable or disable a JDBC resource by using the set subcommand. The JDBC resource is identified by its dotted name.
List JDBC resources by using the list-jdbc-resources(1) subcommand.
Modify the values for the specified JDBC resource by using the set(1) subcommand.
For example:
This example changes the res1 enabled setting to false.
asadmin>set resources.jdbc-resource.res1.enabled=false |
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 deleting a JDBC resource, all associations with this resource must be removed.
Ensure that the server is running.
Remote subcommands require a running server.
List JDBC resources by using the list-jdbc-resources(1) subcommand.
If necessary, notify users that the JDBC resource is being deleted.
Delete a JDBC resource by using the delete-jdbc-resource(1) subcommand.
This example deletes a JDBC resource named DerbyPool.
asadmin> delete-jdbc-resource jdbc/DerbyPool Command delete-jdbc-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jdbc-resource at the command line.
After setting up the connection pool and resources, integrate the JDBC driver in either of the following ways:
Make the driver accessible to the common class loader, and restart the domain.
Copy the driver’s JAR and ZIP files into the domain-dir/lib directory or the as-install/lib directory, or copy the driver's class files into the domain-dir/lib/ext directory. Identify the fully-qualified path name for the driver's JAR file.
GlassFish Server is designed to support connectivity to any database management system by using a corresponding JDBC driver.
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.
The JAR file for DataDirect driver is db2.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: DB2
DataSource Classname: com.ddtek.jdbcx.db2.DB2DataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
databaseName – Set as appropriate.
user – Set as appropriate.
password – Set as appropriate.
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:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: DB2
DataSource Classname: com.ibm.db2.jcc.DB2SimpleDataSource
DataDirect DataSource Classname: com.ddtek.jdbcx.db2.DB2DataSource
Properties:
databaseName - Set as appropriate.
user – Set as appropriate.
password – Set as appropriate.
driverType – Set to 2.
deferPrepares – Set to false.
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:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Java DB
DataSource Classname: Specify one of the following:
org.apache.derby.jdbc.ClientDataSource org.apache.derby.jdbc.ClientXADataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server if it is different from the default.
databaseName – Specify the name of the database.
user - Specify the database user.
This is only necessary if Java DB is configured to use authentication. Java DB does not use authentication by default. When the user is provided, it is the name of the schema where the tables reside.
password – Specify the database password.
This is only necessary if Java DB is configured to use authentication.
The JAR file for the DataDirect driver is sqlserver.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Microsoft SQL Server
DataSource Classname: com.ddtek.jdbcx.sqlserver.SQLServerDataSource
Properties:
serverName – Specify the host name or IP address and the port of the database server.
portNumber – Specify the port number of the database server.
user – Set as appropriate.
password – Set as appropriate.
selectMethod – Set to cursor.
The JAR file for the DataDirect driver is mysql.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: MySQL Server
DataSource: com.ddtek.jdbcx.mysql.MySQLDataSource
Properties:
serverName – Specify the host name or IP address and the port of the database server.
portNumber – Specify the port number of the database server.
user – Set as appropriate.
password – Set as appropriate.
selectMethod – Set to cursor.
The JAR file for the MySQL driver is mysql-connector-java-5.1.7-bin.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Microsoft SQL Server
DataSource Classname:
com.mysql.jdbc.jdbc2.optional.MysqlDataSource com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
databaseName – Set as appropriate.
user – Set as appropriate.
password – Set as appropriate.
The JAR file for the DataDirect driver is oracle.jar.
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:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Oracle
DataSource Classname: com.ddtek.jdbcx.oracle.OracleDataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
user – Set as appropriate.
password – Set as appropriate.
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:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Oracle
DataSource Classname: Specify one of the following:
oracle.jdbc.pool.OracleDataSource oracle.jdbc.xa.client.OracleXADataSource
Properties:
user – Set as appropriate.
password – Set as appropriate.
xa-driver-does-not-support-non-tx-operations - Set to the value true. Only needed if both non-XA and XA connections are retrieved from the same connection pool. Might degrade performance.
As an alternative to setting this property, you can create two connection pools, one for non-XA connections and one for XA connections.
The JAR file for the Oracle driver is ojdbc6.jar.
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).
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:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Oracle
DataSource Classname: Specify one of the following:
oracle.jdbc.pool.OracleDataSource oracle.jdbc.xa.client.OracleXADataSource
DataDirect DataSource Classname: com.ddtek.jdbcx.oracle.OracleDataSource
Properties:
user – Set as appropriate.
password – Set as appropriate.
xa-driver-does-not-support-non-tx-operations - Set to the value true. Optional: only needed if both non-XA and XA connections are retrieved from the same connection pool. Might degrade performance.
As an alternative to setting this property, you can create two connection pools, one for non-XA connections and one for XA connections.
For the Oracle thin driver, the XAResource.recover method repeatedly returns the same set of in-doubt Xids regardless of the input flag. According to the XA specifications, the Transaction Manager initially calls this method with TMSTARTSCAN and then with TMNOFLAGS repeatedly until no Xids are returned. The XAResource.commit method also has some issues.
To disable this GlassFish Server workaround, the oracle-xa-recovery-workaround property value must be set to false.
The JAR file for the PostgreSQL driver is postgresql-8.4-701.jdbc4.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: PostgreSQL Server
DataSource Classname: org.postgresql.ds.PGSimpleDataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
databaseName – Set as appropriate.
user – Set as appropriate.
password – Set as appropriate.
The JAR file for the DataDirect driver is sybase.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Sybase
DataSource Classname: com.ddtek.jdbcx.sybase.SybaseDataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
databaseName – Set as appropriate. This is optional.
user – Set as appropriate.
password – Set as appropriate.
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:
Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Informix
DataSource Classname: Specify one of the following:
com.informix.jdbcx.IfxDataSource com.informix.jdbcx.IfxXADataSource
DataDirect DataSource Classname: com.ddtek.jdbcx.informix.InformixDataSourcee
Properties:
serverName – Specify the Informix database server name.
portNumber – Specify the port number of the database server.
databaseName – Set as appropriate. This is optional.
user – Set as appropriate.
password – Set as appropriate.
IfxIFXHost – Specify the host name or IP address of the database server.
The JAR file for the Inet Oracle driver is Oranxo.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Oracle
DataSource Classname: com.inet.ora.OraDataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
user – Specify the database user.
password – Specify the database password.
serviceName – Specify the URL of the database. The syntax is as follows:
jdbc:inetora:server:port:dbname
For example:
jdbc:inetora:localhost:1521:payrolldb
In this example,localhost is the name of the host running the Oracle server, 1521 is the Oracle server’s port number, and payrolldb is the SID of the database. For more information about the syntax of the database URL, see the Oracle documentation.
streamstolob - If the size of BLOB or CLOB data types exceeds 4 KB and this driver is used for CMP, this property must be set to true.
xa-driver-does-not-support-non-tx-operations - Set to the value true. Only needed if both non-XA and XA connections are retrieved from the same connection pool. Might degrade performance.
As an alternative to setting this property, you can create two connection pools, one for non-XA connections and one for XA connections.
The JAR file for the Inet Microsoft SQL Server driver is Merlia.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Microsoft SQL Server
DataSource Classname: com.inet.tds.TdsDataSource
Properties:
serverName – Specify the host name or IP address and the port of the database server.
portNumber – Specify the port number of the database server.
user – Set as appropriate.
password – Set as appropriate.
The JAR file for the Inet Sybase driver is Sybelux.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Sybase
DataSource Classname: com.inet.syb.SybDataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
databaseName – Set as appropriate. Do not specify the complete URL, only the database name.
user – Set as appropriate.
password – Set as appropriate.
The JAR file for the Sybase driver is jconn4.jar. Configure the connection pool using the following settings:
Name: Use this name when you configure the JDBC resource later.
Resource Type: Specify the appropriate value.
Database Vendor: Sybase
DataSource Classname: Specify one of the following:
com.sybase.jdbc4.jdbc.SybDataSource com.sybase.jdbc4.jdbc.SybXADataSource
Properties:
serverName – Specify the host name or IP address of the database server.
portNumber – Specify the port number of the database server.
databaseName – Set as appropriate. Do not specify the complete URL, only the database name.
user – Set as appropriate.
password – Set as appropriate.
BE_AS_JDBC_COMPLIANT_AS_POSSIBLE – Set to true.
FAKE_METADATA – Set to true.
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.
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 .
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:
Connector Module. A connector module, also called a resource adapter, is a Java EE component that enables applications to interact with EIS software. A connector module is used by GlassFish Server to implement Java Message Service (JMS). Like other Java EE modules, a connector module is installed when it is deployed. For instructions on creating a connector module, see Chapter 12, Developing Connectors, in Oracle GlassFish Server 3.0.1 Application Development Guide
Connector Connection Pool. A connector connection pool is a group of reusable connections for a particular EIS. A connector connection pool is created when you specify the connector module that is associated with the pool. For administration procedures, see Administering Connector Connection Pools.
Connector Resource. A connector resource is a program object that provides an application with a connection to an EIS. A connector resource is created when you specify its JNDI name and its associated connection pool. The JNDI name of a connector resource for an EIS is usually in the java:comp/env/eis-specific subcontext. For administration procedures, see Administering Connector Resources.
Connector Module Configuration. A connector module configuration is the information that resides in the domain configuration file (domain.xml) for the particular connector module (resource adapter). For administration procedures, see Administering the Resource Adapter Configuration.
Connector Security Map. A connector security map associates the caller identity of the application (principal or user group) to a suitable EIS principal or group. For administration procedures, see Administering Connector Security Maps.
Connector Work Security Map. A connector work security map associates 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. For administration procedures, see Administering Connector Work Security Maps.
Administered Object. An administered object provides specialized functionality for an application, such as providing access to a parser that is specific to the connector module and its associated EIS. For administration procedures, see Administering Administered Objects.
At runtime, the following sequence occurs when an application connects to an EIS:
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.
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.
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.
When the application is finished accessing the EIS, the application closes the connection and returns the connection to the connection pool.
After a connector module has been deployed, you are ready to create a connector connection pool for it.
The following topics are addressed here:
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 creating the connector connection pool, the connector must be installed.
Ensure that the server is running.
Remote subcommands require a running server.
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.
(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.
(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.
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-connection-pool at the command line.
Use the list-connector-connection-pools subcommand in remote mode to list the pools that have been created.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-connection-pools(1) subcommand.
This example lists the existing connector connection pools.
asadmin> list-connector-connection-pools jms/qConnPool Command list-connector-connection-pools executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-connection-pools at the command line.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Connect to or reset a connector connection pool by using theflush-connection-pool(1) subcommand or the ping-connection-pool(1) subcommand.
Use the get and set subcommands to view and change the values of the connector connection pool properties.
List the connector connection pools by using the list-connector-connection-pools(1) subcommand.
View the properties of the connector connection pool by using the get(1) subcommand.
For example:
asadmin> get domain.resources.connector-connection-pool.conectionpoolname.* |
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 |
(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.
Use the delete-connector-connection-pool subcommand in remote mode to remove a connector connection pool.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-connection-pools(1) subcommand.
If necessary, notify users that the connector connection pool is being deleted.
Delete the connector connection pool by using the delete-connector-connection-pool(1) subcommand.
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-connection-pool at the command line.
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:
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 creating a connector resource, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.
Ensure that the server is running.
Remote subcommands require a running server.
Create the connector resource by using the create-connector-resource(1) subcommand.
Information about properties for the subcommand is included in this help page.
(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.
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help create-connector-resource at the command line.
Use the list-connector-resources subcommand in remote mode to list the connector resources that have been created.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-resources(1) subcommand.
This example lists the existing connector resources.
asadmin> list-connector-resources jms/qConnFactory Command list-connector-resources executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-connector-resources at the command line.
Use the get and set subcommands to view and change the values of the connector resource properties.
List the connector connection pools by using the list-connector-resources(1) subcommand.
View the properties of the connector resource by using the get(1) subcommand.
For example
asadmin> get domain.resources.connector-resource.jms/qConnFactory |
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 |
(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.
Use the delete-connector-resource subcommand in remote mode to remove a connector resource by specifying the JNDI name.
Before deleting a resource, all associations with the resource must be removed.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector connection pools by using the list-connector-resources(1) subcommand.
If necessary, notify users that the connector resource is being deleted.
Delete the connector resource by using the delete-connector-resource(1) subcommand.
This example deletes the jms/qConnFactory connector resource.
asadmin> delete-connector-resource jms/qConnFactory Command delete-connector-resources executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-connector-resource at the command line.
The following topics are addressed here:
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.
Ensure that the server is running.
Remote subcommands require a running server.
Create configuration information by using the create-resource-adapter-config(1) subcommand.
Information about properties for the subcommand is included in this help page.
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help create-resource-adapter-config at the command line.
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).
Ensure that the server is running.
Remote subcommands require a running server.
List the configurations for a resource adapter by using the list-resource-adapter-configs(1) subcommand.
This example lists all the resource adapter configurations.
asadmin> list-resource-adapter-configs ra1 ra2 Command list-resource-adapter-configs executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-resource-adapter-configs at the command line.
Use the get and set subcommands to view and change the values of the resource adapter configuration properties.
List the configurations for a resource adapter by using the list-resource-adapter-configs(1) subcommand.
View the properties of the connector resource by using the get(1) subcommand.
For example:
asadmin> get domain.resources.resource-adapter-config.ra1.* |
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 |
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).
Ensure that the server is running.
Remote subcommands require a running server.
List the configurations for a resource adapter by using the list-resource-adapter-configs(1) subcommand.
Delete the configuration for a resource adapter by using the delete-resource-adapter-config(1) subcommand.
This example deletes the configuration for resource adapter ra1.
asadmin> delete-resource-adapter-config ra1 Command delete-resource-adapter-config executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-resource-adapter-config at the command line.
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:
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.
For this subcommand to succeed, you must have first created a connector connection pool. For instructions, see To Create a Connector Connection Pool.
Ensure that the server is running.
Remote subcommands require a running server.
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.
(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.
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 |
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.
Ensure that the server is running.
Remote subcommands require a running server.
List existing connector connection pools by using the list-connector-connection-pools(1) subcommand.
List the security maps for a specific connector connection pool by using the list-connector-security-maps(1) subcommand.
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. |
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. |
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. |
Use the update-connector-security-map subcommand in remote mode to create or modify a security map for the specified connector connection pool.
Ensure that the server is running.
Remote subcommands require a running server.
List existing connector security maps by using the list-connector-security-maps(1) subcommand.
Modify a security map for a specific connector connection pool by using the update-connector-security-map(1) subcommand.
(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.
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. |
Use the delete-connector-security-map subcommand in remote mode to delete a security map for the specified connector connection pool.
Ensure that the server is running.
Remote subcommands require a running server.
List existing connector connection pools by using the list-connector-connection-pools(1) subcommand.
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.
This example deletes securityMap1 from connector-pool1.
asadmin> delete-connector-security-map --poolname connector-pool1 securityMap1 Command delete-connector-security-map executed successfully |
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:
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 creating a connector work security map, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.
Ensure that the server is running.
Remote subcommands require a running server.
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.
(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.
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 |
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.
Use the list-connector-work-security-maps subcommand in remote mode to list the work security maps that belong to a specific connector module.
Ensure that the server is running.
Remote subcommands require a running server.
List the connector work security maps by using the list-connector-work-security-maps(1) subcommand.
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. |
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.
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).
Ensure that the server is running.
Remote subcommands require a running server.
List the connector work security maps by using the list-connector-work-security-maps(1) subcommand.
If necessary, notify users that the connector work security map is being modified.
Update a connector work security map by using the update-connector-work-security-map(1) subcommand.
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. |
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.
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).
Ensure that the server is running.
Remote subcommands require a running server.
List the connector work security maps by using the list-connector-work-security-maps(1) subcommand.
Delete a connector work security map by using the delete-connector-work-security-map(1) subcommand.
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. |
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.
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:
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.
The resource adapter must be deployed before running this subcommand (jmsrar.rar).
Create an administered object by using the create-admin-object(1) subcommand.
Information about properties for the subcommand is included in this help page.
(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.
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help create-admin-object at the command line.
Use the list-admin-object subcommand in remote mode to list the existing administered objects.
Ensure that the server is running.
Remote subcommands require a running server.
List the administered objects by using the list-admin-objects(1) subcommand.
This example lists the existing administered objects.
asadmin> list-admin-objects jms/samplequeue Command list-admin-objects executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-admin-object at the command line.
Use the get and set subcommands to view and change the values of the administered objects properties.
List the administered objects by using the list-admin-objects(1) subcommand.
View the properties of the administered object by using the get(1) subcommand.
For example:
asadmin> get domain.resources.admin-object-resource.jms/samplequeue.* |
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 |
(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.
Use the delete-admin-object subcommand to delete an administered objects.
List the administered objects by using the list-admin-objects(1) subcommand.
If necessary, notify users that the administered object is being deleted.
Delete an administered object by using the delete-admin-object(1) subcommand.
This example deletes the administered object with the JNDI name jms/samplequeue.
asadmin> delete-admin-object jms/samplequeue Command delete-admin-object executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-admin-object at the command line.
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.
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:
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).
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.
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).
By default, when GlassFish Server starts, the following HTTP listeners are started automatically:
HTTP listeners associated with the virtual server named server:
The listener named http-listener-1 does not have security enabled.
The listener named http-listener-2 has security enabled
An HTTP listener named admin-listener, associated with the virtual server named __asadmin. For this listener, security is not enabled.
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:
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.
Ensure that the server is running.
Remote subcommands require a running server.
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.
Create an HTTP configuration by using the create-http(1) subcommand.
To use a built-in protocol, skip this step.
Create a transport by using the create-transport(1) subcommand.
To use the built-in tcp transport, skip this step.
(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.
Create an HTTP listener by using the create-network-listener(1) subcommand.
Specify a protocol and transport, optionally a thread pool.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
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.
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:
Use the create-protocol subcommand in remote mode to create a protocol.
Ensure that the server is running.
Remote subcommands require a running server.
Create a protocol by using the create-protocol(1)
Information about options and properties for the subcommand are included in this help page.
This example creates a protocol named http-1 with security enabled.
asadmin> create-protocol --securityenabled=true http-1 Command create-protocol executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-protocol at the command line.
Use the list-protocols subcommand in remote mode to list the existing HTTP protocols.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing protocols by using the list-protocols(1) subcommand.
This example lists the existing protocols.
asadmin> list-protocols admin-listener http-1 http-listener-1 http-listener-2 Command list-protocols executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-protocols at the command line.
Use the delete-protocol subcommand in remote mode to remove a protocol.
Ensure that the server is running.
Remote subcommands require a running server.
Delete a protocol by using the delete-protocol(1) subcommand
This example deletes the protocol named http-1.
asadmin> delete-protocol http-1 Command delete-protocol executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-protocol at the command line.
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:
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,
Ensure that the server is running.
Remote subcommands require a running server.
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.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-http at the command line.
Use the delete-http subcommand in remote mode to remove HTTP parameters from a protocol.
Ensure that the server is running.
Remote subcommands require a running server.
Delete the HTTP parameters from a protocol by using the delete-http(1) subcommand.
This example deletes the HTTP parameter set from a protocol named http-1.
asadmin> delete-http http-1 Command delete-http executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-http at the command line.
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:
Use the create-transport subcommand in remote mode to create a transport for a network listener,
Ensure that the server is running.
Remote subcommands require a running server.
Create a transport by using the create-transport(1) subcommand.
Information about options and properties for the subcommand are included in this help page.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-transport at the command line.
Use the list-transports subcommand in remote mode to list the existing HTTP transports.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing transports by using the list-transports(1) subcommand.
This example lists the existing transports.
asadmin> list-transports http1-trans tcp Command list-transports executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-transports at the command line.
Use the delete-transport subcommand in remote mode to remove a transport.
Ensure that the server is running.
Remote subcommands require a running server.
Delete a transport by using the delete-transport(1) subcommand.
This example deletes he transport named http1-trans.
asadmin> delete-transport http1-trans Command delete-transport executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-transport at the command line.
The following topics are addressed here:
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.
Ensure that the server is running.
Remote subcommands require a running server.
Create an HTTP network listener by using the create-network-listener(1) subcommand or the create-http-listener(1) subcommand.
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.
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. |
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. |
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.
Use the list-http-listeners subcommand or the list-network-listeners subcommand in remote mode to list the existing HTTP listeners.
Ensure that the server is running.
Remote subcommands require a running server.
List HTTP listeners by using the list-http-listeners(1) or list-network-listeners(1) subcommand.
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. |
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.
List HTTP listeners by using the list-http-listeners(1) or list-network-listeners(1) subcommand.
Modify the values for the specified listener by using the set(1) subcommand.
The listener is identified by its dotted name.
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. |
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.
Ensure that the server is running.
Remote subcommands require a running server.
List HTTP listeners by using the list-http-listeners(1) subcommand.
Delete an HTTP listener by using the delete-http-listener(1) or delete-network-listener(1) subcommand.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
This example deletes the HTTP listener named sampleListener:
asadmin> delete-http-listener sampleListener Command delete-http-listener executed successfully. |
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.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Configure an HTTP listener by using the create-ssl(1) subcommand.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-ssl at the command line.
Use the delete-ssl subcommand in remote mode to delete the SSL element in the specified listener. This disables secure communications for the listener.
Ensure that the server is running.
Remote subcommands require a running server.
Delete SSL from an HTTP listener by using the delete-ssl(1) subcommand.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-ssl at the command line.
In the Administration Console, open the HTTP Service component under the relevant configuration.
Open the HTTP Listeners component under the HTTP Service component.
Select or create a new HTTP listener.
Select from the Default Virtual Server drop-down list.
For more information, see To Assign a Default Web Module to a Virtual Server.
For details, click the Help button in the Administration Console from the HTTP Listeners page.
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:
By default, when GlassFish Server starts, the following virtual servers are started automatically:
A virtual server named server, which hosts all user-defined web modules.
For development, testing, and deployment of web services in a non-production environment, server is often the only virtual server required.
A virtual server named __asadmin, which hosts all administration-related web modules (specifically, the Administration Console). This server is restricted, which means that you cannot deploy web modules to this virtual server.
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.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Create a virtual server by using the create-virtual-server(1) subcommand.
Information about properties for this subcommand is included in this help page.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
This example creates a virtual server named sampleServer on localhost.
asadmin> create-virtual-server sampleServer Command create-virtual-server executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-virutal-server at the command line.
Use the list-virtual-servers subcommand in remote mode to list the existing virtual servers.
Ensure that the server is running.
Remote subcommands require a running server.
List virtual servers by using the list-virtual-servers(1) subcommand.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-virutal-servers at the command line.
List virtual servers by using the list-virtual-servers(1) subcommand.
Modify the values for the specified virtual server by using the set(1) subcommand.
The virtual server is identified by its dotted name.
Use the delete-virtual-server subcommand in remote mode to delete an existing virtual server.
Ensure that the server is running.
Remote subcommands require a running server.
List virtual servers by using the list-virtual-servers(1) subcommand.
If necessary, notify users that the virtual server is being deleted.
Delete a virtual server by using the delete-virtual-server(1) subcommand.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
This example deletes the virtual server named sampleServer from localhost.
asadmin> delete-virtual-server sampleServer Command delete-virtual-server executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-virutal-server at the command line.
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
You can assign a virtual server to a deployed application or web module.
The application or module must already be deployed. For more information, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.
In the Administration Console, open the HTTP Service component under the relevant configuration.
Open the Virtual Servers component under the HTTP Service component.
Select the virtual server to which you want to assign a default web module.
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.
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.
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.
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.
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:
Use the create-iiop-listener subcommand in remote mode to create an IIOP listener.
Ensure that the server is running.
Remote subcommands require a running server.
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.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-iiop-listener at the command line.
Use the list-iiop-listeners subcommand in remote mode to list the existing IIOP listeners.
Ensure that the server is running.
Remote subcommands require a running server.
List the IIOP listeners by using the list-iiop-listeners(1) subcommand.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-iiop-listeners at the command line.
List the IIOP listeners by using the list-iiop-listeners(1) subcommand.
Modify the values for the specified IIOP listener by using the set(1) subcommand.
The listener is identified by its dotted name.
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. |
Use the delete-iiop-listener subcommand in remote mode to delete an IIOP listener.
Ensure that the server is running.
Remote subcommands require a running server.
List the IIOP listeners by using the list-iiop-listeners(1) subcommand.
Delete an IIOP listener by using the delete-iiop-listener(1) subcommand.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
This example deletes the IIOP listener named sample_iiop_listener.
asadmin> delete-iiop-listener sample_iiop_listener Command delete-iiop-listener executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-iiop-listener at the command line.
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.
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.
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:
JNDI Name. The unique name for the mail session. Use the naming sub-context prefix mail/ for JavaMail resources. For example: mail/MySession
Mail Host. The host name of the default mail server. The connect methods of the store and transport objects use this value if a protocol-specific host property is not supplied. The name must be resolvable to an actual host name.
Default User. The default user name to provide when connecting to a mail server. The connect methods of the store and transport objects use this value if a protocol-specific username property is not supplied.
Default Return Address. The email address of the default user, in the form: username@host.domain.
Description. A descriptive statement for the component.
Session. Indicates whether or not mail session is enabled or disabled at this time
The following topics are addressed here:
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.
Ensure that the server is running.
Remote subcommands require a running server.
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.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-javamail-resource at the command line.
Use the list-javamail-resources subcommand in remote mode to list the existing JavaMail session resources.
Ensure that the server is running.
Remote subcommands require a running server.
List the JavaMail resources by using the list-javamail-resources(1) subcommand.
This example lists the JavaMail resources on localhost.
asadmin> list-javamail-resources mail/MyMailSession Command list-javamail-resources executed successfuly. |
You can also view the full syntax and options of the subcommands by typing asadmin help list-javamail-resources at the command line.
List the JavaMail resources by using the list-javamail-resources(1) subcommand.
Modify the values for the specified JavaMail source by using the set(1) subcommand.
The resource is identified by its dotted name.
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. |
Use the delete-javamail-resource subcommands in remote mode to delete a JavaMail session resource.
References to the specified resource must be removed before running the delete-javamail-resource subcommands.
Ensure that the server is running.
Remote subcommands require a running server.
List the JavaMail resources by using the list-javamail-resources(1) subcommands.
Delete a JavaMail resource by using the delete-javamail-resource(1) subcommands.
To apply your changes, restart GlassFish Server.
See To Restart a Domain.
This example deletes the JavaMail session resource named mail/MyMailSession.
asadmin> delete-javamail-resource mail/MyMailSession Command delete-javamail-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-javamail-resource at the command line.
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.
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.
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 can be integrated with GlassFish Server in LOCAL, REMOTE, or EMBEDDED mode. These modes are represented by the JMS type attribute.
LOCAL Mode. GlassFish Server starts and stops the Message Queue broker that is specified as the default JMS host. The Message Queue process is started in a separate virtual machine from the GlassFish Server process. GlassFish Server supplies an additional port to the broker, which is used by the broker to start the RMI registry. This port number will be equal to the configured JMS port for that instance, plus 100. For example, if the JMS port number is 37676, then this additional port number is 37776.
In LOCAL mode, use the Start Arguments attribute to specify Message Queue broker startup parameters.
REMOTE Mode. When the type attribute is set to REMOTE, the Message Queue broker must be started and stopped separately from GlassFish Server. Message Queue tools must be used to configure and tune the broker. In this situation, GlassFish Server uses an externally–configured broker or broker cluster. REMOTE type is most suitable for clusters.
In REMOTE mode, you must specify Message Queue broker startup parameters using Message Queue tools. The Start Arguments attribute is ignored.
EMBEDDED Mode (default). When the JMS type attribute is set to EMBEDDED, GlassFish Server and the JMS broker are colocated in the same virtual machine. The JMS Service is started in-process and managed by GlassFish Server.
In EMBEDDED mode, the JMS operations bypass the networking stack, which leads to performance optimization.
For information about administering Message Queue, see Oracle GlassFish Message Queue 4.4.2 Administration Guide.
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:
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.
Ensure that the server is running.
Remote subcommands require a running server.
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.
(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.
This example creates a queue named PhysicalQueue.
asadmin> create-jmsdest --desttype queue --property User=public:Password=public PhysicalQueue Command create-jmsdest executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jmsdest at the command line.
Use the list-jmsdest subcommand in remote mode to list the existing JMS physical destinations.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.
This example lists the physical destinations for the default server instance.
asadmin> list-jmsdest PhysicalQueue queue {} PhysicalTopic topic {} Command list-jmsdest executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jmsdest at the command line.
Use the flush-jmsdest subcommand in remote mode to purge the messages from a physical destination in the specified target's JMS service configuration.
Ensure that the server is running.
Remote subcommands require a running server.
Purge messages from the a JMS physical destination by using the flush-jmsdest(1) subcommand.
(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.
This example purges messages from the queue named PhysicalQueue.
asadmin> flush-jmsdest --desttype queue PhysicalQueue Command flush-jmsdest executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help flush-jmsdest at the command line.
Use the delete-jmsdest subcommand in remote mode to remove the specified JMS physical destination.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.
Delete the physical resource by using the delete-jmsdest(1) subcommand.
This example deletes the queue named PhysicalQueue.
asadmin> delete-jmsdest --desttype queue PhysicalQueue Command delete-jmsdest executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jmsdest at the command line.
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:
Creating a connection factory
Creating a destination, which requires creating a physical destination and a destination resource that refers to the physical destination
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:
QueueConnectionFactory objects, used for point-to-point communication
TopicConnectionFactory objects, used for publish-subscribe communication
ConnectionFactory objects, which can be used for both point-to-point and publish-subscribe communications (recommended for new applications)
GlassFish Server provides the following types of destination objects:
Queue objects, used for point-to-point communication
Topic objects, used for publish-subscribe communication
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.
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.
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.
Ensure that the server is running.
Remote subcommands require a running server.
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.
(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.
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. |
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jms-resource at the command line.
Use the list-jms-resources subcommand in remote mode to list the existing connection factory and destination resources.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS resources by using the list-jms-resources(1) subcommand.
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 |
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jms-resources at the command line.
Use the delete-jms-resource subcommand in remote mode to remove the specified connection factory or destination resource.
Ensure that you remove all references to the specified JMS resource before running this subcommand.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS resources by using the list-jms-resources(1) subcommand.
Delete the JMS resource by using the delete-jms-resource(1) subcommand.
This example deletes the jms/Queue resource.
asadmin> delete-jms-resource jms/Queue Command delete-jms-resource executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jms-resource at the command line.
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:
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.
Ensure that the server is running.
Remote subcommands require a running server.
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.
This example creates a JMS host named MyNewHost.
asadmin> create-jms-host --mqhost pigeon --mqport 7677 MyNewHost Command create-jms-host executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jms-host at the command line.
Use the list-jms-hosts subcommand in remote mode to list the existing JMS hosts.
Ensure that the server is running.
Remote subcommands require a running server.
List the JMS hosts by using the list-jms-hosts(1) subcommand.
The following subcommand lists the existing JMS hosts.
asadmin> list-jms-hosts default_JMS_host MyNewHost Command list-jmsdest executed successfully |
List the JMS hosts by using the list-jms-hosts(1) subcommand.
Use the set(1) subcommand to modify 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" |
You can also view the full syntax and options of the subcommand by typing asadmin help set at the command line.
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.
Ensure that the server is running.
Remote subcommands require a running server.
List the JMS hosts by using the list-jms-hosts(1) subcommand.
Delete a JMS host by using the delete-jms-host(1) subcommand.
This example deletes a JMS host named MyNewHost.
asadmin> delete-jms-host MyNewHost Command delete-jms-host executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jms-host at the command line.
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:
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.
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.
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.
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.
Deploy the generic resource adapter the same way you would deploy a connector module.
Create a connector connection pool.
Create a connector resource.
Create an administered object resource.
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": |
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:
View the GlassFish Server log file, typically located at domain-dir/logs/server.log.
If a the log file indicates that a Message Queue broker did not respond to a message, stop the broker and then restart it.
View the broker log, typically available at as-install/domains/domain1/imq/instances/imqbroker/log/log.txt.
For JMS REMOTE mode, be sure to start Message Queue brokers first, then GlassFish Server.
If all Message Queue brokers are down, it takes 30 minutes for GlassFish Server to go down or up when you are using the default values in JMS. You can change the default values for this timeout. For example:
asadmin set domain1.jms-service.reconnect-interval-in-seconds=5 |
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.
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:
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.
The application component's environment is used as follows:
The application component's business methods access the environment using the JNDI interfaces. In the deployment descriptor, the application component provider declares all the environment entries that the application component expects to be provided in its environment at runtime.
The container provides an implementation of the JNDI naming context that stores the application component environment. The container also provides the tools that allow the deployer to create and manage the environment of each application component.
A deployer uses the tools provided by the container to initialize the environment entries that are declared in the application component's deployment descriptor. The deployer sets and modifies the values of the environment entries.
The container makes the JNDI context available to the application component instances at runtime. These instances use the JNDI interfaces to obtain the values of the environment entries.
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.
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 |
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.
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:
Use the create-custom-resource subcommand in remote mode to create a custom resource.
Ensure that the server is running.
Remote subcommands require a running server.
Create a custom resource by using the create-custom-resource(1) subcommand.
Information on properties for the subcommand is contained in this help page.
Restart GlassFish Server.
See To Restart a Domain.
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-custom-resource at the command line.
Use the list-custom-resources subcommand in remote mode to list the existing custom resources.
Ensure that the server is running.
Remote subcommands require a running server.
List the custom resources by using the list-custom-resources(1) subcommand.
This example lists the existing custom resources.
asadmin> list-custom-resources sample_custom_resource01 sample_custom_resource02 Command list-custom-resources executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-custom-resources at the command line.
List the custom resources by using the list-custom-resources(1) subcommand.
Use the set(1) subcommand to modify 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 |
Use the delete-custom-resource subcommand in remote mode to delete a custom resource.
Ensure that the server is running.
Remote subcommands require a running server.
List the custom resources by using the list-custom-resources(1) subcommand.
Delete a custom resource by using the delete-custom-resource(1) subcommand.
This example deletes a custom resource named sample-custom-resource.
asadmin> delete-custom-resource sample_custom_resource Command delete-custom-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-custom-resource at the command line.
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:
Use the create-jndi-resource subcommand in remote mode to register an external JNDI resource.
The external JNDI factory must implement the javax.naming.spi.InitialContextFactory interface.
Ensure that the server is running.
Remote subcommands require a running server.
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.
Restart GlassFish Server.
See To Restart a Domain.
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jndi-resource at the command line.
Use the list-jndi-resources subcommand in remote mode to list all existing JNDI resources.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JNDI resources by using thelist-jndi-resources(1) subcommand.
This example lists the JNDI resources.
asadmin> list-jndi-resources jndi_resource1 jndi_resource2 jndi_resource3 Command list-jndi-resources executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jndi-resources at the command line.
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.
Ensure that the server is running.
Remote subcommands require a running server.
List the JNDI entries for a configuration by using the list-jndi-entries(1) subcommand.
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 |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jndi-entries at the command line.
List the existing JNDI resources by using thelist-jndi-resources(1) subcommand.
Use the set(1) subcommand to modify 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 |
Use the delete-jndi-resource subcommand in remote mode to remove a JNDI resource.
Ensure that the server is running.
Remote subcommands require a running server.
Remove an external JNDI entry by using the delete-jndi-resource(1) subcommand.
This example deletes an external JNDI resource:
asadmin> delete-jndi-resource jndi_resource2 Command delete-jndi-resource executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jndi-resource at the command line.
<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>
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.
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:
Check to see if the checking account has enough money to cover the transfer.
Debit the amount from the checking account.
Credit the amount to the savings account.
Record the transfer to the checking account log.
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:
Transaction Manager. Provides the services and management functions required to support transaction demarcation, transactional resource management, synchronization, and transaction context propagation.
GlassFish Server. Provides the infrastructure required to support the application runtime environment that includes transaction state management.
Resource Manager. Through a resource adapter, the resource manager provides the application access to resources. The resource manager participates in distributed transactions by implementing a transaction resource interface used by the transaction manager to communicate transaction association, transaction completion, and recovery work. An example of such a resource manager is a relational database server.
Resource Adapter. A system-level software library is used by GlassFish Server or a client to connect to a resource manager. A resource adapter is typically specific to a resource manager. The resource adapter is available as a library and is used within the address space of the client using it. An example of such a resource adapter is a Java Database Connectivity (JDBC) driver. For information on supported JDBC drivers, see Configuration Specifics for JDBC Drivers.
Transactional User Application. In the GlassFish Server environment, the transactional user application uses Java Naming and Directory Interface (JNDI) to look up transactional data sources and, optionally, the user transaction). The application might use declarative transaction attribute settings for enterprise beans, or explicit programmatic transaction demarcation.
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:
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.
Ensure that the server is running.
Remote subcommands require a running server.
Stop the transaction service by using the freeze-transaction-service(1) subcommand.
This example stops the transaction service.
asadmin> freeze-transaction-service Command freeze-transaction-service executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help freeze-transaction-service at the command line.
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.
Stop the transaction service before rolling back an in-flight transaction.
Ensure that the server is running.
Remote subcommands require a running server.
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.
Roll back the transaction by using the rollback-transaction(1) subcommand.
This example rolls back the transaction with transaction ID 0000000000000001_00.
asadmin> rollback-transaction 0000000000000001_00 Command rollback-transaction executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help rollback-transaction at the command line.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Restart the suspended transaction service by using the unfreeze-transaction-service(1) subcommand.
This example restarts the transaction service after it has been frozen.
asadmin> unfreeze-transaction-service Command unfreeze-transaction-service executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help unfreeze-transaction-service at the command line.
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.
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.
Ensure that the server is running.
Remote subcommands require a running server.
Manually recover transactions by using the recover-transactions(1) subcommand.
This example performs manual recovery of transactions on sampleserver.
asadmin recover-transactions sampleserver Transaction recovered. |
You can also view the full syntax and options of the subcommand by typing asadmin help recover-transactions at the command line.