diff options
| -rw-r--r-- | GNUmakefile.in | 4 | ||||
| -rw-r--r-- | README | 8 | ||||
| -rw-r--r-- | aclocal.m4 | 3 | ||||
| -rw-r--r-- | config/java.m4 | 61 | ||||
| -rwxr-xr-x | configure | 150 | ||||
| -rw-r--r-- | configure.in | 19 | ||||
| -rw-r--r-- | doc/src/sgml/filelist.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/installation.sgml | 47 | ||||
| -rw-r--r-- | doc/src/sgml/jdbc.sgml | 3197 | ||||
| -rw-r--r-- | doc/src/sgml/postgres.sgml | 3 | ||||
| -rw-r--r-- | src/Makefile.global.in | 5 | ||||
| -rw-r--r-- | src/interfaces/Makefile | 8 | ||||
| -rw-r--r-- | src/makefiles/Makefile.cygwin | 4 |
13 files changed, 15 insertions, 3497 deletions
diff --git a/GNUmakefile.in b/GNUmakefile.in index bcc157bc2f..5f7e6558de 100644 --- a/GNUmakefile.in +++ b/GNUmakefile.in @@ -1,7 +1,7 @@ # # PostgreSQL top level makefile # -# $PostgreSQL: pgsql/GNUmakefile.in,v 1.36 2003/11/28 20:32:09 pgsql Exp $ +# $PostgreSQL: pgsql/GNUmakefile.in,v 1.37 2004/01/19 21:20:04 tgl Exp $ # subdir = @@ -72,7 +72,7 @@ $(distdir).tar: distdir opt_files := \ src/tools src/corba src/tutorial \ src/bin/pgtclsh \ - $(addprefix src/interfaces/, libpgtcl jdbc) \ + $(addprefix src/interfaces/, libpgtcl) \ $(addprefix src/pl/, plperl plpython tcl) docs_files := doc/postgres.tar.gz doc/src doc/TODO.detail @@ -8,11 +8,11 @@ PostgreSQL is an advanced object-relational database management system that supports an extended subset of the SQL standard, including transactions, foreign keys, subqueries, triggers, user-defined types and functions. This distribution also contains several language -bindings, including C, Perl, Python, and Tcl, as well as a JDBC -driver. +bindings, including C and Tcl. -The ODBC and C++ interfaces have been moved to the PostgreSQL Projects -Web Site at http://gborg.postgresql.org for separate maintenance. +The JDBC, ODBC, C++, and Python interfaces have been moved to the PostgreSQL +Projects Web Site at http://gborg.postgresql.org for separate maintenance. +A Perl DBI/DBD driver is available from CPAN. See the file INSTALL for instructions on how to build and install PostgreSQL. That file also lists supported operating systems and diff --git a/aclocal.m4 b/aclocal.m4 index 1fd7537db7..496f806f96 100644 --- a/aclocal.m4 +++ b/aclocal.m4 @@ -1,10 +1,9 @@ -dnl $PostgreSQL: pgsql/aclocal.m4,v 1.16 2003/11/29 19:51:16 pgsql Exp $ +dnl $PostgreSQL: pgsql/aclocal.m4,v 1.17 2004/01/19 21:20:04 tgl Exp $ m4_include([config/ac_func_accept_argtypes.m4]) m4_include([config/c-compiler.m4]) m4_include([config/c-library.m4]) m4_include([config/docbook.m4]) m4_include([config/general.m4]) -m4_include([config/java.m4]) m4_include([config/libtool.m4]) m4_include([config/perl.m4]) m4_include([config/programs.m4]) diff --git a/config/java.m4 b/config/java.m4 deleted file mode 100644 index 1bfcf31dfb..0000000000 --- a/config/java.m4 +++ /dev/null @@ -1,61 +0,0 @@ -# -# Autoconf macros for configuring the build of Java JDBC Tools -# -# $PostgreSQL: pgsql/config/java.m4,v 1.5 2003/11/29 19:51:17 pgsql Exp $ -# - - -# _PGAC_PROG_ANT_WORKS -# -------------------- -AC_DEFUN([_PGAC_PROG_ANT_WORKS], -[ - AC_CACHE_CHECK([whether $ANT works], [pgac_cv_prog_ant_works], - [ - cat > conftest.java << EOF -public class conftest { - int testmethod(int a, int b) { - return a + b; - } -} -EOF - - cat > conftest.xml << EOF -<project name="conftest" default="conftest"> - <target name="conftest"> - <javac srcdir="." includes="conftest.java"> - </javac> - </target> -</project> -EOF - - pgac_cmd='$ANT -buildfile conftest.xml 1>&2' - AC_TRY_EVAL(pgac_cmd) - pgac_save_status=$? - if test $? = 0 && test -f ./conftest.class ; then - pgac_cv_prog_ant_works=yes - else - echo "configure: failed java program was:" >&AS_MESSAGE_LOG_FD - cat conftest.java >&AS_MESSAGE_LOG_FD - echo "configure: failed build file was:" >&AS_MESSAGE_LOG_FD - cat conftest.xml >&AS_MESSAGE_LOG_FD - pgac_cv_prog_ant_works=no - fi - - rm -f conftest* core core.* *.core - ]) - - if test "$pgac_cv_prog_ant_works" != yes; then - AC_MSG_ERROR([ant does not work]) - fi -]) - - -# PGAC_PATH_ANT -# ------------- -# Look for the ANT tool and set the output variable 'ANT' to 'ant' -# if found, empty otherwise -AC_DEFUN([PGAC_PATH_ANT], -[ - AC_PATH_PROGS(ANT, [jakarta-ant ant ant.sh ant.bat]) - _PGAC_PROG_ANT_WORKS -]) @@ -864,7 +864,6 @@ Optional Packages: --with-tkconfig=DIR tkConfig.sh is in DIR --with-perl build Perl modules (PL/Perl) --with-python build Python modules (PL/Python) - --with-java build JDBC interface and Java tools --with-krb4 build with Kerberos 4 support --with-krb5 build with Kerberos 5 support --with-krb-srvnam=NAME name of the service principal in Kerberos [postgres] @@ -3167,153 +3166,6 @@ echo "${ECHO_T}$with_python" >&6 # -# Optionally build the Java/JDBC tools -# -echo "$as_me:$LINENO: checking whether to build Java/JDBC tools" >&5 -echo $ECHO_N "checking whether to build Java/JDBC tools... $ECHO_C" >&6 - - - -# Check whether --with-java or --without-java was given. -if test "${with_java+set}" = set; then - withval="$with_java" - - case $withval in - yes) - echo "$as_me:$LINENO: result: yes" >&5 -echo "${ECHO_T}yes" >&6 - - for ac_prog in jakarta-ant ant ant.sh ant.bat -do - # Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo "$as_me:$LINENO: checking for $ac_word" >&5 -echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6 -if test "${ac_cv_path_ANT+set}" = set; then - echo $ECHO_N "(cached) $ECHO_C" >&6 -else - case $ANT in - [\\/]* | ?:[\\/]*) - ac_cv_path_ANT="$ANT" # Let the user override the test with a path. - ;; - *) - as_save_IFS=$IFS; IFS=$PATH_SEPARATOR -for as_dir in $PATH -do - IFS=$as_save_IFS - test -z "$as_dir" && as_dir=. - for ac_exec_ext in '' $ac_executable_extensions; do - if $as_executable_p "$as_dir/$ac_word$ac_exec_ext"; then - ac_cv_path_ANT="$as_dir/$ac_word$ac_exec_ext" - echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 - break 2 - fi -done -done - - ;; -esac -fi -ANT=$ac_cv_path_ANT - -if test -n "$ANT"; then - echo "$as_me:$LINENO: result: $ANT" >&5 -echo "${ECHO_T}$ANT" >&6 -else - echo "$as_me:$LINENO: result: no" >&5 -echo "${ECHO_T}no" >&6 -fi - - test -n "$ANT" && break -done - - - echo "$as_me:$LINENO: checking whether $ANT works" >&5 -echo $ECHO_N "checking whether $ANT works... $ECHO_C" >&6 -if test "${pgac_cv_prog_ant_works+set}" = set; then - echo $ECHO_N "(cached) $ECHO_C" >&6 -else - - cat > conftest.java << EOF -public class conftest { - int testmethod(int a, int b) { - return a + b; - } -} -EOF - - cat > conftest.xml << EOF -<project name="conftest" default="conftest"> - <target name="conftest"> - <javac srcdir="." includes="conftest.java"> - </javac> - </target> -</project> -EOF - - pgac_cmd='$ANT -buildfile conftest.xml 1>&2' - { (eval echo "$as_me:$LINENO: \"$pgac_cmd\"") >&5 - (eval $pgac_cmd) 2>&5 - ac_status=$? - echo "$as_me:$LINENO: \$? = $ac_status" >&5 - (exit $ac_status); } - pgac_save_status=$? - if test $? = 0 && test -f ./conftest.class ; then - pgac_cv_prog_ant_works=yes - else - echo "configure: failed java program was:" >&5 - cat conftest.java >&5 - echo "configure: failed build file was:" >&5 - cat conftest.xml >&5 - pgac_cv_prog_ant_works=no - fi - - rm -f conftest* core core.* *.core - -fi -echo "$as_me:$LINENO: result: $pgac_cv_prog_ant_works" >&5 -echo "${ECHO_T}$pgac_cv_prog_ant_works" >&6 - - if test "$pgac_cv_prog_ant_works" != yes; then - { { echo "$as_me:$LINENO: error: ant does not work" >&5 -echo "$as_me: error: ant does not work" >&2;} - { (exit 1); exit 1; }; } - fi - - -if test -z "$ANT"; then - { { echo "$as_me:$LINENO: error: Ant is required to build Java components -If you have Ant already installed, see config.log for details on the failure." >&5 -echo "$as_me: error: Ant is required to build Java components -If you have Ant already installed, see config.log for details on the failure." >&2;} - { (exit 1); exit 1; }; } -fi -if "$ANT" -version | egrep -i 'ant version' | sed q | egrep -v ' 1\.[5-9]| [2-9]\.' >/dev/null ; then - { { echo "$as_me:$LINENO: error: Ant version >= 1.5 is required to build Java components" >&5 -echo "$as_me: error: Ant version >= 1.5 is required to build Java components" >&2;} - { (exit 1); exit 1; }; } -fi - ;; - no) - echo "$as_me:$LINENO: result: no" >&5 -echo "${ECHO_T}no" >&6 - ;; - *) - { { echo "$as_me:$LINENO: error: no argument expected for --with-java option" >&5 -echo "$as_me: error: no argument expected for --with-java option" >&2;} - { (exit 1); exit 1; }; } - ;; - esac - -else - with_java=no -echo "$as_me:$LINENO: result: no" >&5 -echo "${ECHO_T}no" >&6 -fi; - - - -# # Kerberos 4 # echo "$as_me:$LINENO: checking whether to build with Kerberos 4 support" >&5 @@ -18252,8 +18104,6 @@ s,@with_tcl@,$with_tcl,;t t s,@with_tk@,$with_tk,;t t s,@with_perl@,$with_perl,;t t s,@with_python@,$with_python,;t t -s,@ANT@,$ANT,;t t -s,@with_java@,$with_java,;t t s,@with_krb4@,$with_krb4,;t t s,@with_krb5@,$with_krb5,;t t s,@krb_srvtab@,$krb_srvtab,;t t diff --git a/configure.in b/configure.in index 1ed6c78d22..29dd95cac7 100644 --- a/configure.in +++ b/configure.in @@ -1,5 +1,5 @@ dnl Process this file with autoconf to produce a configure script. -dnl $PostgreSQL: pgsql/configure.in,v 1.310 2004/01/09 04:58:09 momjian Exp $ +dnl $PostgreSQL: pgsql/configure.in,v 1.311 2004/01/19 21:20:05 tgl Exp $ dnl dnl Developers, please strive to achieve this order: dnl @@ -410,23 +410,6 @@ AC_MSG_RESULT([$with_python]) AC_SUBST(with_python) # -# Optionally build the Java/JDBC tools -# -AC_MSG_CHECKING([whether to build Java/JDBC tools]) -PGAC_ARG_BOOL(with, java, no, [ --with-java build JDBC interface and Java tools], -[AC_MSG_RESULT(yes) -PGAC_PATH_ANT -if test -z "$ANT"; then - AC_MSG_ERROR([Ant is required to build Java components -If you have Ant already installed, see config.log for details on the failure.]) -fi -if "$ANT" -version | egrep -i 'ant version' | sed q | egrep -v ' 1\.[[5-9]]| [[2-9]]\.' >/dev/null ; then - AC_MSG_ERROR([Ant version >= 1.5 is required to build Java components]) -fi], -[AC_MSG_RESULT(no)]) -AC_SUBST(with_java) - -# # Kerberos 4 # AC_MSG_CHECKING([whether to build with Kerberos 4 support]) diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index bbfd55d9b4..3fd9ce9045 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.34 2003/11/29 19:51:37 pgsql Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.35 2004/01/19 21:20:06 tgl Exp $ --> <!entity history SYSTEM "history.sgml"> <!entity info SYSTEM "info.sgml"> @@ -49,7 +49,6 @@ <!entity extend SYSTEM "extend.sgml"> <!entity func-ref SYSTEM "func-ref.sgml"> <!entity infoschema SYSTEM "information_schema.sgml"> -<!entity jdbc SYSTEM "jdbc.sgml"> <!entity libpgeasy SYSTEM "libpgeasy.sgml"> <!entity libpq SYSTEM "libpq.sgml"> <!entity libpgtcl SYSTEM "libpgtcl.sgml"> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 1fc151abeb..368d82e3cb 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,4 +1,4 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.192 2004/01/11 05:46:58 neilc Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.193 2004/01/19 21:20:06 tgl Exp $ --> <chapter id="installation"> <title><![%standalone-include[<productname>PostgreSQL</>]]> @@ -214,41 +214,6 @@ su - postgres <listitem> <para> - To build the JDBC driver, you need - <application>Ant</application> 1.5 or higher and a - <acronym>JDK</acronym>. <application>Ant</application> is a - special tool for building Java-based packages. It can be - downloaded from the <ulink - url="http://jakarta.apache.org/ant/index.html"><application>Ant</application> - web site</ulink>. - </para> - - <para> - If you have several Java compilers installed, it depends on the - Ant configuration which one gets used. Precompiled - <application>Ant</application> distributions are typically set - up to read a file <filename>.antrc</filename> in the current - user's home directory for configuration. For example, to use a - different <acronym>JDK</acronym> than the default, this may - work: -<programlisting> -JAVA_HOME=/usr/local/sun-jdk1.3 -JAVACMD=$JAVA_HOME/bin/java -</programlisting> - </para> - - <note> - <para> - Do not try to build the driver by calling - <command>ant</command> or even <command>javac</command> - directly. This will not work. Run <command>gmake</command> - normally as described below. - </para> - </note> - </listitem> - - <listitem> - <para> To enable Native Language Support (<acronym>NLS</acronym>), that is, the ability to display a program's messages in a language other than English, you need an implementation of the @@ -802,16 +767,6 @@ JAVACMD=$JAVA_HOME/bin/java </varlistentry> <varlistentry> - <term><option>--with-java</option></term> - <listitem> - <para> - Build the <acronym>JDBC</acronym> driver and associated Java - packages. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><option>--with-krb4</option></term> <term><option>--with-krb5</option></term> <listitem> diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml deleted file mode 100644 index e2f0f39347..0000000000 --- a/doc/src/sgml/jdbc.sgml +++ /dev/null @@ -1,3197 +0,0 @@ -<!-- -$PostgreSQL: pgsql/doc/src/sgml/jdbc.sgml,v 1.52 2003/12/13 23:59:06 neilc Exp $ ---> - - <chapter id="jdbc"> - <title><acronym>JDBC</acronym> Interface</title> - - <indexterm zone="jdbc"> - <primary>JDBC</primary> - </indexterm> - - <indexterm zone="jdbc"> - <primary>Java</primary> - </indexterm> - - <para> - <acronym>JDBC</acronym> is a core <acronym>API</acronym> of Java 1.1 and later. - It provides a standard set of - interfaces to <acronym>SQL</acronym>-compliant databases. - </para> - - <para> - <productname>PostgreSQL</> provides a <firstterm>type - 4</firstterm> <acronym>JDBC</acronym> 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. - </para> - - <para> - This chapter is not intended as a complete guide to - <acronym>JDBC</acronym> programming, but should help to get you - started. For more information refer to the standard - <acronym>JDBC</acronym> <acronym>API</acronym> documentation. - Also, take a look at the examples included with the source. - </para> - - <sect1 id="jdbc-setup"> - <title>Setting up the <acronym>JDBC</acronym> Driver</title> - - <para> - This section describes the steps you need to take before you can - write or run programs that use the <acronym>JDBC</> interface. - </para> - - <sect2 id="jdbc-build"> - <title>Getting the Driver</title> - - <para> - Precompiled versions of the driver can be downloaded from - the <ulink - url="http://jdbc.postgresql.org"><productname>PostgreSQL</productname> - <acronym>JDBC</acronym> web site</ulink>. - </para> - - <para> - Alternatively you can build the driver from source, but you should - only need to do this if you are making changes to the source code. - For details, refer to the <productname>PostgreSQL</> - <link linkend="installation">installation instructions</link>. - After installation, the driver should be found in - <filename><replaceable>PREFIX</>/share/java/postgresql.jar</filename>. - The resulting driver will be built for the version of Java you are - running. If you build with a 1.1 <acronym>JDK</> you will build a - version that supports the <acronym>JDBC</> 1 specification, if you build - with a 1.2 or 1.3 <acronym>JDK</> you will build a version that supports - the <acronym>JDBC</> 2 specification, and finally if you build with a - 1.4 <acronym>JDK</acronym> you will build a version that supports the - <acronym>JDBC</> 3 specification. - </para> - </sect2> - - <sect2 id="jdbc-classpath"> - <title>Setting up the Class Path</title> - - <indexterm zone="jdbc-classpath"> - <primary>class path</primary> - </indexterm> - - <indexterm zone="jdbc-classpath"> - <primary>CLASSPATH</primary> - </indexterm> - - <para> - To use the driver, the JAR archive (named - <filename>postgresql.jar</filename> if you built from source, otherwise - it will likely be named <filename>pg&majorversion;jdbc1.jar</filename>, - <filename>pg&majorversion;jdbc2.jar</filename>, or - <filename>pg&majorversion;jdbc3.jar</filename> for the <acronym>JDBC</> 1, - <acronym>JDBC</> 2, and <acronym>JDBC</> 3 versions respectively) - needs to be included in the class path, either by putting it in the - <envar>CLASSPATH</envar> environment variable, or by using flags on the - <command>java</command> command line. - </para> - - <para> - For instance, assume we have an application that uses the - <acronym>JDBC</acronym> driver to access a database, and that - application is installed as - <filename>/usr/local/lib/myapp.jar</filename>. The - <productname>PostgreSQL</> <acronym>JDBC</> driver installed as - <filename>/usr/local/pgsql/share/java/postgresql.jar</>. To run - the application, we would use: -<programlisting> -export CLASSPATH=/usr/local/lib/myapp.jar:/usr/local/pgsql/share/java/postgresql.jar:. -java MyApp -</programlisting> - </para> - - <para> - Loading the driver from within the application is covered in - <xref linkend="jdbc-use">. - </para> - </sect2> - - <sect2 id="jdbc-prepare"> - <title>Preparing the Database Server for <acronym>JDBC</acronym></title> - - <para> - Because Java only uses TCP/IP connections, the - <productname>PostgreSQL</productname> server must be configured to - accept TCP/IP connections. This can be done by setting - <literal>tcpip_socket = true</literal> in the - <filename>postgresql.conf</filename> file or by supplying the - <option>-i</option> option flag when starting - <command>postmaster</command>. - </para> - - <para> - Also, the client authentication setup in the - <filename>pg_hba.conf</filename> file may need to be configured. - Refer to <xref linkend="client-authentication"> for details. The - <acronym>JDBC</acronym> driver supports the <literal>trust</>, - <literal>ident</>, <literal>password</>, <literal>md5</>, and - <literal>crypt</> authentication methods. - </para> - </sect2> - </sect1> - - <sect1 id="jdbc-use"> - <title>Initializing the Driver</title> - - <para> - This section describes how to load and initialize the <acronym>JDBC</> - driver in your programs. - </para> - - <sect2 id="jdbc-import"> - <title>Importing <acronym>JDBC</acronym></title> - - <para> - Any source that uses <acronym>JDBC</acronym> needs to import the - <literal>java.sql</literal> package, using: - -<programlisting> -import java.sql.*; -</programlisting> - </para> - - <note> - <para> - Do not import the <literal>org.postgresql</literal> package. If - you do, your source will not compile, as - <command>javac</command> will get confused. - </para> - </note> - </sect2> - - <sect2 id="jdbc-load"> - <title>Loading the Driver</title> - - <para> - 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. - </para> - - <para> - In the first method, your code implicitly loads the driver using the - <function>Class.forName()</function> method. - For <productname>PostgreSQL</>, you would use: - -<programlisting> -Class.forName("org.postgresql.Driver"); -</programlisting> - - This will load the driver, and while loading, the driver will automatically - register itself with <acronym>JDBC</acronym>. - </para> - - <note> - <para> - The <function>forName()</function> method can throw a - <classname>ClassNotFoundException</classname> if the driver is - not available. - </para> - </note> - - <para> - This is the most common method to use, but restricts your code to - use just <productname>PostgreSQL</productname>. If your code may - access another database system in the future, and you do not use - any <productname>PostgreSQL</productname>-specific extensions, then - the second method is advisable. - </para> - - <para> - The second method passes the driver as a parameter to the - <acronym>JVM</acronym> as it starts, using the <option>-D</option> - argument. Example: -<programlisting> -java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer -</programlisting> - In this example, the <acronym>JVM</acronym> will attempt to load - the driver as part of its initialization. Once done, the - <classname>ImageViewer</classname> is started. - </para> - - <para> - 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 - <acronym>URL</acronym>, which is covered next. - </para> - - <para> - One last thing: When your code then tries to open a - <classname>Connection</classname>, and you get a <errorname>No - driver available</errorname> <classname>SQLException</classname> - being thrown, this is probably caused by the driver not being in - the class path, or the value in the parameter not being correct. - </para> - </sect2> - - <sect2 id="jdbc-connect"> - <title>Connecting to the Database</title> - - <para> - With <acronym>JDBC</acronym>, a database is represented by a - <acronym>URL</acronym> (Uniform Resource Locator). With - <productname>PostgreSQL</productname>, this takes one of the - following forms: - - <itemizedlist> - <listitem> -<synopsis> -jdbc:postgresql:<replaceable class="parameter">database</replaceable> -</synopsis> - </listitem> - - <listitem> -<synopsis> -jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable> -</synopsis> - </listitem> - - <listitem> -<synopsis> -jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable> -</synopsis> - </listitem> - </itemizedlist> - - The parameters have the following meanings: - - <variablelist> - <varlistentry> - <term> - <replaceable class="parameter">host</replaceable> - </term> - <listitem> - <para> - The host name of the server. Defaults to <literal>localhost</literal>. To specify an IPv6 address your must enclose the <replaceable class="parameter">host</replaceable> parameter with square brackets, for example: -<programlisting> -jdbc:postgresql://[::1]:5740/accounting -</programlisting> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <replaceable class="parameter">port</replaceable> - </term> - <listitem> - <para> - The port number the server is listening on. Defaults to the - <productname>PostgreSQL</productname> standard port number (5432). - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <replaceable class="parameter">database</replaceable> - </term> - <listitem> - <para> - The database name. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - - <para> - To connect, you need to get a <classname>Connection</classname> instance from - <acronym>JDBC</acronym>. To do this, - you use the <function>DriverManager.getConnection()</function> method: - -<programlisting> -Connection db = DriverManager.getConnection(url, username, password); -</programlisting> - </para> - </sect2> - - <sect2 id="jdbc-disconnect"> - <title>Closing the Connection</title> - - <para> - To close the database connection, simply call the - <function>close()</function> method to the <classname>Connection</classname>: -<programlisting> -db.close(); -</programlisting> - </para> - </sect2> - </sect1> - - - <sect1 id="jdbc-query"> - <title>Issuing a Query and Processing the Result</title> - - <indexterm zone="jdbc-query"> - <primary>Statement</primary> - </indexterm> - - <indexterm zone="jdbc-query"> - <primary>PreparedStatement</primary> - </indexterm> - - <indexterm zone="jdbc-query"> - <primary>ResultSet</primary> - </indexterm> - - <para> - Any time you want to issue <acronym>SQL</acronym> statements to - the database, you require a <classname>Statement</classname> or - <classname>PreparedStatement</classname> instance. Once you have - a <classname>Statement</classname> or - <classname>PreparedStatement</classname>, you can use issue a - query. This will return a <classname>ResultSet</classname> - instance, which contains the entire result (see <xref linkend="jdbc-query-with-cursor"> - here for how to alter this behaviour). - <xref linkend="jdbc-query-example"> illustrates this process. - </para> - - <example id="jdbc-query-example"> - <title>Processing a Simple Query in <acronym>JDBC</acronym></title> - - <para> - This example will issue a simple query and print out the first - column of each row using a <classname>Statement</classname>. -<programlisting> -Statement st = db.createStatement(); -ResultSet rs = st.executeQuery("SELECT * FROM mytable WHERE columnfoo = 500"); -while (rs.next()) { - System.out.print("Column 1 returned "); - System.out.println(rs.getString(1)); -} -rs.close(); -st.close(); -</programlisting> - </para> - - <para> - This example issues the same query as before but uses - a <classname>PreparedStatement</classname> - and a bind value in the query. -<programlisting> -int foovalue = 500; -PreparedStatement st = db.prepareStatement("SELECT * FROM mytable WHERE columnfoo = ?"); -st.setInt(1, foovalue); -ResultSet rs = st.executeQuery(); -while (rs.next()) { - System.out.print("Column 1 returned "); - System.out.println(rs.getString(1)); -} -rs.close(); -st.close(); -</programlisting> - </para> - </example> - - <sect2 id="jdbc-query-with-cursor"> - <title>Getting results based on a cursor</title> - - <para>By default the driver collects all the results for the - query at once. This can be inconvenient for large data sets so - the JDBC driver provides a means of basing - a <classname>ResultSet</classname> on a database cursor and - only fetching a small number of rows.</para> - - <para>A small number of rows are cached on the - client side of the connection and when exhausted the next - block of rows is retrieved by repositioning the cursor. - </para> - - <example> - <title>Setting fetch size to turn cursors on and off.</title> - - <para>Changing code to cursor mode is as simple as setting the - fetch size of the <classname>Statement</classname> to the - appropriate size. Setting the fetch size back to 0 will cause - all rows to be cached (the default behaviour). - -<programlisting> -Statement st = db.createStatement(); -// Turn use of the cursor on. -st.setFetchSize(50); -ResultSet rs = st.executeQuery("SELECT * FROM mytable"); -while (rs.next()) { - System.out.print("a row was returned."); -} -rs.close(); -// Turn the cursor off. -st.setFetchSize(0); -ResultSet rs = st.executeQuery("SELECT * FROM mytable"); -while (rs.next()) { - System.out.print("many rows were returned."); -} -rs.close(); -// Close the statement. -st.close(); -</programlisting> - </para> - </example> - </sect2> - - <sect2> - <title>Using the <classname>Statement</classname> or <classname>PreparedStatement</classname> Interface</title> - - <para> - The following must be considered when using the - <classname>Statement</classname> or - <classname>PreparedStatement</classname> interface: - - <itemizedlist> - <listitem> - <para> - You can use a single <classname>Statement</classname> 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 - <classname>ResultSet</classname> can exist per - <classname>Statement</classname> or - <classname>PreparedStatement</classname> at a given time. - </para> - </listitem> - - <listitem> - <para> - If you need to perform a query while processing a - <classname>ResultSet</classname>, you can simply create and - use another <classname>Statement</classname>. - </para> - </listitem> - - <listitem> - <para> - If you are using threads, and several are using the database, - you must use a separate <classname>Statement</classname> for - each thread. Refer to <xref linkend="jdbc-thread"> if you are - thinking of using threads, as it covers some important points. - </para> - </listitem> - - <listitem> - <para> - When you are done using the <classname>Statement</classname> - or <classname>PreparedStatement</classname> - you should close it. - </para> - </listitem> - </itemizedlist> - </para> - </sect2> - - <sect2> - <title>Using the <classname>ResultSet</classname> Interface</title> - - <para> - The following must be considered when using the - <classname>ResultSet</classname> interface: - - <itemizedlist> - <listitem> - <para> - Before reading any values, you must call - <function>next()</function>. This returns true if there is a - result, but more importantly, it prepares the row for - processing. - </para> - </listitem> - - <listitem> - <para> - Under the <acronym>JDBC</acronym> specification, you should - access a field only once. It is safest to stick to this rule, - although at the current time, the - <productname>PostgreSQL</productname> driver will allow you to - access a field as many times as you want. - </para> - </listitem> - - <listitem> - <para> - You must close a <classname>ResultSet</classname> by calling - <function>close()</function> once you have finished using it. - </para> - </listitem> - - <listitem> - <para> - Once you make another query with the - <classname>Statement</classname> used to create a - <classname>ResultSet</classname>, the currently open - <classname>ResultSet</classname> instance is closed - automatically. - </para> - </listitem> - - </itemizedlist> - </para> - </sect2> - </sect1> - - <sect1 id="jdbc-update"> - <title>Performing Updates</title> - - <para> - To change data (perform an <command>INSERT</command>, - <command>UPDATE</command>, or <command>DELETE</command>) you use - the <function>executeUpdate()</function> method. This method is - similar to the method <function>executeQuery()</function> used to - issue a <command>SELECT</command> statement, but it doesn't return - a <classname>ResultSet</classname>; instead it returns the number - of rows affected by the <command>INSERT</command>, - <command>UPDATE</command>, or <command>DELETE</command> statement. - <xref linkend="jdbc-delete-example"> illustrates the usage. - </para> - - <example id="jdbc-delete-example"> - <title>Deleting Rows in <acronym>JDBC</acronym></title> - <para> - This example will issue a simple <command>DELETE</command> - statement and print out the number of rows deleted. -<programlisting> -int foovalue = 500; -PreparedStatement st = db.prepareStatement("DELETE FROM mytable WHERE columnfoo = ?"); -st.setInt(1, foovalue); -int rowsDeleted = st.executeUpdate(); -System.out.println(rowsDeleted + " rows deleted"); -st.close(); -</programlisting> - </para> - </example> - </sect1> - - - <sect1 id="jdbc-callproc"> - <title>Calling Stored Functions</title> - - <para><productname>PostgreSQL's</productname> JDBC driver fully - supports calling <productname>PostgreSQL</productname> stored - functions.</para> - - <example id="jdbc-call-function"> - <title>Calling a built in stored function</title> - - <para>This example shows how to call - a <productname>PostgreSQL</productname> built in - function, <command>upper</command>, which simply converts the - supplied string argument to uppercase. - -<programlisting> -// Turn transactions off. -con.setAutoCommit(false); -// Procedure call. -CallableStatement upperProc = con.prepareCall("{ ? = call upper( ? ) }"); -upperProc.registerOutParameter(1, Types.VARCHAR); -upperProc.setString(2, "lowercase to uppercase"); -upperProc.execute(); -String upperCased = upperProc.getString(1); -upperProc.close(); -</programlisting> - </para> - </example> - - <sect2> - <title>Using the <classname>CallableStatement</classname> Interface</title> - - <para> - All the considerations that apply - for <classname>Statement</classname> - and <classname>PreparedStatement</classname> apply - for <classname>CallableStatement</classname> but in addition - you must also consider one extra restriction: - </para> - - <itemizedlist> - <listitem> - <para>You can only call a stored function from within a - transaction.</para> - </listitem> - </itemizedlist> - - </sect2> - - <sect2> - <title>Obtaining <classname>ResultSet</classname> from a stored function</title> - - <para><productname>PostgreSQL's</productname> stored function - can return results by means of a <type>refcursor</type> - value. A <type>refcursor</type>.</para> - - <para>As an extension to JDBC, - the <productname>PostgreSQL</productname> JDBC driver can - return <type>refcursor</type> values - as <classname>ResultSet</classname> values.</para> - - <example id="get-refcursor-from-function-call"> - <title>Getting <type>refcursor</type> values from a - function</title> - - <para>When calling a function that returns - a <type>refcursor</type> you must cast the return type - of <function>getObject</function> to - a <classname>ResultSet</classname></para> - -<programlisting> -// Turn transactions off. -con.setAutoCommit(false); -// Procedure call. -CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }"); -proc.registerOutParameter(1, Types.Other); -proc.setInt(2, -1); -proc.execute(); -ResultSet results = (ResultSet) proc.getObject(1); -while (results.next()) { - // do something with the results... -} -results.close(); -proc.close(); -</programlisting> - </example> - - <para>It is also possible to treat the <type>refcursor</type> - return value as a distinct type in itself. The JDBC driver - provides - the <classname>org.postgresql.PGRefCursorResultSet</classname> - class for this purpose.</para> - - <example> - <title>Treating <type>refcursor</type> as a distinct - type</title> - -<programlisting> -con.setAutoCommit(false); -CallableStatement proc = con.prepareCall("{ ? = call doquery ( ? ) }"); -proc.registerOutParameter(1, Types.Other); -proc.setInt(2, 0); -org.postgresql.PGRefCursorResultSet refcurs - = (PGRefCursorResultSet) con.getObject(1); -String cursorName = refcurs.getRefCursor(); -proc.close(); -</programlisting> - </example> - </sect2> - - </sect1> - - - <sect1 id="jdbc-ddl"> - <title>Creating and Modifying Database Objects</title> - - <para> - To create, modify or drop a database object like a table or view - you use the <function>execute()</function> method. This method is - similar to the method <function>executeQuery()</function>, but it - doesn't return a result. <xref linkend="jdbc-drop-table-example"> - illustrates the usage. - </para> - - <example id="jdbc-drop-table-example"> - <title>Dropping a Table in JDBC</title> - <para> - This example will drop a table. -<programlisting> -Statement st = db.createStatement(); -st.execute("DROP TABLE mytable"); -st.close(); -</programlisting> - </para> - </example> - </sect1> - - <sect1 id="jdbc-binary-data"> - <title>Storing Binary Data</title> - - <indexterm zone="jdbc-binary-data"> - <primary>bytea</primary> - <secondary sortas="JDBC">in JDBC</secondary> - </indexterm> - - <indexterm zone="jdbc-binary-data"> - <primary>large object</primary> - <secondary sortas="JDBC">in JDBC</secondary> - </indexterm> - - <para> - <productname>PostgreSQL</productname> provides two distinct ways to - store binary data. Binary data can be stored in a table using - the data type <type>bytea</type> or by using the Large Object - feature which stores the binary data in a separate table in a special - format and refers to that table by storing a value of type - <type>oid</type> in your table. - </para> - - <para> - In order to determine which method is appropriate you - need to understand the limitations of each method. The - <type>bytea</type> data type is not well suited for storing very - large amounts of binary data. While a column of type - <type>bytea</type> can hold up to 1 GB of binary data, it would - require a huge amount of memory to - process such a large value. The Large Object method for - storing binary data is better suited to storing very large values, - but it has its own limitations. Specifically deleting a row - that contains a Large Object reference does not delete the Large Object. - Deleting the Large Object is a separate operation that needs to - be performed. Large Objects also have some security - issues since anyone connected to the database can view - and/or modify any Large Object, even if they don't have - permissions to view/update the row containing the Large Object reference. - </para> - - <para> - Version 7.2 was the first release of the <acronym>JDBC</acronym> driver - that supports the <type>bytea</type> data type. The introduction of - this functionality in 7.2 has introduced a change in behavior - as compared to previous releases. Since 7.2, the methods - <function>getBytes()</function>, <function>setBytes()</function>, - <function>getBinaryStream()</function>, and - <function>setBinaryStream()</function> operate on - the <type>bytea</type> data type. In 7.1 and earlier, these methods operated - on the <type>oid</type> data type associated with Large Objects. - It is possible to revert the driver back to the old 7.1 behavior - by setting the property <literal>compatible</literal> on - the <classname>Connection</classname> object to the value - <literal>7.1</literal>. - </para> - - <para> - To use the <type>bytea</type> data type you should simply use - the <function>getBytes()</function>, <function>setBytes()</function>, - <function>getBinaryStream()</function>, or - <function>setBinaryStream()</function> methods. - </para> - - <para> - To use the Large Object functionality you can use either the - <classname>LargeObject</classname> class provided by the - <productname>PostgreSQL</> <acronym>JDBC</acronym> driver, or by - using the <function>getBLOB()</function> and - <function>setBLOB()</function> methods. - </para> - - <important> - <para> - You must access Large Objects within an <acronym>SQL</acronym> - transaction block. You can start a transaction block by calling - <function>setAutoCommit(false)</function>. - </para> - </important> - - <note> - <para> - In a future release of the - <acronym>JDBC</acronym> driver, the <function>getBLOB()</function> - and <function>setBLOB()</function> methods may no longer - interact with Large Objects and will instead work on the data type - <type>bytea</type>. So it is recommended that you - use the <classname>LargeObject</classname> <acronym>API</acronym> - if you intend to use Large Objects. - </para> - </note> - - <para> - <xref linkend="jdbc-binary-data-example"> contains some examples on - how to process binary data using the <productname>PostgreSQL</> - <acronym>JDBC</> driver. - </para> - - <example id="jdbc-binary-data-example"> - <title>Processing Binary Data in <acronym>JDBC</></title> - - <para> - For example, suppose you have a table containing the file names of - images and you also want to store the image in a <type>bytea</type> - column: -<programlisting> -CREATE TABLE images (imgname text, img bytea); -</programlisting> - </para> - - <para> - To insert an image, you would use: -<programlisting> -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()); -ps.executeUpdate(); -ps.close(); -fis.close(); -</programlisting> - - Here, <function>setBinaryStream()</function> transfers a set number - of bytes from a stream into the column of type <type>bytea</type>. - This also could have been done using the <function>setBytes()</function> - method if the contents of the image was already in a - <classname>byte[]</classname>. - </para> - - <para> - Retrieving an image is even easier. (We use - <classname>PreparedStatement</classname> here, but the - <classname>Statement</classname> class can equally be used.) - -<programlisting> -PreparedStatement ps = con.prepareStatement("SELECT img FROM images WHERE imgname = ?"); -ps.setString(1, "myimage.gif"); -ResultSet rs = ps.executeQuery(); -if (rs != null) { - while (rs.next()) { - byte[] imgBytes = rs.getBytes(1); - // use the data in some way here - } - rs.close(); -} -ps.close(); -</programlisting> - </para> - - <para> - Here the binary data was retrieved as an - <classname>byte[]</classname>. You could have used a - <classname>InputStream</classname> object instead. - </para> - - <para> - Alternatively you could be storing a very large file and want to use - the <classname>LargeObject</classname> <acronym>API</acronym> to - store the file: -<programlisting> -CREATE TABLE imageslo (imgname text, imgoid oid); -</programlisting> - </para> - - <para> - To insert an image, you would use: -<programlisting> -// All LargeObject API calls must be within a transaction block -conn.setAutoCommit(false); - -// Get the Large Object Manager to perform operations with -LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI(); - -// Create a new large object -int oid = lobj.create(LargeObjectManager.READ | LargeObjectManager.WRITE); - -// Open the large object for writing -LargeObject obj = lobj.open(oid, LargeObjectManager.WRITE); - -// Now open the file -File file = new File("myimage.gif"); -FileInputStream fis = new FileInputStream(file); - -// Copy the data from the file to the large object -byte buf[] = new byte[2048]; -int s, tl = 0; -while ((s = fis.read(buf, 0, 2048)) > 0) { - obj.write(buf, 0, s); - tl += s; -} - -// Close the large object -obj.close(); - -// Now insert the row into imageslo -PreparedStatement ps = conn.prepareStatement("INSERT INTO imageslo VALUES (?, ?)"); -ps.setString(1, file.getName()); -ps.setInt(2, oid); -ps.executeUpdate(); -ps.close(); -fis.close(); -</programlisting> - </para> - - <para> - Retrieving the image from the Large Object: - -<programlisting> -// All LargeObject API calls must be within a transaction block -conn.setAutoCommit(false); - -// Get the Large Object Manager to perform operations with -LargeObjectManager lobj = ((org.postgresql.PGConnection)conn).getLargeObjectAPI(); - -PreparedStatement ps = con.prepareStatement("SELECT imgoid FROM imageslo WHERE imgname = ?"); -ps.setString(1, "myimage.gif"); -ResultSet rs = ps.executeQuery(); -if (rs != null) { - while (rs.next()) { - // Open the large object for reading - int oid = rs.getInt(1); - LargeObject obj = lobj.open(oid, LargeObjectManager.READ); - - // Read the data - byte buf[] = new byte[obj.size()]; - obj.read(buf, 0, obj.size()); - // Do something with the data read here - - // Close the object - obj.close(); - } - rs.close(); -} -ps.close(); -</programlisting> - </para> - - </example> - </sect1> - - - <sect1 id="jdbc-ext"> - <title><productname>PostgreSQL</productname> Extensions to the - <acronym>JDBC</acronym> <acronym>API</acronym></title> - - <para> - <productname>PostgreSQL</productname> is an extensible database - system. You can add your own functions to the server, which can - then be called from queries, or even add your own data types. As - these are facilities unique to <productname>PostgreSQL</productname>, - 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. - </para> - - <sect2> - <title>Accessing the Extensions</title> - - <para> - To access some of the extensions, you need to use some extra - methods in the <classname>org.postgresql.PGConnection</classname> - class. In this case, you would need to case the return value of - <function>Driver.getConnection()</function>. For example: -<programlisting> -Connection db = Driver.getConnection(url, username, password); -// ... -// later on -Fastpath fp = ((org.postgresql.PGConnection)db).getFastpathAPI(); -</programlisting> - </para> - - <sect3> - <title>Class <classname>org.postgresql.PGConnection</classname></title> - -<synopsis> -public class PGConnection -</synopsis> - - <para> - These are the extra methods used to gain access to - <productname>PostgreSQL</productname>'s extensions. - </para> - - <sect4> - <title>Methods</title> - - <itemizedlist> - <listitem> -<synopsis> -public Fastpath getFastpathAPI() throws SQLException -</synopsis> - <para> - This returns the fast-path <acronym>API</acronym> for the - current connection. It is primarily used by the Large Object - <acronym>API</acronym>. - </para> - - <para> - The best way to use this is as follows: -<programlisting> -import org.postgresql.fastpath.*; -... -Fastpath fp = ((org.postgresql.PGConnection)myconn).getFastpathAPI(); -</programlisting> - where <varname>myconn</> is an open <classname>Connection</> to <productname>PostgreSQL</productname>. - </para> - - <formalpara> - <title>Returns:</title> - <para> - <classname>Fastpath</> object allowing access to functions on the - <productname>PostgreSQL</productname> server. - </para> - </formalpara> - - <formalpara> - <title>Throws:</title> - <para> - <classname>SQLException</> by <classname>Fastpath</> when initializing for first time - </para> - </formalpara> - </listitem> - - <listitem> - <para> -<synopsis> -public LargeObjectManager getLargeObjectAPI() throws SQLException -</synopsis> - This returns the Large Object <acronym>API</acronym> for the - current connection. - </para> - - <para> - The best way to use this is as follows: -<programlisting> -import org.postgresql.largeobject.*; -... -LargeObjectManager lo = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI(); -</programlisting> - where <varname>myconn</> is an open <classname>Connection</> to - <productname>PostgreSQL</productname>. - </para> - - <formalpara> - <title>Returns:</title> - <para> - <classname>LargeObject</classname> object that implements the <acronym>API</acronym> - </para> - </formalpara> - - <formalpara> - <title>Throws:</title> - <para> - <classname>SQLException</classname> by <classname>LargeObject</classname> when initializing for first time - </para> - </formalpara> - </listitem> - - <listitem> - <para> -<synopsis> -public void addDataType(String type, String name) -</synopsis> - This allows client code to add a handler for one of - <productname>PostgreSQL</productname>'s more unique data types. Normally, a data type not - known by the driver is returned by <literal>ResultSet.getObject()</literal> as a - <classname>PGobject</> instance. This method allows you to write a class - that extends <classname>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. - </para> - - <para> - The best way to use this is as follows: -<programlisting> - ... -((org.postgresql.PGConnection)myconn).addDataType("mytype","my.class.name"); - ... -</programlisting> - where <varname>myconn</varname> is an open <classname>Connection</> to - <productname>PostgreSQL</productname>. The handling class must - extend <classname>org.postgresql.util.PGobject</classname>. - </para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - - - <sect3> - <title>Class <classname>org.postgresql.Fastpath</classname></title> - -<synopsis> -public class Fastpath extends Object - -java.lang.Object - | - +----org.postgresql.fastpath.Fastpath -</synopsis> - - <para> - <classname>Fastpath</classname> is an <acronym>API</acronym> that - exists within the <application>libpq</application> C interface, and allows a client machine - to execute a function on the database server. Most client code - will not need to use this method, but it is provided because the - Large Object <acronym>API</acronym> uses it. - </para> - - <para> - To use, you need to import the - <classname>org.postgresql.fastpath</classname> package, using the - line: -<programlisting> -import org.postgresql.fastpath.*; -</programlisting> - Then, in your code, you need to get a - <classname>FastPath</classname> object: -<programlisting> -Fastpath fp = ((org.postgresql.PGConnection)conn).getFastpathAPI(); -</programlisting> - This will return an instance associated with the database - connection that you can use to issue commands. The casing of - <classname>Connection</classname> to - <classname>org.postgresql.PGConnection</classname> is required, as - the <function>getFastpathAPI()</function> is an extension method, - not part of <acronym>JDBC</acronym>. Once you have a - <classname>Fastpath</classname> instance, you can use the - <function>fastpath()</function> methods to execute a server - function. - </para> - - <formalpara> - <title>See Also:</title> - <para> - <classname>FastpathFastpathArg</classname>, <classname>LargeObject</classname> - </para> - </formalpara> - - <sect4> - <title>Methods</title> - - <itemizedlist> - <listitem> -<synopsis> -public Object fastpath(int fnid, - boolean resulttype, - FastpathArg args[]) throws SQLException -</synopsis> - <para> - Send a function call to the <productname>PostgreSQL</productname> server. - </para> - - <formalpara> - <title>Parameters:</title> - <para> - <parameter>fnid</> - Function id - <parameter>resulttype</> - True if the result is an integer, false -for - other results - <parameter>args</> - <classname>FastpathArguments</classname> to pass to fast-path call - </para> - </formalpara> - - <formalpara> - <title>Returns:</title> - <para> - null if no data, Integer if an integer result, or byte[] - otherwise - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public Object fastpath(String name, - boolean resulttype, - FastpathArg args[]) throws SQLException -</synopsis> - <para> - Send a function call to the <productname>PostgreSQL</productname> server by name. - </para> - - <note> - <para> - The mapping for the procedure name to function id needs to - exist, usually to an earlier call to <function>addfunction()</function>. This is - the preferred method to call, as function id's can/may change - between versions of the server. For an example of how this - works, refer to org.postgresql.LargeObject - </para> - </note> - - <formalpara> - <title>Parameters:</title> - <para> - <parameter>name</> - Function name - <parameter>resulttype</> - True if the result is an integer, false -for - other results - <parameter>args</> - <classname>FastpathArguments</classname> to pass to fast-path call - </para> - </formalpara> - - <formalpara> - <title>Returns:</title> - <para> - null if no data, Integer if an integer result, or byte[] - otherwise - </para> - </formalpara> - - <formalpara> - <title>See Also:</title> - <para><classname>LargeObject</classname></para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public int getInteger(String name, - FastpathArg args[]) throws SQLException -</synopsis> - <para> - This convenience method assumes that the return value is an Integer - </para> - - <formalpara> - <title>Parameters:</title> - <para> - <parameter>name</parameter> - Function name - <parameter>args</parameter> - Function arguments - </para> - </formalpara> - - <formalpara> - <title>Returns:</title> - <para>integer result</para> - </formalpara> - - <formalpara> - <title>Throws:</title> - <para> - <classname>SQLException</classname> if a database-access error occurs or no result - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public byte[] getData(String name, - FastpathArg args[]) throws SQLException -</synopsis> - <para> - This convenience method assumes that the return value is binary - data. - </para> - - <formalpara> - <title>Parameters:</title> - <para> - <parameter>name</parameter> - Function name - <parameter>args</parameter> - Function arguments - </para> - </formalpara> - - <formalpara> - <title>Returns:</title> - <para>byte[] array containing result</para> - </formalpara> - - <formalpara> - <title>Throws:</title> - <para> - <classname>SQLException</classname> if a database-access error occurs or no result - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public void addFunction(String name, - int fnid) -</synopsis> - <para> - This adds a function to our look-up table. User code should - use the <function>addFunctions</function> 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. - </para> - </listitem> - - <listitem> -<synopsis> -public void addFunctions(ResultSet rs) throws SQLException -</synopsis> - <para> - This takes a <classname>ResultSet</classname> containing two columns. Column 1 - contains the function name, Column 2 the OID. It reads the - entire <classname>ResultSet</classname>, loading the values into the function table. - </para> - - <important> - <para> - Remember to <function>close()</function> the - <classname>ResultSet</classname> after calling this! - </para> - </important> - - <note> - <title>Implementation note about function name look-ups</title> - - <para> - <productname>PostgreSQL</productname> stores the function id's and their corresponding - names in the <classname>pg_proc</> table. To speed things up locally, - instead of querying each function from that table when - required, a <classname>Hashtable</classname> is used. Also, only the function's - required are entered into this table, keeping connection - times as fast as possible. - </para> - - <para> - The <classname>org.postgresql.LargeObject</classname> class - performs a query upon its start-up, and passes the returned - <classname>ResultSet</classname> to the - <function>addFunctions()</function> method here. Once this - has been done, the Large Object <acronym>API</acronym> refers - to the functions by name. - </para> - - <para> - Do not think that manually converting them to the OIDs 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. - </para> - </note> - - <formalpara> - <title>See Also:</title> - <para> - <classname>LargeObjectManager</classname> - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public int getID(String name) throws SQLException -</synopsis> - <para> - This returns the function id associated by its name If - <function>addFunction()</function> or <function>addFunctions()</function> have not been called for this - name, then an <classname>SQLException</classname> is thrown. - </para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - - - <sect3> - <title>Class <classname>org.postgresql.fastpath.FastpathArg</classname></title> - -<synopsis> -public class FastpathArg extends Object - -java.lang.Object - | - +----org.postgresql.fastpath.FastpathArg -</synopsis> - - <para> - Each fast-path 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. - </para> - - <para> - For an example on how to use this, refer to the - <classname>org.postgresql.LargeObject</classname> package. - </para> - - <formalpara> - <title>See Also:</title> - <para> - <classname>Fastpath</classname>, <classname>LargeObjectManager</classname>, <classname>LargeObject</classname> - </para> - </formalpara> - - <sect4> - <title>Constructors</title> - - <itemizedlist> - <listitem> -<synopsis> -public FastpathArg(int value) -</synopsis> - <para> - Constructs an argument that consists of an integer value - </para> - - <formalpara> - <title>Parameters:</title> - <para> - value - int value to set - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public FastpathArg(byte bytes[]) -</synopsis> - <para> - Constructs an argument that consists of an array of bytes - </para> - - <formalpara> - <title>Parameters:</title> - <para> - bytes - array to store - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public FastpathArg(byte buf[], - int off, - int len) -</synopsis> - <para> - Constructs an argument that consists of part of a byte array - </para> - - <formalpara> - <title>Parameters:</title> - <para> - <variablelist> - <varlistentry> - <term><parameter>buf</></term> - <listitem> - <simpara>source array</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><parameter>off</parameter></term> - <listitem> - <simpara>offset within array</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><parameter>len</parameter></term> - <listitem> - <simpara>length of data to include</simpara> - </listitem> - </varlistentry> - </variablelist> - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public FastpathArg(String s) -</synopsis> - <para> - Constructs an argument that consists of a String. - </para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - </sect2> - - - <sect2> - <title>Geometric Data Types</title> - - <para> - <productname>PostgreSQL</productname> 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. - </para> - -<programlisting> -Class org.postgresql.geometric.PGbox - -java.lang.Object - | - +----org.postgresql.util.PGobject - | - +----org.postgresql.geometric.PGbox - - public class PGbox extends PGobject implements Serializable, -Cloneable - - This represents the box data type within <productname>PostgreSQL</productname>. - -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 <productname>PostgreSQL</productname> 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 -overridden, 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 overridden to allow the object to be cloned - - Overrides: - clone in class PGobject - - public String getValue() - - Returns: - the PGbox in the syntax expected by <productname>PostgreSQL</productname> - - Overrides: - getValue in class PGobject - -<!-- **************************************************************** --> -Class org.postgresql.geometric.PGcircle - -java.lang.Object - | - +----org.postgresql.util.PGobject - | - +----org.postgresql.geometric.PGcircle - - public class PGcircle extends PGobject implements Serializable, -Cloneable - - This represents <productname>PostgreSQL</productname>'s circle data type, consisting of a point -and a radius - -Variables - - public PGpoint center - - This is the center point - - double radius - - This is the radius - -Constructors - - public PGcircle(double x, - double y, - double r) - - Parameters: - 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 center - r - radius of circle - - public PGcircle(String s) throws SQLException - - Parameters: - s - definition of the circle in <productname>PostgreSQL</productname>'s syntax. - - Throws: SQLException - on conversion failure - - public PGcircle() - - This constructor is used by the driver. - -Methods - - public void setValue(String s) throws SQLException - - Parameters: - s - definition of the circle in <productname>PostgreSQL</productname>'s syntax. - - Throws: SQLException - on conversion failure - - Overrides: - setValue in class PGobject - - public boolean equals(Object obj) - - Parameters: - obj - Object to compare with - - Returns: - true if the two circles are identical - - Overrides: - equals in class PGobject - - public Object clone() - - 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 <productname>PostgreSQL</productname> - - Overrides: - getValue in class PGobject - -<!-- **************************************************************** --> -Class org.postgresql.geometric.PGline - -java.lang.Object - | - +----org.postgresql.util.PGobject - | - +----org.postgresql.geometric.PGline - - public class PGline extends PGobject implements Serializable, -Cloneable - - This implements a line consisting of two points. Currently line is -not yet implemented in the server, but this class ensures that when -it's done were ready for it. - -Variables - - public PGpoint point[] - - These are the two points. - -Constructors - - public PGline(double x1, - double y1, - double x2, - double y2) - - Parameters: - x1 - coordinate for first point - y1 - coordinate for first point - x2 - coordinate for second point - y2 - coordinate for second point - - public PGline(PGpoint p1, - PGpoint p2) - - Parameters: - p1 - first point - p2 - second point - - public PGline(String s) throws SQLException - - Parameters: - s - definition of the line in <productname>PostgreSQL</productname>'s syntax. - - Throws: SQLException - on conversion failure - - public PGline() - - required by the driver - -Methods - - public void setValue(String s) throws SQLException - - Parameters: - s - Definition of the line segment in <productname>PostgreSQL</productname>'s -syntax - - Throws: SQLException - on conversion failure - - Overrides: - setValue in class PGobject - - public boolean equals(Object obj) - - Parameters: - obj - Object to compare with - - Returns: - true if the two lines are identical - - Overrides: - equals in class PGobject - - public Object clone() - - 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 <productname>PostgreSQL</productname> - - Overrides: - getValue in class PGobject - -<!-- **************************************************************** --> -Class org.postgresql.geometric.PGlseg - -java.lang.Object - | - +----org.postgresql.util.PGobject - | - +----org.postgresql.geometric.PGlseg - - public class PGlseg extends PGobject implements Serializable, -Cloneable - - This implements a lseg (line segment) consisting of two points - -Variables - - public PGpoint point[] - - These are the two points. - -Constructors - - public PGlseg(double x1, - double y1, - double x2, - double y2) - - Parameters: - - x1 - coordinate for first point - y1 - coordinate for first point - x2 - coordinate for second point - y2 - coordinate for second point - - public PGlseg(PGpoint p1, - PGpoint p2) - - Parameters: - p1 - first point - p2 - second point - - public PGlseg(String s) throws SQLException - - Parameters: - s - Definition of the line segment in <productname>PostgreSQL</productname>'s syntax. - - Throws: SQLException - on conversion failure - - public PGlseg() - - required by the driver - -Methods - - public void setValue(String s) throws SQLException - - Parameters: - s - Definition of the line segment in <productname>PostgreSQL</productname>'s -syntax - - Throws: SQLException - on conversion failure - - Overrides: - setValue in class PGobject - - public boolean equals(Object obj) - - Parameters: - obj - Object to compare with - - Returns: - true if the two line segments are identical - - Overrides: - equals in class PGobject - - public Object clone() - - 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 <productname>PostgreSQL</productname> - - Overrides: - getValue in class PGobject - -<!-- **************************************************************** --> -Class org.postgresql.geometric.PGpath - -java.lang.Object - | - +----org.postgresql.util.PGobject - | - +----org.postgresql.geometric.PGpath - - public class PGpath extends PGobject implements Serializable, -Cloneable - - This implements a path (a multiply segmented line, which may be -closed) - -Variables - - public boolean open - - True if the path is open, false if closed - - public PGpoint points[] - - The points defining this path - -Constructors - - public PGpath(PGpoint points[], - boolean open) - - Parameters: - points - the PGpoints that define the path - open - True if the path is open, false if closed - - public PGpath() - - Required by the driver - - public PGpath(String s) throws SQLException - - Parameters: - s - definition of the path in <productname>PostgreSQL</productname>'s syntax. - - Throws: SQLException - on conversion failure - -Methods - - public void setValue(String s) throws SQLException - - Parameters: - s - Definition of the path in <productname>PostgreSQL</productname>'s syntax - - Throws: SQLException - on conversion failure - - Overrides: - setValue in class PGobject - - public boolean equals(Object obj) - - Parameters: - obj - Object to compare with - - Returns: - true if the two pathes are identical - - Overrides: - equals in class PGobject - - public Object clone() - - This must be overridden to allow the object to be cloned - - Overrides: - clone in class PGobject - - public String getValue() - - This returns the path in the syntax expected by -<productname>PostgreSQL</productname> - - Overrides: - getValue in class PGobject - - public boolean isOpen() - - This returns true if the path is open - - public boolean isClosed() - - This returns true if the path is closed - - public void closePath() - - Marks the path as closed - - public void openPath() - - Marks the path as open - -<!-- **************************************************************** --> -Class org.postgresql.geometric.PGpoint - -java.lang.Object - | - +----org.postgresql.util.PGobject - | - +----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 data type in <productname>PostgreSQL</productname>. - -Variables - - public double x - - The X coordinate of the point - - public double y - - The Y coordinate of the point - -Constructors - - public PGpoint(double x, - double y) - - Parameters: - x - coordinate - y - coordinate - - public PGpoint(String value) throws SQLException - - This is called mainly from the other geometric types, when a -point is embedded within their definition. - - Parameters: - value - Definition of this point in <productname>PostgreSQL</productname>'s -syntax - - public PGpoint() - - Required by the driver - -Methods - - public void setValue(String s) throws SQLException - - Parameters: - s - Definition of this point in <productname>PostgreSQL</productname>'s syntax - - Throws: SQLException - on conversion failure - - Overrides: - setValue in class PGobject - - public boolean equals(Object obj) - - Parameters: - obj - Object to compare with - - Returns: - true if the two points are identical - - Overrides: - equals in class PGobject - - public Object clone() - - 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 <productname>PostgreSQL</productname> - - Overrides: - getValue in class PGobject - - public void translate(int x, - int y) - - Translate the point with the supplied amount. - - Parameters: - x - integer amount to add on the x axis - y - integer amount to add on the y axis - - public void translate(double x, - double y) - - Translate the point with the supplied amount. - - Parameters: - x - double amount to add on the x axis - y - double amount to add on the y axis - - public void move(int x, - int y) - - Moves the point to the supplied coordinates. - - Parameters: - x - integer coordinate - y - integer coordinate - -public void move(double x, - double y) - - Moves the point to the supplied coordinates. - - Parameters: - x - double coordinate - y - double coordinate - - public void setLocation(int x, - int y) - - Moves the point to the supplied coordinates. refer to - java.awt.Point for description of this - - Parameters: - x - integer coordinate - y - integer coordinate - - See Also: - Point - - public void setLocation(Point p) - - Moves the point to the supplied java.awt.Point refer to - java.awt.Point for description of this - - Parameters: - p - Point to move to - - See Also: - Point - -<!-- **************************************************************** --> -Class org.postgresql.geometric.PGpolygon - -java.lang.Object - | - +----org.postgresql.util.PGobject - | - +----org.postgresql.geometric.PGpolygon - - public class PGpolygon extends PGobject implements Serializable, -Cloneable - - This implements the polygon data type within <productname>PostgreSQL</productname>. - -Variables - - public PGpoint points[] - - The points defining the polygon - -Constructors - - public PGpolygon(PGpoint points[]) - - Creates a polygon using an array of PGpoints - - Parameters: - points - the points defining the polygon - - public PGpolygon(String s) throws SQLException - - Parameters: - s - definition of the polygon in <productname>PostgreSQL</productname>'s syntax. - - Throws: SQLException - on conversion failure - - public PGpolygon() - - Required by the driver - -Methods - - public void setValue(String s) throws SQLException - - Parameters: - s - Definition of the polygon in <productname>PostgreSQL</productname>'s syntax - - Throws: SQLException - on conversion failure - - Overrides: - setValue in class PGobject - - public boolean equals(Object obj) - - Parameters: - obj - Object to compare with - - Returns: - true if the two polygons are identical - - Overrides: - equals in class PGobject - - public Object clone() - - 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 <productname>PostgreSQL</productname> - - Overrides: - getValue in class PGobject -</programlisting> - </sect2> - - - <sect2> - <title>Large Objects</title> - - <para> - Large objects are supported in the standard - <acronym>JDBC</acronym> specification. However, that interface is - limited, and the <acronym>API</acronym> provided by <productname>PostgreSQL</productname> allows for random - access to the objects contents, as if it was a local file. - </para> - - <para> - The org.postgresql.largeobject package provides to Java the <application>libpq</application> - C interface's large object <acronym>API</acronym>. It consists of - two classes, <classname>LargeObjectManager</classname>, which deals with creating, - opening and deleting large objects, and <classname>LargeObject</classname> which deals - with an individual object. - </para> - - <sect3> - <title>Class <classname>org.postgresql.largeobject.LargeObject</classname></title> - -<synopsis> -public class LargeObject extends Object - -java.lang.Object - | - +----org.postgresql.largeobject.LargeObject -</synopsis> - - <para> - This class implements the large object interface to - <productname>PostgreSQL</productname>. - </para> - - <para> - It provides the basic methods required to run the interface, plus - a pair of methods that provide <classname>InputStream</classname> and <classname>OutputStream</classname> - classes for this object. - </para> - - <para> - Normally, client code would use the methods in - <classname>BLOB</classname> to access large objects. - </para> - - <para> - However, sometimes lower level access to Large Objects is - required, that is not supported by the <acronym>JDBC</acronym> - specification. - </para> - - <para> - Refer to org.postgresql.largeobject.LargeObjectManager on how to - gain access to a Large Object, or how to create one. - </para> - - <formalpara> - <title>See Also:</title> - <para><classname>LargeObjectManager</classname></para> - </formalpara> - - <sect4> - <title>Variables</title> - - <variablelist> - <varlistentry> - <term>public static final int SEEK_SET</term> - <listitem> - <para>Indicates a seek from the beginning of a file</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>public static final int SEEK_CUR</term> - <listitem> - <para>Indicates a seek from the current position</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>public static final int SEEK_END</term> - <listitem> - <para>Indicates a seek from the end of a file</para> - </listitem> - </varlistentry> - </variablelist> - </sect4> - - <sect4> - <title>Methods</title> - - <itemizedlist> - <listitem> -<synopsis> -public int getOID() -</synopsis> - <para> - Returns the OID of this <classname>LargeObject</classname> - </para> - </listitem> - - <listitem> -<synopsis> -public void close() throws SQLException -</synopsis> - <para> - This method closes the object. You must not call methods in - this object after this is called. - </para> - </listitem> - - <listitem> -<synopsis> -public byte[] read(int len) throws SQLException -</synopsis> - <para> - Reads some data from the object, and return as a byte[] array - </para> - </listitem> - - <listitem> -<synopsis> -public int read(byte buf[], - int off, - int len) throws SQLException -</synopsis> - <para> - Reads some data from the object into an existing array - </para> - - <formalpara> - <title>Parameters:</title> - <para> - <variablelist> - <varlistentry> - <term><parameter>buf</></term> - <listitem> - <simpara>destination array</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><parameter>off</></term> - <listitem> - <simpara>offset within array</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><parameter>len</></term> - <listitem> - <simpara>number of bytes to read</simpara> - </listitem> - </varlistentry> - </variablelist> - </para> - </formalpara> - </listitem> - - <listitem> -<synopsis> -public void write(byte buf[]) throws SQLException -</synopsis> - <para> - Writes an array to the object - </para> - </listitem> - - <listitem> -<synopsis> -public void write(byte buf[], - int off, - int len) throws SQLException -</synopsis> - <para> - Writes some data from an array to the object - </para> - - <formalpara> - <title>Parameters:</title> - <para> - <variablelist> - <varlistentry> - <term><parameter>buf</></term> - <listitem> - <simpara>destination array</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><parameter>off</></term> - <listitem> - <simpara>offset within array</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><parameter>len</></term> - <listitem> - <simpara>number of bytes to write</simpara> - </listitem> - </varlistentry> - </variablelist> - </para> - </formalpara> - </listitem> - -<!-- - public void seek(int pos, - int ref) throws SQLException - - Sets the current position within the object. - - This is similar to the fseek() call in the standard C -library.It allows you to have random access to the large object. - - Parameters: - pos - position within object - ref - Either SEEK_SET, SEEK_CUR or SEEK_END - Throws: SQLException - if a database-access error occurs. - - public void seek(int pos) throws SQLException - - Sets the current position within the object. - - This is similar to the fseek() call in the standard C -library.It allows you to have random access to the large object. - - Parameters: - pos - position within object from begining - - Throws: SQLException - if a database-access error occurs. - - public int tell() throws SQLException - - Returns: - the current position within the object - - Throws: SQLException - if a database-access error occurs. - - public int size() throws SQLException - - This method is inefficient, as the only way to find out the -size of the object is to seek to the end, record the current position, -then return to the original position. - - A better method will be found in the future. - - Returns: - the size of the large object - - Throws: SQLException - if a database-access error occurs. - - public InputStream getInputStream() throws SQLException - - Returns an InputStream from this object. - - This InputStream can then be used in any method that -requires an InputStream. - - Throws: SQLException - if a database-access error occurs. - - public OutputStream getOutputStream() throws SQLException - - Returns an OutputStream to this object - - This OutputStream can then be used in any method that -requires an OutputStream. - - Throws: SQLException - if a database-access error occurs. ---> - </itemizedlist> - </sect4> - </sect3> - - - <sect3> - <title>Class <classname>org.postgresql.largeobject.LargeObjectManager</classname></title> - -<synopsis> -public class LargeObjectManager extends Object - -java.lang.Object - | - +----org.postgresql.largeobject.LargeObjectManager -</synopsis> - - <para> - This class implements the large object interface to - <productname>PostgreSQL</productname>. It provides methods that - allow client code to create, open and delete large objects from - the database. When opening an object, an instance of - <classname>org.postgresql.largeobject.LargeObject</classname> is - returned, and its methods then allow access to the object. - </para> - - <para> - This class can only be created by org.postgresql.PGConnection. To - get access to this class, use the following segment of code: -<programlisting> -import org.postgresql.largeobject.*; -Connection conn; -LargeObjectManager lobj; -// ... code that opens a connection ... -lobj = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI(); -</programlisting> - </para> - - <para> - Normally, client code would use the <classname>BLOB</classname> - methods to access large objects. However, sometimes - lower level access to Large Objects is required, that is not - supported by the <acronym>JDBC</acronym> specification. - </para> - - <para> - Refer to org.postgresql.largeobject.LargeObject on how to - manipulate the contents of a Large Object. - </para> - - <sect4> - <title>Variables</title> - - <variablelist> - <varlistentry> - <term><literal>public static final int WRITE</></term> - <listitem> - <simpara>This mode indicates we want to write to an object.</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>public static final int READ</></term> - <listitem> - <simpara>This mode indicates we want to read an object.</simpara> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>public static final int READWRITE</></term> - <listitem> - <simpara>This mode is the default. It indicates we want read and write access to a large object.</simpara> - </listitem> - </varlistentry> - </variablelist> - </sect4> - - <sect4> - <title>Methods</title> - - <itemizedlist> - <listitem> -<synopsis> -public LargeObject open(int oid) throws SQLException -</synopsis> - <para> - This opens an existing large object, based on its OID. This - method assumes that <symbol>READ</> and - <symbol>WRITE</> access is required (the default). - </para> - </listitem> - - <listitem> -<synopsis> -public LargeObject open(int oid, - int mode) throws SQLException -</synopsis> - <para> - This opens an existing large object, based on its OID, and - allows setting the access mode. - </para> - </listitem> - - <listitem> -<synopsis> -public int create() throws SQLException -</synopsis> - <para> - This creates a large object, returning its OID. - It defaults to <symbol>READWRITE</> for the new object's attributes. - </para> - </listitem> - - <listitem> -<synopsis> -public int create(int mode) throws SQLException -</synopsis> - <para> - This creates a large object, returning its OID, and sets the - access mode. - </para> - </listitem> - - <listitem> -<synopsis> -public void delete(int oid) throws SQLException -</synopsis> - <para> - This deletes a large object. - </para> - </listitem> - - <listitem> -<synopsis> -public void unlink(int oid) throws SQLException -</synopsis> - <para> - This deletes a large object. It is identical to the delete - method, and is supplied as the C <acronym>API</acronym> uses - <quote>unlink</quote>. - </para> - </listitem> - </itemizedlist> - </sect4> - </sect3> - </sect2> - - </sect1> - - - <sect1 id="jdbc-thread"> - <title>Using the Driver in a Multithreaded or a Servlet Environment</title> - - <indexterm zone="jdbc-thread"> - <primary>threads</primary> - <secondary sortas="JDBC">with JDBC</secondary> - </indexterm> - - <para> - A problem with many <acronym>JDBC</acronym> drivers is that only - one thread can use a <classname>Connection</classname> at any one - time --- otherwise a thread could send a query while another one is - receiving results, and this could cause severe confusion. - </para> - - <para> - The <productname>PostgreSQL</productname> <acronym>JDBC</acronym> driver - is thread safe. - Consequently, if your application uses multiple threads then you do - not have to worry about complex algorithms to ensure that only one thread - uses the database at a time. - </para> - - <para> - 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 the operation is a regular <acronym>SQL</acronym> - statement, then the operation consists of sending the statement and - retrieving any <classname>ResultSet</classname> (in full). If it - is a fast-path call (e.g., reading a block - from a large object) then it consists of - sending and retrieving the respective data. - </para> - - <para> - This is fine for applications and applets but can cause a - performance problem with servlets. If you have several threads - performing queries then each but one will pause. - To solve this, you are advised to create a pool of connections. - When ever a thread needs to use the database, it asks a manager - class for a <classname>Connection</classname> object. 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 using the connection, it returns it to the manager - which 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. The down side of a connection pool is - that it increases the load on the server because a new session is - created for each <classname>Connection</classname> object. It is - up to you and your applications' requirements. - </para> - </sect1> - - <sect1 id="jdbc-datasource"> - <title>Connection Pools and Data Sources</title> - - <indexterm zone="jdbc-datasource"> - <primary>connection pool</primary> - <secondary sortas="JDBC">in JDBC</secondary> - </indexterm> - - <indexterm zone="jdbc-datasource"> - <primary>DataSource</primary> - </indexterm> - - <para> - <acronym>JDBC</> 2 introduced standard connection pooling features in an - add-on <acronym>API</> known as the <acronym>JDBC</acronym> 2.0 Optional - Package (also known as the <acronym>JDBC</acronym> 2.0 - Standard Extension). These features have since been included in - the core <acronym>JDBC</> 3 <acronym>API</>. The - <productname>PostgreSQL</productname> <acronym>JDBC</acronym> drivers - support these features if it has been compiled with - <acronym>JDK</acronym> 1.3.x in combination with the - <acronym>JDBC</acronym> 2.0 Optional Package - (<acronym>JDBC</acronym> 2), or with <acronym>JDK</acronym> 1.4 or higher - (<acronym>JDBC</acronym> 3). Most application servers include - the <acronym>JDBC</acronym> 2.0 Optional Package, but it is - also available separately from the Sun - <ulink - url="http://java.sun.com/products/jdbc/download.html#spec"><acronym>JDBC</acronym> download site</ulink>. - </para> - - <sect2 id="jdbc-ds-intro"> - <title>Overview</title> - - <para> - The <acronym>JDBC</acronym> <acronym>API</> provides a client - and a server interface for connection pooling. The client - interface is <literal>javax.sql.DataSource</literal>, - which is what application code will typically use to - acquire a pooled database connection. The server interface - is <literal>javax.sql.ConnectionPoolDataSource</literal>, - which is how most application servers will interface with - the <productname>PostgreSQL</productname> <acronym>JDBC</acronym> - driver. - </para> - - <para> - In an application server environment, the - application server configuration will typically refer to - the <productname>PostgreSQL</productname> - <literal>ConnectionPoolDataSource</literal> implementation, - while the application component code will typically acquire a - <literal>DataSource</literal> implementation provided by - the application server (not by - <productname>PostgreSQL</productname>). - </para> - - <para> - For an environment without an application server, - <productname>PostgreSQL</productname> provides two implementations - of <literal>DataSource</literal> which an application can use - directly. One implementation performs connection pooling, - while the other simply provides access to database connections - through the <literal>DataSource</literal> interface without - any pooling. Again, these implementations should not be used - in an application server environment unless the application - server does not support the - <literal>ConnectionPoolDataSource</literal> interface. - </para> - </sect2> - - <sect2 id="jdbc-ds-cpds"> - <title>Application Servers: <classname>ConnectionPoolDataSource</classname></title> - - <para> - <productname>PostgreSQL</productname> includes one implementation - of <classname>ConnectionPoolDataSource</classname> for - <acronym>JDBC</acronym> 2 and one for <acronym>JDBC</acronym> 3, - as shown in <xref linkend="jdbc-ds-cpds-imp-table">. - </para> - - - <table id="jdbc-ds-cpds-imp-table"> - <title><classname>ConnectionPoolDataSource</classname> Implementations</title> - - <tgroup cols=2> - <thead> - <row> - <entry><acronym>JDBC</acronym></entry> - <entry>Implementation Class</entry> - </row> - </thead> - - <tbody> - <row> - <entry>2</entry> - <entry><literal>org.postgresql.jdbc2.optional.ConnectionPool</literal></entry> - </row> - - <row> - <entry>3</entry> - <entry><literal>org.postgresql.jdbc3.Jdbc3ConnectionPool</literal></entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - Both implementations use the same configuration scheme. - <acronym>JDBC</acronym> requires that a - <classname>ConnectionPoolDataSource</classname> be configured via - JavaBean properties, shown in <xref linkend="jdbc-ds-cpds-props">, - so there are get and set methods for each of these properties. - </para> - - <table id="jdbc-ds-cpds-props"> - <title><classname>ConnectionPoolDataSource</> Configuration Properties</title> - - <tgroup cols=3> - <thead> - <row> - <entry>Property</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>serverName</literal></entry> - <entry><type>String</type></entry> - <entry><productname>PostgreSQL</productname> database server - host name</entry> - </row> - - <row> - <entry><literal>databaseName</literal></entry> - <entry><type>String</type></entry> - <entry><productname>PostgreSQL</productname> database name</entry> - </row> - - <row> - <entry><literal>portNumber</literal></entry> - <entry><type>int</type></entry> - <entry> - TCP port which the <productname>PostgreSQL</productname> - database server is listening on (or 0 to use the default port) - </entry> - </row> - - <row> - <entry><literal>user</literal></entry> - <entry><type>String</type></entry> - <entry>User used to make database connections</entry> - </row> - - <row> - <entry><literal>password</literal></entry> - <entry><type>String</type></entry> - <entry>Password used to make database connections</entry> - </row> - - <row> - <entry><literal>defaultAutoCommit</literal></entry> - <entry><type>boolean</type></entry> - <entry> - Whether connections should have autocommit enabled or disabled - when they are supplied to the caller. The default is - <literal>false</literal>, to disable autocommit. - </entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - Many application servers use a properties-style syntax to - configure these properties, so it would not be unusual to enter - properties as a block of text. If the application server provides - a single area to enter all the properties, they might be listed - like this: -<programlisting> -serverName=localhost -databaseName=test -user=testuser -password=testpassword -</programlisting> - Or, if semicolons are used as separators instead of newlines, it - could look like this: -<programlisting> -serverName=localhost;databaseName=test;user=testuser;password=testpassword -</programlisting> - </para> - - </sect2> - - <sect2 id="jdbc-ds-ds"> - <title>Applications: <classname>DataSource</></title> - - <para><productname>PostgreSQL</productname> includes two - implementations of <literal>DataSource</literal> - for <acronym>JDBC</acronym> 2 and two for <acronym>JDBC</acronym> - 3, as shown in <xref linkend="jdbc-ds-ds-imp">. - The pooling implementations do not actually close connections - when the client calls the <literal>close</literal> method, but - instead return the connections to a pool of available connections - for other clients to use. This avoids any overhead of repeatedly - opening and closing connections, and allows a large number of - clients to share a small number of database connections.</para> - <para>The pooling data-source implementation provided here is not - the most feature-rich in the world. Among other things, - connections are never closed until the pool itself is closed; - there is no way to shrink the pool. As well, connections - requested for users other than the default configured user are - not pooled. Many application servers - provide more advanced pooling features and use the - <literal>ConnectionPoolDataSource</literal> implementation - instead.</para> - - <table id="jdbc-ds-ds-imp"> - <title><classname>DataSource</> Implementations</title> - - <tgroup cols=3> - <thead> - <row> - <entry><acronym>JDBC</acronym></entry> - <entry>Pooling</entry> - <entry>Implementation Class</entry> - </row> - </thead> - - <tbody> - <row> - <entry>2</entry> - <entry>No</entry> - <entry><literal>org.postgresql.jdbc2.optional.SimpleDataSource</literal></entry> - </row> - - <row> - <entry>2</entry> - <entry>Yes</entry> - <entry><literal>org.postgresql.jdbc2.optional.PoolingDataSource</literal></entry> - </row> - - <row> - <entry>3</entry> - <entry>No</entry> - <entry><literal>org.postgresql.jdbc3.Jdbc3SimpleDataSource</literal></entry> - </row> - - <row> - <entry>3</entry> - <entry>Yes</entry> - <entry><literal>org.postgresql.jdbc3.Jdbc3PoolingDataSource</literal></entry> - </row> - - </tbody> - </tgroup> - </table> - - <para> - All the implementations use the same configuration scheme. - <acronym>JDBC</acronym> requires that a - <literal>DataSource</literal> be configured via JavaBean - properties, shown in <xref linkend="jdbc-ds-ds-props">, so there - are get and set methods for each of these properties. - </para> - - <table id="jdbc-ds-ds-props"> - <title><classname>DataSource</> Configuration Properties</title> - - <tgroup cols=3> - <thead> - <row> - <entry>Property</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>serverName</literal></entry> - <entry><type>String</type></entry> - <entry><productname>PostgreSQL</productname> database server - host name</entry> - </row> - - <row> - <entry><literal>databaseName</literal></entry> - <entry><type>String</type></entry> - <entry><productname>PostgreSQL</productname> database name</entry> - </row> - - <row> - <entry><literal>portNumber</literal></entry> - <entry><type>int</type></entry> - <entry>TCP port which the - <productname>PostgreSQL</productname> database server is - listening on (or 0 to use the default port)</entry> - </row> - - <row> - <entry><literal>user</literal></entry> - <entry><type>String</type></entry> - <entry>User used to make database connections</entry> - </row> - - <row> - <entry><literal>password</literal></entry> - <entry><type>String</type></entry> - <entry>Password used to make database connections</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>The pooling implementations require some additional - configuration properties, which are shown in <xref linkend="jdbc-ds-ds-xprops">.</para> - - <table id="jdbc-ds-ds-xprops"> - <title>Additional Pooling <classname>DataSource</> Configuration Properties</title> - - <tgroup cols=3> - <thead> - <row> - <entry>Property</entry> - <entry>Type</entry> - <entry>Description</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>dataSourceName</literal></entry> - <entry><type>String</type></entry> - <entry>Every pooling <literal>DataSource</literal> must have a - unique name.</entry> - </row> - - <row> - <entry><literal>initialConnections</literal></entry> - <entry><type>int</type></entry> - <entry>The number of database connections to be created - when the pool is initialized.</entry> - </row> - - <row> - <entry><literal>maxConnections</literal></entry> - <entry><type>int</type></entry> - <entry>The maximum number of open database connections to - allow. When more connections are requested, the caller - will hang until a connection is returned to the pool.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para><xref linkend="jdbc-ds-example"> shows an example of typical application code using a - pooling <literal>DataSource</literal>.</para> - - <example id="jdbc-ds-example"> - <title><literal>DataSource</literal> Code Example</title> - - <para> - Code to initialize a pooling <classname>DataSource</classname> might look like this: -<programlisting> -Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource(); -source.setDataSourceName("A Data Source"); -source.setServerName("localhost"); -source.setDatabaseName("test"); -source.setUser("testuser"); -source.setPassword("testpassword"); -source.setMaxConnections(10); -</programlisting> - Then code to use a connection from the pool might look - like this. Note that it is critical that the connections - are eventually closed. Else the pool will <quote>leak</> connections and - will eventually lock all the clients out. -<programlisting> -Connection con = null; -try { - con = source.getConnection(); - // use connection -} catch (SQLException e) { - // log error -} finally { - if (con != null) { - try { con.close(); } catch (SQLException e) {} - } -} -</programlisting> - </para> - </example> - </sect2> - - <sect2 id="jdbc-jndi"> - <title>Data Sources and <acronym>JNDI</acronym></title> - - <indexterm zone="jdbc-jndi"> - <primary>JNDI</primary> - </indexterm> - - <para> - All the <literal>ConnectionPoolDataSource</literal> and - <literal>DataSource</literal> implementations can be stored - in <acronym>JNDI</acronym>. In the case of the nonpooling - implementations, a new instance will be created every time the - object is retrieved from <acronym>JNDI</acronym>, with the - same settings as the instance that was stored. For the - pooling implementations, the same instance will be retrieved - as long as it is available (e.g., not a different - <acronym>JVM</acronym> retrieving the pool from - <acronym>JNDI</acronym>), or a new instance with the same - settings created otherwise. - </para> - - <para> - In the application server environment, typically the - application server's <literal>DataSource</literal> instance - will be stored in <acronym>JNDI</acronym>, instead of the - <productname>PostgreSQL</productname> - <literal>ConnectionPoolDataSource</literal> implementation. - </para> - - <para> - In an application environment, the application may store - the <literal>DataSource</literal> in <acronym>JNDI</acronym> - so that it doesn't have to make a reference to the - <literal>DataSource</literal> available to all application - components that may need to use it. An example of this is - shown in <xref linkend="jdbc-ds-jndi">. - </para> - - <example id="jdbc-ds-jndi"> - <title><classname>DataSource</classname> <acronym>JNDI</acronym> Code Example</title> - - <para> - Application code to initialize a pooling <classname>DataSource</classname> and add - it to <acronym>JNDI</acronym> might look like this: -<programlisting> -Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource(); -source.setDataSourceName("A Data Source"); -source.setServerName("localhost"); -source.setDatabaseName("test"); -source.setUser("testuser"); -source.setPassword("testpassword"); -source.setMaxConnections(10); -new InitialContext().rebind("DataSource", source); -</programlisting> - Then code to use a connection from the pool might look - like this: -<programlisting> -Connection con = null; -try { - DataSource source = (DataSource)new InitialContext().lookup("DataSource"); - con = source.getConnection(); - // use connection -} catch (SQLException e) { - // log error -} catch (NamingException e) { - // DataSource wasn't found in JNDI -} finally { - if (con != null) { - try { con.close(); } catch (SQLException e) {} - } -} -</programlisting> - </para> - </example> - </sect2> - - </sect1> - - <sect1 id="jdbc-reading"> - <title>Further Reading</title> - - <para> - If you have not yet read it, you are advised you read the - <acronym>JDBC</acronym> <acronym>API</acronym> Documentation - (supplied with Sun's <acronym>JDK</acronym>) and the - <acronym>JDBC</acronym> Specification. Both are available from - <ulink - url="http://java.sun.com/products/jdbc/index.html"></ulink>. - </para> - - <para> - <ulink - url="http://jdbc.postgresql.org"></ulink> - contains updated information not included in this chapter and - also offers precompiled drivers. - </para> - </sect1> -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode:sgml -sgml-omittag:nil -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:1 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:"./reference.ced" -sgml-exposed-tags:nil -sgml-local-catalogs:("/usr/lib/sgml/catalog") -sgml-local-ecat-files:nil -End: ---> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 2fbbf40130..7e2e76de70 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,5 +1,5 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.62 2003/11/29 19:51:37 pgsql Exp $ +$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.63 2004/01/19 21:20:06 tgl Exp $ --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ @@ -179,7 +179,6 @@ $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.62 2003/11/29 19:51:37 pgsql E &lobj; &libpgtcl; &ecpg; - &jdbc; &infoschema; </part> diff --git a/src/Makefile.global.in b/src/Makefile.global.in index 68c3bf8078..f3a1d39182 100644 --- a/src/Makefile.global.in +++ b/src/Makefile.global.in @@ -1,5 +1,5 @@ # -*-makefile-*- -# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.172 2003/12/19 23:29:15 momjian Exp $ +# $PostgreSQL: pgsql/src/Makefile.global.in,v 1.173 2004/01/19 21:20:06 tgl Exp $ #------------------------------------------------------------------------------ # All PostgreSQL makefiles include this file and use the variables it sets, @@ -111,7 +111,6 @@ override docdir := $(docdir)/postgresql endif endif -javadir := $(DESTDIR)$(datadir)/java localedir := @localedir@ @@ -121,7 +120,6 @@ localedir := @localedir@ # # Records the choice of the various --enable-xxx and --with-xxx options. -with_java = @with_java@ with_perl = @with_perl@ with_python = @with_python@ with_tcl = @with_tcl@ @@ -209,7 +207,6 @@ perl_embed_ldflags = @perl_embed_ldflags@ # Miscellaneous -ANT = @ANT@ AWK = @AWK@ LN_S = @LN_S@ MSGFMT = @MSGFMT@ diff --git a/src/interfaces/Makefile b/src/interfaces/Makefile index 052d66dd14..1fa91d5375 100644 --- a/src/interfaces/Makefile +++ b/src/interfaces/Makefile @@ -4,7 +4,7 @@ # # Copyright (c) 1994, Regents of the University of California # -# $PostgreSQL: pgsql/src/interfaces/Makefile,v 1.51 2003/11/29 19:52:08 pgsql Exp $ +# $PostgreSQL: pgsql/src/interfaces/Makefile,v 1.52 2004/01/19 21:20:06 tgl Exp $ # #------------------------------------------------------------------------- @@ -14,16 +14,12 @@ include $(top_builddir)/src/Makefile.global DIRS := libpq ecpg -ALLDIRS := $(DIRS) libpgtcl jdbc +ALLDIRS := $(DIRS) libpgtcl ifeq ($(with_tcl), yes) DIRS += libpgtcl endif -ifeq ($(with_java), yes) -DIRS += jdbc -endif - all install installdirs uninstall dep depend distprep: @for dir in $(DIRS); do $(MAKE) -C $$dir $@ || exit; done diff --git a/src/makefiles/Makefile.cygwin b/src/makefiles/Makefile.cygwin index 0449313276..b3ee00c09e 100644 --- a/src/makefiles/Makefile.cygwin +++ b/src/makefiles/Makefile.cygwin @@ -1,4 +1,4 @@ -# $PostgreSQL: pgsql/src/makefiles/Makefile.cygwin,v 1.3 2003/11/29 19:52:12 pgsql Exp $ +# $PostgreSQL: pgsql/src/makefiles/Makefile.cygwin,v 1.4 2004/01/19 21:20:06 tgl Exp $ DLLTOOL= dlltool DLLWRAP= dllwrap BE_DLLLIBS= -L$(top_builddir)/src/backend -lpostgres @@ -32,6 +32,4 @@ ifneq (,$(findstring src/pl/plpython,$(subdir))) override CPPFLAGS+= -DUSE_DL_IMPORT endif -override javadir := '$(shell cygpath -w $(javadir))' - sqlmansect = 7 |