jdbc.sgml

关系型数据库 Postgresql 6.5.2

<para>
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 <acronym>JDBC</acronym> Specification, which states that any
InputStream returned is closed when ResultSet.next() or ResultSet.close() is called.
</para>
</sect1>

<sect1>
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>

<para>
<application>Postgres</application> 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.
</para>
<para>
Now, as these are facilities unique to us, we support them from Java, with
a set of extension <acronym>API</acronym>'s. Some features within 
the core of the standard driver
actually use these extensions to implement Large Objects, etc.

<!--
************************************************************
Nothing marked up from here on. It looks like it will be tricky:
what do we want to do with the class inheritance diagrams?
- thomas 1998-10-23
************************************************************
-->

<programlisting>
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,user,pass);

    // later on
    Fastpath fp = ((postgresql.Connection)db).getFastpathAPI();

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 <acronym>API</acronym> for the current connection.

          NOTE: This is not part of <acronym>JDBC</acronym>, but allows access to 
functions on the postgresql backend itself.

          It is primarily used by the LargeObject <acronym>API</acronym>

          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 <acronym>API</acronym> for the current connection.

          NOTE: This is not part of <acronym>JDBC</acronym>, 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.

        Returns:
                LargeObject object that implements the <acronym>API</acronym>

        Throws: SQLException
                by LargeObject when initialising for first time

 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.

          NOTE: This is not part of <acronym>JDBC</acronym>, but an extension.

          The best way to use this is as follows:

 ...
 ((postgresql.Connection)myconn).addDataType("mytype","my.class.name"-
);
 ...

          where myconn is an open Connection to postgresql.

          The handling class must extend postgresql.util.PGobject

        See Also:
                PGobject

Fastpath

Fastpath is an <acronym>API</acronym> 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 <acronym>API</acronym> 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 <acronym>JDBC</acronym>'s.

Once you have a Fastpath instance, you can use the fastpath() methods 
to execute a backend function.

Class postgresql.fastpath.Fastpath

java.lang.Object
   |
   +----postgresql.fastpath.Fastpath

   public class 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.

   It is based around the file src/interfaces/libpq/fe-exec.c

   See Also:
          FastpathFastpathArg, LargeObject

Methods

 public Object fastpath(int fnid,
                        boolean resulttype,
                        FastpathArg args[]) throws SQLException

          Send a function call to the PostgreSQL backend
          
        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
         
        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

        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

        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

        Parameters:
                name - Function name
                args - Function arguments

        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

        Parameters:
                name - Function name
                args - Function arguments

        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 
startup, 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

        Throws: SQLException
                if a database-access error occurs.
          
        See Also:
                LargeObjectManager

 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.

        Parameters:
                name - Function name to lookup

        Returns:
                Function ID for fastpath call

        Throws: SQLException
                is function is unknown.

Class postgresql.fastpath.FastpathArg

java.lang.Object
   |
   +----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

Constructors

 public FastpathArg(int value)
 
          Constructs an argument that consists of an integer value

        Parameters:
                value - int value to set

 public FastpathArg(byte bytes[])
          
          Constructs an argument that consists of an array of bytes

        Parameters:
                bytes - array to store

 public FastpathArg(byte buf[],
                    int off,
                    int len)

           Constructs an argument that consists of part of a byte 
array

        Parameters:
                buf - source array
                off - offset within array
                len - length of data to include

 public FastpathArg(String s)
          
          Constructs an argument that consists of a String.
      
        Parameters:
                s - String to store

Geometric Data Types

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.

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.

Class postgresql.geometric.PGbox

java.lang.Object
   |
   +----postgresql.util.PGobject
           |
           +----postgresql.geometric.PGbox

   public class PGbox extends PGobject implements Serializable, 
Cloneable

   This represents the box datatype within postgresql.

Variables

 public PGpoint point[]

          These are the two corner points of the box.

Constructors

 public PGbox(double x1,
              double y1,
              double x2,
              double y2)

        Parameters:
                x1 - first x coordinate
                y1 - first y coordinate
                x2 - second x coordinate
                y2 - second y coordinate

 public PGbox(PGpoint p1,
              PGpoint p2)

        Parameters:
                p1 - first point
                p2 - second point

 public PGbox(String s) throws SQLException
                            
        Parameters:
                s - Box definition in PostgreSQL syntax

        Throws: SQLException
                if definition is invalid
                
 public PGbox()

          Required constructor
              
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.
                            
        Parameters:
                value - a string representation of the value of the 
object
        Throws: SQLException
                thrown if value is invalid for this type

        Overrides:
                setValue in class PGobject

 public boolean equals(Object obj)

        Parameters:
                obj - Object to compare with
                
        Returns:
                true if the two boxes are identical
          
        Overrides:
                equals in class PGobject

 public Object clone()
        
          This must be overidden to allow the object to be cloned

        Overrides:
                clone in class PGobject
   
 public String getValue()
        
        Returns:
                the PGbox in the syntax expected by postgresql

        Overrides:
                getValue in class PGobject

Class postgresql.geometric.PGcircle

java.lang.Object
   |