oracle.cle.persistence
Class ConnectionProvider

java.lang.Object
  |
  +--oracle.cle.persistence.ConnectionProvider

All Implemented Interfaces:

Connectable, java.io.Serializable

Direct Known Subclasses:

ApplicationModuleProvider, ClientSessionProvider, DefaultContextProvider, JDBCConnectionProvider, JDBCPoolProvider, JndiObjectProvider, LibrarySessionProvider, TOPLink3TierConnectionProvider, TOPLinkConnectionProvider

public abstract class ConnectionProvider

extends java.lang.Object

implements Connectable, java.io.Serializable

Vital information required for connections.

Attributes can automatically be set and loaded by specifying properties in the "cle-providers.xml" file at the root of the classpath (ie. WEB-INF/classes/cle-providers.xml). See the http://xmlns.oracle.com/ias/mvc/cle-providers.dtd for more on structure of the file.

Most providers require the following properties to be specified in either the cle-providers.xml file or a persistence_deploymentkey.properties (the properties file method is now deprecated in favor of the cle-providers.xml file):

• username
• password
• encryptiontype (eg: NONE or BASE64)
• host
• port
• connectionstring (if encryptiontype indicates an encrypted password then the password in this string must also be encrypted)
• sid (depends on the specific connectionprovider implementation being used)
• drivertype (eg. oracle.jdbc.driver.OracleDriver)
• persistencebase (eg: oracle.demo.personnel.persistence.bc4j)
• failover (deploymentkey to try if this one fails)
• scope (the scope of the connection: none, request, session)

See the javadocs for the individual ConnectionProvider implementations for concrete examples of properties needed.

See Also:

Serialized Form

Field Summary

static java.lang.String	BASE64 Constant for specifying BASE64 encryption password encryption.
protected java.lang.Object	connection
protected java.lang.String	connectionString
static java.lang.String	CONNECTIONSTRING
protected java.util.Properties	defaultProperties
protected java.lang.String	deploymentKey
protected java.lang.String	driverType
static java.lang.String	DRIVERTYPE
protected java.lang.String	encryptionType
static java.lang.String	ENCRYPTIONTYPE
protected java.lang.String	failover
static java.lang.String	FAILOVER
protected java.lang.String	host
static java.lang.String	HOST
static java.lang.String	NO_SCOPE
static java.lang.String	NONE Constant for specifying NONE encryption password encryption.
protected java.lang.String	password
static java.lang.String	PASSWORD
protected java.lang.String	persistenceBase
static java.lang.String	PERSISTENCEBASE
protected java.lang.String	port
static java.lang.String	PORT
protected java.util.Collection	releasedConnectionIds This map contains all the connection ids that can be released at the end of the request.
static java.lang.String	REQUEST_SCOPE
protected java.lang.String	scope Scope defines when a connection is released.
static java.lang.String	SCOPE
static java.lang.String	SESSION_SCOPE
protected java.util.Map	sessionConnectionIds This map contains the connection ids that belong to a particular session id where connectionId != sessionId.
protected java.lang.String	sid
static java.lang.String	SID
static java.lang.String	USER
protected java.lang.String	userName

Constructor Summary

ConnectionProvider()
Default Constructor for generic Databases

ConnectionProvider(java.util.Properties properties)
Constructor for generic Databases

Method Summary

protected void	addPropertyKey(java.lang.String key)
protected void	addPropertyKeys() Each subclass should overload or override this method to include all the properties that it will use.
void	applyDynamicProperties(java.util.Properties dynamicProperties) applies dynamically passed in properties.
ConnectionProvider	clone(java.util.Properties dynamicProperties) This method returns a Provider clone with dynamic properties used.
boolean	compareDynamicProperties(java.util.Properties dynamicProperties) compares dynamically passed in properties with the ones allready in place.
protected boolean	compareProperty(java.util.Properties connectionProperties, java.lang.String property) A convenience method for comparing a property.
boolean	equals(java.lang.Object anObject) Override Object.equals() so that we can differentiate Connection copies in the ConnectionPool.
java.lang.Object	getConnection() Uses the sessionId returned from CLEUtil.getSessionId()
java.lang.Object	getConnection(int i) Uses the sessionId returned from CLEUtil.getSessionId()
abstract java.lang.Object	getConnection(java.lang.Object connectionId) This method gets a connection from a specific connection provider.
abstract java.lang.Object	getConnection(java.lang.Object connectionId, int i) This method gets a connection from a specific connection provider.
java.lang.Object	getConnection(java.lang.Object sessionId, java.lang.String connectionId) Use this method to get a connection.
java.lang.Object	getConnection(java.lang.Object sessionId, java.lang.String connectionId, int i) Use this method if you want to get a second connection of the same type.
java.lang.Object	getConnection(java.lang.String connectionId) Use this method to get a connection.
java.lang.Object	getConnection(java.lang.String connectionId, int i) Use this method if you want to get a second connection of the same type.
java.lang.String	getConnectionString() Returns the connection string for this provider.
java.util.Properties	getDefaultProperties()
java.lang.String	getDeploymentKey()
java.lang.String	getDriverType()
java.lang.String	getEncryptionType() Current option are: 'BASE64' and 'NONE'.
java.lang.String	getFailOver()
java.lang.String	getHost()
java.lang.String	getPassword() Returns the decrypted password property.
java.lang.String	getPassword(boolean encrypted) Returns the encrypted password property if parameter is true...
java.lang.String	getPersistenceBase()
java.lang.String	getPort()
protected java.lang.String	getProperty(java.util.Properties connectionProperties, java.lang.String property) A convenience method for getting a property.
java.util.Set	getPropertyKeys()
java.lang.String	getScope()
java.lang.String	getSid()
protected java.util.Set	getUnspecifiedKeys()
java.lang.String	getUserName()
int	hashCode() Override Object.hashCode() so that we can differentiate Connection copies in the ConnectionPool.
boolean	isSame(ConnectionProvider aConnectionProvider) Compares this connection info and returns true if their values are the same...
protected void	issueWarnings() Warns the user of missing required property keys.
void	releaseAllConnections() This method releases all connections that were retrieved during a session.
void	releaseAllConnections(java.lang.Object sessionId) This method releases all connections that were retrieved during a session.
void	releaseConnection() Release the Connection associated with the sessionId.
abstract void	releaseConnection(java.lang.Object connectionId) Release the Connection associated with the sessionId.
void	releaseConnection(java.lang.Object sessionId, java.lang.String connectionId) This method releases a connection or marks a connection so that it can be released at the end of a request.
void	releaseConnection(java.lang.String connectionId) This method releases a connection or marks a connection so that it can be released at the end of a request.
void	releaseRequestScopedConnections() This method releases all request scoped connections that were released during the request.
void	releaseRequestScopedConnections(java.lang.Object sessionId) This method releases all request scoped connections that were released during the request.
protected void	removePropertyKey(java.lang.String key)
void	setConnectionString(java.lang.String aString)
void	setDefaultProperties(java.util.Properties newDefaultProperties)
protected void	setDeploymentKey(java.lang.String deploymentKey)
void	setEncryptionType(java.lang.String aString)
void	setHost(java.lang.String aString)
void	setPassword(java.lang.String aString)
void	setPersistenceBase(java.lang.String aString)
void	setPort(java.lang.String anInt)
void	setScope(java.lang.String aString)
void	setSid(java.lang.String aString)
void	setUserName(java.lang.String aString)
protected void	warn(java.lang.String warning)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.cle.persistence.Connectable

connect, disconnect, isConnected

Field Detail

USER

public static final java.lang.String USER

PASSWORD

public static final java.lang.String PASSWORD

HOST

public static final java.lang.String HOST

PORT

public static final java.lang.String PORT

FAILOVER

public static final java.lang.String FAILOVER

SID

public static final java.lang.String SID

DRIVERTYPE

public static final java.lang.String DRIVERTYPE

CONNECTIONSTRING

public static final java.lang.String CONNECTIONSTRING

PERSISTENCEBASE

public static final java.lang.String PERSISTENCEBASE

ENCRYPTIONTYPE

public static final java.lang.String ENCRYPTIONTYPE

SCOPE

public static final java.lang.String SCOPE

REQUEST_SCOPE

public static final java.lang.String REQUEST_SCOPE

SESSION_SCOPE

public static final java.lang.String SESSION_SCOPE

NO_SCOPE

public static final java.lang.String NO_SCOPE

defaultProperties

protected java.util.Properties defaultProperties

userName

protected java.lang.String userName

password

protected java.lang.String password

host

protected java.lang.String host

port

protected java.lang.String port

failover

protected java.lang.String failover

sid

protected java.lang.String sid

driverType

protected java.lang.String driverType

connectionString

protected java.lang.String connectionString

persistenceBase

protected java.lang.String persistenceBase

encryptionType

protected java.lang.String encryptionType

scope

protected java.lang.String scope

Scope defines when a connection is released. There are three possibilities: 1. NO_SCOPE, the connection is released immediately when the releaseConnection method is called. This is the default scope. 2. REQUEST_SCOPE, the connection at the end of the request. The connection is only released if releaseConnection is called during this request. 3. SESSION_SCOPE, the connection is only released at the end of a session. releaseConnection doesn't do anything if this scope is used.

connection

protected java.lang.Object connection

deploymentKey

protected java.lang.String deploymentKey

BASE64

public static final java.lang.String BASE64

Constant for specifying BASE64 encryption password encryption. Value is: "BASE64"

NONE

public static final java.lang.String NONE

Constant for specifying NONE encryption password encryption. Value is: "NONE"

sessionConnectionIds

protected java.util.Map sessionConnectionIds

This map contains the connection ids that belong to a particular session id where connectionId != sessionId. It basically contains all connections that are retrieved with the getConnection(Object sessionId, Object connectionId) method (with connectionId is not null). Each entry in this map has the session id as a key and a collection of connection ids as a value.

releasedConnectionIds

protected java.util.Collection releasedConnectionIds

This map contains all the connection ids that can be released at the end of the request.

Constructor Detail

ConnectionProvider

public ConnectionProvider()

Default Constructor for generic Databases

ConnectionProvider

public ConnectionProvider(java.util.Properties properties)

Constructor for generic Databases

Method Detail

addPropertyKeys

protected void addPropertyKeys()

Each subclass should overload or override this method to include all the properties that it will use.

getPropertyKeys

public java.util.Set getPropertyKeys()

addPropertyKey

protected void addPropertyKey(java.lang.String key)

removePropertyKey

protected void removePropertyKey(java.lang.String key)

getUnspecifiedKeys

protected java.util.Set getUnspecifiedKeys()

issueWarnings

protected void issueWarnings()

Warns the user of missing required property keys. Missing keys may cause the ConnectionProvider to malfunction.

warn

protected void warn(java.lang.String warning)

applyDynamicProperties

public void applyDynamicProperties(java.util.Properties dynamicProperties)

applies dynamically passed in properties. This method is to be used only during the dynamic instance creation procedure. On generic instances it will have non or unpredictable impact

Parameters:

dynamicProperties - : Properties the dynamic properties to be used by this provider

compareDynamicProperties

public boolean compareDynamicProperties(java.util.Properties dynamicProperties)

compares dynamically passed in properties with the ones allready in place. This method is to be used only during the dynamic instance creation procedure. On generic instances it will have non or unpredictable impact.

Parameters:

dynamicProperties - : Properties the dynamic properties to be compared

Returns:

boolean true if the dynamicProperties match the existing ones false otherwise

equals

public boolean equals(java.lang.Object anObject)

Override Object.equals() so that we can differentiate Connection copies in the ConnectionPool.

Overrides:

equals in class java.lang.Object

See Also:

Object

hashCode

public int hashCode()

Override Object.hashCode() so that we can differentiate Connection copies in the ConnectionPool. Uses the String class' hashCode method because the mere mortals who wrote this method didn't want to be bothered by writing it

Overrides:

hashCode in class java.lang.Object

See Also:

Object

getProperty

protected java.lang.String getProperty(java.util.Properties connectionProperties,
                                       java.lang.String property)

A convenience method for getting a property. If the property is found in the specified connectionProperties (a Properties of default overrides), then return that property value, otherwise return the default value.

compareProperty

protected boolean compareProperty(java.util.Properties connectionProperties,
                                  java.lang.String property)

A convenience method for comparing a property. If the property is found to be equal to the defaultproperties true is returned false otherwise in the specified connectionProperties

Parameters:

connectionProperties - : Properties the properties to be compared

property - : String the name of the property entry to be compared

Returns:

boolean : true if the the value of the property matches

isSame

public boolean isSame(ConnectionProvider aConnectionProvider)

Compares this connection info and returns true if their values are the same... false otherwise.

getDeploymentKey

public java.lang.String getDeploymentKey()

setDeploymentKey

protected void setDeploymentKey(java.lang.String deploymentKey)

getUserName

public java.lang.String getUserName()

getEncryptionType

public java.lang.String getEncryptionType()

Current option are: 'BASE64' and 'NONE'. An unrecognized type will be interpreted as 'NONE'.

getPassword

public java.lang.String getPassword()

Returns the decrypted password property. If no encryption type property is set, then no decrypting is done. Likewise, if encryption type is set to 'NONE', then no decryption is done.

getPassword

public java.lang.String getPassword(boolean encrypted)

Returns the encrypted password property if parameter is true... decrypted otherwise.

getHost

public java.lang.String getHost()

getPort

public java.lang.String getPort()

getSid

public java.lang.String getSid()

getScope

public java.lang.String getScope()

getDriverType

public java.lang.String getDriverType()

getFailOver

public java.lang.String getFailOver()

setUserName

public void setUserName(java.lang.String aString)

setEncryptionType

public void setEncryptionType(java.lang.String aString)

getConnectionString

public java.lang.String getConnectionString()

Returns the connection string for this provider.

NOTE:
If an encrypted password matching the one returned from getPassword(true) lies anywhere in this String, then it will be replaced by the cleartext version of the password and returned as a cleartext connectionstring.

setConnectionString

public void setConnectionString(java.lang.String aString)

getPersistenceBase

public java.lang.String getPersistenceBase()

setPersistenceBase

public void setPersistenceBase(java.lang.String aString)

setPassword

public void setPassword(java.lang.String aString)

setHost

public void setHost(java.lang.String aString)

setPort

public void setPort(java.lang.String anInt)

setSid

public void setSid(java.lang.String aString)

setScope

public void setScope(java.lang.String aString)

getConnection

public java.lang.Object getConnection(java.lang.Object sessionId,
                                      java.lang.String connectionId)
                               throws java.lang.Exception

Use this method to get a connection.

getConnection

public java.lang.Object getConnection(java.lang.String connectionId)
                               throws java.lang.Exception

Use this method to get a connection.

getConnection

public java.lang.Object getConnection(java.lang.Object sessionId,
                                      java.lang.String connectionId,
                                      int i)
                               throws java.lang.Exception

Use this method if you want to get a second connection of the same type. DO NOT USE getConnection(Object sessionId) with a sessionId that is not really the session id (e.g. sessionId+"1"). If you do that then connections may not be released correctly. Instead use this method: getConnection(sessionId, "1")

getConnection

public java.lang.Object getConnection(java.lang.String connectionId,
                                      int i)
                               throws java.lang.Exception

Use this method if you want to get a second connection of the same type. DO NOT USE getConnection(Object sessionId) with a sessionId that is not really the session id (e.g. sessionId+"1"). If you do that then connections may not be released correctly. Instead use this method: getConnection(sessionId, "1")

getConnection

public abstract java.lang.Object getConnection(java.lang.Object connectionId)
                                        throws java.lang.Exception

This method gets a connection from a specific connection provider. Applications should NOT invoke this method.

getConnection

public java.lang.Object getConnection()
                               throws java.lang.Exception

Uses the sessionId returned from CLEUtil.getSessionId()

Returns:

connection specific to the provider

getConnection

public abstract java.lang.Object getConnection(java.lang.Object connectionId,
                                               int i)
                                        throws java.lang.Exception

This method gets a connection from a specific connection provider. Applications should NOT invoke this method.

getConnection

public java.lang.Object getConnection(int i)
                               throws java.lang.Exception

Uses the sessionId returned from CLEUtil.getSessionId()

Parameters:

failover -

Returns:

connection specific to the provider

releaseConnection

public abstract void releaseConnection(java.lang.Object connectionId)

Release the Connection associated with the sessionId. Applications should NOT invoke this method.

releaseConnection

public void releaseConnection()

Release the Connection associated with the sessionId. Applications should NOT invoke this method.

releaseRequestScopedConnections

public void releaseRequestScopedConnections(java.lang.Object sessionId)

This method releases all request scoped connections that were released during the request.

releaseRequestScopedConnections

public void releaseRequestScopedConnections()

This method releases all request scoped connections that were released during the request.

releaseAllConnections

public void releaseAllConnections(java.lang.Object sessionId)

This method releases all connections that were retrieved during a session.

releaseAllConnections

public void releaseAllConnections()

This method releases all connections that were retrieved during a session.

releaseConnection

public void releaseConnection(java.lang.Object sessionId,
                              java.lang.String connectionId)

This method releases a connection or marks a connection so that it can be released at the end of a request.

releaseConnection

public void releaseConnection(java.lang.String connectionId)

This method releases a connection or marks a connection so that it can be released at the end of a request.

getDefaultProperties

public java.util.Properties getDefaultProperties()

setDefaultProperties

public void setDefaultProperties(java.util.Properties newDefaultProperties)

clone

public ConnectionProvider clone(java.util.Properties dynamicProperties)
                         throws CLEException

This method returns a Provider clone with dynamic properties used.

Parameters:

dynamicProperties - : Properties the dynamicProperties