From 2db9d5e53a15551b2a04fcb367598b86f08d96d7 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sat, 24 Feb 2001 12:40:27 +0000 Subject: [PATCH] Markup, spell check, refine JDBC documentation. --- doc/src/sgml/jdbc.sgml | 2415 ++++++++++++++++++++--------------- doc/src/sgml/stylesheet.dsl | 8 +- 2 files changed, 1416 insertions(+), 1007 deletions(-) diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml index 7643abfbdd..cf7b159dcf 100644 --- a/doc/src/sgml/jdbc.sgml +++ b/doc/src/sgml/jdbc.sgml @@ -1,19 +1,17 @@ - JDBC Interface + <acronym>JDBC</acronym> Interface - - - Author - - Written by Peter T. Mount (peter@retep.org.uk), the - author of the JDBC driver. - - - + + Author + + Written by Peter T. Mount (peter@retep.org.uk), the + author of the JDBC driver. + + JDBC is a core API of Java 1.1 and later. @@ -22,148 +20,185 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.18 2000/12/22 21:51:58 - Postgres provides - a type 4 JDBC Driver. - Type 4 indicates that the driver - is written in Pure Java, and communicates in the database's own network - protocol. Because of this, the driver is platform independent. Once compiled, - the driver can be used on any platform. + Postgres provides a type + 4 JDBC Driver. Type 4 indicates + that the driver is written in Pure Java, and communicates in the + database system's own network protocol. Because of this, the driver + is platform independent; once compiled, the driver can be used on + any system. - - Building the <acronym>JDBC</acronym> Interface + + This chapter is not intended as a complete guide to + JDBC programming, but should help to get you + started. For more information refer to the standard + JDBC API documentation. + Also, take a look at the examples included with the source. The + basic example is used here. + - - Compiling the Driver + + Setting up the <acronym>JDBC</acronym> Driver - - The driver's source is located in the src/interfaces/jdbc - directory of the - source tree. To compile simply change directory to that directory, and type: + + Building the Driver - -% make - - + + Precompiled versions of the driver are regularly made available on + the PostgreSQL + JDBC web site. Here we describe how to + build the driver manually. + - - Upon completion, you will find the archive postgresql.jar - in the current - directory. This is the JDBC driver. + + Starting with PostgreSQL version 7.1, + the preferred way to build the JDBC driver is + using Ant, a special tool for building + Java-based packages. You should download + Ant from the Ant + web site and install it before proceeding. + - - - You must use make, - not javac, - as the driver uses some dynamic - loading techniques for performance reasons, - and javac cannot cope. - The Makefile will generate the jar archive. - - - - + + The build the driver, issue the command + +$ ant + + in the top level directory of the + PostgreSQL source distribution. + - - Installing the Driver + + To install the driver, enter the command + +$ ant -Dinstall.directory=mydir install + + Replace mydir with a directory name of + your choice; the directory will be created if necessary. The + PostgreSQL JDBC + driver consists of a postgresql.jar file that + will be copied to that directory. + + + Alternatively, you can use the old make-based + interface. The driver's source is located in the src/interfaces/jdbc directory of the + source tree. To compile, simply change directory to that + directory, and type: + +$ gmake + + (Remember to use GNU make.) Upon completion, + you will find the archive postgresql.jar in + the current directory. This is the JDBC driver, + which you can copy to an appropriate directory in your system. + + + - To use the driver, the jar archive postgresql.jar needs to be included in - the CLASSPATH. + You must not use javac directly, as the + driver uses some dynamic loading techniques for performance + reasons, and javac cannot cope. + + - - Example - - - I have an application that uses the JDBC driver to access a large database - containing astronomical objects. I have the application and the jdbc driver - installed in the /usr/local/lib directory, and the java jdk installed in /usr/local/jdk1.1.6. - + + Setting up the Class Path - - To run the application, I would use: + + To use the driver, the jar archive + postgresql.jar needs to be included in the + class path, either by putting it in the CLASSPATH + environment variable, or by using flags on the + java command line. + - -export CLASSPATH = /usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:. + + + For instance, I have an application that uses the + JDBC driver to access a large database + containing astronomical objects. I have the application and the + JDBC driver installed in the /usr/local/lib directory, and the + Java JDK installed in + /usr/local/jdk1.1.6. To run the + application, I would use: + +export CLASSPATH=/usr/local/lib/finder.jar:/usr/local/lib/postgresql.jar:. java uk.org.retep.finder.Main - - + + + + + finder.jar contains my application. + + + + - - Loading the driver is covered later on in this chapter. - - - - + + Loading the driver from within the application is covered in + . + + + - + Preparing the Database for <acronym>JDBC</acronym> - Because Java can only use TCP/IP connections, the Postgres postmaster - must be running with the -i flag. - - - - Also, the pg_hba.conf file must be configured. It's located in the PGDATA - directory. In a default installation, this file permits access only by Unix - domain sockets. For the JDBC driver to connect to the same localhost, you need - to add something like: - - -host all 127.0.0.1 255.255.255.255 password - - - Here access to all databases are possible from the local machine - with JDBC. + Because Java can only use TCP/IP connections, the + Postgres server must be configured to + accept TCP/IP connections, for instance by supplying the + option flag when starting the + postmaster. - The JDBC Driver supports trust, ident, - password and crypt authentication methods. + Also, the client authentication setup in the + pg_hba.conf file may need to be configured. + Refer to the Administrator's Guide for + details. The JDBC Driver supports trust, + ident, password, and crypt authentication methods. - - - - Using the Driver + + - - This section is not intended as a complete guide to - JDBC programming, but - should help to get you started. For more information refer to the standard - JDBC API documentation. - Also, take a look at the examples included with the source. The basic - example is used here. - - + + Using the Driver - + Importing <acronym>JDBC</acronym> - Any source that uses JDBC - needs to import the java.sql package, using: + Any source that uses JDBC needs to import the + java.sql package, using: - + import java.sql.*; - + - Do not import the postgresql package. If you do, your source will not - compile, as javac will get confused. + Do not import the org.postgresql package. If + you do, your source will not compile, as + javac will get confused. - + - + Loading the Driver - Before you can connect to a database, you need to load the driver. There - are two methods available, and it depends on your code to the best one to use. + Before you can connect to a database, you need to load the + driver. There are two methods available, and it depends on your + code which is the best one to use. @@ -171,80 +206,84 @@ import java.sql.*; Class.forName() method. For Postgres, you would use: - + Class.forName("org.postgresql.Driver"); - + This will load the driver, and while loading, the driver will automatically register itself with JDBC. - - - Note: The forName() method - can throw a ClassNotFoundException, so you will - need to catch it if the driver is not available. + + + The forName() method can throw a + ClassNotFoundException if the driver is + not available. + + - This is the most common method to use, but restricts your code to use just - Postgres. - If your code may access another database in the future, and you - don't use our extensions, then the second method is advisable. + This is the most common method to use, but restricts your code to + use just Postgres. If your code may + access another database system in the future, and you do not use + any Postgres-specific extensions, then + the second method is advisable. - The second method passes the driver as a parameter to the JVM as it starts, - using the -D argument. Example: - - -% java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer - - - In this example, the JVM will attempt to load the driver as part of it's - initialisation. Once done, the ImageViewer is started. + The second method passes the driver as a parameter to the + JVM as it starts, using the + argument. Example: + +java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer + + In this example, the JVM will attempt to load + the driver as part of its initialization. Once done, the + ImageViewer is started. - Now, this method is the better one to use because it allows your code to - be used with other databases, without recompiling the code. The only thing - that would also change is the URL, which is covered next. + Now, this method is the better one to use because it allows your + code to be used with other database packages without recompiling + the code. The only thing that would also change is the connection + URL, which is covered next. - One last thing. When your code then tries to open a Connection, and you get - a No driver available SQLException being thrown, - this is probably - caused by the driver not being in the classpath, or the value in the parameter - not being correct. + One last thing: When your code then tries to open a + Connection, and you get a No + driver available SQLException + being thrown, this is probably caused by the driver not being in + the class path, or the value in the parameter not being correct. - + - + Connecting to the Database - With JDBC, a database is represented by a URL - (Uniform Resource Locator). - With Postgres, this takes one of the following - forms: + With JDBC, a database is represented by a + URL (Uniform Resource Locator). With + Postgres, this takes one of the + following forms: - - jdbc:postgresql:database - + +jdbc:postgresql:database + - - jdbc:postgresql://host/database - + +jdbc:postgresql://host/database + - - jdbc:postgresql://hostport/database - + +jdbc:postgresql://host:port/database + @@ -257,7 +296,7 @@ Class.forName("org.postgresql.Driver"); - The hostname of the server. Defaults to "localhost". + The host name of the server. Defaults to localhost. @@ -268,8 +307,8 @@ Class.forName("org.postgresql.Driver"); - The port number the server is listening on. Defaults to the Postgres - standard port number (5432). + The port number the server is listening on. Defaults to the + Postgres standard port number (5432). @@ -280,7 +319,7 @@ Class.forName("org.postgresql.Driver"); - The database name. + The database name. @@ -288,53 +327,95 @@ Class.forName("org.postgresql.Driver"); - To connect, you need to get a Connection instance from + To connect, you need to get a Connection instance from JDBC. To do this, - you would use the DriverManager.getConnection() method: + you would use the DriverManager.getConnection() method: - -Connection db = DriverManager.getConnection(url,user,pwd); - + +Connection db = DriverManager.getConnection(url, username, password); + - + + + + Closing the Connection + + + To close the database connection, simply call the + close() method to the Connection: + +db.close(); + + + + + Issuing a Query and Processing the Result - Any time you want to issue SQL statements to the database, you require a - Statement instance. Once you have a Statement, you can use the executeQuery() - method to issue a query. This will return a ResultSet instance, which contains - the entire result. + Any time you want to issue SQL statements to + the database, you require a Statement + instance. Once you have a Statement, you + can use the executeQuery() method to issue a + query. This will return a ResultSet + instance, which contains the entire result. illustrates this process. + + Processing a Simple Query in <acronym>JDCB</acronym> + + + This example with issue a simple query and print out the first + column of each row. + +Statement st = db.createStatement(); +ResultSet rs = st.executeQuery("SELECT * FROM mytable"); +while(rs.next()) { + System.out.print("Column 1 returned "); + System.out.println(rs.getString(1)); +} +rs.close(); +st.close(); + + + + - Using the Statement Interface + Using the <classname>Statement</classname> Interface - The following must be considered when using the Statement interface: + The following must be considered when using the + Statement interface: - You can use a Statement instance as many times as you want. You could - create one as soon as you open the connection, and use it for the connections - lifetime. You have to remember that only one ResultSet can exist per Statement. + You can use a single Statement instance + as many times as you want. You could create one as soon as you + open the connection and use it for the connection's + lifetime. But you have to remember that only one + ResultSet can exist per + Statement. - If you need to perform a query while processing a ResultSet, you can - simply create and use another Statement. + If you need to perform a query while processing a + ResultSet, you can simply create and + use another Statement. + - If you are using Threads, and several are using the database, you must - use a separate Statement for each thread. Refer to the sections covering - Threads and Servlets later in this document if you are thinking of using them, - as it covers some important points. + If you are using threads, and several are using the database, + you must use a separate Statement for + each thread. Refer to if you are + thinking of using threads, as it covers some important points. @@ -342,58 +423,50 @@ Connection db = DriverManager.getConnection(url,user,pwd); - Using the ResultSet Interface + Using the <classname>ResultSet</classname> Interface - The following must be considered when using the ResultSet interface: + The following must be considered when using the + ResultSet interface: - Before reading any values, you must call next(). This returns true if - there is a result, but more importantly, it prepares the row for processing. + Before reading any values, you must call + next(). This returns true if there is a + result, but more importantly, it prepares the row for + processing. - Under the JDBC spec, you should access a - field only once. It's safest to stick to this rule, although - at the current time, the Postgres driver - will allow you to access a field as many times as you want. + Under the JDBC specification, you should + access a field only once. It is safest to stick to this rule, + although at the current time, the + Postgres driver will allow you to + access a field as many times as you want. - You must close a ResultSet by calling - close() once you have finished with it. + You must close a ResultSet by calling + close() once you have finished using it. - Once you request another query with the Statement used to create a - ResultSet, the currently open instance is closed. + Once you make another query with the + Statement used to create a + ResultSet, the currently open + ResultSet instance is closed + automatically. - - - An example is as follows: - - -Statement st = db.createStatement(); -ResultSet rs = st.executeQuery("select * from mytable"); -while(rs.next()) { - System.out.print("Column 1 returned "); - System.out.println(rs.getString(1)); -} -rs.close(); -st.close(); - - @@ -401,114 +474,113 @@ st.close(); Performing Updates - To perform an update (or any other SQL statement that does not return a - result), you simply use the executeUpdate() method: - - -st.executeUpdate("create table basic (a int2, b int2)"); - - - - - - Closing the Connection - - - To close the database connection, simply call the close() method to the Connection: + To perform an update (or any other SQL + statement that does not return a result), you simply use the + executeUpdate() method: - -db.close(); - + +st.executeUpdate("CREATE TABLE basic (a int, b int)"); + - - Using Large Objects + + Using Large Objects - - In Postgres, - large objects (also known as blobs) are used to hold data in - the database that cannot be stored in a normal SQL table. They are stored as a - Table/Index pair, and are referred to from your own tables by an OID value. - + + In Postgres, Large + Objects (also known as BLOBs) are + used to hold data in the database that cannot be stored in a normal + SQL table. They are stored in a separate table in a special format, + and are referred to from your own tables by an OID value. + + - - - For Postgres, you must access large - objects within an SQL transaction. Although this has always been - true in principle, it was not strictly enforced until the - release of version 6.5. You would open a transaction by using the - setAutoCommit() method with an input - parameter of false: - - + For Postgres, you must access Large + Objects within an SQL transaction. You would + open a transaction by using the + setAutoCommit() method with an input + parameter of false: + Connection mycon; ... mycon.setAutoCommit(false); -... now use Large Objects - - - +... // now use Large Objects + + - Now, there are two methods of using Large Objects. The first is the + There are two methods of using Large Objects. The first is the standard JDBC way, and is documented here. The - other, uses our own extension - to the api, which presents the libpq large object - API to Java, providing even - better access to large objects than the standard. Internally, the driver uses - the extension to provide large object support. + other, uses PostgreSQL extensions to + the API, which presents the libpq large object + API to Java, providing even better access to + large objects than the standard. Internally, the driver uses the + extension to provide large object support. - In JDBC, the standard way to access them is using the getBinaryStream() - method in ResultSet, and setBinaryStream() method in PreparedStatement. These - methods make the large object appear as a Java stream, allowing you to use the - java.io package, and others, to manipulate the object. + In JDBC, the standard way to access Large + Objects is using the getBinaryStream() method + in ResultSet, and + setBinaryStream() method in + PreparedStatement. These methods make the + large object appear as a Java stream, allowing you to use the + java.io package, and others, to manipulate the + object. illustrates the usage of + this approach. - - For example, suppose - you have a table containing the file name of an image, and a large object - containing that image: + + Using the <acronym>JDBC</acronym> Large Object Interface - -create table images (imgname name,imgoid oid); - + + For example, suppose you have a table containing the file name of + an image and you have a large object containing that image: + +CREATE TABLE images (imgname text, imgoid oid); + To insert an image, you would use: - - + File file = new File("myimage.gif"); FileInputStream fis = new FileInputStream(file); -PreparedStatement ps = conn.prepareStatement("insert into images values (?,?)"); -ps.setString(1,file.getName()); -ps.setBinaryStream(2,fis,file.length()); +PreparedStatement ps = conn.prepareStatement("INSERT INTO images VALUES (?, ?)"); +ps.setString(1, file.getName()); +ps.setBinaryStream(2, fis, file.length()); ps.executeUpdate(); ps.close(); fis.close(); - - - - - Now in this example, setBinaryStream transfers a set number of bytes from a - stream into a large object, and stores the OID into the field holding a - reference to it. + + + + + The question marks must appear literally. The actual data is + substituted by the next lines. + + + + Here, setBinaryStream transfers a set number + of bytes from a stream into a Large Object, and stores the OID + into the field holding a reference to it. Notice that the + creation of the Large Object itself in the database happens + transparently. - Retrieving an image is even easier (I'm using PreparedStatement here, but - Statement can equally be used): + Retrieving an image is even easier. (We use + PreparedStatement here, but the + Statement class can equally be used.) - -PreparedStatement ps = con.prepareStatement("select oid from images where name=?"); -ps.setString(1,"myimage.gif"); + +PreparedStatement ps = con.prepareStatement("SELECT oid FROM images WHERE name=?"); +ps.setString(1, "myimage.gif"); ResultSet rs = ps.executeQuery(); -if(rs!=null) { +if (rs != null) { while(rs.next()) { InputStream is = rs.getBinaryInputStream(1); // use the stream in some way here @@ -517,418 +589,593 @@ if(rs!=null) { rs.close(); } ps.close(); - + - Now here you can see where the Large Object is retrieved as an InputStream. - You'll also notice that we close the stream before processing the next row in - the result. This is part of the JDBC Specification, which states that any - InputStream returned is closed when ResultSet.next() or ResultSet.close() is called. + Here you can see how the Large Object is retrieved as an + InputStream. You will also notice that we + close the stream before processing the next row in the + result. This is part of the JDBC specification, + which states that any InputStream returned + is closed when ResultSet.next() or + ResultSet.close() is called. - + + - - <application>Postgres</application> Extensions to the - <acronym>JDBC</acronym> <acronym>API</acronym> - - Postgres is an extensible database system. - You can add your own functions - to the backend, which can then be called from queries, or even add your own - data types. - + + <application>PostgreSQL</application> Extensions to the + <acronym>JDBC</acronym> <acronym>API</acronym> - - Now, as these are facilities unique to us, we support them from Java, with - a set of extension API's. Some features within - the core of the standard driver - actually use these extensions to implement Large Objects, etc. + + Postgres is an extensible database + system. You can add your own functions to the backend, which can + then be called from queries, or even add your own data types. As + these are facilities unique to Postgres, + we support them from Java, with a set of extension + API's. Some features within the core of the + standard driver actually use these extensions to implement Large + Objects, etc. + - + + Accessing the Extensions + + To access some of the extensions, you need to use some extra + methods in the org.postgresql.Connection + class. In this case, you would need to case the return value of + Driver.getConnection(). For example: -Accessing the extensions - -To access some of the extensions, you need to use some extra methods -in the postgresql.Connection class. In this case, you would need to -case the return value of Driver.getConnection(). - -For example: +Connection db = Driver.getConnection(url, username, password); +// ... +// later on +Fastpath fp = ((org.postgresql.Connection)db).getFastpathAPI(); + + - Connection db = Driver.getConnection(url,user,pass); + + Class <classname>org.postgresql.Connection</classname> - // later on - Fastpath fp = ((postgresql.Connection)db).getFastpathAPI(); + +public class Connection extends Object implements Connection -Class postgresql.Connection - java.lang.Object | - +----postgresql.Connection - - public class Connection extends Object implements Connection - -These are the extra methods used to gain access to our extensions. I -have not listed the methods defined by java.sql.Connection. - - public Fastpath getFastpathAPI() throws SQLException - - This returns the Fastpath API for the current connection. - - NOTE: This is not part of JDBC, but allows access to -functions on the postgresql backend itself. - - It is primarily used by the LargeObject API + +----org.postgresql.Connection + - The best way to use this is as follows: - - import postgresql.fastpath.*; - ... - Fastpath fp = ((postgresql.Connection)myconn).getFastpathAPI(); - - where myconn is an open Connection to postgresql. - - Returns: - Fastpath object allowing access to functions on the -postgresql backend. - - Throws: SQLException - by Fastpath when initialising for first time - - public LargeObjectManager getLargeObjectAPI() throws SQLException - - This returns the LargeObject API for the current connection. - - NOTE: This is not part of JDBC, but allows access to -functions on the postgresql backend itself. - - The best way to use this is as follows: - - import postgresql.largeobject.*; - ... - LargeObjectManager lo = -((postgresql.Connection)myconn).getLargeObjectAPI(); - - where myconn is an open Connection to postgresql. + + These are the extra methods used to gain access to + PostgreSQL's extensions. Methods + defined by java.sql.Connection are not + listed. + - Returns: - LargeObject object that implements the API + + Methods - Throws: SQLException - by LargeObject when initialising for first time + + + +public Fastpath getFastpathAPI() throws SQLException + + + This returns the Fastpath API for the + current connection. It is primarily used by the Large Object + API. + - public void addDataType(String type, - String name) + + The best way to use this is as follows: + +import org.postgresql.fastpath.*; +... +Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI(); + + where myconn is an open Connection to PostgreSQL. + - This allows client code to add a handler for one of -postgresql's more unique data types. Normally, a data type not known -by the driver is returned by ResultSet.getObject() as a PGobject -instance. + + Returns: + + Fastpath object allowing access to functions on the + PostgreSQL backend. + + + + + Throws: + + SQLException by Fastpath when initializing for first time + + + -This method allows you to write a class that extends PGobject, and -tell the driver the type name, and class name to use. + + + +public LargeObjectManager getLargeObjectAPI() throws SQLException + + This returns the Large Object API for the + current connection. + -The down side to this, is that you must call this method each time a -connection is made. + + The best way to use this is as follows: + +import org.postgresql.largeobject.*; +... +LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI(); + + where myconn is an open Connection to + PostgreSQL. + - NOTE: This is not part of JDBC, but an extension. + + Returns: + + LargeObject object that implements the API + + + + + Throws: + + SQLException by LargeObject when initializing for first time + + + - The best way to use this is as follows: + + + +public void addDataType(String type, String name) + + This allows client code to add a handler for one of + PostgreSQL's more unique data types. Normally, a data type not + known by the driver is returned by ResultSet.getObject() as a + PGobject instance. This method allows you to write a class + that extends PGobject, and tell the driver the type name, and + class name to use. The down side to this, is that you must + call this method each time a connection is made. + + + The best way to use this is as follows: + ... - ((postgresql.Connection)myconn).addDataType("mytype","my.class.name"- -); +((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name"); ... + + where myconn is an open Connection to + PostgreSQL. The handling class must + extend org.postgresql.util.PGobject. + + + + + - where myconn is an open Connection to postgresql. - - The handling class must extend postgresql.util.PGobject - - See Also: - PGobject - -Fastpath - -Fastpath is an API that exists within the libpq C interface, and -allows a client machine to execute a function on the database backend. -Most client code will not need to use this method, but it's provided -because the Large Object API uses it. - -To use, you need to import the postgresql.fastpath package, using the -line: - import postgresql.fastpath.*; - -Then, in your code, you need to get a FastPath object: - Fastpath fp = ((postgresql.Connection)conn).getFastpathAPI(); - -This will return an instance associated with the database connection -that you can use to issue commands. The casing of Connection to -postgresql.Connection is required, as the getFastpathAPI() is one of -our own methods, not JDBC's. -Once you have a Fastpath instance, you can use the fastpath() methods -to execute a backend function. + + Class <classname>org.postgresql.Fastpath</classname> -Class postgresql.fastpath.Fastpath + +public class Fastpath extends Object java.lang.Object | - +----postgresql.fastpath.Fastpath - - public class Fastpath + +----org.postgresql.fastpath.Fastpath + - extends Object - - This class implements the Fastpath api. - - This is a means of executing functions imbeded in the postgresql -backend from within a java application. + + Fastpath is an API that + exists within the libpq C interface, and allows a client machine + to execute a function on the database backend. Most client code + will not need to use this method, but it is provided because the + Large Object API uses it. + - It is based around the file src/interfaces/libpq/fe-exec.c + + To use, you need to import the + org.postgresql.fastpath package, using the + line: + +import org.postgresql.fastpath.*; + + Then, in your code, you need to get a + FastPath object: + +Fastpath fp = ((org.postgresql.Connection)conn).getFastpathAPI(); + + This will return an instance associated with the database + connection that you can use to issue commands. The casing of + Connection to + org.postgresql.Connection is required, as + the getFastpathAPI() is an extension method, + not part of JDBC. Once you have a + Fastpath instance, you can use the + fastpath() methods to execute a backend + function. + - See Also: - FastpathFastpathArg, LargeObject + + See Also: + + FastpathFastpathArg, LargeObject + + -Methods + + Methods - public Object fastpath(int fnid, - boolean resulttype, - FastpathArg args[]) throws SQLException + + + +public Object fastpath(int fnid, + boolean resulttype, + FastpathArg args[]) throws SQLException + + + Send a function call to the PostgreSQL backend. + - Send a function call to the PostgreSQL backend - - Parameters: + + Parameters: + fnid - Function id resulttype - True if the result is an integer, false for other results args - FastpathArguments to pass to fastpath + + + + + Returns: + + null if no data, Integer if an integer result, or byte[] + otherwise + + + - Returns: - null if no data, Integer if an integer result, or -byte[] - otherwise - - Throws: SQLException - if a database-access error occurs. - - public Object fastpath(String name, - boolean resulttype, - FastpathArg args[]) throws SQLException - - Send a function call to the PostgreSQL backend by name. - -Note: - the mapping for the procedure name to function id needs to -exist, usually to an earlier call to addfunction(). This is the -prefered method to call, as function id's can/may change between -versions of the backend. For an example of how this works, refer to -postgresql.LargeObject + + +public Object fastpath(String name, + boolean resulttype, + FastpathArg args[]) throws SQLException + + + Send a function call to the PostgreSQL backend by name. + - Parameters: + + + The mapping for the procedure name to function id needs to + exist, usually to an earlier call to addfunction(). This is + the preferred method to call, as function id's can/may change + between versions of the backend. For an example of how this + works, refer to org.postgresql.LargeObject + + + + + Parameters: + name - Function name resulttype - True if the result is an integer, false for other results args - FastpathArguments to pass to fastpath + + + + + Returns: + + null if no data, Integer if an integer result, or byte[] + otherwise + + + + + See Also: + LargeObject + + - Returns: - null if no data, Integer if an integer result, or -byte[] - otherwise - - Throws: SQLException - if name is unknown or if a database-access error -occurs. - - See Also: - LargeObject - - public int getInteger(String name, - FastpathArg args[]) throws SQLException - - This convenience method assumes that the return value is an -Integer + + +public int getInteger(String name, + FastpathArg args[]) throws SQLException + + + This convenience method assumes that the return value is an Integer + - Parameters: + + Parameters: + name - Function name args - Function arguments + + + + + Returns: + integer result + + + + Throws: + + SQLException if a database-access error occurs or no result + + + - Returns: - integer result - - Throws: SQLException - if a database-access error occurs or no result - - public byte[] getData(String name, - FastpathArg args[]) throws SQLException - - This convenience method assumes that the return value is -binary data + + +public byte[] getData(String name, + FastpathArg args[]) throws SQLException + + + This convenience method assumes that the return value is binary + data. + - Parameters: + + Parameters: + name - Function name args - Function arguments + + + + + Returns: + byte[] array containing result + + + + Throws: + + SQLException if a database-access error occurs or no result + + + - Returns: - byte[] array containing result - - Throws: SQLException - if a database-access error occurs or no result - - public void addFunction(String name, - int fnid) - - This adds a function to our lookup table. - - User code should use the addFunctions method, which is based -upon a query, rather than hard coding the oid. The oid for a function -is not guaranteed to remain static, even on different servers of the -same version. - - Parameters: - name - Function name - fnid - Function id - - public void addFunctions(ResultSet rs) throws SQLException - - This takes a ResultSet containing two columns. Column 1 -contains the function name, Column 2 the oid. - - It reads the entire ResultSet, loading the values into the -function table. - - REMEMBER to close() the resultset after calling this!! - - Implementation note about function name lookups: - - PostgreSQL stores the function id's and their corresponding -names in the pg_proc table. To speed things up locally, instead of -querying each function from that table when required, a Hashtable is -used. Also, only the function's required are entered into this table, -keeping connection times as fast as possible. - - The postgresql.LargeObject class performs a query upon it's -start-up, and passes the returned ResultSet to the addFunctions() -method here. - - Once this has been done, the LargeObject api refers to the -functions by name. - - Dont think that manually converting them to the oid's will -work. Ok, they will for now, but they can change during development -(there was some discussion about this for V7.0), so this is -implemented to prevent any unwarranted headaches in the future. - - Parameters: - rs - ResultSet + + +public void addFunction(String name, + int fnid) + + + This adds a function to our look-up table. User code should + use the addFunctions method, which is based upon a query, + rather than hard coding the oid. The oid for a function is not + guaranteed to remain static, even on different servers of the + same version. + + - Throws: SQLException - if a database-access error occurs. - - See Also: - LargeObjectManager + + +public void addFunctions(ResultSet rs) throws SQLException + + + This takes a ResultSet containing two columns. Column 1 + contains the function name, Column 2 the oid. It reads the + entire ResultSet, loading the values into the function table. + - public int getID(String name) throws SQLException - - This returns the function id associated by its name - - If addFunction() or addFunctions() have not been called for -this name, then an SQLException is thrown. + + + Remember to close() the + ResultSet after calling this! + + + + + Implementation note about function name look-ups + + + PostgreSQL stores the function id's and their corresponding + names in the pg_proc table. To speed things up locally, + instead of querying each function from that table when + required, a Hashtable is used. Also, only the function's + required are entered into this table, keeping connection + times as fast as possible. + + + + The org.postgresql.LargeObject class + performs a query upon its start-up, and passes the returned + ResultSet to the + addFunctions() method here. Once this + has been done, the Large Object API refers + to the functions by name. + + + + Do not think that manually converting them to the oid's will + work. Okay, they will for now, but they can change during + development (there was some discussion about this for V7.0), + so this is implemented to prevent any unwarranted headaches + in the future. + + + + + See Also: + + LargeObjectManager + + + - Parameters: - name - Function name to lookup + + +public int getID(String name) throws SQLException + + + This returns the function id associated by its name If + addFunction() or addFunctions() have not been called for this + name, then an SQLException is thrown. + + + + + - Returns: - Function ID for fastpath call - Throws: SQLException - is function is unknown. + + Class <classname>org.postgresql.fastpath.FastpathArg</classname> -Class postgresql.fastpath.FastpathArg + +public class FastpathArg extends Object java.lang.Object | - +----postgresql.fastpath.FastpathArg + +----org.postgresql.fastpath.FastpathArg + - public class FastpathArg extends Object - - Each fastpath call requires an array of arguments, the number and -type dependent on the function being called. - - This class implements methods needed to provide this capability. - - For an example on how to use this, refer to the -postgresql.largeobject package - - See Also: - Fastpath, LargeObjectManager, LargeObject + + Each fastpath call requires an array of arguments, the number and + type dependent on the function being called. This class + implements methods needed to provide this capability. + -Constructors + + For an example on how to use this, refer to the + org.postgresql.LargeObject package. + - public FastpathArg(int value) - - Constructs an argument that consists of an integer value + + See Also: + + Fastpath, LargeObjectManager, LargeObject + + - Parameters: - value - int value to set + + Constructors - public FastpathArg(byte bytes[]) - - Constructs an argument that consists of an array of bytes + + + +public FastpathArg(int value) + + + Constructs an argument that consists of an integer value + - Parameters: - bytes - array to store + + Parameters: + + value - int value to set + + + - public FastpathArg(byte buf[], - int off, - int len) + + +public FastpathArg(byte bytes[]) + + + Constructs an argument that consists of an array of bytes + - Constructs an argument that consists of part of a byte -array + + Parameters: + + bytes - array to store + + + - Parameters: - buf - source array - off - offset within array - len - length of data to include + + +public FastpathArg(byte buf[], + int off, + int len) + + + Constructs an argument that consists of part of a byte array + - public FastpathArg(String s) - - Constructs an argument that consists of a String. - - Parameters: - s - String to store + + Parameters: + + + + buf + + source array + + + + + off + + offset within array + + + + + len + + length of data to include + + + + + + -Geometric Data Types + + +public FastpathArg(String s) + + + Constructs an argument that consists of a String. + + + + + + -PostgreSQL has a set of datatypes that can store geometric features -into a table. These range from single points, lines, and polygons. -We support these types in Java with the postgresql.geometric package. + + Geometric Data Types -It contains classes that extend the postgresql.util.PGobject class. -Refer to that class for details on how to implement your own data type -handlers. + + PostgreSQL has a set of data types that + can store geometric features into a table. These include single + points, lines, and polygons. We support these types in Java with + the org.postgresql.geometric package. It contains classes that + extend the org.postgresql.util.PGobject class. Refer to that + class for details on how to implement your own data type handlers. + -Class postgresql.geometric.PGbox + +Class org.postgresql.geometric.PGbox java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.geometric.PGbox + +----org.postgresql.geometric.PGbox public class PGbox extends PGobject implements Serializable, Cloneable - This represents the box datatype within postgresql. + This represents the box data type within PostgreSQL. Variables @@ -973,7 +1220,7 @@ Methods public void setValue(String value) throws SQLException This method sets the value of this object. It should be -overidden, but still called by subclasses. +overridden, but still called by subclasses. Parameters: value - a string representation of the value of the @@ -997,7 +1244,7 @@ object public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -1005,30 +1252,31 @@ object public String getValue() Returns: - the PGbox in the syntax expected by postgresql + the PGbox in the syntax expected by PostgreSQL Overrides: getValue in class PGobject -Class postgresql.geometric.PGcircle + +Class org.postgresql.geometric.PGcircle java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.geometric.PGcircle + +----org.postgresql.geometric.PGcircle public class PGcircle extends PGobject implements Serializable, Cloneable - This represents postgresql's circle datatype, consisting of a point + This represents PostgreSQL's circle data type, consisting of a point and a radius Variables public PGpoint center - This is the centre point + This is the center point public double radius @@ -1041,15 +1289,15 @@ Constructors double r) Parameters: - x - coordinate of centre - y - coordinate of centre + x - coordinate of center + y - coordinate of center r - radius of circle public PGcircle(PGpoint c, double r) Parameters: - c - PGpoint describing the circle's centre + c - PGpoint describing the circle's center r - radius of circle public PGcircle(String s) throws SQLException @@ -1090,7 +1338,7 @@ Methods public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -1098,18 +1346,19 @@ Methods public String getValue() Returns: - the PGcircle in the syntax expected by postgresql + the PGcircle in the syntax expected by PostgreSQL Overrides: getValue in class PGobject -Class postgresql.geometric.PGline + +Class org.postgresql.geometric.PGline java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.geometric.PGline + +----org.postgresql.geometric.PGline public class PGline extends PGobject implements Serializable, Cloneable @@ -1154,7 +1403,7 @@ Constructors public PGline() - reuired by the driver + required by the driver Methods @@ -1183,7 +1432,7 @@ syntax public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -1191,18 +1440,19 @@ syntax public String getValue() Returns: - the PGline in the syntax expected by postgresql + the PGline in the syntax expected by PostgreSQL Overrides: getValue in class PGobject -Class postgresql.geometric.PGlseg + +Class org.postgresql.geometric.PGlseg java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.geometric.PGlseg + +----org.postgresql.geometric.PGlseg public class PGlseg extends PGobject implements Serializable, Cloneable @@ -1246,7 +1496,7 @@ Constructors public PGlseg() - reuired by the driver + required by the driver Methods @@ -1275,7 +1525,7 @@ syntax public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -1283,18 +1533,19 @@ syntax public String getValue() Returns: - the PGlseg in the syntax expected by postgresql + the PGlseg in the syntax expected by PostgreSQL Overrides: getValue in class PGobject -Class postgresql.geometric.PGpath + +Class org.postgresql.geometric.PGpath java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.geometric.PGpath + +----org.postgresql.geometric.PGpath public class PGpath extends PGobject implements Serializable, Cloneable @@ -1359,7 +1610,7 @@ Methods public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -1367,7 +1618,7 @@ Methods public String getValue() This returns the polygon in the syntax expected by -postgresql +PostgreSQL Overrides: getValue in class PGobject @@ -1388,13 +1639,14 @@ postgresql Marks the path as open -Class postgresql.geometric.PGpoint + +Class org.postgresql.geometric.PGpoint java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.geometric.PGpoint + +----org.postgresql.geometric.PGpoint public class PGpoint extends PGobject implements Serializable, Cloneable @@ -1402,7 +1654,7 @@ Cloneable This implements a version of java.awt.Point, except it uses double to represent the coordinates. - It maps to the point datatype in postgresql. + It maps to the point data type in PostgreSQL. Variables @@ -1426,7 +1678,7 @@ Constructors public PGpoint(String value) throws SQLException This is called mainly from the other geometric types, when a -point is imbeded within their definition. +point is embedded within their definition. Parameters: value - Definition of this point in PostgreSQL's @@ -1462,7 +1714,7 @@ Methods public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -1470,7 +1722,7 @@ Methods public String getValue() Returns: - the PGpoint in the syntax expected by postgresql + the PGpoint in the syntax expected by PostgreSQL Overrides: getValue in class PGobject @@ -1535,18 +1787,19 @@ public void move(double x, See Also: Point -Class postgresql.geometric.PGpolygon + +Class org.postgresql.geometric.PGpolygon java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.geometric.PGpolygon + +----org.postgresql.geometric.PGpolygon public class PGpolygon extends PGobject implements Serializable, Cloneable - This implements the polygon datatype within PostgreSQL. + This implements the polygon data type within PostgreSQL. Variables @@ -1601,7 +1854,7 @@ Methods public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -1609,133 +1862,224 @@ Methods public String getValue() Returns: - the PGpolygon in the syntax expected by postgresql + the PGpolygon in the syntax expected by PostgreSQL Overrides: getValue in class PGobject + + -Large Objects -Large objects are supported in the standard JDBC specification. -However, that interface is limited, and the api provided by PostgreSQL -allows for random access to the objects contents, as if it was a local -file. + + Large Objects -The postgresql.largeobject package profides to Java the libpq C -interface's large object API. It consists of two classes, -LargeObjectManager, which deals with creating, opening and deleting -large obejects, and LargeObject which deals with an individual object. + + Large objects are supported in the standard + JDBC specification. However, that interface is + limited, and the API provided by PostgreSQL allows for random + access to the objects contents, as if it was a local file. + -Class postgresql.largeobject.LargeObject + + The org.postgresql.largeobject package provides to Java the libpq + C interface's large object API. It consists of + two classes, LargeObjectManager, which deals with creating, + opening and deleting large objects, and LargeObject which deals + with an individual object. + -java.lang.Object - | - +----postgresql.largeobject.LargeObject + + Class <classname>org.postgresql.largeobject.LargeObject</classname> + public class LargeObject extends Object -This class implements the large object interface to postgresql. - - It provides the basic methods required to run the interface, plus a -pair of methods that provide InputStream and OutputStream classes for -this object. - - Normally, client code would use the getAsciiStream, -getBinaryStream, or getUnicodeStream methods in ResultSet, or -setAsciiStream, setBinaryStream, or setUnicodeStream methods in -PreparedStatement to access Large Objects. - - However, sometimes lower level access to Large Objects are -required, that are not supported by the JDBC specification. - - Refer to postgresql.largeobject.LargeObjectManager on how to gain -access to a Large Object, or how to create one. - - See Also: - LargeObjectManager - -Variables - - public static final int SEEK_SET - - Indicates a seek from the begining of a file - - public static final int SEEK_CUR - - Indicates a seek from the current position - - public static final int SEEK_END +java.lang.Object + | + +----org.postgresql.largeobject.LargeObject + - Indicates a seek from the end of a file + + This class implements the large object interface to + PostgreSQL. + -Methods + + It provides the basic methods required to run the interface, plus + a pair of methods that provide InputStream and OutputStream + classes for this object. + - public int getOID() + + Normally, client code would use the getAsciiStream, + getBinaryStream, or getUnicodeStream methods in ResultSet, or + setAsciiStream, setBinaryStream, or setUnicodeStream methods in + PreparedStatement to access Large Objects. + - Returns: - the OID of this LargeObject + + However, sometimes lower level access to Large Objects are + required, that are not supported by the JDBC + specification. + - public void close() throws SQLException + + Refer to org.postgresql.largeobject.LargeObjectManager on how to + gain access to a Large Object, or how to create one. + - This method closes the object. You must not call methods in -this object after this is called. + + See Also: + LargeObjectManager + + + + Variables + + + + public static final int SEEK_SET + + Indicates a seek from the beginning of a file + + + + + public static final int SEEK_CUR + + Indicates a seek from the current position + + + + + public static final int SEEK_END + + Indicates a seek from the end of a file + + + + + + + Methods - Throws: SQLException - if a database-access error occurs. + + + +public int getOID() + + + Returns the OID of this LargeObject + + - public byte[] read(int len) throws SQLException + + +public void close() throws SQLException + + + This method closes the object. You must not call methods in + this object after this is called. + + - Reads some data from the object, and return as a byte[] -array + + +public byte[] read(int len) throws SQLException + + + Reads some data from the object, and return as a byte[] array + + - Parameters: - len - number of bytes to read + + +public void read(byte buf[], + int off, + int len) throws SQLException + + + Reads some data from the object into an existing array + - Returns: - byte[] array containing data read + + Parameters: + + + + buf + + destination array + + + + + off + + offset within array + + + + + len + + number of bytes to read + + + + + + - Throws: SQLException - if a database-access error occurs. + + +public void write(byte buf[]) throws SQLException + + + Writes an array to the object + + - public void read(byte buf[], + + +public void write(byte buf[], int off, int len) throws SQLException + + + Writes some data from an array to the object + - Reads some data from the object into an existing array - - Parameters: - buf - destination array - off - offset within array - len - number of bytes to read - - Throws: SQLException - if a database-access error occurs. - - public void write(byte buf[]) throws SQLException - - Writes an array to the object - - - Parameters: - buf - array to write - - Throws: SQLException - if a database-access error occurs. - - public void write(byte buf[], - int off, - int len) throws SQLException - - Writes some data from an array to the object - - Parameters: - buf - destination array - off - offset within array - len - number of bytes to write - - Throws: SQLException - if a database-access error occurs. + + Parameters: + + + + buf + + destination array + + + + + off + + offset within array + + + + + len + + number of bytes to write + + + + + + + + + + -Class postgresql.largeobject.LargeObjectManager - -java.lang.Object - | - +----postgresql.largeobject.LargeObjectManager - -public class LargeObjectManager extends Object - -This class implements the large object interface to postgresql. - - It provides methods that allow client code to create, open and -delete large objects from the database. When opening an object, an -instance of postgresql.largeobject.LargeObject is returned, and its -methods then allow access to the object. - -This class can only be created by postgresql.Connection - -To get access to this class, use the following segment of code: - - import postgresql.largeobject.*; - Connection conn; - LargeObjectManager lobj; - ... code that opens a connection ... - lobj = ((postgresql.Connection)myconn).getLargeObjectAPI(); - -Normally, client code would use the getAsciiStream, getBinaryStream, -or getUnicodeStream methods in ResultSet, or setAsciiStream, -setBinaryStream, or setUnicodeStream methods in PreparedStatement to -access Large Objects. - - However, sometimes lower level access to Large Objects are -required, that are not supported by the JDBC specification. - - Refer to postgresql.largeobject.LargeObject on how to manipulate -the contents of a Large Object. - - See Also: - LargeObject - -Variables - - public static final int WRITE - - This mode indicates we want to write to an object - - public static final int READ - - This mode indicates we want to read an object - - public static final int READWRITE - - This mode is the default. It indicates we want read and -write access to a large object - -Methods - - public LargeObject open(int oid) throws SQLException - - This opens an existing large object, based on its OID. This - method assumes that READ and WRITE access is required (the -default). - - Parameters: - oid - of large object - - Returns: - LargeObject instance providing access to the object - - Throws: SQLException - on error - - public LargeObject open(int oid, - int mode) throws SQLException - - This opens an existing large object, based on its OID - - Parameters: - oid - of large object - mode - mode of open - - Returns: - LargeObject instance providing access to the object - - Throws: SQLException - on error - - public int create() throws SQLException - - This creates a large object, returning its OID. - It defaults to READWRITE for the new object's attributes. + + Class <classname>org.postgresql.largeobject.LargeObjectManager</classname> - Returns: - oid of new object + +public class LargeObjectManager extends Object - Throws: SQLException - on error +java.lang.Object + | + +----org.postgresql.largeobject.LargeObjectManager + - public int create(int mode) throws SQLException + + This class implements the large object interface to + PostgreSQL. It provides methods that + allow client code to create, open and delete large objects from + the database. When opening an object, an instance of + org.postgresql.largeobject.LargeObject is + returned, and its methods then allow access to the object. + - This creates a large object, returning its OID + + This class can only be created by org.postgresql.Connection. To + get access to this class, use the following segment of code: + +import org.postgresql.largeobject.*; +Connection conn; +LargeObjectManager lobj; +// ... code that opens a connection ... +lobj = ((org.postgresql.Connection)myconn).getLargeObjectAPI(); + + - Parameters: - mode - a bitmask describing different attributes of -the - new object + + Normally, client code would use the getAsciiStream, + getBinaryStream, or getUnicodeStream methods in ResultSet, or + setAsciiStream, setBinaryStream, or setUnicodeStream methods in + PreparedStatement to access Large Objects. However, sometimes + lower level access to Large Objects are required, that are not + supported by the JDBC specification. + - Returns: - oid of new object + + Refer to org.postgresql.largeobject.LargeObject on how to + manipulate the contents of a Large Object. + - Throws: SQLException - on error + + Variables + + + + public static final int WRITE + + This mode indicates we want to write to an object. + + + + + public static final int READ + + This mode indicates we want to read an object. + + + + + public static final int READWRITE + + This mode is the default. It indicates we want read and write access to a large object. + + + + + + + Methods - public void delete(int oid) throws SQLException - - This deletes a large object. - - Parameters: - oid - describing object to delete + + + +public LargeObject open(int oid) throws SQLException + + + This opens an existing large object, based on its OID. This + method assumes that READ and WRITE access is required (the + default). + + - Throws: SQLException - on error + + +public LargeObject open(int oid, + int mode) throws SQLException + + + This opens an existing large object, based on its OID, and + allows setting the access mode. + + - public void unlink(int oid) throws SQLException + + +public int create() throws SQLException + + + This creates a large object, returning its OID. + It defaults to READWRITE for the new object's attributes. + + - This deletes a large object. + + +public int create(int mode) throws SQLException + + + This creates a large object, returning its OID, and sets the + access mode. + + - It is identical to the delete method, and is supplied as the -C API uses unlink. + + +public void delete(int oid) throws SQLException + + + This deletes a large object. + + - Parameters: - oid - describing object to delete + + +public void unlink(int oid) throws SQLException + + + This deletes a large object. It is identical to the delete + method, and is supplied as the C API uses + unlink. + + + + + + - Throws: SQLException - on error -Object Serialisation -PostgreSQL is not a normal SQL Database. It is far more extensible -than most other databases, and does support Object Oriented features -that are unique to it. + + Object Serialization -One of the consequences of this, is that you can have one table refer -to a row in another table. For example: + + PostgreSQL is not a normal + SQL database. It is more extensible than most + other databases, and does support object oriented features that + are unique to it. + + + One of the consequences of this, is that you can have one table + refer to a row in another table. For example: + test=> create table users (username name,fullname text); CREATE test=> create table server (servername name,adminuser users); @@ -1968,58 +2331,80 @@ servername|adminuser ----------+--------- maidast | 2610132 (1 row) + + Okay, the above example shows that we can use a table name as a + field, and the row's oid value is stored in that field. + -Ok, the above example shows that we can use a table name as a field, -and the row's oid value is stored in that field. - -What does this have to do with Java? - -In Java, you can store an object to a Stream as long as it's class -implements the java.io.Serializable interface. This process, known as -Object Serialization, can be used to store complex objects into the -database. - -Now, under JDBC, you would have to use a LargeObject to store them. -However, you cannot perform queries on those objects. + + What does this have to do with Java? + -What the postgresql.util.Serialize class does, is provide a means of -storing an object as a table, and to retrieve that object from a -table. In most cases, you would not need to access this class direct, -but you would use the PreparedStatement.setObject() and -ResultSet.getObject() methods. Those methods will check the objects -class name against the table's in the database. If a match is found, -it assumes that the object is a Serialized object, and retrieves it -from that table. As it does so, if the object contains other -serialized objects, then it recurses down the tree. + + In Java, you can store an object to a Stream as long as it's class + implements the java.io.Serializable interface. This process, known + as Object Serialization, can be used to store complex objects into + the database. + -Sound's complicated? In fact, it's simpler than what I wrote - it's -just difficult to explain. + + Now, under JDBC, you would have to use a + Large Object to store them. However, you cannot perform queries on + those objects. + -The only time you would access this class, is to use the create() -methods. These are not used by the driver, but issue one or more -"create table" statements to the database, based on a Java Object or -Class that you want to serialize. + + What the org.postgresql.util.Serialize class does, is provide a + means of storing an object as a table, and to retrieve that object + from a table. In most cases, you would not need to access this + class direct, but you would use the PreparedStatement.setObject() + and ResultSet.getObject() methods. Those methods will check the + objects class name against the table's in the database. If a match + is found, it assumes that the object is a Serialized object, and + retrieves it from that table. As it does so, if the object + contains other serialized objects, then it recurses down the tree. + -Oh, one last thing. If your object contains a line like: + + Sound's complicated? In fact, it's simpler than what I wrote - + it's just difficult to explain. + - public int oid; + + The only time you would access this class, is to use the create() + methods. These are not used by the driver, but issue one or more + "create table" statements to the database, based on a Java Object + or Class that you want to serialize. + -then, when the object is retrieved from the table, it is set to the -oid within the table. Then, if the object is modified, and re- -serialized, the existing entry is updated. + + Oh, one last thing. If your object contains a line like: + +public int oid; + + then, when the object is retrieved from the table, it is set to + the oid within the table. Then, if the object is modified, and re- + serialized, the existing entry is updated. + -If the oid variable is not present, then when the object is -serialized, it is always inserted into the table, and any existing -entry in the table is preserved. + + If the oid variable is not present, then when the object is + serialized, it is always inserted into the table, and any existing + entry in the table is preserved. + -Setting oid to 0 before serialization, will also cause the object to -be inserted. This enables an object to be duplicated in the database. + + Setting oid to 0 before serialization, will also cause the object + to be inserted. This enables an object to be duplicated in the + database. + -Class postgresql.util.Serialize + +Class org.postgresql.util.Serialize java.lang.Object | - +----postgresql.util.Serialize + +----org.postgresql.util.Serialize public class Serialize extends Object @@ -2036,7 +2421,7 @@ Constructors String type) throws SQLException This creates an instance that can be used to serialize -ordeserialize a Java object from a PostgreSQL table. +or deserialize a Java object from a PostgreSQL table. Methods @@ -2147,7 +2532,7 @@ serializing any objects. public static String toPostgreSQL(String name) throws SQLException - This converts a Java Class name to a postgresql table, by + This converts a Java Class name to a PostgreSQL table, by replacing . with _ Because of this, a Class name may not have _ in the name. @@ -2167,7 +2552,7 @@ forced by PostgreSQL). public static String toClassName(String name) throws SQLException - This converts a postgresql table to a Java Class name, by + This converts a PostgreSQL table to a Java Class name, by replacing _ with . Parameters: @@ -2178,19 +2563,19 @@ forced by PostgreSQL). Throws: SQLException on error - + Utility Classes -The postgresql.util package contains classes used by the internals of +The org.postgresql.util package contains classes used by the internals of the main driver, and the other extensions. -Class postgresql.util.PGmoney +Class org.postgresql.util.PGmoney java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject | - +----postgresql.util.PGmoney + +----org.postgresql.util.PGmoney public class PGmoney extends PGobject implements Serializable, Cloneable @@ -2249,7 +2634,7 @@ Methods public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class PGobject @@ -2257,16 +2642,17 @@ Methods public String getValue() Returns: - the PGpoint in the syntax expected by postgresql + the PGpoint in the syntax expected by PostgreSQL Overrides: getValue in class PGobject -Class postgresql.util.PGobject + +Class org.postgresql.util.PGobject java.lang.Object | - +----postgresql.util.PGobject + +----org.postgresql.util.PGobject public class PGobject extends Object implements Serializable, Cloneable @@ -2274,18 +2660,18 @@ Cloneable This class is used to describe data types that are unknown by JDBC Standard. - A call to postgresql.Connection permits a class that extends this + A call to org.postgresql.Connection permits a class that extends this class to be associated with a named type. This is how the -postgresql.geometric package operates. +org.postgresql.geometric package operates. ResultSet.getObject() will return this class for any type that is -not recognised on having it's own handler. Because of this, any -postgresql data type is supported. +not recognized on having it's own handler. Because of this, any +PostgreSQL data type is supported. Constructors public PGobject() - This is called by postgresql.Connection.getObject() to + This is called by org.postgresql.Connection.getObject() to create the object. Methods @@ -2302,7 +2688,7 @@ Methods public void setValue(String value) throws SQLException This method sets the value of this object. It must be -overidden. +overridden. Parameters: value - a string representation of the value of the @@ -2321,15 +2707,15 @@ final. public String getValue() - This must be overidden, to return the value of the object, -in the form required by postgresql. + This must be overridden, to return the value of the object, +in the form required by PostgreSQL. Returns: the value of this object public boolean equals(Object obj) - This must be overidden to allow comparisons of objects + This must be overridden to allow comparisons of objects Parameters: obj - Object to compare with @@ -2342,38 +2728,39 @@ in the form required by postgresql. public Object clone() - This must be overidden to allow the object to be cloned + This must be overridden to allow the object to be cloned Overrides: clone in class Object public String toString() - This is defined here, so user code need not overide it. + This is defined here, so user code need not override it. Returns: the value of this object, in the syntax expected by -postgresql +PostgreSQL Overrides: toString in class Object -Class postgresql.util.PGtokenizer + +Class org.postgresql.util.PGtokenizer java.lang.Object | - +----postgresql.util.PGtokenizer + +----org.postgresql.util.PGtokenizer public class PGtokenizer extends Object - This class is used to tokenize the text output of postgres. + This class is used to tokenize the text output of PostgreSQL. We could have used StringTokenizer to do this, however, we needed to handle nesting of '(' ')' '[' ']' '<' and '>' as these are used by the geometric data types. It's mainly used by the geometric classes, but is useful in parsing -any output from custom data types output from postgresql. +any output from custom data types output from PostgreSQL. See Also: PGbox, PGcircle, PGlseg, PGpath, PGpoint, PGpolygon @@ -2383,7 +2770,7 @@ Constructors public PGtokenizer(String string, char delim) - Create a tokeniser. + Create a tokenizer. Parameters: string - containing tokens @@ -2418,7 +2805,7 @@ delimiter. char delim) This returns a new tokenizer based on one of our tokens. The -geometric datatypes use this to process nested tokens (usually +geometric data types use this to process nested tokens (usually PGpoint). Parameters: @@ -2502,15 +2889,16 @@ PGpoint). Returns: String without the < or > -Class postgresql.util.Serialize + +Class org.postgresql.util.Serialize -This was documented earlier under Object Serialisation. +This was documented earlier under Object Serialization. -Class postgresql.util.UnixCrypt +Class org.postgresql.util.UnixCrypt java.lang.Object | - +----postgresql.util.UnixCrypt + +----org.postgresql.util.UnixCrypt public class UnixCrypt extends Object @@ -2529,7 +2917,7 @@ Methods public static final String crypt(String salt, String original) - Encrypt a password given the cleartext password and a + Encrypt a password given the clear-text password and a "salt". Parameters: @@ -2537,7 +2925,7 @@ Methods used to iterate the encryption engine in lots of different ways. If you are generating a new encryption then this - value should be randomised. + value should be randomized. original - The password to be encrypted. Returns: @@ -2547,7 +2935,7 @@ by public static final String crypt(String original) - Encrypt a password given the cleartext password. This method + Encrypt a password given the clear-text password. This method generates a random salt using the 'java.util.Random' class. Parameters: @@ -2568,83 +2956,98 @@ by two characters are assumed to be the salt. This string would be the same as one found in a Unix /etc/passwd file. enteredPassword - The password as entered by the user -(or otherwise aquired). +(or otherwise acquired). Returns: true if the password should be considered correct. + + -Using the driver in a multi Threaded or Servlet environment - -A problem with many JDBC drivers, is that only one thread can use a -Connection at any one time - otherwise a thread could send a query -while another one is receiving results, and this would be a bad thing -for the database engine. - -PostgreSQL 6.4, brings thread safety to the entire driver. Standard -JDBC was thread safe in 6.3.x, but the Fastpath - API wasn't. + + -So, if your application uses multiple threads (which most decent ones -would), then you don't have to worry about complex schemes to ensure -only one uses the database at any time. + + Using the driver in a multi-threaded or a servlet environment -If a thread attempts to use the connection while another is using it, -it will wait until the other thread has finished it's current -operation. + + A problem with many JDBC drivers is that only + one thread can use a Connection at any one + time -- otherwise a thread could send a query while another one is + receiving results, and this would be a bad thing for the database + engine. + -If it's a standard SQL statement, then the operation is sending the -statement, and retrieving any ResultSet (in full). + + PostgreSQL 6.4 brought thread safety to + the entire driver. (Standard JDBC was thread + safe in 6.3, but the Fastpath API was not.) + Consequently, if your application uses multiple threads then you do + not have to worry about complex algorithms to ensure that only one + uses the database at any time. + -If it's a Fastpath call (ie: reading a block from a LargeObject), then -it's the time to send, and retrieve that block. + + If a thread attempts to use the connection while another one is + using it, it will wait until the other thread has finished its + current operation. If it is a regular SQL + statement, then the operation consists of sending the statement and + retrieving any ResultSet (in full). If it + is a Fastpath call (e.g., reading a block + from a LargeObject) then it is the time to + send and retrieve that block. + -This is fine for applications & applets, but can cause a performance -problem with servlets. + + This is fine for applications and applets but can cause a + performance problem with servlets. With servlets you can have a + heavy load on the connection. If you have several threads + performing queries then each but one will pause, which may not be what + you are after. + -With servlets, you can have a heavy load on the connection. If you -have several threads performing queries, then each one will pause, -which may not be what you are after. + + To solve this, you would be advised to create a pool of + connections. When ever a thread needs to use the database, it asks + a manager class for a Connection. The + manager hands a free connection to the thread and marks it as + busy. If a free connection is not available, it opens one. Once + the thread has finished with it, it returns it to the manager who + can then either close it or add it to the pool. The manager would + also check that the connection is still alive and remove it from + the pool if it is dead. + -To solve this, you would be advised to create a pool of Connections. + + So, with servlets, it is up to you to use either a single + connection, or a pool. The plus side for a pool is that threads + will not be hit by the bottle neck caused by a single network + connection. The down side is that it increases the load on the + server, as a backend process is created for each + Connection. It is up to you and your + applications requirements. + + -When ever a thread needs to use the database, it asks a manager class -for a Connection. It hands a free connection to the thread, and marks -it as busy. If a free connection is not available, it opens one. -Once the thread has finished with it, it returns it to the manager, -who can then either close it, or add it to the pool. The manager would -also check that the connection is still alive, and remove it from the -pool if it's dead. + + Further Reading -So, with servlets, it's up to you to use either a single connection, -or a pool. The plus side for a pool is that threads will not be hit by -the bottle neck caused by a single network connection. The down side, -is that it increases the load on the server, as a backend is created -for each Connection. + + If you have not yet read it, I'd advise you read the + JDBC API Documentation + (supplied with Sun's JDK), and the + JDBC Specification. Both are available from + http://java.sun.com/products/jdbc/index.html. + -It's up to you, and your applications requirements. - - - - - -Further Reading - - -If you have not yet read it, I'd advise you read the JDBC - API -Documentation (supplied with Sun's JDK), - and the JDBC Specification. -Both are available on -JavaSoft's web site. - - - -My own web site - contains updated information not included in this -document, and also includes precompiled drivers for versions 6.4 and earlier. - - + + http://jdbc.postgresql.org + contains updated information not included in this document, and + also includes precompiled drivers. + + + @@ -23,6 +23,10 @@ (define %refentry-xref-manvolnum% #f) (define %section-autolabel% #t) +(define %callout-graphics% #f) + +(define %content-title-end-punct% + '(#\. #\! #\? #\:)) (element lineannotation ($italic-seq$)) (element structfield ($mono-seq$)) @@ -41,6 +45,8 @@ (define (toc-depth nd) (cond ((string=? (gi nd) (normalize "book")) 3) ((string=? (gi nd) (normalize "set")) 2) + ((string=? (gi nd) (normalize "part")) 2) + ((string=? (gi nd) (normalize "chapter")) 2) (else 1))) ;; Put date of creation into header -- GitLab