Program guide > (deprecated) Partitioning facility > Partitioning facility programming > Proxy DataSource development


Deprecated feature: The partitioning facility (WPF) feature is deprecated. You can configure partitioning with WebSphere eXtreme Scale.


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);
}


Parent topic:

Partitioning facility programming


Related concepts

Partitioning facility programming