From the IBM WebSphere Developer Technical Journal.

Introduction

In Part 1 of this two-part series, we covered the basics on administering IBM® WebSphere® Application Server Community Edition (hereafter called Community Edition), including an overview of the directory structure, starting up the server with different options, and using different commands and options provided by the deployer. In addition, you learned how to configure the server, including Tomcat default ports and logging properties, and how to recover your server from system failure. In Part 2, you will learn how to configure databases (including IBM® Cloudscape, Oracle®, Microsoft® SQL server and DB2®), Java Message Service (JMS), SSL, LDAP, and CORBA over IIOP.

The samples referenced in this article, including EMPdemo and dayTrader, are available in a zip file you can download from the Community Edition product download page.

Before you continue: This article was written for WebSphere Application Server Community Edition V1.0, which was the current version at the time the article was published. Some of the information in this article may not be applicable to later versions. To follow along with this article, be sure to use the product version on which this article is based. If you wish, you can download the current version of WebSphere Application Server Community Edition, or you can download an earlier version by visiting the product archive page.

Back to top

Configuring database resources

Most enterprise applications use a relational database. Community Edition uses the open source TranQL project as its database persistence engine. Community Edition provides a generic resource adapter to make a JDBC driver available as a J2EE Connection Architecture (J2CA) resource, and IBM Cloudscape vendor-specific resource adapters to make Cloudscape available as a J2CA resource from Tranql. As an added value, Community Edition also provides a WebSphere embedded resource adapter to make Microsoft SQL 2000 server available as a J2CA resource. Understanding the following files in the Community Edition repository will help you select the correct resource adapter for your datasource and build the database deployment plan:

• repository\tranql\rars\
• tranql-connector-1.0.rar: This is the TranQL Generic JDBC Resource Adapter that provides access to a SQL database via a generic JDBC connection. Connections are obtained from a java.sql.Driver using the configured JDBC URL, username, and password. As this interface does not provide access to an XAResource, only Local transactions are supported.
• tranql-connector-derby-client-local-1.0.rar: This is the TranQL Client Local Transaction Resource Adapter for IBM Cloudscape. The resource adapter provides access to a remote IBM Cloudscape database with local transaction support.
• tranql-connector-derby-client-xa-1.0.rar: This is the TranQL Client XA Transaction Resource Adapter for IBM Cloudscape. The resource adapter provides access to a remote IBM Cloudscape database with XA transaction support.
• tranql-connector-derby-embed-local-1.0.rar: This is the TranQL Embedded Local Resource Adapter for IBM Cloudscape. The resource adaptor provides access to an embedded IBM Cloudscape database with local transaction support.
• tranql-connector-derby-embed-xa-1.0.rar: This is the TranQL Embedded XA Resource Adapter for IBM Cloudscape. The resource adaptor provides access to an embedded IBM Cloudscape database with XA transaction support.
• tranql-connector-websphere-embed-local-1.0.rar: This is the TranQL IBM WebSphere Connect JDBC Driver Embedded Local Resource Adapter for Microsoft SQL 2000 server. The resource adaptor provides access to a Microsoft SQL 2000 server database with local transaction support.
• tranql-connector-websphere-embed-xa-1.0.rar: This is the TranQL IBM WebSphere Connect JDBC Driver Embedded XA Resource Adapter for Microsoft SQL 2000 server. The resource adaptor provides access to a Microsoft SQL 2000 server database with XA transaction support.
• All the TranQL rar files mentioned above include the tranql-1.1.ibm.jar file, which is the database persistence engine.
• repository\org.apache.derby\jars: This directory contains the IBM Cloudscape database server jar files.
• repository\websphere\jars: This directory contains the WebSphere embedded JDBC driver for Microsoft SQL 2000 database server.

You might be wondering why you do not see anything specific to Oracle, DB2, or MySQL databases mentioned above, even though Community Edition supports these databases. This is because JDBC drivers for Oracle, DB2, and MySQL database servers are not included in the Community Edition installation image. Instead, you will use the generic resource adapter (tranql-connector-1.0.rar) to deploy datasources for Oracle, DB2, and MySQL database servers and copy the necessary database-specific classes into the Community Edition repository. More information related to this will be covered later in this article.

Database configuration pool type

Community Edition supports the following three database configuration pool types. You can decide what database configuration pool type you need for your J2EE applications.

1. Server-wide datasource: This is used by all the applications running on the server. The EMPdemo sample provided by Community Edition uses the server-wide datasource.
2. Application scoped datasource: This is used by one or more modules of the same application.
3. Module scoped datasource: This is used only by one specific module in the application. The daytrader sample provided by Community Edition uses the module scoped datasource.

Configuring a database pool

No matter what database configuration pool type you decide to use, you need to build a database pool deployment plan. In the database pool deployment plan, you can specify the datasource configuration ID, its parent, dependencies, and resource adapter configuration information, such as the datasource name, and pool minimum and maximum size. By using the database pool deployment plan provided by the EMPdemo sample, we will show you how to understand and modify this plan to build your own database deployment plan.

• Define the datasource configuration ID and parent ID: The following portion of the database deployment plan specifies the configId, which needs to be unique to the Community Edition server instance. If the parent (value of the parentId) is not running when the datasource is deployed, the deployer starts the parent first to make sure it is available. In the EMPdemo sample, this portion of the database deployment plan is the same for different database servers (Listing 1).
  
  Listing 1: EMPdemo Cloudscape database pool deployment plan, Part I
  

  <?xml version="1.0"?> <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0" configId="EmployeeDatasource" parentId="org/apache/geronimo/Server">

  
  
• Define the dependency elements: The dependency elements define all the datasource dependencies, and their relative path to the Community Edition repository (Listing 2). IBM Cloudscape database server and its vendor-specific tranql resource adapters are shipped with Community Edition, so you do not have to worry about copying the jar files to the repository. By specifying these as dependencies, you can avoid including them within your own application.
  
  Listing 2: EMPdemo Cloudscape database pool deployment plan, Part II
  

  <dependency> <uri>org.apache.derby/jars/derby-10.1.ibm.jar</uri> </dependency> <dependency>s <uri>org.apache.derby/jars/derbynet-10.1.ibm.jar</uri> </dependency>

  
  As mentioned above, Community Edition also includes the WebSphere embedded Tranql resource adapter and WebSphere embedded type 4 JDBC driver (jar files located at repository\websphere\jars directory) for Microsoft SQL 2000 server. Based on this fact, you can come up with the following dependency elements for a datasource that accesses a Microsoft SQL 2000 server (Listing 3).
  
  Listing 3: EMPdemo Microsoft SQL database pool deployment plan, Part II
  

  <dependency> <uri>websphere/jars/base-3.5.11.jar</uri> </dependency> <dependency> <uri>websphere/jars/util-3.5.11.jar</uri> </dependency> <dependency> <uri>websphere/jars/sqlserver-3.5.11.jar</uri> </dependency>

  
  If you want to build the dependency elements for Oracle, DB2 or MySQL server, you can follow the same pattern. However, you need to create the directory and sub directory in the Community Edition repository, copy the JDBC driver jar files from the database server to the newly created directory, and specify the jar files and their path within the dependency uri elements before you try deploying the database deployment plan.
  
  
• Configure the resource adapter
• IBM Cloudscape database: The resource adapter configuration for IBM Cloudscape is straightforward because the Cloudscape specific resource adapter is already provided by Community Edition. You do not need to enter the JDBC driver information. You also do not need to create the database ahead of time if you set the CreateDatabase property to true. If you look at the example below, you just need to modify the name, UserName, Password, DatabaseName, CreateDatabase elements, and configure your database pool to build your own resource adapter configuration for Cloudscape (Listing 4). The name element defines the name that other modules will use to refer to this connection pool. It has to be unique within the database pool scope you define. For example, jdbc/EmployeeDatasource has to be unique on a server-wide scope because the configuration is for a server-wide datasource. You also need to specify your UserName, Password, DatabaseName, and CreateDatabase elements.
  
  The max-size element defines the maximum number of concurrent connections that are allowed. The min-size element defines the minimum number of concurrent connections that are allowed. The blocking-timeout-milliseconds element defines how many milliseconds the call will wait when getting a connection from the pool before it gives up. The idle-timeout-minutes element defines how many minutes the connection can be idle before it is closed and removed from the pool.
  
  You may also be wondering why the global-jndi-name element is commented out. This is because it is used when trying to connect to the datasource from a J2EE application client. There are no J2EE application clients in the EMPdemo sample. For more details regarding the Cloudscape resource adapters, see the ra.xml files in the tranql-connector-derby-client-local-1.0.rar, tranql-connector-derby-client-xa-1.0.rar, tranql-connector-derby-embed-local-1.0.rar, and tranql-connector-derby-embed-xa-1.0.rar files.
  
  Listing 4: EMPdemo Cloudscape database pool deployment plan, Part III
  

  <resourceadapter> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>javax.sql.DataSource </connectionfactory-interface> <connectiondefinition-instance> <name>jdbc/EmployeeDatasource</name> <config-property-setting name="UserName"> </config-property-setting> <config-property-setting name="Password"> </config-property-setting> <config-property-setting name="DatabaseName">Employee </config-property-setting> <config-property-setting name="CreateDatabase">true </config-property-setting> <connectionmanager> <xa-transaction> <transaction-caching/> </xa-transaction> <single-pool> <max-size>5</max-size> <min-size>0</min-size> <blocking-timeout-milliseconds>5000 </blocking-timeout-milliseconds> <idle-timeout-minutes>15</idle-timeout-minutes> <match-one/> </single-pool> </connectionmanager> <!--global-jndi-name>EmployeeDatasource</global-jndi-name--> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> </connector>

  
  
• Oracle database: As mentioned above, Community Edition provides specific resource adapters for IBM Cloudscape and Microsoft SQL server 2000. For Oracle, DB2 or MySQL database, you need to use the generic resource adapter that allows you to specify the Driver and ConnectionURL for the JDBC driver (Listing 5). For details on the generic resource adapter, see the ra.xml file in the tranql-connector-1.0.rar file.
  
  Listing 5: EMPdemo Oracle database resource adapter configuration
  

  ... <config-property-setting name="UserName">wasce</config-property-setting> <config-property-setting name="Password">password</config-property-setting> <config-property-setting name="Driver">oracle.jdbc.driver.OracleDriver</ config-property-setting> <config-property-setting name="ConnectionURL">jdbc:oracle:thin: @oracleServer.ibm.com:1521:orcl</config-property-setting> ...

  
  
• IBM DB2 database: The IBM DB2 database resource adapter configuration is the same as Oracle, except that you need to specify the DB2-specific UserName, Password, Driver and ConnectionURL elements (Listing 6).
  
  Listing 6: Daytrader DB2 database resource adapter configuration
  

  ... <config-property-setting name="UserName">db2inst1 </config-property-setting> <config-property-setting name="Password">password </config-property-setting> <config-property-setting name="Driver">com.ibm.db2.jcc.DB2Driver </config-property-setting> <config-property-setting name="ConnectionURL"> jdbc:db2://db2.raleigh.ibm.com:50001/tradedb </config-property-setting> ...

  
  
• Microsoft SQL 2000 Server: As an added value on top of Apache Geronimo, Community Edition provides the WebSphere embedded Tranql resource adapters for Microsoft SQL 2000 server, which handles the Driver and ConnectionURL information for you, so you just specify the ServerName and DatabaseName (Listing 7). If your SQL server is running on a different port than the default port (1433), you can specify the PortNumber property, after the DatabaseName element. For details on the resource adapters, see the ra.xml files in the tranql-connector-websphere-embed-local-1.0.rar and tranql-connector-websphere-embed-xa-1.0.rar files.
  
  Listing 7: EMPdemo Microsoft SQL database resource adapter configuration
  

  ... <config-property-setting name="UserName">wasce </config-property-setting> <config-property-setting name="Password">password </config-property-setting> <config-property-setting name="ServerName">servername.ibm.com </config-property-setting> <config-property-setting name="DatabaseName">wascedb </config-property-setting> ...

  
  

Deploying and modifying a database pool

Deploy a database pool: You have learned how to build the database deployment plan and what resource adapters you should use for different database servers. Let's walk through how to deploy a database pool in a Community Edition server using the deployer tool from the bin directory (Listing 8).

                            
deploy.[bat|sh] --user system --password manager deploy ..\repository\tranql\rars\
tranql-connector-derby-embed-xa-1.0.rar Cloudscape-db-plan.xml
		

In the command window that runs the deployment command, you will see an output indicating if the database pool has been deployed successfully. Replace the administrator user name and password as needed. If you want to use other resource adapters, replace the rar file provided above with your choice. For example, if you deploy the EMPdemo Oracle database, replace tranql-connector-derby-embed-xa-1.0.rar with tranql-connector-1.0.rar, and replace Cloudscape-db-plan with the EMPdemo Oracle database deployment plan (oracle-db-plan.xml).

Modify a database pool: The deployment tool does not provide a modify command. To modify a database pool, you need to undeploy the database pool and deploy it.

Using a database pool

To use the database pool you just deployed, define the specific resource reference in the Apache Geronimo deployment plan to refer to it (Listing 9). You also need to declare the resource reference in web.xml and look for the database pool via JNDI from the application code. You can look at the src\webapp\WEB-INF\web.xml and src\webapp\jsp\EMPdemo.jsp files in your EMPdemo home directory for details.

                            
<resource-ref>
	<ref-name>jdbc/DataSource</ref-name>
	<resource-link>jdbc/EmployeeDatasource</resource-link>
</resource-ref>
		

Back to top

Configuring Java Message Service

Java Message Service (JMS) supports the sending of messages between different application components, even when distributed. Message-driven beans use JMS to receive messages, and then potentially take some action based on those messages.

ActiveMQ

JMS support in Community Edition is provided by ActiveMQ. ActiveMQ is a JMS 1.1 provider that fully supports J2EE 1.4 compliant servers, including Community Edition. It also includes a Java Connector Architecture (JCA) 1.5 resource adapter that allows the application server to pool connections, manage transactions, and control connector security. Access to JMS resources is provided by the ActiveMQ JCA-compliant resource adapter. Currently, ActiveMQ is the only JMS provider known to work with Community Edition.

JMS message broker

The ActiveMQ server, or message broker, is started by default when the Community Edition server is started. Its configuration, org/apache/geronimo/ActiveMQServer, is defined in system-activemq-plan.xml found in the wasce_install_root/doc/plan directory. This configuration includes two transports, a TCP transport running on port 61616, and a direct transport for clients running in the same JVM (Listing 10). Other transports supported by ActiveMQ include SSL, NIO, UDP, multicast, JGroups, and JXTA transports.

                    
<gbean gbeanName="geronimo.server:J2EEApplication=null,
J2EEModule=org/apache/geronimo/ActiveMQServer,J2EEServer=geronimo,
j2eeType=JMSConnector,broker=ActiveMQ,name=ActiveMQ.tcp.default"
class="org.activemq.gbean.ActiveMQConnectorGBean">
        <attribute name="protocol">tcp</attribute>
        <attribute name="host">0.0.0.0</attribute>
        <attribute name="port">61616</attribute>
        <reference name="activeMQContainer">
        <gbean-name>geronimo.server:j2eeType=JMSServer,name=ActiveMQ,*
        </gbean-name></reference>
    </gbean>

    <gbean gbeanName="geronimo.server:J2EEApplication=null,
    J2EEModule=org/apache/geronimo/ActiveMQServer,J2EEServer=geronimo,j2eeType=JMSConnector,
    broker=ActiveMQ,name=ActiveMQ.vm.localhost" 
	class="org.activemq.gbean.ActiveMQConnectorGBean">
        <attribute name="protocol">vm</attribute>
        <attribute name="host">localhost</attribute>
        <attribute name="port">-1</attribute>
        <reference name="activeMQContainer">
        <gbean-name>geronimo.server:j2eeType=JMSServer,name=ActiveMQ,*
        </gbean-name></reference>
    </gbean>
        

The recommended way to change the message broker configuration is to use config.xml to configure the correct attributes. See Part 1 for more information on using config.xml to configure server attributes. The problem is that, in practice, it is difficult to determine what the correct gbean attributes are and if they are manageable. The alternative, redeploying the system-activemq-plan.xml, is not recommended because it can cause problems later on. If you can figure out the attribute names (and if they are manageable), you can edit config.xml by changing these plans, and then redeploying them.

Configuring JMS resources

The message broker is only useful when it has destinations configured on it. Creating and configuring these resources in Community Edition means deploying a resource adapter instance with information on how to talk to the message broker. For an example, take a look at system-jms-plan.xml (found in the wasce_install_root/doc/plan directory). This plan creates a resource adapter instance and the connection factory needed to create two queues, MDBTransferBeanOutQueue and SendReceiveQueue, for internal use (Listing 11).

                    
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0"
    configId="org/apache/geronimo/SystemJMS"
    parentId="org/apache/geronimo/ActiveMQServer">
    <resourceadapter>
        <resourceadapter-instance>
            <resourceadapter-name>ActiveMQ RA</resourceadapter-name>
            <config-property-setting name="ServerUrl"
            >tcp://0.0.0.0:61616</config-property-setting>
            ...
            </resourceadapter-instance>
            ...
    </resourceadapter>
    		...
    	  <adminobject>
    	  <adminobject-interface>javax.jms.Queue</adminobject-interface>
    	  <adminobject-class>org.codehaus.activemq.message.ActiveMQQueue
    	  </adminobject-class>
    	  <adminobject-instance>
    	  <message-destination-name>SendReceiveQueue</message-destination-name>
    	  <config-property-setting name="PhysicalName"
            >SendReceiveQueue</config-property-setting>
        </adminobject-instance>
    </adminobject>
</connector>
        

To create your own resource adapter instance, you can copy the connector element from the system-jms-plan.xml plan, give it its own configId, and replace its queues with your own queues and topics. Where you copy the connector element to depends on the scope you want your connector instance to have. You can define and deploy your resource adapter as a standalone connector visible to all other modules by putting it into its own plan and deploying it with a reference to the activemq rar file:

deploy.[bat|sh] deploy my-jms-plan.xml ..\repository\activemq\rars\activemq-ra-3.2-M1.ibm.rar

The other option is to create a resource adapter instance within your application or module's scope.

The dayTrader sample application is an example of an application with its own resource adapter instance. It has references to one queue, TradeBrokerQueue, and one topic, TradeStreamerTopic. The definition of these resources is found within one of the ext-module elements in daytrader-plan.xml (Listing 12). By using the ext-module element dayTrader, you can use the existing copy of the Active MQ connector without having to include it in the application.

                    
<ext-module>
        <connector>TradeJMS</connector>
        <external-path>activemq/rars/activemq-ra-3.2-M1.ibm.rar</external-path>
        <connector
            xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector"
            xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
            configId="TradeJMS"
            parentId="TradeDataSource">
            ...
           </connector>
</ext-module>
        

Both the resource adapter instance in system-jms-plan.xml and the one in daytrader-plan.xml are configured with the same information: how to connect to the JMS server, what settings the queue and topic connection factories should use when creating new resources, and references to queues and topics. This is the same information you need to provide when configuring your own resource adapter instances.

The purpose of the adminobject elements within the connector is to connect the message destination references declared in the application's J2EE descriptors with actual physical destinations. In daytrader's ejb-jar.xml file, for example, message-destination-ref elements for TradeBrokerQueue and TradeStreamerStopic are declared (Listing 13).

                    
<message-destination-ref>
	<message-destination-ref-name>jms/TradeBrokerQueue</message-destination-ref-name>
	<message-destination-type>javax.jms.Queue</message-destination-type>
	<message-destination-usage>Produces</message-destination-usage>
	<message-destination-link>TradeBrokerQueue</message-destination-link>
</message-destination-ref>
<message-destination-ref>
	<message-destination-ref-name>jms/TradeStreamerTopic</message-destination-ref-name>
	<message-destination-type>javax.jms.Topic</message-destination-type>
	<message-destination-usage>Produces</message-destination-usage>
	<message-destination-link>TradeStreamerTopic</message-destination-link>
</message-destination-ref>

Because adminobject elements are just mappings between message destination references and physical destinations, they can be mapped in multiple locations. dayTrader's J2EE application client, tradeStreamerAppclient, also has a resource adapter instance that knows how to talk to the Community Edition server as long as it is accessible at the specified serverUrl. In this case, it is tcp://localhost:61616. This client also has an adminobject element that maps the TradeStreamerTopic reference to its actual destination.

Back to top

Other useful resources

This section provides other resources for you.

Configuring SSL

Community Edition supports using Secure Sockets Layer (SSL) to secure access to Web resources using the HTTPS protocol. SSL support for Enterprise JavaBeans is not yet available. By default, Community Edition starts an HTTPS connector on port 8443 to access your Web applications. This initial configuration uses a keystore you can use for testing, but you should not use it in a production environment. Since the same keystore is distributed with every copy of Community Edition, the key can no longer be considered secret. If you need to change the initial configuration, the existing keystore, or what entities are trusted, the best source is the Community Edition documentation. The following sections are relevant:

• Configuring an HTTPS connector
• Managing SSL certificates
• Managing trust

Configuring Community Edition with LDAP

Community Edition supports Lightweight Directory Access Protocol (LDAP) authentication against directory servers. You can either use IBM LDAP server or Apache LDAP Directory. No matter which LDAP server you choose, you need to install and set it up first because Community Edition does not provide any LDAP servers. You also need to build a Community Edition-specific LDAP security realm plan that defines the name of the GenericSecurityRealm and its authentication policy by wiring up login modules configuration into the realm. For more information on this topic, see Configuring Apache LDAP Directory.

Configuring CORBA over IIOP

Common Object Request Broker Architecture (CORBA) is a vendor-independent architecture and infrastructure that allows computer applications to work together over networks. Community Edition provides CORBA support for both Sun® and IBM JDK/JRE. If your application uses CORBA with the IBM JDK/JRE, make sure that you have the supported JDK/JRE ifixes documented in the product documentation. For more information on CORBA configuration, see Forge ahead with Geronimo CORBA interoperability.

Back to top

Conclusion

Part 2 of this two-part series showed how to configure database resources, including IBM Cloudscape, Oracle, Microsoft SQL 2000, and DB2 as well as JMS resources. In addition, useful resources are provided if you need information on how to configure SSL, LDAP, and CORBA over IIOP. Now that you have the information you need to get started with system administration, you can successfully manage your Community Edition server.

Resources

Learn

• IBM WebSphere Developer Technical Journal: Get started with WebSphere Application Server Community Edition
  
  
• TranQL is Community Edition's persistence engine.
  
  
• ActiveMQ provides Community Edition's JMS support.
  
  
• IBM WebSphere Application Server Community Edition product documentation
  
  
• IBM WebSphere Application Server Community Edition resources
  
  
• Apache Geronimo project resources
  
  
• Apache Geronimo and IBM WebSphere Application Server Community Edition forums
  
  

Get products and technologies

• Download the latest version of IBM WebSphere Application Server Community Edition
  
  
• Download an earlier version of IBM WebSphere Application Server Community Edition
  
  
• IBM WebSphere Application Server Community Edition technical support offerings
  
  

Discuss

• Participate in the discussion forum.
  
  
• developerWorks blogs: Get involved in the developerWorks community.
  
  

About the authors

Lin Sun is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group WebSphere Application Server Community Edition Development Team. She received a master's degree in information science from the University of North Carolina at Chapel Hill.

Nell Gawor is an advisory software engineer for IBM in Research Triangle Park, North Carolina, in the Software Group Advanced Design and Technology Group. She received a Masters Degree in Computer Science from the University of Illinois at Urbana-Champaign. Contact Nell at ngawor@us.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Configuring database resources
• Configuring Java Message Service
• Other useful resources
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: DB2 Enterprise
• Demo: DB2 serving ATOM feed
• Webcast: A smarter way to successful SOA - Information as a trusted strategic asset
• Briefing: Information on Demand
• Buy: DB2 Enterprise

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers