com.ibm.websphere.proxyds
Interface WSProxyDataSourceHelper


public interface WSProxyDataSourceHelper

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.

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 fore 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); } ...... *


Field Summary
static java.lang.String JNDI_NAME
          The JNDI name for user to look up an instance of WSProxyDataSourceHelper
 
Method Summary
 java.lang.String resolveDataSourceReference(java.lang.String dsResRefName)
          Resolve the datasource reference to the global JNDI name.
 void setCurrentDataSourceJndiName(java.lang.String proxyJndiName, java.lang.String dsJndiName)
          Set the JNDI name (not the resource reference name) of the Delegate DataSource that the current transaction will access.
 

Field Detail

JNDI_NAME

static final java.lang.String JNDI_NAME
The JNDI name for user to look up an instance of WSProxyDataSourceHelper

See Also:
Constant Field Values
Method Detail

resolveDataSourceReference

java.lang.String resolveDataSourceReference(java.lang.String dsResRefName)
                                            throws ResRefNotFoundException
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".

Parameters:
dsResRefName - resource reference name
Returns:
the resolved datasource global JNDI name for this resource reference.
Throws:
ResRefNotFoundException - indicates the resource reference name cannot be found.

setCurrentDataSourceJndiName

void setCurrentDataSourceJndiName(java.lang.String proxyJndiName,
                                  java.lang.String dsJndiName)

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.

Parameters:
proxyJndiName - the Proxy DataSource JNDI name
dsJndiName - the current Delegate DataSource JNDI name