Table of Contents
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.
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.
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.
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.
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.
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.
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 JEUS MQ Guide. "6.1. JEUS MQ Message Bridge".
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").
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.
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.
Data sources handle configurations that are related to the database. For more information, refer to "Chapter 6. DB Connection Pool and JDBC".
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.
Click [Add] to register a mail source to the domain.
Since the property names in the 'Main Property' section follow the JavaMail specification, refer to the JavaMain specification for each property configuration.
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.
Click [Add] to register a URL source to the domain.
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; } }
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.
The following screenshots show how to dynamically register a custom resource in WebAdmin.
Select [Resources] > [Custom Resource] from the left menu of WebAdmin.
Register a custom resource for the domain by clicking [Add]. Enter the configuration information of the custom resource and click [OK].
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.
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].
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.
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) ================================================================================
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.
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.
The following describes the configuration items.
Item | Description |
---|---|
Vendor | JMS vendor. Select one of:
|
Factory Class Name | Factory class name of the JMS resource. |
Resource Type | JMS type. Select one of:
|
Export Name | Name to bind to JNDI. Can be used to obtain JMS ConnectionFactory and Destination. |
Queue | Use only when the resource type is Q. |
QueueManager | Use only when the resource type is Q. |
Topic | Use only when the resource type is T. |
Property | Necessary attributes for JMS resources. It has a name, a type, and a value. |
Refer to the IBM MQ or the Sonic MQ manual for more information about each item.
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.
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); }
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.
The following shows how to dynamically register an external resource using WebAdmin.
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.
Enter the external resource configuration and click [OK].
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.
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].
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.
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) ================================================================================