001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.api.db.explorer;
043:
044: import java.sql.Connection;
045: import org.netbeans.modules.db.explorer.ConnectionList;
046: import org.netbeans.modules.db.explorer.DatabaseConnectionAccessor;
047:
048: /**
049: * Encapsulates a database connection. Each DatabaseConnection instance
050: * represents a connection to a database in the Database Explorer.
051: *
052: * <p>This class provides access to the properties of a database connection,
053: * such as the connection name, database URL, user or default schema. New connections
054: * can be created using the {@link #create} method (these connections can be
055: * added to the Database Explorer using the
056: * {@link ConnectionManager#addConnection} method.</p>
057: *
058: * <p>It is also possible to retrieve the JDBC {@link java.sql.Connection}
059: * using the {@link #getJDBCConnection} method (the connection can be connected
060: * or disconnected using the {@link ConnectionManager#showConnectionDialog}
061: * and {@link ConnectionManager#disconnect} methods.</p>
062: *
063: * @author Andrei Badea
064: *
065: * @see ConnectionManager
066: */
067: public final class DatabaseConnection {
068:
069: private org.netbeans.modules.db.explorer.DatabaseConnection delegate;
070:
071: /*
072: * DatabaseConnection's methods delegate to
073: * org.netbeans.modules.db.explorer.DatabaseConnection. Each instance of
074: * org.netbeans.modules.db.explorer.DatabaseConnection
075: * creates and maintains an instance of
076: * DatabaseConnection. Since the constructor of
077: * DatabaseConnection is package-protected, an accessor is needed
078: * to create instances of DatabaseConnection from
079: * org.netbeans.modules.db.explorer.DatabaseConnection.
080: *
081: * See org.netbeans.modules.db.explorer.DatabaseConnectionAccessor
082: */
083:
084: static {
085: DatabaseConnectionAccessor.DEFAULT = new DatabaseConnectionAccessor() {
086: public DatabaseConnection createDatabaseConnection(
087: org.netbeans.modules.db.explorer.DatabaseConnection conn) {
088: return new DatabaseConnection(conn);
089: }
090: };
091: }
092:
093: /**
094: * Package-protected constructor.
095: */
096: DatabaseConnection(
097: org.netbeans.modules.db.explorer.DatabaseConnection delegate) {
098: assert delegate != null;
099: this .delegate = delegate;
100: }
101:
102: /**
103: * Returns the org.netbeans.modules.db.explorer.DatabaseConnection which this instance delegates to.
104: */
105: org.netbeans.modules.db.explorer.DatabaseConnection getDelegate() {
106: return delegate;
107: }
108:
109: /**
110: * Creates a new DatabaseConnection instance.
111: *
112: * @param driver the JDBC driver the new connection uses; cannot be null.
113: * @param databaseURL the URL of the database to connect to; cannot be null.
114: * @param user the username.
115: * @param schema the schema to use, or null for the default schema
116: * @param password the password.
117: * @param rememberPassword whether to remeber the password for the current session.
118: *
119: * @return the new instance.
120: *
121: * @throws NullPointerException if driver or database are null.
122: */
123: public static DatabaseConnection create(JDBCDriver driver,
124: String databaseURL, String user, String schema,
125: String password, boolean rememberPassword) {
126: if (driver == null || databaseURL == null) {
127: throw new NullPointerException();
128: }
129: org.netbeans.modules.db.explorer.DatabaseConnection conn = new org.netbeans.modules.db.explorer.DatabaseConnection();
130: conn.setDriverName(driver.getName());
131: conn.setDriver(driver.getClassName());
132: conn.setDatabase(databaseURL);
133: conn.setUser(user);
134: conn.setSchema(schema);
135: conn.setPassword(password);
136: conn.setRememberPassword(rememberPassword);
137:
138: return conn.getDatabaseConnection();
139: }
140:
141: /**
142: * Returns the JDBC driver class that this connection uses.
143: *
144: * @return the JDBC driver class
145: */
146: public String getDriverClass() {
147: return delegate.getDriver();
148: }
149:
150: /**
151: * Returns this connection's database URL.
152: *
153: * @return the connection's database URL
154: */
155: public String getDatabaseURL() {
156: return delegate.getDatabase();
157: }
158:
159: /**
160: * Returns this connection's default schema.
161: *
162: * @return the schema
163: */
164: public String getSchema() {
165: return delegate.getSchema();
166: }
167:
168: /**
169: * Returns the user name used to connect to the database.
170: *
171: * @return the user name
172: */
173: public String getUser() {
174: return delegate.getUser();
175: }
176:
177: /**
178: * Returns the password used to connect to the database.
179: *
180: * @return the password
181: */
182: public String getPassword() {
183: return delegate.getPassword();
184: }
185:
186: /**
187: * Returns the programmatic name of this connection in the Database Explorer.
188: *
189: * @return the programmatic name
190: */
191: public String getName() {
192: return delegate.getName();
193: }
194:
195: /**
196: * Returns the name used to display this connection in the UI.
197: *
198: * @return the display name
199: */
200: public String getDisplayName() {
201: return delegate.getName();
202: }
203:
204: /**
205: * Returns the {@link java.sql.Connection} instance which encapsulates
206: * the physical connection to the database if this database connection
207: * is connected. Note that "connected" here means "connected using the
208: * Database Explorer". There is no check if {@link java.sql.Connection#close}
209: * has been called on the returned connection. However,
210: * clients should not call <code>Connection.close()</code> on the returned
211: * connection, therefore this method should always return a non-closed
212: * connection or <code>null</code>.
213: *
214: * <p><strong>Calling {@link java.sql.Connection#close} on the connection
215: * returned by this method is illegal. Use
216: * {@link ConnectionManager#disconnect}
217: * to close the connection.</strong></p>
218: *
219: * @return the physical connection or null if not connected.
220: *
221: * @throws IllegalStateException if this connection is not added to the
222: * ConnectionManager.
223: */
224: public Connection getJDBCConnection() {
225: if (!ConnectionList.getDefault().contains(delegate)) {
226: throw new IllegalStateException(
227: "This connection is not added to the ConnectionManager."); // NOI18N
228: }
229: return delegate.getJDBCConnection();
230: }
231:
232: /**
233: * Returns a string representation of the database connection.
234: */
235: public String toString() {
236: return "DatabaseConnection[name='" + getName() + "']"; // NOI18N
237: }
238: }
|