Configuring Resources

The Java^TM Web Services Tutorial

Configuring Resources

The Resources node represents the Global Naming Resources component. The elements under this node represent the global JNDI resources which are defined for the Server. The following resources can be used to configure the resource manager (or object factory) used to return objects when a Web application performs a JNDI lookup operation on the corresponding resource name:

Data Sources
Environment Entries
User Databases

For more information on configuring Global Naming Resources, read the document titled GlobalNamingResources Component, available from <JWSDP_HOME>/docs/tomcat/config/globalresources.html.

Configuring Data Sources

Many Web applications need to access a database via a JDBC driver to support the functionality required by that application. The J2EE Platform Specification requires J2EE Application Servers to make a Data Source implementation (that is, a connection pool for JDBC connections) available for this purpose. Tomcat offers the same support so that database-based applications developed on Tomcat using this service will run unchanged on any J2EE server.

To edit a Data Source,

Expand the Resources element in the left pane.
Select the Data Source to edit.
Edit the values in the right pane.
Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new Data Source for Tomcat,

Start deploytool. Select or create the WAR for your application.
Select the Resource Refs tabbed page. Click the Add button to add a Resource Ref.
Enter any name you'd like in the table. At the bottom of the page, select Import Data Sources, then select the JNDI Name from the drop-down list. The JNDI Name should be the name of the Global Resource you wish to add using admintool.
Select Tools->Deploy to deploy the application. When the application is deployed, a Context is created in server.xml and a Resource Link is added within the context.
In admintool, select the Data Source element in the left pane.
Select Create New Data Source from the Available Actions list.
Set the Data Source attributes. See Data Source Attributes for more information on the options. Use the JNDI Name you specified in deploytool. Add the Driver Name, URL, User Name, and Password.
Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

If you select Commit Changes, the <JWSDP_HOME>/conf/server.xml file would would be updated with an entry for Resource and Resource Params within the GlobalNamingResources element. The Resource created here is linked to the context via the Resource Link element.

The following example is a section of a server.xml that shows the Resource and its associated ResourceParams element within the GlobalNamingResources and the Resource link within the context.
<GlobalNamingResources>
  <Environment description="Absolute Path name of the JWSDP
    Installation" name="jwsdp.home"
    override="true" type="java.lang.String"
    value="/home/your_name/jwsdp-1_0"/> 
  <Resource auth="Container" description="Users and Groups
    Database" name="UserDatabase"
    scope="Shareable" 
    type="org.apache.catalina.UserDatabase"/>  
  <Resource name="jdbc/ActivityDB" scope="Shareable"
     type="javax.sql.DataSource"/>    
  <ResourceParams name="UserDatabase">
    <parameter>
      <name>factory</name>
      <value>org.apache.catalina.users.MemoryUserDatabaseFacto
ry</value>
    </parameter>
    <parameter>        
      <name>pathname</name>
      <value>conf/tomcat-users.xml</value>      
    </parameter>    
  </ResourceParams>    
  <ResourceParams name="jdbc/ActivityDB">
    <parameter> 
      <name>validationQuery</name> 
      <value></value> 
    </parameter>      
    <parameter>
      <name>user</name>
      <value>your_user_name</value>
    </parameter>      
    <parameter>
      <name>maxWait</name> 
      <value>5000</value> 
    </parameter>   
    <parameter>   
      <name>maxActive</name> 
      <value>4</value>     
    </parameter>      
    <parameter>     
      <name>password</name> 
      <value>your_password</value> 
    </parameter>     
    <parameter> 
      <name>url</name>  
      <value>jdbc:pointbase:server://localhost/ActivityDB</val
ue>      
    </parameter>     
    <parameter>        
      <name>driverClassName</name>  
      <value>com.pointbase.jdbc.jdbcUniversalDriver</value>
    </parameter>     
    <parameter> 
      <name>maxIdle</name> 
      <value>2</value>    
    </parameter>    
  </ResourceParams> 
</GlobalNamingResources>   
  <Context
    className="org.apache.catalina.core.StandardContext"
    cachingAllowed="true"charsetMapperClass="org.apache.
    catalina .util.CharsetMapper" cookies="true"
    crossContext="false" debug="0"displayName="JSTLActTrack"
    docBase="/home/your_name/work/Standard
    Engineõocalhost\manager\JSTLActTrack.war"
    mapperClass="org.apache.catalina.core.
    StandardContextMapper" path="/JSTLActTrack"
    privileged="false"reloadable="false" useNaming="true"
    wrapperClass="org.apache.catalina.core.StandardWrapper">  
    <ResourceLink global="jdbc/ActivityDB" name="ActivityDB"/> 
  </Context>
 
Data Source Attributes

Note: In order to use a Data Source, you must have a JDBC driver installed and configured.

The attributes outlined in Table A-20 may be viewed, set, or modified for a Data Source.

Table A-20 Data Source Attributes
Attribute
Description

JNDI Name
The JNDI name under which you will look up preconfigured data sources. By convention, all such names should resolve to the jdbc subcontext (relative to the standard java:comp/env naming context that is the root of all provided resource factories.) For example, this entry might look like jdbc/EmployeeDB.

Data Source URL
The connection URL to be passed to the JDBC driver. One example is jdbc:HypersonicSQL:database.

JDBC Driver Class
The fully-qualified Java class name of the JDBC driver to be used. One example is org.hsql.jdbcDriver.

User Name
The database user name to be passed to the JDBC driver.

Password
The database password to be passed to the JDBC driver.

Max. Active Connections
The maximum number of active instances that can be allocated from this pool at the same time. Default value is 4.

Max. Idle Connections
The maximum number of connections that can sit idle in this pool at the same time. Default value is 2.

Max. Wait for Connections
The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. Default value is 5000.

Validation Query
A SQL query that can be used by the pool to validate connections before they are returned to the application. If specified, this query MUST be an SQL SELECT statement that returns at least one row.

Configuring Environment Entries

Use this element to configure or delete named values that will be made visible to Web applications as environment entry resources. An example of an environment entry that might be useful is the absolute path to the Java WSDP installation, which is already defined as an Environment Entry.

To edit an Environment Entry,

Expand the Resources element in the left pane.
Select Environment Entries in the left pane.
Select the Environment Entry to edit in the right pane. By default, an environment entry for the absolute path to the Java WSDP installation displays.
Edit the values in the right pane.
Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new Environment Entry for Tomcat,

Select the Environment Entries element in the left pane.
Select Create New Env Entry from the Available Actions list.
Set the Environment Entries attributes. See Environment Entries Attributes for more information on the options.
Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

Environment Entries Attributes

Table A-21 Environment Entries Attributes
Attribute
Description

Name
The name of the environment entry to be created, relative to the java:comp/env context. For example, jwsdp.home.

Type
The fully qualified Java class name expected by the Web application for this environment entry: java.lang.Boolean, java.lang.Byte, java.lang.Character, java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short, or java.lang.String.

Value
The parameter value that will be presented to the application when requested from the JNDI context. This value must be convertible to the Java type defined by the type attribute. For example, <path_to_home_directory>/jwsdp-1_0.

Override Application Level Entries
Whether or not you want an Environment Entry for the same environment entry name, found in the Web application's deployment descriptor, to override the value specified here. Set this to False if you do not want an Environment Entry for the same environment entry name, found in the Web application's deployment descriptor, to override the value specified here. By default, overrides are allowed.

Description
An optional, human-readable description of this environment entry.

The valid attributes for an Environment element are outlined in Table A-21.

Configuring User Databases

Use this Resource to configure and edit a database of users for this server. The default database, <JWSDP_HOME>/conf/tomcat-users.xml, is already defined.

To edit a User Database,

Expand the Resources element in the left pane.
Select User Databases in the left pane.
Select the User Database to edit in the right pane. By default, a user database for Tomcat displays.
Edit the values in the right pane.
Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

To create a new User Database for Tomcat,

Select the User Databases element in the left pane.
Select Create New User Database from the Available Actions list.
Set the User Database attributes. See User Database Attributes for more information on the options.
Select Save to save the changes for this session. Select Commit Changes to save the changes for when Tomcat is restarted.

User Database Attributes

Configure a User Database with the attributes outlined in Table A-22.

Table A-22 User Database Attributes
Attribute
Description

Name
The name of the user database to be created, for example, UserDatabase.

Location
The location where the user database should be created, for example, conf/tomcat-users.xml.

Factory
The type of factory to use for this database, usually org.apache.catalina.users.MemoryUserDatabaseFactory.

Description
A human-readable description of what type of data the database holds, for example, Users and Groups Database.

**Table A-20 Data Source Attributes**
Attribute	Description
JNDI Name	The JNDI name under which you will look up preconfigured data sources. By convention, all such names should resolve to the `jdbc` subcontext (relative to the standard `java:comp/env` naming context that is the root of all provided resource factories.) For example, this entry might look like `jdbc/EmployeeDB`.
Data Source URL	The connection URL to be passed to the JDBC driver. One example is `jdbc:HypersonicSQL:database`.
JDBC Driver Class	The fully-qualified Java class name of the JDBC driver to be used. One example is `org.hsql.jdbcDriver`.
User Name	The database user name to be passed to the JDBC driver.
Password	The database password to be passed to the JDBC driver.
Max. Active Connections	The maximum number of active instances that can be allocated from this pool at the same time. Default value is 4.
Max. Idle Connections	The maximum number of connections that can sit idle in this pool at the same time. Default value is 2.
Max. Wait for Connections	The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. Default value is 5000.
Validation Query	A SQL query that can be used by the pool to validate connections before they are returned to the application. If specified, this query MUST be an SQL SELECT statement that returns at least one row.

**Table A-21 Environment Entries Attributes**
Attribute	Description
Name	The name of the environment entry to be created, relative to the `java:comp/env` context. For example, `jwsdp.home`.
Type	The fully qualified Java class name expected by the Web application for this environment entry: `java.lang.Boolean`, `java.lang.Byte`, `java.lang.Character`, `java.lang.Double`, `java.lang.Float`, `java.lang.Integer`, `java.lang.Long`, `java.lang.Short`, or `java.lang.String`.
Value	The parameter value that will be presented to the application when requested from the JNDI context. This value must be convertible to the Java type defined by the type attribute. For example, `<path_to_home_directory>/jwsdp-1_0`.
Override Application Level Entries	Whether or not you want an Environment Entry for the same environment entry name, found in the Web application's deployment descriptor, to override the value specified here. Set this to `False` if you do not want an Environment Entry for the same environment entry name, found in the Web application's deployment descriptor, to override the value specified here. By default, overrides are allowed.
Description	An optional, human-readable description of this environment entry.

**Table A-22 User Database Attributes**
Attribute	Description
Name	The name of the user database to be created, for example, `UserDatabase`.
Location	The location where the user database should be created, for example, `conf/tomcat-users.xml`.
Factory	The type of factory to use for this database, usually `org.apache.catalina.users.MemoryUserDatabaseFactory`.
Description	A human-readable description of what type of data the database holds, for example, Users and Groups Database.

Home
TOC
Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.