oracle.jdeveloper.cm
Class ConnectionManager

java.lang.Object
  oracle.jdeveloper.cm.ConnectionManager

public final class ConnectionManager

extends java.lang.Object

ConnectionManager is responsible for creating and managing connections to data sources such as Oracle8i/9i, Oracle8i Lite, JDBC-ODBC, Vanilla JDBC, FTP, any any others)

The connection information is stored in a file which is read by the ConnectionStore associated with the ConnectionManager instance. By default, this information is stored in connections.properties. The JDeveloper IDE automatically creates this file as part of the deployment process. Upon request, ConnectionManager reads the information from the properties file in order to instantiate a connection.

If configured to do so by information stored in the properties file, ConnectionManager will prompt the user for username, password, or other necessary connection information. This prevents security from being compromised by removing the need to store sensitive information externally.

ConnectionManager is designed to be a singleton class so as to be easy to use and support. However, under certain circumstances (especially with Applets), users may desire to manage their own instance of ConnectionManager. In these cases, the JDeveloper IDE may not be able to assist in automatic code generation.

Using ConnectionManager in an Application

Using ConnectionManager is a fairly straightforward exercise. There are only a few things the developer needs to be aware of.

First, and probably most importantly, it is imperative that some user object (usually the application itself) hold on to an instance of ConnectionManager for the duration of the application. This prevents ConnectionManager from being inadvertantly garbage collected.

A related issue which greatly affects performance is excessive use of getConnection followed very shortly by close. While it is possible to use these two methods everywhere the developer desires to use a connection, it can severely impact performance. If a connections reference count goes to zero, that connection is shut down. Any subsequent attempt to use that same named connection will result in a time-consuming login operation. Thus, the developer must take care to manage the lifecycle of open connections appropriately.

Using ConnectionManager in an Applet.

For the Applet developer, there are a few other issues to take heed of.

Applets loaded from the same network source can share the same namespace. This means that different applets can share the same ConnectionManager, and therefore, access to the same connections. This is not considered to be a security compromise for the following reasons:

• Only applets loaded from the same network source can share the same ConnectionManager
.
• Sensitive connection information should not be stored in the properties files.
• Applets can only open connections to the network source from which they were loaded. Therefore, the host to which JDBC will attempt a connection is not a secret.

However, for developers who would like to insulate themselves further from possible security risks, ConnectionManager allows developers to manage their own instance(s) of ConnectionManager.

Altering ConnectionManager's prompting behavior.

By default, ConnectionManager will always prompt for username, password, and role (only applicable for IIOP connections). However, this behavior may not always be appropriate. Furthermore, appropriate behavior may change from connection to connection. Therefore, ConnectionManager allows it behavior in this area to be customized.

Using the setDefaultPrompter method, users are able to customize not only the UI used by default to prompt for connection information, but also whether, by default, to prompt for information at all. The getConnection methods also allow for customization of prompting behavior. Examples of these can be found below.

ConnectionManager allows the developer

Examples

• Using ConnectionManager within an application.

         import oracle.jdeveloper.cm.ConnectionManager;
         import oracle.jdeveloper.cm.ConnectionWrapper;
         import oracle.jdeveloper.cm.ConnectionDescriptor;
          
         public class Application
         {
           private ConnectionManager cm;
            
           Application()
           {
             // Hold on to an instance of ConnectionManager for the
             // duration of the application.  This ensures that the
             // singleton ConnectionManager is not garbage collected.
             cm = ConnectionManager.getInstance();
           }
           ...
         }
          
         public class UseConnection
         {
           ...
           public ResultSet executeQuery()
           {
             ConnectionWrapper cw = cm.getConnection("MyConnectionToOracle");  // NORES
             Connection c = (Connection) cw.getPresentation(ConnectionDescriptor.PRESENTATION_JDBC);
             ResultSet rs = c.createStatement().
                              executeQuery("select * from emp");  // NORES
             c.close();
             return rs;
           }
           ...
         }
         

• Using ConnectionManager within an Applet, but using a private instance of ConnectionManager.

         import oracle.jdeveloper.cm.ConnectionManager;
         import oracle.jdeveloper.cm.ConnectionWrapper;
         import oracle.jdeveloper.cm.ConnectionDescriptor;
          
         public class MyApplet extends Applet
         {
           private ConnectionManager cm = null;
            
           public void init()
           {
             ...
           }
           public static synchronized ConnectionManager getCM() 
           { 
             // Hold on to an instance of ConnectionManager for the
             // duration of the application.  This ensures that the
             // singleton ConnectionManager is not garbage collected.
             if ( cm == null )
             {
               cm = ConnectionMananger.getPrivateInstance();
             }
             return cm; 
           }
           ...
         }
          
          
         public class UseConnection
         {
           ...
           public ResultSet executeQuery()
           {
             ConnectionWrapper cw = MyApplet.getCM().getConnection("MyConnectionToOracle");  // NORES
             Connection c = (Connection) cw.getPresentation(ConnectionDescriptor.PRESENTATION_JDBC);
             ResultSet rs = c.createStatement().executeQuery("select * from emp");  // NORES
             c.close();
             return rs;
           }
           ...
         }
         

• Customizing ConnectionManager's prompting behavior.

         ...
         ConnectionManager cm = ConnectionManager.getInstance();
          
         // By default, ConnectionManager uses ConnectInformationDialog
         // to prompt
          
         // Prompt user (Default behavior)
         Connection c = (Connection) cm.getConnection("Connection1").getPresentation(ConnectionDescriptor.PRESENTATION_JDBC);  // NORES
         nbsp;
         // Don't prompt user (override default behavior)
         Connection c2 =
           (Connection) cm.getConnection("Connection2",  // NORES
                                         (ConnectInfoPrompter) null).getPresentation(ConnectionDescriptor.PRESENTATION_JDBC);
          
         // The default prompter
         oracle.jdeveloper.cm.ConnectInformationDialog dlg =
           new oracle.jdeveloper.cm.ConnectInformationDialog();
          
         // Change the default behavior (turn off prompting altogether)
         cm.setDefaultPrompter(null);
          
         // Don't prompt user (New default behavior)
         c = (Connection) cm.getConnection("Connection1").getPresentation(ConnectionDescriptor.PRESENTATION_JDBC);  // NORES
          
         // Prompt user (override "default" behavior)  // NORES
         c2 = (Connection) cm.getConnection("Connection2", dlg).getPresentation(ConnectionDescriptor.PRESENTATION_JDBC);  // NORES
         ...
         

Since:

JDeveloper 2.0.190

See Also:

ConnectionWrapper, ConnectionDescriptor

Method Summary

void	addConnectionListener(ConnectionListener listener) Adds a ConnectionListener to ConnectionManager.
boolean	connectionDescriptorExists(java.lang.String name) Returns true if the ConnectionDescriptor by the given name exists in the ConnectionManager.
void	deployToFile(java.lang.String destination) Deploys all the connections to the specified file.
void	deployToFile(java.lang.String destination, boolean stripPasswords) Deploys all the connections to the specified file.
ConnectionWrapper	getConnection(ConnectionDescriptor descriptor) Returns a private connection using the specified connection descriptor.
ConnectionWrapper	getConnection(ConnectionDescriptor descriptor, ConnectInfoPrompter prompter) returns a private connection using the specified connection descriptor.
ConnectionWrapper	getConnection(java.lang.String name) returns the named connection.
ConnectionWrapper	getConnection(java.lang.String name, ConnectInfoPrompter prompter) Returns the named connection.
ConnectionWrapper	getConnection(java.lang.String name, java.util.Properties properties) returns a private connection based upon the specified name. This function allows the user to also specify a property object which includes properties which should add to and/or replace existing properties within the named connection.
ConnectionWrapper	getConnection(java.lang.String name, java.util.Properties properties, ConnectInfoPrompter prompter) returns a private connection based upon the specified name. This function allows the user to also specify a property object which includes properties which should add to and/or replace existing properties within the named connection. Also, ConnectionManager uses prompter instead of the current default prompting mechanism.
ConnectionDescriptor	getConnectionDescriptor(java.lang.String name) Returns a copy of the named connection descriptor.
java.lang.String[]	getConnectionNames() returns an array of defined named connections.
java.lang.String[]	getConnectionNames(java.util.Properties properties) returns an array of defined named connections containing the specified properties.
java.lang.String[]	getConnectionNames(java.lang.String type) returns an array of defined named connections of the specified type.
java.lang.String[]	getConnectionNames(java.lang.String type, boolean oracleOnly) returns an array of defined named connections of the specified type.
java.lang.String[]	getConnectionNamesForClass(java.lang.String connectionClassName)
ConnectionStore	getConnectionStore()
ConnectionType	getConnectionType(java.lang.String type) Returns a ConnectionType object for a given type
java.lang.String[]	getConnectionTypeNames() Returns a string list of the types of connections supported by the ConnectionManager
java.lang.String[]	getConnectionTypeNamesForClass(java.lang.String connectionClassName)
java.util.Iterator	getConnectionTypes() Returns a ConnectionType object for a given type
ConnectInfoPrompter	getDefaultPrompter() Returns the current default prompter.
static ConnectionManager	getInstance() Returns the singleton instance of ConnectionManager, creating it if necessary.
static ConnectionManager	getPrivateInstance() Returns a private instance of ConnectionManager.
ConnectionDescriptor	getUniqueConnectionDescriptor(java.lang.String base) returns a copy of a newly created named connection descriptor.
void	putConnectionDescriptor(java.lang.String name, ConnectionDescriptor descriptor) Inserts the ConnectionDescriptor into the list of available ConnectionDescriptors.
ConnectionDescriptor	removeConnectionDescriptor(java.lang.String name) removes the named ConnectionDescriptor from the list of available connection descriptors.
void	removeConnectionListener(ConnectionListener listener) removes the specified ConnectionListener from ConnectionManager
void	setConnectionStore(ConnectionStore store)
void	setDefaultPrompter(ConnectInfoPrompter prompter) Allows the user to customize the default prompting behavior.
void	setPrompter(ConnectInfoPrompter prompter) Deprecated. - replaced by setDefaultPrompter(prompter)

Methods inherited from class java.lang.Object

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

Method Detail

getConnectionTypeNames

public java.lang.String[] getConnectionTypeNames()

Returns a string list of the types of connections supported by the ConnectionManager

getConnectionType

public ConnectionType getConnectionType(java.lang.String type)

Returns a ConnectionType object for a given type

getConnectionTypes

public java.util.Iterator getConnectionTypes()

Returns a ConnectionType object for a given type

putConnectionDescriptor

public void putConnectionDescriptor(java.lang.String name,
                                    ConnectionDescriptor descriptor)
                             throws java.io.IOException

Inserts the ConnectionDescriptor into the list of available ConnectionDescriptors.

This method fires off a ConnectionEvent event if any changes were actually made to the list of connection descriptors. The old and new values will be the old and new values of the connection descriptor which changed.

Parameters:

name - the name of the connection described by the ConnectionDescriptor.

descriptor - the ConnectionDescriptor to add to the list of available named connections.

Returns:

the old ConnectionDescriptor (if any) currently associated with name.

Throws:

java.io.IOException

See Also:

ConnectionDescriptor

deployToFile

public void deployToFile(java.lang.String destination)
                  throws CMException

Deploys all the connections to the specified file. Note, this method overwrites the contents of the destination file if it already exists.

Parameters:

destination - the destination file

Throws:

java.io.IOException - if something goes wrong

CMException

deployToFile

public void deployToFile(java.lang.String destination,
                         boolean stripPasswords)
                  throws CMException

Deploys all the connections to the specified file. Note, this method overwrites the contents of the destination file if it already exists.

Parameters:

destination - the destination file

stripPasswords - if this parameter is true, any connection which is configured to prompt for security information will have its password stripped before deploying to the destination file.

Throws:

java.io.IOException - if something goes wrong

java.lang.IllegalArgumentException - if the ConnectionStore is not an instance of WritableConnectionStore.

CMException

getInstance

public static ConnectionManager getInstance()

Returns the singleton instance of ConnectionManager, creating it if necessary. It is important that some user object (usually the Application or Applet) hold on to an instance of ConnectionManager for the duration of the Application/Applet.

Returns:

the singleton instance of ConnectionManager

getPrivateInstance

public static ConnectionManager getPrivateInstance()

Returns a private instance of ConnectionManager. This method should only be used if the user is extremely concerned with security. Generally, only applet developers will have need of this function since application developers have more control over their universes.

Returns:

a new instance of ConnectionManager

getConnection

public ConnectionWrapper getConnection(java.lang.String name)
                                throws java.io.IOException,
                                       CMException

returns the named connection. If necessary, getConnection creates a new ConnectionWrapper.

Parameters:

name - the name of the desired connection object

Returns:

the corresponding ConnectionWrapper object

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

CMException - other connection related errors.

See Also:

ConnectionWrapper

getConnection

public ConnectionWrapper getConnection(java.lang.String name,
                                       ConnectInfoPrompter prompter)
                                throws java.io.IOException,
                                       CMException

Returns the named connection. If necessary, getConnection creates a new ConnectionWrapper. ConnectionManager uses prompter instead of the current default prompting mechanism.

Parameters:

name - the name of the desired connection object

prompter - a ConnectInfoPrompter to use to get the user connection information.

Returns:

the corresponding ConnectionWrapper object

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

CMException - other connection related errors.

See Also:

ConnectionWrapper, ConnectInfoPrompter

getConnection

public ConnectionWrapper getConnection(java.lang.String name,
                                       java.util.Properties properties)
                                throws CMException,
                                       java.io.IOException

returns a private connection based upon the specified name. This function allows the user to also specify a property object which includes properties which should add to and/or replace existing properties within the named connection.

Parameters:

name - the name of the connection descriptor to use

properties - the property object which includes overrides and/or new properties to use.

Returns:

a new private ConnectionWrapper object

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

CMException - other connection related errors.

See Also:

ConnectionWrapper

getConnection

public ConnectionWrapper getConnection(java.lang.String name,
                                       java.util.Properties properties,
                                       ConnectInfoPrompter prompter)
                                throws CMException,
                                       java.io.IOException

returns a private connection based upon the specified name. This function allows the user to also specify a property object which includes properties which should add to and/or replace existing properties within the named connection. Also, ConnectionManager uses prompter instead of the current default prompting mechanism.

Parameters:

name - the name of the connection descriptor to use

properties - the property object which includes overrides and/or new properties to use.

prompter - a ConnectInfoPrompter to use to get the user connection information.

Returns:

a new private ConnectionWrapper object

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

CMException - other connection related errors.

See Also:

ConnectionWrapper, ConnectInfoPrompter

getConnection

public ConnectionWrapper getConnection(ConnectionDescriptor descriptor)
                                throws CMException

Returns a private connection using the specified connection descriptor.

Parameters:

descriptor - the connection descriptor to use.

Returns:

a new private ConnectionWrapper object

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

CMException - other connection related errors.

See Also:

ConnectionWrapper

getConnection

public ConnectionWrapper getConnection(ConnectionDescriptor descriptor,
                                       ConnectInfoPrompter prompter)
                                throws CMException

returns a private connection using the specified connection descriptor. ConnectionManager uses prompter instead of the current default prompting mechanism.

Parameters:

descriptor - the connection descriptor to use.

prompter - a ConnectInfoPrompter to use to get the user connection information.

Returns:

a new private ConnectionWrapper object

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

CMException - other connection related errors.

See Also:

ConnectionWrapper, ConnectInfoPrompter

getUniqueConnectionDescriptor

public ConnectionDescriptor getUniqueConnectionDescriptor(java.lang.String base)
                                                   throws java.io.IOException

returns a copy of a newly created named connection descriptor. The new descriptor will have a guaranteed unique name based on the root name provided plus any additional characters to ensure its uniqueness (e.g. base1, base2, base3, etc.)

Parameters:

base - the name desired for the new connection descriptor

Returns:

a new ConnectionDescriptor object with a name derived from base

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

getConnectionDescriptor

public ConnectionDescriptor getConnectionDescriptor(java.lang.String name)
                                             throws java.io.IOException

Returns a copy of the named connection descriptor.

Parameters:

name - the name of the desired connection descriptor

Returns:

the corresponding ConnectionDescriptor object

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

connectionDescriptorExists

public boolean connectionDescriptorExists(java.lang.String name)
                                   throws java.io.IOException

Returns true if the ConnectionDescriptor by the given name exists in the ConnectionManager. Returns false otherwise.

Parameters:

name - the name of the desired connection descriptor

Returns:

true if the ConnectionDescriptor exists; false otherwise

Throws:

java.io.IOExecption - occurs if an error is encountered while reading the source file.

java.io.IOException

getConnectionNames

public java.lang.String[] getConnectionNames()
                                      throws java.io.IOException

returns an array of defined named connections. If the connection descriptors have not yet been loaded, this method will force them to be read in.

Returns:

a String array of connection names. If there are no connections defined, an array of length zero (0) is returned.

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

getConnectionNames

public java.lang.String[] getConnectionNames(java.lang.String type)
                                      throws java.io.IOException

returns an array of defined named connections of the specified type. If the connection descriptors have not yet been loaded, this method will force them to be read in.

Parameters:

type - a java.lang.String representing the type. Valid types are defined within the class ConnectionDescriptor.

Returns:

a String array of connection names.

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

getConnectionNames

public java.lang.String[] getConnectionNames(java.lang.String type,
                                             boolean oracleOnly)
                                      throws java.io.IOException

returns an array of defined named connections of the specified type. The user can specify whether they would like Oracle only connections as well.If the connection descriptors have not yet been loaded, this method will force them to be read in.

Parameters:

type - a java.lang.String representing the type. Valid types are defined within the class ConnectionDescriptor.

oracleOnly - whether the user wants only Oracle connections

Returns:

a String array of connection names.

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

getConnectionNames

public java.lang.String[] getConnectionNames(java.util.Properties properties)
                                      throws java.io.IOException

returns an array of defined named connections containing the specified properties. If the connection descriptors have not yet been loaded, this method will force them to be read in.

Parameters:

properties - the Properties object containing the desired properties

Returns:

a String array of connection names.

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

getConnectionNamesForClass

public java.lang.String[] getConnectionNamesForClass(java.lang.String connectionClassName)
                                              throws java.io.IOException

Throws:

java.io.IOException

getConnectionTypeNamesForClass

public java.lang.String[] getConnectionTypeNamesForClass(java.lang.String connectionClassName)
                                                  throws java.io.IOException

Throws:

java.io.IOException

getDefaultPrompter

public ConnectInfoPrompter getDefaultPrompter()

Returns the current default prompter.

Returns:

the current default prompter.

removeConnectionDescriptor

public ConnectionDescriptor removeConnectionDescriptor(java.lang.String name)
                                                throws java.io.IOException

removes the named ConnectionDescriptor from the list of available connection descriptors. The old connection descriptor, if there is one, is returned.

Parameters:

name - the name of the ConnectionDescriptor to remove

Returns:

the ConnectionDescriptor being removed.

Throws:

java.io.IOException - occurs if an error is encountered while reading the source file.

setPrompter

public void setPrompter(ConnectInfoPrompter prompter)

Deprecated. - replaced by setDefaultPrompter(prompter)

Allows the user to customize the default prompting behavior.

Parameters:

prompter - the object to use to prompt users for connection information

See Also:

ConnectInfoPrompter

setDefaultPrompter

public void setDefaultPrompter(ConnectInfoPrompter prompter)

Allows the user to customize the default prompting behavior.

Parameters:

prompter - the object to use to prompt users for connection information

See Also:

ConnectInfoPrompter

addConnectionListener

public void addConnectionListener(ConnectionListener listener)

Adds a ConnectionListener to ConnectionManager.

Parameters:

listener - a ConnectionListener object to notify when a ConnectionEvent occurs.

See Also:

ConnectionListener, ConnectionEvent

removeConnectionListener

public void removeConnectionListener(ConnectionListener listener)

removes the specified ConnectionListener from ConnectionManager

Parameters:

listener - the listener to be removed.

setConnectionStore

public void setConnectionStore(ConnectionStore store)

getConnectionStore

public ConnectionStore getConnectionStore()