oracle.jdeveloper.db

Class DatabaseConnections

java.lang.Object

oracle.jdeveloper.db.DatabaseConnections

All Implemented Interfaces:

Connections

public class DatabaseConnections
extends java.lang.Object
implements Connections

API to retrieve information about the database connections available in a given connection store in JDeveloper (or related FCP product).

Since:

11

See Also:

DatabaseConnectionStores

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DatabaseConnections.DatabaseConnectionTester Class that can optionally be passed to DatabaseConnections.DatabaseConnectionTester.testConnection(java.sql.Connection) to peform extra tests on the Connection before it is closed.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DatabaseConnections(java.lang.String storeName, DatabaseContextManager.ContextWrapper contextWrapper, DatabaseFactory.ConnectionCreator connCreator) Constructs a new DatabaseConnections wrapper.

Method Summary

Modifier and Type	Method and Description
void	addConnection(java.lang.String connName, java.util.Properties props) Creates a connection in the underlying namespace with the given name and properties.
void	addDisconnectListener(DisconnectListener l) Adds a listener to this store of connections to be notified of (and be able to veto) disconnection events.
void	addListener(ConnectionsListener l) Adds a listener to this store of connections to be notified of connection events.
void	addListener(DatabaseConnectionsListener dcl) Adds a listener to be notified of operations within this DatabaseConnections instance.
protected void	closeOpenConnections() Forces all open Connections made by this instance to be closed.
protected void	closeStore() Used by DatabaseConnectionStores when a store is removed to close the store down, and remove any listeners or state it is using.
void	disconnect(java.lang.String connName) Disconnect the cached JDBC connections for the given connection name, and closes the associated Database as well.
boolean	disconnect(java.lang.String connName, boolean force) Disconnect the cached JDBC connections for the given connection name, and closes the associated Database as well.
java.sql.Connection	getConnection(java.util.Properties props) Returns a new JDBC connection for the given connection Properties.
java.sql.Connection	getConnection(java.lang.String connName) Returns a JDBC connection for the given connection name.
Database	getDatabase(java.lang.String connName) Returns a Database for the given connection name.
Database	getDatabase(java.lang.String connName, boolean create) Returns a Database for the given connection name if one is already cached, and only creates a new one if create == true.
protected java.util.Collection<? extends DisconnectListener>	getDisconnectListeners() Deprecated. use getListeners()
static DatabaseConnections	getInstance() Returns the central instance of database connections for the current session.
static DatabaseConnections	getLegacyPrivateInstance(java.net.URL url) Creates a private DatabaseConnections instance that exclusively uses legacy encryption.
protected java.util.Collection<DatabaseConnectionsListener>	getListeners() Gets the listeners to this set of connections.
static DatabaseConnections	getPrivateInstance(java.net.URL url) Gets a connections instance for the given URL.
static DatabaseConnections	getPrivateInstance(java.net.URL url, java.lang.String key) Returns a private instance of database connections for the given URL.
java.util.Properties	getProperties(java.lang.String connName) Returns a Properties object containing the properties for the given connection name.
DatabaseProvider	getReferenceable(java.lang.String connName) Returns the Referenceable for the given connection name, containing the details about the connection.
java.lang.String	getStoreName() Returns the name (unique identifier) for this store of database connections.
java.sql.Connection	getUniqueConnection(java.lang.String connName) Returns a JDBC connection for the given connection name.
boolean	isCentralStore() Convinience method to determine whether this is the central "IDE Connections" database store.
java.util.Collection<java.lang.String>	listConnections() Lists the names of the available database connections.
java.util.Collection<java.lang.String>	listConnections(boolean oracleOnly) Lists the available database connections, optionally limiting the returned names to connections to Oracle databases (not including Lite).
java.util.Collection<java.lang.String>	listConnections(java.util.Properties filter) Lists all database connections whose properties match the given filter.
java.util.Collection<java.lang.String>	listConnections(java.lang.String[] subTypes) List the available database connections that have a connection subtype in the given list.
java.util.Collection<java.lang.String>	listOpenConnections() Lists the names of the connections that have been opened in this store.
boolean	removeConnection(java.lang.String connName) Removes the connection with the given name.
boolean	removeDisconnectListener(DisconnectListener l) Removes a DisconnectionListener that has been previously added.
boolean	removeListener(ConnectionsListener l) Removes a connection listener that was previously added using #addListener(ConnectionsListner).
boolean	removeListener(DatabaseConnectionsListener dcl) Removed a DatabaseConnectionsListener that has been previously added.
void	saveConnections() Saves the database connection store.
void	testConnection(java.util.Properties props) Takes the given properties for a connection and attempts to connect to the database.
void	testConnection(java.util.Properties props, DatabaseConnections.DatabaseConnectionTester tester) Takes the given properties for a connection and attempts to connect to the database.
boolean	updateConnection(java.lang.String connName, java.lang.String newName, java.util.Properties newProps) Updates the definition of the given connection with the new set of properties.
boolean	updateConnection(java.lang.String connName, java.lang.String newName, java.util.Properties newProps, boolean skipDisconnect) Updates the definition of the given connection with the new set of properties.
static void	useStandaloneConnectionStore() Deprecated. with no replacement. This is configured automatically if a product other than JDeveloper has no jndi context wrapper set up using the appropriate singleton hook.

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseConnections

protected DatabaseConnections(java.lang.String storeName,
                              DatabaseContextManager.ContextWrapper contextWrapper,
                              DatabaseFactory.ConnectionCreator connCreator)

Constructs a new DatabaseConnections wrapper.

Parameters:

storeName - the name of this connection store.

contextWrapper - the wrapper for the underlying JNDI context

connCreator - the ConnectionCreator to create new connections

Method Detail

closeStore

protected void closeStore()

Used by DatabaseConnectionStores when a store is removed to close the store down, and remove any listeners or state it is using.

closeOpenConnections

protected void closeOpenConnections()

Forces all open Connections made by this instance to be closed.

addListener

public void addListener(ConnectionsListener l)

Adds a listener to this store of connections to be notified of connection events.

To add connection listeners generically to any or all database connection stores, add a StoreProvider using the appropriate extension.xml hook and use the events passed to that provider to add and remove listeners to the DatabaseConnections store(s) required.

Specified by:

addListener in interface Connections

Parameters:

l - the listener to add

removeListener

public boolean removeListener(ConnectionsListener l)

Removes a connection listener that was previously added using #addListener(ConnectionsListner).

Specified by:

removeListener in interface Connections

Parameters:

l - the listener to remove

Returns:

true if the listener had been previously added and is now removed

getListeners

protected java.util.Collection<DatabaseConnectionsListener> getListeners()

Gets the listeners to this set of connections.

Returns:

an unmodifiable copy of the listeners to this set of connections

addDisconnectListener

public void addDisconnectListener(DisconnectListener l)

Adds a listener to this store of connections to be notified of (and be able to veto) disconnection events.

To add disconnect listeners generically to any or all database connection stores, add a StoreProvider using the appropriate extension.xml hook and use the events passed to that provider to add and remove listeners to the DatabaseConnections store(s) required.

Specified by:

addDisconnectListener in interface Connections

Parameters:

l - the listener to add

removeDisconnectListener

public boolean removeDisconnectListener(DisconnectListener l)

Removes a DisconnectionListener that has been previously added.

Specified by:

removeDisconnectListener in interface Connections

Parameters:

l - the listener to remove

Returns:

true if the listener was succcessfully removed

See Also:

addDisconnectListener(DisconnectListener)

addListener

public void addListener(DatabaseConnectionsListener dcl)

Adds a listener to be notified of operations within this DatabaseConnections instance.

Parameters:

dcl - the listener to add

removeListener

public boolean removeListener(DatabaseConnectionsListener dcl)

Removed a DatabaseConnectionsListener that has been previously added.

Parameters:

dcl - the listener to remove

Returns:

true if the listener was succcessfully removed

See Also:

addListener(DatabaseConnectionsListener)

getDisconnectListeners

@Deprecated
protected java.util.Collection<? extends DisconnectListener> getDisconnectListeners()

Deprecated. use getListeners()

listConnections

public final java.util.Collection<java.lang.String> listConnections()

Lists the names of the available database connections.

Specified by:

listConnections in interface Connections

Returns:

the listed connection names

listConnections

public final java.util.Collection<java.lang.String> listConnections(boolean oracleOnly)

Lists the available database connections, optionally limiting the returned names to connections to Oracle databases (not including Lite).

Parameters:

oracleOnly - if true only oracle connections will be listed

Returns:

the listed connection names

listConnections

public java.util.Collection<java.lang.String> listConnections(java.lang.String[] subTypes)

List the available database connections that have a connection subtype in the given list.

Parameters:

subTypes - the connection subtypes to list

Returns:

the listed connection names

listConnections

public final java.util.Collection<java.lang.String> listConnections(java.util.Properties filter)

Lists all database connections whose properties match the given filter.

Specified by:

listConnections in interface Connections

Parameters:

filter - the properties that all listed connections must match

Returns:

the listed connection names

listOpenConnections

public java.util.Collection<java.lang.String> listOpenConnections()

Lists the names of the connections that have been opened in this store.

Returns:

the listed connection names

getConnection

public final java.sql.Connection getConnection(java.lang.String connName)
                                        throws ConnectionException

Returns a JDBC connection for the given connection name. The Connection returned is that wrapped by the Database object in the javatools db API. This method is not appropriate if a unique connection is required. Do not close the connection returned by this method, as the rest of the product will be using it.

Parameters:

connName - the connection name

Returns:

a Connection to the database for the given connection name

Throws:

ConnectionException - if the connection cannot be created

See Also:

getUniqueConnection(java.lang.String)

getUniqueConnection

public final java.sql.Connection getUniqueConnection(java.lang.String connName)
                                              throws ConnectionException

Returns a JDBC connection for the given connection name. This can be used to test that a connection's details are valid. The returned Connection is always newly created, and therefore unique to the caller of this method. It is the responsibility of the caller to close the connection when it is finished with, however if the given connection name is explictly disconnected by the user, all unique connections will also be disconnected otherwise there is no way for the user to ensure that all connection(s) to the database are closed without closing the product.

Parameters:

connName - the connection name

Returns:

a new Connection instance to the database for the given connection name

Throws:

ConnectionException - if the connection cannot be created

See Also:

getConnection(String)

getConnection

public final java.sql.Connection getConnection(java.util.Properties props)
                                        throws ConnectionException

Returns a new JDBC connection for the given connection Properties. It is the responsibility of the caller to close the connection appropriately.

Parameters:

props - the properties to get a Connection for

Returns:

a Connection created using the given properties

Throws:

ConnectionException - if the connection cannot be created

getDatabase

public final Database getDatabase(java.lang.String connName)
                           throws DBException

Returns a Database for the given connection name. This wraps the usage of DBObjectProviderFactory using Database.PROVIDER_TYPE and the qualified connection name.

Note: for a private instance this method will work, but using DBObjectProviderFactory directly will not because a private instance doesn't exist in the DatabaseConnectionStores.

Parameters:

connName - the connection name

Returns:

a Database representing the database for the given connection name

Throws:

DBException - if a connection cannot be made.

See Also:

DBObjectProviderFactory.findOrCreateProvider(String,Object)

getDatabase

public final Database getDatabase(java.lang.String connName,
                                  boolean create)
                           throws DBException

Returns a Database for the given connection name if one is already cached, and only creates a new one if create == true. This wraps the usage of DBObjectProviderFactory using Database.PROVIDER_TYPE and the qualified connection name.

Note: for a private instance this method will work, but using DBObjectProviderFactory directly will not because a private instance doesn't exist in the DatabaseConnectionStores.

Parameters:

connName - the connection name to look for

create - whether to create a Database if one exists

Returns:

a Database

Throws:

DBException - if a connection cannot be made or the Database fails to initialise.

See Also:

DBObjectProviderFactory.findProvider(String,Object), DBObjectProviderFactory.findOrCreateProvider(String,Object)

getReferenceable

public DatabaseProvider getReferenceable(java.lang.String connName)
                                  throws ConnectionException

Returns the Referenceable for the given connection name, containing the details about the connection. The returned object is the object stored in the underlying namespace.

Specified by:

getReferenceable in interface Connections

Parameters:

connName - the connection name

Returns:

the Referenceable from the underlying JNDI context with the connection details

Throws:

ConnectionException - if an error occurs locating the given connection name.

getProperties

public final java.util.Properties getProperties(java.lang.String connName)
                                         throws ConnectionException

Returns a Properties object containing the properties for the given connection name. The Properties are a copy of those stored in the underlying Referenceable.

Specified by:

getProperties in interface Connections

Parameters:

connName - the connection name

Returns:

the connection properties for the given connection name

Throws:

ConnectionException - if an error occurs locating the given connection name.

addConnection

public void addConnection(java.lang.String connName,
                          java.util.Properties props)
                   throws ConnectionException

Creates a connection in the underlying namespace with the given name and properties.

Specified by:

addConnection in interface Connections

Parameters:

connName - the name for the new connection

props - the properties for the new connection

Throws:

ConnectionException - if the connection cannot be added (for example the name is already in use).

removeConnection

public boolean removeConnection(java.lang.String connName)
                         throws ConnectionException

Removes the connection with the given name. It will return true if the operation succeeded, and false if no such connection exists to remove.

Specified by:

removeConnection in interface Connections

Parameters:

connName - the name of the connection to remove

Returns:

true if successful, false if connName not found or the removal was vetoed.

Throws:

ConnectionException - if an error is encountered removing the connection

updateConnection

public boolean updateConnection(java.lang.String connName,
                                java.lang.String newName,
                                java.util.Properties newProps)
                         throws ConnectionException

Updates the definition of the given connection with the new set of properties. If the connection properties have changed then any open Connection will be closed automatically.

Specified by:

updateConnection in interface Connections

Parameters:

connName - the name of the connection as already defined

newName - the new name for the connection. if null the old name is kept

newProps - the new Properties for the connection.

Returns:

true if the update operation suceeded. Possible reasons for failure include a veto of the existing connection being closed before the update.

Throws:

ConnectionException - if there is no existing connection, if the new connection name exists, or if there is a problem binding the new connection details.

updateConnection

public boolean updateConnection(java.lang.String connName,
                                java.lang.String newName,
                                java.util.Properties newProps,
                                boolean skipDisconnect)
                         throws ConnectionException

Updates the definition of the given connection with the new set of properties.

Care should be taken specifying skipDisconnect as leaving an open Connection that doesn't match the underlying connection properties could cause problems.

Parameters:

connName - the name of the connection as already defined

newName - the new name for the connection. if null the old name is kept

newProps - the new Properties for the connection.

skipDisconnect - whether to leave any open connections and simply update the connection properties, if false any open Connection will be closed if the connection properties have changed.

Returns:

true if the update operation suceeded. Possible reasons for failure include a veto of the existing connection being closed before the update.

Throws:

ConnectionException - if there is no existing connection, if the new connection name exists, or if there is a problem binding the new connection details.

testConnection

public final void testConnection(java.util.Properties props)
                          throws ConnectionException

Takes the given properties for a connection and attempts to connect to the database.

Specified by:

testConnection in interface Connections

Parameters:

props - the properties to test

Throws:

ConnectionException - if the test fails

testConnection

public final void testConnection(java.util.Properties props,
                                 DatabaseConnections.DatabaseConnectionTester tester)
                          throws ConnectionException

Takes the given properties for a connection and attempts to connect to the database.

Parameters:

props - the properties to test

tester - an optional tester class that can peform extra tests on the Connection.

Throws:

ConnectionException - if the test fails

disconnect

public final void disconnect(java.lang.String connName)
                      throws ConnectionException

Disconnect the cached JDBC connections for the given connection name, and closes the associated Database as well. If the connection does not save its password this will mean the user is prompted again if they try and reconnect to this connection.

Any registered DisconnectListeners can veto this operation. If the result of the disconnect is required the use disconnect(String,boolean).

Specified by:

disconnect in interface Connections

Parameters:

connName - the connection name

Throws:

ConnectionException - if an error is encountered getting or disconnecting the connection.

disconnect

public final boolean disconnect(java.lang.String connName,
                                boolean force)
                         throws ConnectionException

Disconnect the cached JDBC connections for the given connection name, and closes the associated Database as well. If the connection does not save its password this will mean the user is prompted again if they try and reconnect to this connection.

Any registered DisconnectListeners can veto this operation. If the result of the disconnect is required the use disconnect(String,boolean).

Parameters:

connName - the connection to disconnect

force - whether to ignore the veto attempts of any disconnect listeners

Returns:

true if the connection exists and disconnect was succesful

Throws:

ConnectionException

saveConnections

public void saveConnections()
                     throws ConnectionException

Saves the database connection store.

Specified by:

saveConnections in interface Connections

Throws:

ConnectionException - if the connection store cannot be saved (e.g. read only file system).

getStoreName

public java.lang.String getStoreName()

Returns the name (unique identifier) for this store of database connections.

Returns:

the name of this connection store

See Also:

DatabaseConnectionStores

isCentralStore

public boolean isCentralStore()

Convinience method to determine whether this is the central "IDE Connections" database store.

Returns:

true if this connection store is the central store

See Also:

DatabaseConnectionStores.CENTRAL_STORE

getInstance

public static DatabaseConnections getInstance()

Returns the central instance of database connections for the current session.

Returns:

the central "IDE Connections" database store, or null if this FCP has no central store.

See Also:

DatabaseConnectionStores.getCurrentStore(oracle.ide.Context)

getPrivateInstance

public static DatabaseConnections getPrivateInstance(java.net.URL url)

Gets a connections instance for the given URL.

If the url exists, and contains a valid CA connections xml file, this will automatically detect whether it is a legacy file, or needs a key (passphrase). If it needs a key, the system key will be used. Use getPrivateInstance(URL,String) to provide the key for encryption/decryption of credentials for a specific URL.

If the file does not exist the system key will be used to encrypt any credentials. Note there is no system key in FCP products that use a resource catalog (e.g. JDeveloper), and in that case credentials will not be saved in the returned store.

This cannot be used on CM xml files. These must be migrated first using CMConnectionsReader.

Parameters:

url - the url for the connection instance

Returns:

a connection instance wrapping the given url

getLegacyPrivateInstance

public static DatabaseConnections getLegacyPrivateInstance(java.net.URL url)

Creates a private DatabaseConnections instance that exclusively uses legacy encryption. This should only be used for writing connections that are specifically required to be backwards compatible with either jdev 10.1.3 or sqldev < 4.

Parameters:

url - the location of the legacy connections xml file

Returns:

a connection store containing connections saved at the given url

getPrivateInstance

public static DatabaseConnections getPrivateInstance(java.net.URL url,
                                                     java.lang.String key)

Returns a private instance of database connections for the given URL. The key provided is used to encrypt/decrypt passwords in the xml. Note that binding directly to the underlying naming context will not correctly encrypt the credentials.

If no key is provided, and the URL does not exist, the store will not support encryption and no credentials will be saved to the xml file.

If no key is provided, and the URL exists and contains passwords, the system key will be used.

Parameters:

url - the location of the connections xml file

key - the key/passphrase to encrypt/decrypt credentials to the file.

Returns:

a connection store whose connections are saved at the given url

useStandaloneConnectionStore

@Deprecated
public static void useStandaloneConnectionStore()

Deprecated. with no replacement. This is configured automatically if a product other than JDeveloper has no jndi context wrapper set up using the appropriate singleton hook.