WebSphere eXtreme Scale (formerly Data Grid), Version 6.1
             Operating Systems: AIX, HP-UX, Linux, Solaris, Windows


API

The main API for the proxy datasource support is WSProxyDataSourceHelper. Following is the WSProxyDataSourceHelper interface:

package com.ibm.websphere.proxyds;

/**
* 

WSProxyDataSourceHelper interface is an interface used for CMP multiple 
* datasource support (also called Proxy DataSource). Users can look up an 
* instance of WSProxyDataSourceHelper from the JNDI name space using JNDI name 
* WSProxyDataSourceHelper.JNDI_NAME.


* 
* This interface is used to support the Proxy DataSource model. The 
* interface WSDataSourceHelper which supports V5 Proxy DataSource model 
* is deprecated. Users are strongly recommended to use this interface to 
* utilize the benefits of the Proxy DataSource model.


* 
* 

There are two helper methods in this interface.



* 

		* resolveDataSourceReference(String):
			* This helper method is used to resolve the global JNDI name of the 
			* datasource associated with a resource reference. For example, if a 
			* resource reference "jdbc/myDS1" is mapped to a datasource with global 
			* JNDI name "jdbc/Bank1", method call resolveDataSourceReference("jdbc/myDS1") 
			* will return "jdbc/Bank1".
			* 
			* 
		* setCurrentDataSourceJndiName(String, String):
			* This method is used to set the JNDI name (not the resource reference name) of 
			* the Delegate DataSource of a particular Proxy DataSource that the current transaction 
			* will access. The JNDI name of the DataSource can be acquired by using the 
			* resolveDataSourceReference(String) method.
* 
* 

* Here is an example:


* 
* 



An application has a CMP EJB "Account". The Account data 
* are spread in two different DB2 database servers, one in west coast, and the other 
* in east coast. In order to make the CMP EJB 
* Account access both databases, the Proxy DataSource model is used.


* 
* 

The CMP EJB Account is configured with CMP Connection Factory "jdbc/ProxyDS". 
* The Session Bean AccountTransaction, which acts as
* the session facade to the CMP EJB Account, is configured with three 
* resource references "jdbc/myDS1", "jdbc/myDS2", and "jdbc/proxy".


* 
* 

In the administration space, the administrator creates two DB2 datasources 
* "jdbc/Account1" and "jdbc/Account2",one for the west coast database, and the 
* other for the east coast database. The administrator also creates a 
* Proxy DataSource "jdbc/Accountroxy".
* The custom property jndiNames of this Proxy DataSource is set to 
* "jdbc/Account1;jdbc/Account2"


* 
* 


During the deployment time, the datasource reference "jdbc/myDS1" and "jdbc/myDS2"
* are mapped to the physical datasources "jdbc/Account1" and "jdbc/Acocunt2". 
* The datasource reference "jdbc/proxy" 
* is mapped to the physical proxy datasource "jdbc/AccountProxy". The CMP connection factory 
* "jdbc/ProxyDS" is also mapped to the same physical Proxy DataSource "jdbc/AccountProxy". 



* 
* 

During the development time, the application doesn't know which 
* physical datasources these resource references 
* are mapped to. In order to get the JNDI name of the physical datasources, the 
* application can resolve the datasources in the setSessionContext method using 
* the following code:


* 
*


// Look up the WSProxyDataSourceHelper 
* dsHelper = (WSProxyDataSourceHelper) ic.lookup(WSProxyDataSourceHelper.JNDI_NAME);
* ...
* ds1JndiName = dsHelper.resolveDataSourceReference("jdbc/myDS1"); 
* ds2JndiName = dsHelper.resolveDataSourceReference("jdbc/myDS2");
* proxyJndiName = dsHelper.resolveDataSourceReference("jdbc/proxy");



* 
* 
* 

Before the session bean calls the CMP EJBs, the session bean can use 
* setCurrentDataSourceJndiName(String, String) method to indicate which 
* delegate datasource this CMP EJB will use. In our example, if the account ID 
* starts with "W", which means the data resides on the west coast database, the 
* first delegate datasource should be used. For example:


* public String createAccount(String accountId, float balance) {
// Set the datasource this transaction will access.

// If the account Id starts with "W", the CMP will access the first datasource;
// Otherwise, the second datasource will be used.
if (accountId.startsWith("W")) {
dsHelper.setCurrentDataSourceJndiName(proxyJndiName, ds1JndiName);
}
else {
dsHelper.setCurrentDataSourceJndiName(proxyJndiName, ds2JndiName);
}


AccountLocal account = null;
try {
account = accountHome.create(accountId);
account.setCreationDate(new Timestamp(System.currentTimeMillis()));
account.setOpenBalance(balance);
account.setBalance(balance);
}
catch (CreateException ce) {
throw new EJBException(ce);
}
......

* 
* * 
* @ibm-api
*/
public interface WSProxyDataSourceHelper {

/** The JNDI name for user to look up an instance of WSProxyDataSourceHelper */
String JNDI_NAME = "java:comp/env/com/ibm/websphere/proxyds/WSProxyDataSourceHelper";

/**
* Resolve the datasource reference to the global JNDI name. For example, 
* if a resource reference "jdbc/myDS1" is mapped to a datasource with 
* global JNDI name "jdbc/Bank1", resolveDataSourceReference("jdbc/myDS1") 
* will return "jdbc/Bank1".
* 
* @param dsResRefName resource reference name
* @return the resolved datasource global JNDI name for this resource reference.
* @exception ResRefNotFoundException indicates the resource reference name 
* cannot be found.
*/
String resolveDataSourceReference(String dsResRefName) throws ResRefNotFoundException;

/**
* 

Set the JNDI name (not the resource reference name) of the Delegate DataSource 
* that the current transaction will access. Currently, one transaction can 
* access multiple Proxy DataSources. However, for a particular Proxy 
* DataSource, only one Delegate DataSource can be accessed.


 *
 * 
For example, there are two Proxy DataSources with JNDI name "jdbc/proxy1"
* and "jdbc/proxy2". The Delegate DataSources for Proxy DataSource "jdbc/proxy1"
* are "jdbc/ds1" and "jdbc/ds2". The Delegate DataSources for Proxy DataSource 
* "jdbc/proxy2" are "jdbc/ds3" and "jdbc/ds4". In one transaction, you can 
* access both "jdbc/proxy1" and "jdbc/proxy2". However, you cannot access both 
* Delegate DataSources "jdbc/ds1" and "jdbc/ds2" for proxy datasource 
* "jdbc/proxy1". Neither can you access both Delegate DataSources "jdbc/ds3"
* and "jdbc/ds4" for the Proxy DataSource "jdbc/proxy2".


* 
* 

During the development time, the developers cannot know the global JNDI 
* name of the datasource that a resource reference will be mapped to. The 
* only known fact is the resource reference name. The recommeneded practice is 
* to call the resolveDataSourceReference(String) method to get the JNDI name of 
* the mapped datasource, and then call setCurrentDataSourceJndiName(String, String) 
* with the global JNDI name.


* 
* @param proxyJndiName the Proxy DataSource JNDI name
* @param dsJndiName the current Delegate DataSource JNDI name
*/
void setCurrentDataSourceJndiName(String proxyJndiName, String dsJndiName);
}



Related concepts
Partitioning facility programming
Reference topic    

Terms of Use | Feedback

Last updated: Oct 30, 2009 6:09:57 PM EDT
http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r1/index.jsp?topic=/com.ibm.websphere.dataint.doc/info/WPF51/rwpfapi.html