+ linkend="jdbc-query-example"> 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 <span class="marked">Statement</span> Interface
+
Using the <span class="marked"><classname>Statement</classname></span> 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.
-
Using the <span class="marked">ResultSet</span> Interface
+
Using the <span class="marked"><classname>ResultSet</classname></span> 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();
-
-
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
- 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.
-
+ 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+ t
he 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
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</div>
<div class="diff rem">- <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</div>
<div class="diff add">+ <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</title</span>></div>
<div class="diff ctx"> </div>
<div class="diff rem">- Throws: SQLException</div>
<div class="diff rem">- by LargeObject when initialising for first time</div>
<div class="diff add">+ <itemizedlist></div>
<div class="diff add">+ <listitem></div>
<div class="diff add">+<synopsis></div>
<div class="diff add">+public Fastpath getFastpathAPI() throws SQLException</div>
<div class="diff add">+</synopsis></div>
<div class="diff add">+ <para></div>
<div class="diff add">+ This returns the Fastpath <acronym>API</acronym> for the</div>
<div class="diff add">+ current connection. It is primarily used by the Large Object</div>
<div class="diff add">+ <acronym>API</acronym>.</div>
<div class="diff add">+ </para></div>
<div class="diff ctx"> </div>
<div class="diff rem">- public void addDataType(String type,</div>
<div class="diff rem">- String name)</div>
<div class="diff add">+ <para></div>
<div class="diff add">+ The best way to use this is as follows:</div>
<div class="diff add">+<programlisting></div>
<div class="diff add">+import org.postgresql.fastpath.*;</div>
<div class="diff add">+...</div>
<div class="diff add">+Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI();</div>
<div class="diff add">+</programlisting></div>
<div class="diff add">+ where myconn is an open Connection to <productname>PostgreSQL</productname>.</div>
<div class="diff add">+ </para></div>
<div class="diff ctx"> </div>
<div class="diff rem">- This allows client code to add a handler for one of </div>
<div class="diff rem">-postgresql's more unique data types. Normally, a data type not known </div>
<div class="diff rem">-by the driver is returned by ResultSet.getObject() as a PGobject </div>
<div class="diff rem">-instance.</div>
<div class="diff add">+ <formalpara></div>
<div class="diff add">+ <title>Returns:
+ Fastpath object allowing access to functions on the
+
+
+
+
+
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
+
- 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:
+
+
- 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:
+
+
+
+
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
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
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
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
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
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
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
public PGline()
- reuired by the driver
+ required by the driver
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
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
public PGlseg()
- reuired by the driver
+ required by the driver
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
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
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
public String getValue()
This returns the polygon in the syntax expected by
-postgresql
Overrides:
getValue in class PGobject
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
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
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
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
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
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
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
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
+
-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:
+
+
+
+
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
+
+
+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);
----------+---------
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
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
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.
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:
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
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
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
This class is used to describe data types that are unknown by
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
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
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
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
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
public PGtokenizer(String string,
char delim)
- Create a tokeniser.
+ Create a tokenizer.
Parameters:
string - containing tokens
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:
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
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:
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:
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:
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
+
+
-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
+ (supplied with Sun's
JDK), and the
+
JDBC Specification. Both are available from
+
+ url="http://java.sun.com/products/jdbc/index.html">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-Documentation (supplied with Sun's
JDK),
- and the
JDBC Specification.
-Both are available on
-
-
- contains updated information not included in this
-document, and also includes precompiled drivers for versions 6.4 and earlier.
-
-
+
+ url="http://jdbc.postgresql.org">http://jdbc.postgresql.org
+ contains updated information not included in this document, and
+ also includes precompiled drivers.
+
+
+
(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$))
(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
projects / postgresql.git / commitdiff