|
Extension SDK 10.1.2 | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
oracle.jdeveloper.cm.ConnectionManager
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:
ConnectionManager
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
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; } ... }
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; } ... }
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 ...
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 |
public java.lang.String[] getConnectionTypeNames()
ConnectionManager
public ConnectionType getConnectionType(java.lang.String type)
ConnectionType
object for a given typepublic java.util.Iterator getConnectionTypes()
ConnectionType
object for a given typepublic void putConnectionDescriptor(java.lang.String name, ConnectionDescriptor descriptor) throws java.io.IOException
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.
name
- the name of the connection described by the ConnectionDescriptor.descriptor
- the ConnectionDescriptor to add to the list of available named connections.name
.java.io.IOException
ConnectionDescriptor
public void deployToFile(java.lang.String destination) throws CMException
destination
- the destination filejava.io.IOException
- if something goes wrongCMException
public void deployToFile(java.lang.String destination, boolean stripPasswords) throws CMException
destination
- the destination filestripPasswords
- 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.java.io.IOException
- if something goes wrongjava.lang.IllegalArgumentException
- if the ConnectionStore
is not an instance of WritableConnectionStore
.CMException
public static ConnectionManager getInstance()
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.ConnectionManager
public static ConnectionManager getPrivateInstance()
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.ConnectionManager
public ConnectionWrapper getConnection(java.lang.String name) throws java.io.IOException, CMException
getConnection
creates a new ConnectionWrapper.name
- the name of the desired connection objectjava.io.IOException
- occurs if an error is encountered while reading the source file.CMException
- other connection related errors.ConnectionWrapper
public ConnectionWrapper getConnection(java.lang.String name, ConnectInfoPrompter prompter) throws java.io.IOException, CMException
getConnection
creates a new ConnectionWrapper. ConnectionManager
uses prompter
instead of the current default prompting mechanism.name
- the name of the desired connection objectprompter
- a ConnectInfoPrompter
to use to get the user connection information.java.io.IOException
- occurs if an error is encountered while reading the source file.CMException
- other connection related errors.ConnectionWrapper
, ConnectInfoPrompter
public ConnectionWrapper getConnection(java.lang.String name, java.util.Properties properties) throws CMException, java.io.IOException
name
- the name of the connection descriptor to useproperties
- the property object which includes overrides and/or new properties to use.java.io.IOException
- occurs if an error is encountered while reading the source file.CMException
- other connection related errors.ConnectionWrapper
public ConnectionWrapper getConnection(java.lang.String name, java.util.Properties properties, ConnectInfoPrompter prompter) throws CMException, java.io.IOException
ConnectionManager
uses prompter
instead of the current default prompting mechanism.name
- the name of the connection descriptor to useproperties
- the property object which includes overrides and/or new properties to use.prompter
- a ConnectInfoPrompter
to use to get the user connection information.java.io.IOException
- occurs if an error is encountered while reading the source file.CMException
- other connection related errors.ConnectionWrapper
, ConnectInfoPrompter
public ConnectionWrapper getConnection(ConnectionDescriptor descriptor) throws CMException
descriptor
- the connection descriptor to use.java.io.IOException
- occurs if an error is encountered while reading the source file.CMException
- other connection related errors.ConnectionWrapper
public ConnectionWrapper getConnection(ConnectionDescriptor descriptor, ConnectInfoPrompter prompter) throws CMException
ConnectionManager
uses prompter
instead of the current default prompting mechanism.descriptor
- the connection descriptor to use.prompter
- a ConnectInfoPrompter
to use to get the user connection information.java.io.IOException
- occurs if an error is encountered while reading the source file.CMException
- other connection related errors.ConnectionWrapper
, ConnectInfoPrompter
public ConnectionDescriptor getUniqueConnectionDescriptor(java.lang.String base) throws java.io.IOException
base
- the name desired for the new connection descriptorjava.io.IOException
- occurs if an error is encountered while reading the source file.public ConnectionDescriptor getConnectionDescriptor(java.lang.String name) throws java.io.IOException
name
- the name of the desired connection descriptorjava.io.IOException
- occurs if an error is encountered while reading the source file.public boolean connectionDescriptorExists(java.lang.String name) throws java.io.IOException
true
if the ConnectionDescriptor
by the given name
exists in the ConnectionManager
. Returns false
otherwise.name
- the name of the desired connection descriptortrue
if the ConnectionDescriptor
exists; false
otherwisejava.io.IOExecption
- occurs if an error is encountered while reading the source file.java.io.IOException
public java.lang.String[] getConnectionNames() throws java.io.IOException
java.io.IOException
- occurs if an error is encountered while reading the source file.public java.lang.String[] getConnectionNames(java.lang.String type) throws java.io.IOException
type
- a java.lang.String representing the type. Valid types are defined within the class ConnectionDescriptor
.java.io.IOException
- occurs if an error is encountered while reading the source file.public java.lang.String[] getConnectionNames(java.lang.String type, boolean oracleOnly) throws java.io.IOException
type
- a java.lang.String representing the type. Valid types are defined within the class ConnectionDescriptor
.oracleOnly
- whether the user wants only Oracle connectionsjava.io.IOException
- occurs if an error is encountered while reading the source file.public java.lang.String[] getConnectionNames(java.util.Properties properties) throws java.io.IOException
properties
- the Properties object containing the desired propertiesjava.io.IOException
- occurs if an error is encountered while reading the source file.public java.lang.String[] getConnectionNamesForClass(java.lang.String connectionClassName) throws java.io.IOException
java.io.IOException
public java.lang.String[] getConnectionTypeNamesForClass(java.lang.String connectionClassName) throws java.io.IOException
java.io.IOException
public ConnectInfoPrompter getDefaultPrompter()
public ConnectionDescriptor removeConnectionDescriptor(java.lang.String name) throws java.io.IOException
ConnectionDescriptor
from the list of available connection descriptors. The old connection descriptor, if there is one, is returned.name
- the name of the ConnectionDescriptor
to removeConnectionDescriptor
being removed.java.io.IOException
- occurs if an error is encountered while reading the source file.public void setPrompter(ConnectInfoPrompter prompter)
prompter
- the object to use to prompt users for connection informationConnectInfoPrompter
public void setDefaultPrompter(ConnectInfoPrompter prompter)
prompter
- the object to use to prompt users for connection informationConnectInfoPrompter
public void addConnectionListener(ConnectionListener listener)
ConnectionListener
to ConnectionManager
.listener
- a ConnectionListener
object to notify when a ConnectionEvent
occurs.ConnectionListener
, ConnectionEvent
public void removeConnectionListener(ConnectionListener listener)
ConnectionListener
from ConnectionManager
listener
- the listener to be removed.public void setConnectionStore(ConnectionStore store)
public ConnectionStore getConnectionStore()
|
Extension SDK | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 1997, 2004, Oracle. All rights reserved.