Driver.java.in 12.9 KB
Newer Older
Peter Mount's avatar
Peter Mount committed
1 2 3 4 5 6 7
package org.postgresql;

import java.sql.*;
import java.util.*;

import org.postgresql.util.PSQLException;

8
/*
Peter Mount's avatar
Peter Mount committed
9 10 11 12 13 14 15 16 17 18 19 20
 * The Java SQL framework allows for multiple database drivers.  Each
 * driver should supply a class that implements the Driver interface
 *
 * <p>The DriverManager will try to load as many drivers as it can find and
 * then for any given connection request, it will ask each driver in turn
 * to try to connect to the target URL.
 *
 * <p>It is strongly recommended that each Driver class should be small and
 * standalone so that the Driver class can be loaded and queried without
 * bringing in vast quantities of supporting code.
 *
 * <p>When a Driver class is loaded, it should create an instance of itself
21
 * and register it with the DriverManager.	This means that a user can load
Peter Mount's avatar
Peter Mount committed
22 23 24 25 26
 * and register a driver by doing Class.forName("foo.bah.Driver")
 *
 * @see org.postgresql.Connection
 * @see java.sql.Driver
 */
27
public class Driver implements java.sql.Driver
Peter Mount's avatar
Peter Mount committed
28
{
29

30 31
	// make these public so they can be used in setLogLevel below

Barry Lind's avatar
Barry Lind committed
32
	public static final int DEBUG = 2;
33
	public static final int INFO = 1;
Barry Lind's avatar
Barry Lind committed
34 35
        public static boolean logDebug = false;
        public static boolean logInfo = false;
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50

	static
	{
		try
		{
			// moved the registerDriver from the constructor to here
			// because some clients call the driver themselves (I know, as
			// my early jdbc work did - and that was based on other examples).
			// Placing it here, means that the driver is registered once only.
			java.sql.DriverManager.registerDriver(new Driver());
		}
		catch (SQLException e)
		{
			e.printStackTrace();
		}
Peter Mount's avatar
Peter Mount committed
51
	}
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72

	/*
	 * Try to make a database connection to the given URL.	The driver
	 * should return "null" if it realizes it is the wrong kind of
	 * driver to connect to the given URL.	This will be common, as
	 * when the JDBC driverManager is asked to connect to a given URL,
	 * it passes the URL to each loaded driver in turn.
	 *
	 * <p>The driver should raise an SQLException if it is the right driver
	 * to connect to the given URL, but has trouble connecting to the
	 * database.
	 *
	 * <p>The java.util.Properties argument can be used to pass arbitrary
	 * string tag/value pairs as connection arguments.
	 *
	 * user - (optional) The user to connect as
	 * password - (optional) The password for the user
	 * charSet - (optional) The character set to be used for converting
	 *	 to/from the database to unicode.  If multibyte is enabled on the
	 *	 server then the character set of the database is used as the default,
	 *	 otherwise the jvm character encoding is used as the default.
Barry Lind's avatar
Barry Lind committed
73 74 75 76 77 78
         * loglevel - (optional) Enable logging of messages from the driver.
         *       The value is an integer from 1 to 2 where:
         *         INFO = 1, DEBUG = 2
         *       The output is sent to DriverManager.getPrintWriter() if set,
         *       otherwise it is sent to System.out.
	 * compatible - (optional) This is used to toggle
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
	 *	 between different functionality as it changes across different releases
	 *	 of the jdbc driver code.  The values here are versions of the jdbc
	 *	 client and not server versions.  For example in 7.1 get/setBytes
	 *	 worked on LargeObject values, in 7.2 these methods were changed
	 *	 to work on bytea values.  This change in functionality could
	 *	 be disabled by setting the compatible level to be "7.1", in
	 *	 which case the driver will revert to the 7.1 functionality.
	 *
	 * <p>Normally, at least
	 * "user" and "password" properties should be included in the
	 * properties.	For a list of supported
	 * character encoding , see
	 * http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html
	 * Note that you will probably want to have set up the Postgres database
	 * itself to use the same encoding, with the "-E <encoding>" argument
	 * to createdb.
	 *
	 * Our protocol takes the forms:
	 * <PRE>
	 *	jdbc:org.postgresql://host:port/database?param1=val1&...
	 * </PRE>
	 *
	 * @param url the URL of the database to connect to
	 * @param info a list of arbitrary tag/value pairs as connection
	 *	arguments
	 * @return a connection to the URL or null if it isnt us
	 * @exception SQLException if a database access error occurs
	 * @see java.sql.Driver#connect
	 */
	public java.sql.Connection connect(String url, Properties info) throws SQLException
	{
		if ((props = parseURL(url, info)) == null)
		{
Barry Lind's avatar
Barry Lind committed
112
			if (Driver.logDebug) Driver.debug("Error in url" + url);
113 114 115 116
			return null;
		}
		try
		{
Barry Lind's avatar
Barry Lind committed
117
			if (Driver.logDebug) Driver.debug("connect " + url);
118 119 120 121 122 123 124

			org.postgresql.Connection con = (org.postgresql.Connection)(Class.forName("@JDBCCONNECTCLASS@").newInstance());
			con.openConnection (host(), port(), props, database(), url, this);
			return (java.sql.Connection)con;
		}
		catch (ClassNotFoundException ex)
		{
Barry Lind's avatar
Barry Lind committed
125
			if (Driver.logDebug) Driver.debug("error", ex);
126 127 128 129 130 131 132 133 134 135
			throw new PSQLException("postgresql.jvm.version", ex);
		}
		catch (PSQLException ex1)
		{
			// re-throw the exception, otherwise it will be caught next, and a
			// org.postgresql.unusual error will be returned instead.
			throw ex1;
		}
		catch (Exception ex2)
		{
Barry Lind's avatar
Barry Lind committed
136
			if (Driver.logDebug) Driver.debug("error", ex2);
137 138
			throw new PSQLException("postgresql.unusual", ex2);
		}
Peter Mount's avatar
Peter Mount committed
139
	}
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157

	/*
	 * Returns true if the driver thinks it can open a connection to the
	 * given URL.  Typically, drivers will return true if they understand
	 * the subprotocol specified in the URL and false if they don't.  Our
	 * protocols start with jdbc:org.postgresql:
	 *
	 * @see java.sql.Driver#acceptsURL
	 * @param url the URL of the driver
	 * @return true if this driver accepts the given URL
	 * @exception SQLException if a database-access error occurs
	 *	(Dont know why it would *shrug*)
	 */
	public boolean acceptsURL(String url) throws SQLException
	{
		if (parseURL(url, null) == null)
			return false;
		return true;
Peter Mount's avatar
Peter Mount committed
158
	}
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179

	/*
	 * The getPropertyInfo method is intended to allow a generic GUI
	 * tool to discover what properties it should prompt a human for
	 * in order to get enough information to connect to a database.
	 *
	 * <p>Note that depending on the values the human has supplied so
	 * far, additional values may become necessary, so it may be necessary
	 * to iterate through several calls to getPropertyInfo
	 *
	 * @param url the Url of the database to connect to
	 * @param info a proposed list of tag/value pairs that will be sent on
	 *	connect open.
	 * @return An array of DriverPropertyInfo objects describing
	 *	possible properties.  This array may be an empty array if
	 *	no properties are required
	 * @exception SQLException if a database-access error occurs
	 * @see java.sql.Driver#getPropertyInfo
	 */
	public DriverPropertyInfo[] getPropertyInfo(String url, Properties info) throws SQLException
	{
Barry Lind's avatar
Barry Lind committed
180
                //This method isn't really implemented
181
		Properties p = parseURL(url, info);
Barry Lind's avatar
Barry Lind committed
182
		return new DriverPropertyInfo[0];
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
	}

	/*
	 * Gets the drivers major version number
	 *
	 * @return the drivers major version number
	 */
	public int getMajorVersion()
	{
		return @MAJORVERSION@;
	}

	/*
	 * Get the drivers minor version number
	 *
	 * @return the drivers minor version number
	 */
	public int getMinorVersion()
	{
		return @MINORVERSION@;
	}

	/*
	 * Returns the VERSION variable from Makefile.global
	 */
	public static String getVersion()
	{
Barry Lind's avatar
Barry Lind committed
210
		return "@VERSION@ jdbc driver build " + m_buildNumber;
211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348
	}

	/*
	 * Report whether the driver is a genuine JDBC compliant driver.  A
	 * driver may only report "true" here if it passes the JDBC compliance
	 * tests, otherwise it is required to return false.  JDBC compliance
	 * requires full support for the JDBC API and full support for SQL 92
	 * Entry Level.
	 *
	 * <p>For PostgreSQL, this is not yet possible, as we are not SQL92
	 * compliant (yet).
	 */
	public boolean jdbcCompliant()
	{
		return false;
	}

	private Properties props;

	static private String[] protocols = { "jdbc", "postgresql" };

	/*
	 * Constructs a new DriverURL, splitting the specified URL into its
	 * component parts
	 * @param url JDBC URL to parse
	 * @param defaults Default properties
	 * @return Properties with elements added from the url
	 * @exception SQLException
	 */
	Properties parseURL(String url, Properties defaults) throws SQLException
	{
		int state = -1;
		Properties urlProps = new Properties(defaults);
		String key = "";
		String value = "";

		StringTokenizer st = new StringTokenizer(url, ":/;=&?", true);
		for (int count = 0; (st.hasMoreTokens()); count++)
		{
			String token = st.nextToken();

			// PM Aug 2 1997 - Modified to allow multiple backends
			if (count <= 3)
			{
				if ((count % 2) == 1 && token.equals(":"))
					;
				else if ((count % 2) == 0)
				{
					boolean found = (count == 0) ? true : false;
					for (int tmp = 0;tmp < protocols.length;tmp++)
					{
						if (token.equals(protocols[tmp]))
						{
							// PM June 29 1997 Added this property to enable the driver
							// to handle multiple backend protocols.
							if (count == 2 && tmp > 0)
							{
								urlProps.put("Protocol", token);
								found = true;
							}
						}
					}

					if (found == false)
						return null;
				}
				else
					return null;
			}
			else if (count > 3)
			{
				if (count == 4 && token.equals("/"))
					state = 0;
				else if (count == 4)
				{
					urlProps.put("PGDBNAME", token);
					state = -2;
				}
				else if (count == 5 && state == 0 && token.equals("/"))
					state = 1;
				else if (count == 5 && state == 0)
					return null;
				else if (count == 6 && state == 1)
					urlProps.put("PGHOST", token);
				else if (count == 7 && token.equals(":"))
					state = 2;
				else if (count == 8 && state == 2)
				{
					try
					{
						Integer portNumber = Integer.decode(token);
						urlProps.put("PGPORT", portNumber.toString());
					}
					catch (Exception e)
					{
						return null;
					}
				}
				else if ((count == 7 || count == 9) &&
						 (state == 1 || state == 2) && token.equals("/"))
					state = -1;
				else if (state == -1)
				{
					urlProps.put("PGDBNAME", token);
					state = -2;
				}
				else if (state <= -2 && (count % 2) == 1)
				{
					// PM Aug 2 1997 - added tests for ? and &
					if (token.equals(";") || token.equals("?") || token.equals("&") )
						state = -3;
					else if (token.equals("="))
						state = -5;
				}
				else if (state <= -2 && (count % 2) == 0)
				{
					if (state == -3)
						key = token;
					else if (state == -5)
					{
						value = token;
						urlProps.put(key, value);
						state = -2;
					}
				}
			}
		}

		return urlProps;

	}

	/*
	 * @return the hostname portion of the URL
	 */
	public String host()
	{
		return props.getProperty("PGHOST", "localhost");
Peter Mount's avatar
Peter Mount committed
349 350
	}

351
	/*
Barry Lind's avatar
Barry Lind committed
352
	 * @return the port number portion of the URL or the default if no port was specified
353 354 355 356 357 358 359 360 361 362 363
	 */
	public int port()
	{
		return Integer.parseInt(props.getProperty("PGPORT", "@DEF_PGPORT@"));
	}

	/*
	 * @return the database name of the URL
	 */
	public String database()
	{
364
		return props.getProperty("PGDBNAME", "");
365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
	}

	/*
	 * @return the value of any property specified in the URL or properties
	 * passed to connect(), or null if not found.
	 */
	public String property(String name)
	{
		return props.getProperty(name);
	}

	/*
	 * This method was added in v6.5, and simply throws an SQLException
	 * for an unimplemented method. I decided to do it this way while
	 * implementing the JDBC2 extensions to JDBC, as it should help keep the
	 * overall driver size down.
	 */
	public static SQLException notImplemented()
	{
		return new PSQLException("postgresql.unimplemented");
	}
386 387 388 389 390

	/**
	*	used to turn logging on to a certain level, can be called 
	*	by specifying fully qualified class ie org.postgresql.Driver.setLogLevel()
	*	@param int logLevel sets the level which logging will respond to
Barry Lind's avatar
Barry Lind committed
391
	* 	INFO being almost no messages
392 393 394 395
	*	DEBUG most verbose
	*/
	public static void setLogLevel(int logLevel)
	{
Barry Lind's avatar
Barry Lind committed
396 397
            logDebug = (logLevel >= DEBUG) ? true : false;
            logInfo = (logLevel >= INFO) ? true : false;
398
	}
399 400 401 402 403 404
	/*
	 * logging message at the debug level
	 * messages will be printed if the logging level is less or equal to DEBUG
	 */
	public static void debug(String msg)
	{
Barry Lind's avatar
Barry Lind committed
405
		if (logDebug)
406 407 408 409 410 411 412 413 414 415
		{
			DriverManager.println(msg);
		}
	}
	/*
	 * logging message at the debug level
	 * messages will be printed if the logging level is less or equal to DEBUG
	 */
	public static void debug(String msg, Exception ex)
	{
Barry Lind's avatar
Barry Lind committed
416
		if (logDebug)
417 418 419 420 421 422 423 424 425 426
		{
			DriverManager.println(msg + ex != null ? ex.getMessage() : "null Exception");
		}
	}
	/*
	 * logging message at info level
	 * messages will be printed if the logging level is less or equal to INFO
	 */
	public static void info(String msg)
	{
Barry Lind's avatar
Barry Lind committed
427
		if (logInfo)
428 429 430 431 432 433 434 435 436 437
		{
			DriverManager.println(msg);
		}
	}
	/*
	 * logging message at info level
	 * messages will be printed if the logging level is less or equal to INFO
	 */
	public static void info(String msg, Exception ex)
	{
Barry Lind's avatar
Barry Lind committed
438
		if (logInfo)
439 440 441 442
		{
			DriverManager.println(msg + ex != null ? ex.getMessage() : "null Exception");
		}
	}
Barry Lind's avatar
Barry Lind committed
443 444

        //The build number should be incremented for every new build
445
        private static int m_buildNumber = 101;
Barry Lind's avatar
Barry Lind committed
446

447
}