Chapter 5. External Resources

Table of Contents

5.1. Resource Types
5.2. Resource Configuration
5.2.1. Configuring a Data Source
5.2.2. Configuring a Mail Source
5.2.3. Configuring a URL Source
5.2.4. Configuring a Custom Resource
5.2.5. Configuring an External Resource (JMS)
5.2.6. External Resource Configuration (Tmax)

This chapter describes a variety of external resources that can be used to build a system by integrating with JEUS, and how to configure them. Refer to each external resource guide for more information about configuring external resources and their usage.

5.1. Resource Types

External resources exist outside JEUS, and applications can access them through JEUS. A typical example is a database. Resources like these can be accessed by adding related configurations to JEUS.

Note

If an external resource provides a resource adapter with JCA standard compatibility, it is recommended to deploy and use the provided resource adapter.

The following are the resources that can be configured in JEUS.

  • Data Source

    JDBC compliant database.

    A client can directly access a data source without adding any configurations to JEUS. However, configuring a data source enables applications to more easily access databases by using JDBC connection pool through JNDI. Refer to "Chapter 6. DB Connection Pool and JDBC" for more information about data source configurations.

  • Mail Resource

    A mail resource is used by a client application to send an e-mail by using a mail protocol like SMTP. In JEUS, a mail resource binds the e-mail host information to the JNDI export name and allows the client to indirectly gain access to the host.

    A mail resource of the javax.mail.Session type can be obtained through JNDI lookup.

  • URL Resource

    A URL resource allows applications to access the external URL objects through JNDI.

    If a URL changes, the URL configuration is modified and the applications can continue to use the resource without source modification.

    A URL object of the java.net.URL type can be obtained through JNDI lookup.

  • Message Bridge

    A message bridge is used to connect destinations of multiple JMS vendors.

    An MQ that complies with the JMS 1.1 specification can be configured without any limitations. For more information, refer to ????.

  • Custom Resource

    A custom resource allows a Java bean resource to be bound to the JNDI repository. It is a typical resource that performs a lookup by using a service that is registered through the JNDI ObjectFactory.

  • External Resource - IBM MQ and Sonic MQ

    Denormalized resources that can be connected to JEUS. Usually, Java Message Service(JMS) products of IBM MQ or Sonic MQ and Tmax TP Monitor can be configured in JEUS.

    These resources can be accessed by using the Java API even though they are not configured in JEUS. However, configuration is required if they are managed by a transaction manager. (Refer to"Chapter 7. Transaction Manager").

  • External Resource

    Resources running on JEUS. They are usually used by WebT, jTmax, or InfiniteCache that are integrated with JEUS. A class that implements the jeus.external.ResourceBootstrapper interface must be used to access the external resources in JEUS.

  • Concurrency Utilities Resource

    Resources provided by Concurrency Utilities for Java EE. This is used to define tasks that can be managed in an application server, and maintain contexts while implementing the tasks. For more information, refer to "JEUS Concurrency Utilities for Java EE Guide".

5.2. Resource Configuration

This section describes how to configure each resource in WebAdmin.


Resources are configured within the scope of the domain and registered on a server when the server starts.

Select [Resources] from the left menu of WebAdmin to view each resource and register it on the server, as well as modify or delete it.

[Figure 5.1] Configuring a Resource in WebAdmin

Configuring a Resource in WebAdmin


5.2.1. Configuring a Data Source

Data sources handle configurations that are related to the database. For more information, refer to "Chapter 6. DB Connection Pool and JDBC".

5.2.2. Configuring a Mail Source

A mail source can be used to configure an SMTP host that is used by a client application to send an e-mail to JEUS. Each e-mail host on each SMTP server is configured in WebAdmin. Refer to the JavaMail specification for more information about e-mail hosts.

Select [Resources] > [mail Source] from the left menu of WebAdmin and look up a mail source that is registered to the domain.

[Figure 5.2] Configuring a Mail Source in WebAdmin(1)

Configuring a Mail Source in WebAdmin(1)


Click [Add] to register a mail source to the domain.

[Figure 5.3] Configuring a Mail Source in WebAdmin(2)

Configuring a Mail Source in WebAdmin(2)


Note

Since the property names in the 'Main Property' section follow the JavaMail specification, refer to the JavaMain specification for each property configuration.

5.2.3. Configuring a URL Source

The following values are bound to the JNDI names, PRIMARY_URL and SECONDARY_URL respectively.

http://www.foo.com
http://www.bar.com

Select [Resources] > [URL Source] from the left menu of WebAdmin to go to the screen to look up, register, change, or delete a URL source.

[Figure 5.4] Configuring a URL Source in WebAdmin (1)

Configuring a URL Source in WebAdmin (1)

Click [Add] to register a URL source to the domain.

[Figure 5.5] Configuring a URL Source in WebAdmin(2)

Configuring a URL Source in WebAdmin(2)

5.2.4. Configuring a Custom Resource

Custom resources enable the lookup and use of Java bean resources through JNDI ObjectFactory. This section describes how to configure and register custom resources.

The following is an example of an object factory class that creates a Java bean resource class and resource instance. This class must be exist in the 'SERVER_HOME/lib/application' or 'DOMAIN_HOME/lib/application' directory.

[Example 5.1] Custom Resource Class Example

package dog;

import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.Name;
import javax.naming.spi.ObjectFactory;

public class DogFactory implements ObjectFactory {    
    public DogFactory() {}

    public Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?, ?> environment) 
        throws Exception {
        Dog dog = Dog.getInstance();
        System.out.println("Creating a dog whose name is " + dog.getName() + ", and age is " + dog.getAge());
        return dog;
    }
}

[Example 5.2] Factory Class Example that Creates Custom Resources

package dog;

public class Dog implements java.io.Serializable {
    public static final String DOG_NAME = "wangwang";
    public static final int DOG_AGE = 1;
    
    private static Dog instance = new Dog();
    
    private int age = DOG_AGE;
    private String name = DOG_NAME;
    
    public Dog() {}
    
    public static Dog getInstance() {
        return instance;
    }
    
    public int getAge() {
        return age;
    }
    
    public void setAge(int age) {
        this.age = age;
    }
    
    public String getName() {
        return name;
    }
    
    public void setName(String name) {
        this.name = name;
    }

    public boolean equals(Object anObject) {
        if (this == anObject) {
            return true;
        }
        if (anObject instanceof Dog) {
            Dog anotherDog = (Dog) anObject;
            return (this.age == anotherDog.age && this.name.equals(anotherDog.name));
        }
        return false;
    }
    
}

Note

To dynamically add a custom resource, the applicable classes must exist in the class path of the server class loader. If the class loader cannot load the classes, then the add command, which is normally executed dynamically, is processed as pending. In this case, add the custom resource classes to the 'SERVER_HOME/lib/application' or 'DOMAIN_HOME/lib/application' folder and restart the server.

Deleting a custom resource is not performed gracefully. In other words, even if there is a request in progress, the system does not wait until the request is complete which may cause errors to occur in the user applications.

Using WebAdmin

The following screenshots show how to dynamically register a custom resource in WebAdmin.

  1. Select [Resources] > [Custom Resource] from the left menu of WebAdmin.

    [Figure 5.6] Configuring a Custom Resource in WebAdmin (1)

    Configuring a Custom Resource in WebAdmin (1)


  2. Register a custom resource for the domain by clicking [Add]. Enter the configuration information of the custom resource and click [OK].

    [Figure 5.7] Configuring a Custom Resource in WebAdmin (2)

    Configuring a Custom Resource in WebAdmin (2)


  3. Temporarily save the resource by clicking [OK], and the result is displayed at the top of the screen. The resource information to add to the custom resource table is also displayed.

    [Figure 5.8] Configuring a Custom Resource in WebAdmin (3)

    Configuring a Custom Resource in WebAdmin (3)


  4. Add the custom resource to the server configuration so that it can be used on the server.

    Go to [Servers] > [Server1] > [Basic Info] > Custom Resource Refs from the left menu of WebAdmin. Select the added custom resource, and click [OK].

    [Figure 5.9] Configuring a Custom Resource in WebAdmin(4)

    Configuring a Custom Resource in WebAdmin(4)


  5. Click [Apply Changes] to apply the custom resource to the domain. A message stating that the custom resource has been applied to the domain is displayed at the top of the screen.

    The custom resource can be used immediately on the server.

Using the Console Tool

A custom resource can be looked up and dynamically added or deleted using the console tool.

[Example 5.3] Looking up, Adding, and Deleting Custom Resources in the Console Tool

[DAS]domain1.adminServer>add-custom-resource custom/dog -resource dog.Dog -factory dog.DogFactory
Successfully performed the ADD operation for A custom resource.
Check the results using "list-custom-resources or add-custom-resource"

[DAS]domain1.adminServer>list-custom-resources
List of Custom Resources
================================================================================
+-------------+--------------------+--------------------------+----------------+
| Export Name |   Resource Class   |       Factory Class      |   Properties   |
+-------------+--------------------+--------------------------+----------------+
| custom/dog  | dog.Dog            | dog.DogFactory           | [test=1,       |
|             |                    |                          |test1=2]        |
+-------------+--------------------+--------------------------+----------------+
================================================================================

[DAS]domain1.adminServer>add-custom-resource-to-servers custom/dog -servers server1
Successfully performed the ADD operation for A custom resource.
Check the results using "list-custom-resources"

[DAS]domain1.adminServer>remove-custom-resource custom/dog
Successfully performed the REMOVE operation for A custom resource.
Check the results using "list-custom-resources or remove-custom-resource"

[DAS]domain1.adminServer>list-custom-resources
List of Custom Resources
================================================================================
+-------------+--------------------+--------------------------+----------------+
| Export Name |   Resource Class   |       Factory Class      |   Properties   |
+-------------+--------------------+--------------------------+----------------+
(No data available)
================================================================================

5.2.5. Configuring an External Resource (JMS)

External resources are largely divided into JMS source and Connector.

Select [Resources] > [External Source] from the left menu of WebAdmin to go to the external resource list to enter the configurations.

[Figure 5.10] Configuring an External Resource in WebAdmin

Configuring an External Resource in WebAdmin


JMS Source

JMS sources that are configured in the domain can be looked up, added, modified, or deleted in WebAdmin.

To add a JMS source, click [Add] at the top of JMS Source in the External Resource list screen.

The following describes the JMS source configuration.

[Figure 5.11] Adding a Jms Source in WebAdmin

Adding a Jms Source in WebAdmin

The following describes the configuration items.

ItemDescription
Vendor

JMS vendor. Select one of:

  • ibmmq: IBM product.

  • sonicmq: Sonic MQ.

  • others: other product.

Factory Class NameFactory class name of the JMS resource.
Resource Type

JMS type.

Select one of:

  • QCF

  • TCF

  • Q

  • T

  • XAQCF

  • XATCF

  • LOCALXAQCF

  • LOCALXATCF

Export NameName to bind to JNDI. Can be used to obtain JMS ConnectionFactory and Destination.
QueueUse only when the resource type is Q.
QueueManagerUse only when the resource type is Q.
TopicUse only when the resource type is T.
PropertyNecessary attributes for JMS resources. It has a name, a type, and a value.

Note

Refer to the IBM MQ or the Sonic MQ manual for more information about each item.

Adding a Connector

A connector that is configured in the domain can be looked up, added, changed, or deleted in WebAdmin. Refer to "JEUS JCA guide" for more information about connectors.

5.2.6. External Resource Configuration (Tmax)

External resources can be configured so that JEUS can integrate with Tmax or Infinite Cache. For integration with Tmax, JEUS connects to Tmax to configure WebT and JTmax. WebT is an outbound service that uses Tmax transaction services, and JTmax is an inbound service that receives requests from Tmax. Refer to the JTmax Server Guide of the Tmax manual for more information.

This section describes how to implement and register the external resources.

The following is the jeus.external.ResourceBootstrapper interface. The class that implements this interface must reside in the 'SERVER_HOME/lib/application' or 'DOMAIN_HOME/lib/application' directory.

[Example 5.4] jeus.external.ResourceBootstrapper

package jeus.external;

import javax.naming.Context;
import java.util.Map;

/**
 * A bootstrapper that enables external resources to be used by JEUS. 
 */
public interface ResourceBootstrapper {
    /**
     *
     * @param propertyMap Map that has the resource configurations.
     */
    void setProperties(Map propertyMap) throws InvalidPropertyException;

    /**
     * Binds a resource.
     * @param context
     */
    void initResources(Context context);

    /**
     * Returns information about the available properties.
     * @return
     */
    ResourcePropertyInfo[] getPropertyInfo();

    /**
     *
     * @param propertyMap Map that has the changed properties.
     */
    void modifyProperties(Map propertyMap) throws InvalidPropertyException;

    /**
     * Binds the resources again.
     * @param context
     */
    void reconfigResources(Context context);

    /**
     * Removes the resource(s).
     * @param context
     */
    void destroyResources(Context context);
}


Note

To dynamically add an external resource, the applicable classes must exist in the class path of the server class loader. If the class loader cannot load the classes, then the add command, which is normally executed dynamically, is processed as pending. In this case, add the external resource classes to the 'SERVER_HOME/lib/application' or 'DOMAIN_HOME/lib/application' folder and restart the server.

Deleting an external resource is not performed gracefully. This means that an incomplete request may cause errors to occur in the user applications.

Using WebAdmin

The following shows how to dynamically register an external resource using WebAdmin.

  1. Select [Resources] < [External Resource] from the left menu in WebAdmin. Click [ADD] to register a ResourceBootstrapper for JTmax, WebT, and Infinite Cache to the domain.

    [Figure 5.12] External Resource Configuration in WebAdmin (1)

    External Resource Configuration in WebAdmin (1)


  2. Enter the external resource configuration and click [OK].

    [Figure 5.13] External Resource Configuration in WebAdmin (2)

    External Resource Configuration in WebAdmin (2)

  3. Temporarily save the resource by clicking [OK], and the result is displayed at the top of the screen. The resource information to add to the external resource table is also displayed.

    [Figure 5.14] External Resource Configuration in WebAdmin (3)

    External Resource Configuration in WebAdmin (3)

  4. Add the external resource to the server configuration so that it can be used on the server.

    Go to [Servers] > [Server1] > [Basic Info] > External Resource Refs from the left menu of WebAdmin. Select the added external resource, and click [OK].

    [Figure 5.15] External Resource Configuration in WebAdmin (4)

    External Resource Configuration in WebAdmin (4)

  5. Click [Apply Changes] to apply the external resource to the domain. The message stating that the external resource has been applied to the domain is displayed at the top of the screen.

    The external resource can be used immediately on the server.

Using the Console Tool

An external resource can be looked up and dynamically added or deleted by using the console tool.

[Example 5.5] Viewing, Adding, and Deleting an External Resource in the Console Tool

[DAS]domain1.adminServer>add-external-resource test/ext -resource test.ext.TestResourceBootstrapper  
Successfully performed the ADD operation for A external resource.
Check the results using "list-external-resources or add-external-resource"

[DAS]domain1.adminServer>list-external-resources
List of External Resources
================================================================================
+-------------+---------------------------------------------------+------------+
| Export Name |                   Resource Class                  | Properties |
+-------------+---------------------------------------------------+------------+
| test/ext    | test.ext.TestResourceBootstrapper                 | []         |
+-------------+---------------------------------------------------+------------+
================================================================================

[DAS]domain1.adminServer>add-external-resource-to-servers test/ext -servers server1
Successfully performed the ADD operation for A external resource.
Check the results using "list-external-resources"

[DAS]domain1.adminServer>remove-external-resource test/ext 
Successfully performed the REMOVE operation for A external resource.
Check the results using "list-external-resources or remove-external-resource"

[DAS]domain1.adminServer>list-external-resources
List of External Resources
================================================================================
+-------------+---------------------------------------------------+------------+
| Export Name |                   Resource Class                  | Properties |
+-------------+---------------------------------------------------+------------+
(No data available)
================================================================================