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

Constructor Summary

Constructors

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

Method Summary

Methods

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 is 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) Deprecated. use getPrivateInstance(URL,String) to provide the passphrase for encryption/decryption of credentials.
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.
javax.naming.Referenceable	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 the given listener from this store if it was registered.
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.
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.
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)

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)

Description copied from interface: Connections

Removes the given listener from this store if it was registered.

Specified by:

removeListener in interface Connections

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

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).

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.

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

listOpenConnections

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

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

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.

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.

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.

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 is simple a utility method wrapping the DBObjectProviderFactory.

This will NOT work with a private instance, only the central instance returned by DatabaseConnections.getInstance().

Throws:

DBException - if a connection cannot be made.

See Also:

DBObjectProviderFactory.findOrCreateProvider(java.lang.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 is true.

This will NOT work with a private instance, only the central instance returned by DatabaseConnections.getInstance().

Parameters:

connName - the connection name to look for

create - whether to create a Database if one exists

Throws:

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

See Also:

DBObjectProviderFactory.findProvider(java.lang.Object), DBObjectProviderFactory.findOrCreateProvider(java.lang.Object)

getReferenceable

public javax.naming.Referenceable 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

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

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

Throws:

ConnectionException

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.

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

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

Throws:

ConnectionException

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 to disconnect

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

getStoreName

public java.lang.String getStoreName()

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

See Also:

DatabaseConnectionStores

isCentralStore

public boolean isCentralStore()

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

See Also:

DatabaseConnectionStores.CENTRAL_STORE

getInstance

public static DatabaseConnections getInstance()

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

getPrivateInstance

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

Deprecated. use getPrivateInstance(URL,String) to provide the passphrase for encryption/decryption of credentials.

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.

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.

Parameters:

url - the location of the connections xml file

key - the key/passphrase to encrypt/decrypt credentials to the file. If null the system key will be used.

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.