Sun Java System Web Server 7.0 Update 4 Administrator's Guide

Configuring Java Resources

Web applications may access a wide variety of resources such as resource managers, data sources (for example SQL datasources), mail sessions, and URL connection factories. The Java EE platform exposes such resources to the applications through the Java Naming and Directory Interface (JNDI) service.

The Sun Java System Web Server enables you to create and manage the following Java EE resources:

Configuring JDBC Resources

A JDBC Datasource is a Java EE resource that you can create and manage using the Sun Java System Web Server.

The JDBC API is the API for connectivity with relational database systems. The JDBC API has two parts:

A JDBC Datasource object is an implementation of a data source in the Java programming language. In basic terms, a data source is a facility for storing data. It can be as sophisticated as a complex database for a large corporation or as simple as a file with rows and columns. A JDBC datasource is a Java EE resource that can be created and managed through the Sun Java System Web Server.

The JDBC API provides a set of classes for Java with a standard SQL database access interface to ensure uniform access to a wide range of relational databases.

Using JDBC, SQL statements can be sent to virtually any database management system (DBMS). It is used as an interface for both relational and object DBMSs.

Adding a JDBC Resource

To add a JDBC resource through CLI, execute the following command.


wadm> create-jdbc-resource --user=admin --password-file=admin.pwd --host=serverhost
--port=8989 --config=config1 --datasource-class=oracle.jdbc.pool.OracleDataSource jdbc

See CLI Reference, create-jdbc-resource(1).

In the previous example, com.pointbase.jdbc.jdbcDataSource represents the JDBC driver class.

For a list of supported JDBC drivers, see JDBC Drivers Known to Work With the Sun Java System Web Server.

JDBC Drivers Known to Work With the Sun Java System Web Server

The following table provides a list of common JDBC drivers and their properties. These drivers need to be configured while adding a new JDBC resource. See Adding a new JDBC Resource.

Table 11–2 List of common and JDBC drivers

Driver

Class Name

Properties

Oracle driver

oracle.jdbc.pool.OracleDataSource

  • url

  • user

  • password

Sun Java System JDBC driver for Oracle

com.sun.sql.jdbcx.oracle.OracleDataSource

  • serverName

  • portNumber

  • user

  • password

  • SID

DB2 IBM driver

com.ibm.db2.jdbc.DB2DataSource

  • serverName

  • databaseName

  • portNumber

  • user

  • password

  • driverType

Sun Java System JDBC driver for DB2

com.sun.sql.jdbcx.db2.DB2DataSource

  • databaseName

  • locationName

  • packageName

  • password

  • portNumber

  • serverName

  • user

MS SQLServer driver

com.ddtek.jdbcx.sqlserver.SQLServerDataSource

  • databaseName

  • password

  • user

  • serverName

  • portNumber

Sun Java System JDBC driver for MS

com.sun.sql.jdbcx.sqlserver.SQLServerDataSource

  • databaseName

  • password

  • user

  • serverName

  • portNumber

Sybase driver

com.sybase.jdbcx.SybDataSource

  • databaseName

  • password

  • portNumber

  • serverName

  • user

Sun Java System JDBC driver for Sybase

com.sun.sql.jdbcx.sybase.SybaseDataSource

  • databaseName

  • password

  • user

  • portNumber

  • serverName

MySQL driver

com.mysql.jdbc.jdbc2.optional.MysqlDataSource

  • serverName

  • port

  • databaseName

  • user

  • password

Informix driver

com.informix.jdbcx.IfxDataSource

  • portNumber

  • databaseName

  • IfxIFXHOST (The IP address or the host name of the computer running the Informix database)

  • serverName

  • user

  • password

Sun Java System JDBC driver for Informix

com.sun.sql.jdbcx.informix.InformixDataSource

  • databaseName

  • informixServer ( The name of the Informix database server to which you want to connect)

  • password

  • portNumber

  • severName

PostgreSQL driver

org.postgresql.ds.PGSimpleDataSource

  • serverName

  • databaseName

  • portNumber

  • user

  • password

Apache Derby driver

org.apache.derby.jdbc.EmbeddedDataSource

  • databaseName

  • user

  • password


Note –

In the previously mentioned list, all of the Sun Java System JDBC drivers are shipped with the Web Server. For other drivers, check with the driver vendor documentation for the latest versions of these drivers and the class names. The information provided in the previously mentioned list may not be the latest driver information.


Managing JDBC Resources

ProcedureAdding a new JDBC Resource

  1. Click the Configuration tab and select the configuration from the configuration list.

  2. ClickJava > Resources tab.

  3. Under JDBC Resources, click New.

  4. Select the Driver Vendor.

    Specify a unique value for the JNDI name and select the JDBC driver vendor from the available list.

  5. Provide JDBC Resource Properties.

    Based on the JDBC driver vendor selection in the previous step, the class name for the driver and the JDBC resource properties are automatically populated.

  6. Review.

    View the summary and click Finish to create the new JDBC resource.

Managing JDBC Connection Pools

Configuring JDBC Connection Pool

In Web Server 7.0, JDBC Connection Pools are configured through JDBC resource elements. The simplest connection pool can be configured by following the steps listed below. In this example, the connection pool will use the Oracle JDBC driver.

ProcedureTo Create a JDBC Connection Pool

  1. Start wadm.

  2. Create a JDBC Resource with the basic configuration.

    Other attributes are available to fine tune the connection pool. Refer to the Manual Pages for more attributes and examples.


    wadm> create-jdbc-resource --config=test 
    --datasourceclass=oracle.jdbc.pool.OracleDataSource jdbc/MyPool
  3. Configure Vendor Specific Properties.

    Properties are used to configure the driver's vendor specific properties. In the example below the properties url, user and password are added to the JDBC resource.


    wadm> add-jdbc-resource-userprop --config=test --jndi-name=jdbc/MyPool 
    url=jdbc:oracle:thin:@hostname:1521:MYSID user=myuser password=mypassword
  4. Enable Connection Validation.

    Connection validation can be enabled for the pool. If this option is used, connections will be validated before they are passed to the application. This enables the web server to automatically re-establish database connections in the case of the database becoming unavailable due to network failure or database server crash. Validation of connections will incur additional overhead and slightly reduce performance.


    wadm> set-jdbc-resource-prop --config=test --jndi-name=jdbc/MyPool 
    connection-validation-table-name=test connection-validation=table
  5. Change Default Pool Settings.

    In this example, change the maximum number of connections.


    wadm> set-jdbc-resource-prop --config=test --jndi-name=jdbc/MyPool 
    max-connections=100
  6. Deploy the Configuration.


    wadm> deploy-config test
  7. Provide the Jar Files Containing the JDBC driver.

    The server needs to be provided with the classes that implement the driver. This can be done in two ways:

    • Copy the driver's jar file into the server instance lib directory. This is the simplest way, as the jar files included in the instance lib directory will be automatically loaded and available to the server.

    • Modify the JVM's class-path-suffix to include the JDBC driver's jar file.


      wadm> set-jvm-prop  --config=test class-path-suffix=/export/home/lib/classes12.jar
  8. Usage in Web Applications.

    • Modifying WEB-INF/web.xml.


      <web-app>
      ...
        <resource-ref>
          <description>JDBC Connection Pool</description>
          <res-ref-name>jdbc/myJdbc</res-ref-name>
          <res-type>javax.sql.DataSource</res-type>
          <res-auth>Container</res-auth>
        </resource-ref>
      ...
      </web-app>
    • Modifying WEB-INF/sun-web.xml.


      <sun-web-app>
      ...
        <resource-ref>
          <res-ref-name>jdbc/myJdbc</res-ref-name>
          <jndi-name>jdbc/MyPool</jndi-name>
        </resource-ref>
      ...
      </sun-web-app>
    • Using the Connection Pool.


      Context initContext = new InitialContext();
          Context webContext = (Context)context.lookup("java:/comp/env");
      
          DataSource ds = (DataSource) webContext.lookup("jdbc/myJdbc");
          Connection dbCon = ds.getConnection();

Registering Custom Resources

You can register a custom resource with the instance by performing this task.

ProcedureTo Add a Custom Resource

  1. Click Configurations tab and select the configuration from the list.

  2. Click Java > Resources tab.

  3. Under Custom Resource, click New.

Properties for Custom Resources

The following table describes the properties available for creating a custom resource.

Table 11–3 Custom Resources Properties

Property

Description

JNDI Name

Provides a unique JNDI name for the custom resource. 

Enabled

Determines if this custom resource is enabled at runtime. 

Resource Type

Fully qualified type of resource. 

Factory Class

Class that instantiates resources of this type. The fully qualified name of the user-written factory class that implements the javax.naming.spi.ObjectFactory.

Description

Provide a short description for the custom resource. 

Properties

Provides CLI properties. Click Add Property to use. 


Note –

Using CLI

To create a custom resource through CLI, execute the following command:


wadm> create-custom-resource --user=admin --password-file=admin.pwd --host=serverhost 
--port=8989 --config=config1 --res-type=samples.jndi.customResource.MyBean 
--factory-class=samples.jndi.customResource.MyCustomConnectionFactory custom

See CLI Reference, create-custom-resource(1).


Working With External JNDI Resources

Creating External JNDI Resources

This option lets you create an external Java Naming and Directory Interface (JNDI) resource. You need a JNDI resource to access resources stored in an external JNDI repository.

ProcedureTo Add an External JNDI Resource

  1. Click the Configuration tab and select the configuration from the list.

  2. Click Java > Resources tab.

  3. Under External JNDI, click New.

Properties for External JNDI Resources

The following table describes the properties available when adding a new external JNDI resource.

Table 11–4 External JNDI Resources Properties

Property

Description

JNDI Name

Provides a unique name for the new external JNDI resource. 

Enabled

Determines if this external JNDI resource is enabled at runtime. 

External JNDI Name

Name of the external JNDI resource. 

Resource Type

Fully qualified type of resource. 

Factory Class

Class that instantiates resources of this type. 

Description

Provides a short description for the external JNDI resource. 

Properties

Optionally provides CLI properties. Enabled by clicking the Add Property button. 


Note –

Using CLI

To create an external JNDI resource through CLI, execute the following command:


wadm> create-external-jndi-resource --user=admin 
--password-file=admin.pwd --host=serverhost --port=8989 --config=config1 
--res-type=org.apache.naming.resources.Resource 
--factory-class=samples.jndi.externalResource.MyExternalConnectionFactory 
--jndilookupname=index.html external-jndi

See CLI Reference, create-external-jndi-resource(1).


Configuring Mail Resources

JMS destinations are Java EE resources that can be created and managed through the Sun Java System Web Server.

Many internet applications require the ability to send email notifications. The Java EE platform includes the JavaMail API along with a JavaMail service provider that enables an application component to send internet mail.

ProcedureTo Add a Mail Resource

  1. Click the Configuration tab to view the list of configurations and select the configuration you need.

  2. Click Java > Resources tab.

  3. Under Mail Resource, click New.

Properties for Mail Resource

The following table describes the properties available while adding a new mail resource.

Table 11–5 Mail Resource Properties

Property

Description

JNDI Name

Provides a unique name for the new mail resource. 

Enabled

Determines if this mail resource is enabled at runtime. 

User

Valid user name registered in the mail server. 

From

Email address from which the server sends mail. 

Host

Host name/IP address of the mail server. 

Store Protocol

Protocol used to retrieve messages. 

Store Protocol Class

Storage service provider implementation for store-protocol. Fully qualified class name of a class that implements store-protocol. The default class is com.sun.mail.imap.IMAPStore.

Transport Protocol

Protocol used to send messages. 

Transport Protocol Class

Transport service provider implementation for transport-protocol. Fully qualified class name of a class that implements transport-protocol. The default class is com.sun.mail.smtp.SMTPTransport.


Note –

Using CLI

To create a mail resource, execute the following command:


wadm> create-mail-resource --config=test --server-host=localhost 
--mail-user=nobody --from=xyz@foo.com mail/Session

See CLI Reference, create-mail-resource(1).