jdbc.xml

<?xml version="1.0" encoding="ISO-8859-15"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

 <chapter id="jdbc">
  <title>Interface <acronym>JDBC</acronym></title>

  <indexterm zone="jdbc">
   <primary>JDBC</primary>
  </indexterm>

  <indexterm zone="jdbc">
   <primary>Java</primary>
  </indexterm>

  <para>
   <acronym>JDBC</acronym> est une <acronym>API</acronym> au c&oelig;ur de
   Java 1.1 et ultérieur. Elle fournit un ensemble standard d'interfaces vers
   les bases de données compatibles <acronym>SQL</acronym>.
  </para>

  <para>
   <productname>PostgreSQL</productname> fournit un pilote <acronym>JDBC</acronym> de
   <firstterm>type 4</firstterm>. Le type 4 indique que le pilote est écrit en
   pur Java et communique dans le propre protocole réseau du système des bases
   de données. De ce fait, le pilote est indépendant de la plate-forme.
   Une fois compilé, le pilote peut être utilisé sur tout système.
  </para>

  <para>
   Ce chapitre n'a pas pour but d'être un guide complet de programmation
   <acronym>JDBC</acronym> mais devrait vous aider à commencer. Pour plus
   d'informations, référez-vous à la documentation standard de
   l'<acronym>API</acronym> <acronym>JDBC</acronym>. De même, jetez un &oelig;il
   sur les exemples inclus dans les sources.
  </para>

 <sect1 id="jdbc-setup">
  <title>Configurer le pilote <acronym>JDBC</acronym></title>

  <para>
   Cette section décrit les étapes nécessaires avant de commencer à écrire ou
exécuter des programmes utilisant l'interface <acronym>JDBC</acronym>.
  </para>

  <sect2 id="jdbc-build">
   <title>Obtenir le pilote</title>

   <para>
    Les versions pré compilées du pilote sont téléchargeables à partir du <ulink
    url="http://jdbc.postgresql.org">site web <acronym>JDBC</acronym> pour
    <productname>PostgreSQL</productname></ulink>.
   </para>

   <para>
    Vous pouvez aussi construire le pilote à partir des sources mais
    vous n'avez réellement besoin de le faire que si vous modifiez le code
    source. Pour plus de détails, référez-vous aux <link
    linkend="installation">instructions d'installation</link> de
    <productname>PostgreSQL</productname>. Après installation, le pilote devrait se
    trouver dans
    <filename><replaceable>PREFIX</replaceable>/share/java/postgresql.jar</filename>. Le
    pilote résultant sera construit pour la version de Java que vous utilisez.
    Si vous construisez avec un <acronym>JDK</acronym>, version 1.1, vous construirez
    une version qui supporte la spécification <acronym>JDBC</acronym> 1,
    si vous construisez avec un <acronym>JDK</acronym> 1.2 ou 1.3, vous construirez une
    version supportant la spécification <acronym>JDBC</acronym> 2, et enfin si vous
    construisez avec un <acronym>JDK</acronym> 1.4, vous construirez une version
    supportant la spécification <acronym>JDBC</acronym> 3.
   </para>
  </sect2>

  <sect2 id="jdbc-classpath">
   <title>Configurer le chemin des classes</title>

   <indexterm zone="jdbc-classpath">
    <primary>chemin des classes</primary>
   </indexterm>

   <indexterm zone="jdbc-classpath">
    <primary>CLASSPATH</primary>
   </indexterm>

   <para>
    Pour utiliser le pilote, l'archive JAR (nommée
    <filename>postgresql.jar</filename> si vous l'avez construite à partir des
    sources, sinon elle sera probablement nommée
    <filename>pg&majorversion;jdbc1.jar</filename>,
    <filename>pg&majorversion;jdbc2.jar</filename> ou
    <filename>pg&majorversion;jdbc3.jar</filename> respectivement pour
    les versions <acronym>JDBC</acronym> 1, <acronym>JDBC</acronym> 2 et <acronym>JDBC</acronym>
    3) a besoin d'être inclue dans le chemin des classes, soit en le plaçant
    dans la variable d'environnement <envar>CLASSPATH</envar> soit en utilisant
    des options sur la ligne de commande <command>java</command>.
   </para>

   <para>
    Pour l'instant, supposons que nous avons une application qui utilise le
    pilote <acronym>JDBC</acronym> pour accéder à une base de données et que
    l'application est installée en tant que
    <filename>/usr/local/lib/myapp.jar</filename>. Le pilote <acronym>JDBC</acronym> de
    PostgreSQL est installé comme
    <filename>/usr/local/pgsql/share/java/postgresql.jar</filename>. Pour lancer
    l'application, nous pourrions utiliser&nbsp;:
<programlisting>export CLASSPATH=/usr/local/lib/myapp.jar:/usr/local/pgsql/share/java/postgresql.jar:.
java MyApp
</programlisting>
    </para>

    <para>
     Charger le pilote dans l'application est traité dans
     <xref linkend="jdbc-use"/>.
    </para>
  </sect2>

  <sect2 id="jdbc-prepare">
   <title>Préparer le serveur de bases de données pour
    <acronym>JDBC</acronym></title>

   <para>
    Comme Java utilise uniquement les connexions TCP/IP, le serveur
    <application>PostgreSQL</application> doit être configuré pour accepter les
    connexions TCP/IP. Ceci se fait en configurant <literal>tcpip_socket =
    true</literal> dans le fichier <filename>postgresql.conf</filename> ou en
    fournissant l'option <option>-i</option> au lancement de
    <command>postmaster</command>.
   </para>

   <para>
    De plus, la méthode d'authentification du client dans le fichier
    <filename>pg_hba.conf</filename> pourrait avoir besoin d'être configurée.
    Référez-vous à <xref linkend="client-authentication"/> pour plus de détails.
    Le pilote <acronym>JDBC</acronym> supporte les méthodes d'accès
    <literal>trust</literal>, <literal>ident</literal>, <literal>password</literal>, <literal>md5</literal>,
    et <literal>crypt</literal>.
   </para>
  </sect2>
 </sect1>

 <sect1 id="jdbc-use">
  <title>Initialiser le pilote</title>

  <para>
   Cette section décrit comment charger et initialiser le pilote
   <acronym>JDBC</acronym> dans vos programmes.
  </para>

  <sect2 id="jdbc-import">
   <title>Importer <acronym>JDBC</acronym></title>

   <para>
    Toute source utilisant <acronym>JDBC</acronym> a besoin d'importer le paquet
    <literal>java.sql</literal> en utilisant&nbsp;:

<programlisting>import java.sql.*;
</programlisting>
   </para>

    <note>
     <para>
      N'importez pas le paquet <literal>org.postgresql</literal>. Si vous le
      faites, vos sources ne compileront pas car <command>javac</command> sera
      en pleine confusion.
     </para>
    </note>
  </sect2>

  <sect2 id="jdbc-load">
   <title>Charger le pilote</title>

   <para>
    Avant de vous connecter à une base de données, vous avez besoin de charger
    le pilote. Deux méthodes sont disponibles et celui à utiliser dépend de
    votre code.
   </para>

   <para>
    Dans la première méthode, votre code charge implicitement le pilote en
    utilisant la méthode <function>Class.forName()</function>. Pour
    <productname>PostgreSQL</productname>, vous devriez utiliser&nbsp;:

<programlisting>Class.forName("org.postgresql.Driver");
</programlisting>

    Ceci charge le pilote et, pendant le chargement, le pilote s'enregistre
    lui-même avec <acronym>JDBC</acronym>.
   </para>

    <note>
     <para>
      La méthode <function>forName()</function> peut renvoyer
      <classname>ClassNotFoundException</classname> si le pilote n'est pas
      disponible.
     </para>
    </note>

   <para>
    C'est la méthode la plus communément utilisée mais elle oblige votre
    code à utiliser uniquement <productname>PostgreSQL</productname>. Si votre
    code peut accéder à d'autres systèmes de bases de données dans le futur
    et que vous ne souhaitez pas utiliser d'extensions spécifiques à
    <productname>PostgreSQL</productname>, alors la deuxième méthode est
    conseillée.
   </para>

   <para>
    La seconde méthode passe le pilote en paramètre à la <acronym>JVM</acronym>
    lors de son lancement en utilisant l'argument <option>-D</option>.
    Exemple&nbsp;:
<programlisting>java -Djdbc.drivers=org.postgresql.Driver example.ImageViewer
</programlisting>
    Dans cet exemple, la <acronym>JVM</acronym> tentera de charger le pilote
    pendant son initialisation. Ceci fait, <classname>ImageViewer</classname>
    est lancée.
   </para>

   <para>
    Cette méthode est la meilleure car elle permet à
    votre code d'être utilisé avec d'autres paquets de bases de données sans
    recompiler le code. Le seul élément qui pourrait changer est
    l'<acronym>URL</acronym> de connexion. Ce point est traité tout de suite après.
   </para>

   <para>
    Une dernière chose&nbsp;: Quand votre code essaie d'ouvrir une
    <classname>Connection</classname> et que vous obtenez une
    <classname>SQLException</classname> de type <errorname>No driver
    available</errorname> , ceci est probablement dû au fait que pilote ne fait
    pas partie du chemin de classe ou que la valeur du paramètre n'est pas
    correcte.
   </para>
  </sect2>

  <sect2 id="jdbc-connect">
   <title>Se connecter à la base de données</title>

   <para>
    Avec <acronym>JDBC</acronym>, une base de données est représentée par une
    <acronym>URL</acronym> (Uniform Resource Locator). Avec
    <application>PostgreSQL</application>, elle peut prendre l'une des formes
    suivantes&nbsp;:

    <itemizedlist>
     <listitem>
<synopsis>jdbc:postgresql:<replaceable class="parameter">base_de_données</replaceable>
</synopsis>
     </listitem>

     <listitem>
<synopsis>jdbc:postgresql://<replaceable class="parameter">hôte</replaceable>/<replaceable
class="parameter">base_de_données</replaceable>
</synopsis>
     </listitem>

     <listitem>
<synopsis>jdbc:postgresql://<replaceable class="parameter">hôte</replaceable>:<replaceable
class="parameter">port</replaceable>/<replaceable
class="parameter">base_de_données</replaceable>
</synopsis>
     </listitem>
    </itemizedlist>

    Les paramètres ont les significations suivantes&nbsp;:

    <variablelist>
     <varlistentry>
      <term>
       <replaceable class="parameter">hôte</replaceable>
      </term>
      <listitem>
       <para>
        Le nom d'hôte du serveur. Par défaut, <literal>localhost</literal>.
        Pour spécifier une adresse IPv6, vous devez englober le paramètre
        <replaceable class="parameter">hôte</replaceable> avec des crochets, par
        exemple&nbsp;:
<programlisting>jdbc:postgresql://[::1]:5740/accounting
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       <replaceable class="parameter">port</replaceable>
      </term>
      <listitem>
       <para>
        Le numéro de port sur lequel le serveur est en écoute. Par défaut, il
        s'agit du numéro de port standard de
        <productname>PostgreSQL</productname> (5432).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>
       <replaceable class="parameter">base_de_données</replaceable>
      </term>
      <listitem>
       <para>
        Le nom de la base de données.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    Pour vous connecter, vous avez besoin d'une instance de
    <classname>Connection</classname> provenant de <acronym>JDBC</acronym>.
    Pour cela, vous utilisez la méthode
    <function>DriverManager.getConnection()</function>&nbsp;:

<programlisting>Connection db = DriverManager.getConnection(url, username, password);
</programlisting>
   </para>
  </sect2>

  <sect2 id="jdbc-disconnect">
   <title>Fermer la connexion</title>

   <para>
    Pour fermer la connexion de la base de données, appelez simplement la
    méthode <function>close()</function> pour la 
    <classname>Connection</classname>&nbsp;:
<programlisting>db.close();
</programlisting>
   </para>
  </sect2>
 </sect1>


  <sect1 id="jdbc-query">
   <title>Lancer une requête et traiter les résultats</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>
    À chaque fois que vous voulez exécuter des instructions
    <acronym>SQL</acronym> sur la base de données, vous avez besoin d'une
    instance <classname>Statement</classname> ou
    <classname>PreparedStatement</classname>. Une fois que vous avez un
    <classname>Statement</classname> ou un
    <classname>PreparedStatement</classname>, vous pouvez lancer une requête.
Elle renvoie une instance <classname>ResultSet</classname> contenant le
    résultat complet (voir <xref linkend="jdbc-query-with-cursor"/> pour savoir
    comment modifier ce comportement). <xref linkend="jdbc-query-example"/>
    illustre ce processus.
   </para>

   <example id="jdbc-query-example">
    <title>Traiter une requête simple avec <acronym>JDBC</acronym></title>

    <para>
     Cet exemple lance une requête simple et affiche la première colonne de
chaque ligne en utilisant un <classname>Statement</classname>.
<programlisting>Statement st = db.createStatement();
ResultSet rs = st.executeQuery("SELECT * FROM matable WHERE macolonne = 500");
while (rs.next()) {
    System.out.print("Colonne 1 renvoyée ");
    System.out.println(rs.getString(1));
}
rs.close();
st.close();
</programlisting>
    </para>

    <para>
     Cet exemple lance la même requête que précédemment mais utilise un
     <classname>PreparedStatement</classname> et une valeur liée dans la
     requête.
<programlisting>int foovalue = 500;
PreparedStatement st = db.prepareStatement("SELECT * FROM matable WHERE
ma colonne = ?");
st.setInt(1, valeur);
ResultSet rs = st.executeQuery();
while (rs.next()) {
    System.out.print("Colonne 1 renvoyée ");
    System.out.println(rs.getString(1));
}
rs.close();
st.close();
</programlisting>
    </para>
   </example>

   <sect2 id="jdbc-query-with-cursor">
     <title>Obtenir des résultats basés sur un curseur</title>

     <para>Par défaut, le pilote récupère tous les résultats d'une requête en
     une seule fois. Ceci présente des inconvénients pour les gros ensembles de
     données. Le pilote JDBC fournit un moyen de baser un
     <classname>ResultSet</classname> sur un curseur de bases de données pour ne
     récupérer qu'un petit nombre de lignes.</para>

     <para>Un bloc de lignes est en cache du côté client de la
     connexion et, une fois qu'il est entièrement lu, le prochain bloc de 
     lignes est récupéré en repositionnant le curseur.
     </para>

     <example>
       <title>Configurer la taille de la récupération pour activer ou désactiver
        les curseurs.</title>

     <para>Passer le code en mode curseur revient à configurer
     la taille de récupération de <classname>Statement</classname> à la bonne
     taille. Le reconfigurer à 0 fera que toutes les lignes seront en cache (le
     comportement par défaut).

<programlisting>Statement st = db.createStatement();
// Active le curseur.
st.setFetchSize(50);
ResultSet rs = st.executeQuery("SELECT * FROM matable");
while (rs.next()) {
   System.out.print("une ligne a été renvoyée.");
}
rs.close();
// Désactive le curseur.
st.setFetchSize(0);
ResultSet rs = st.executeQuery("SELECT * FROM matable");
while (rs.next()) {
   System.out.print("toutes les lignes ont été renvoyées.");
}
rs.close();
// Ferme l'instruction.
st.close();
</programlisting>
     </para>
   </example>
   </sect2>

   <sect2>
    <title>Utiliser les interfaces <classname>Statement</classname> ou
     <classname>PreparedStatement</classname></title>

    <para>
     Points à considérer pour l'utilisation de l'interface
     <classname>Statement</classname> ou
     <classname>PreparedStatement</classname>&nbsp;:

     <itemizedlist>
      <listitem>
       <para>
        Vous pouvez utiliser une simple instance
        <classname>Statement</classname> autant de fois que vous le voulez. Vous
        pouvez aussi en créer une dès que vous avez ouvert la connexion et
        l'utiliser pendant toute la durée de la connexion. Mais vous devez
        vous rappeler qu'un seul <classname>ResultSet</classname> peut
        exister par <classname>Statement</classname> ou
        <classname>PreparedStatement</classname> à un moment donné.
       </para>
      </listitem>

      <listitem>
       <para>
        Si vous avez besoin de lancer une requête pendant le traitement d'un
        <classname>ResultSet</classname>, il suffit de créer et
        utiliser un autre <classname>Statement</classname>.
       </para>
      </listitem>

      <listitem>
       <para>
        Si vous utilisez les threads et que plusieurs personnes
        utilisent la base de données, vous pouvez utiliser un
        <classname>Statement</classname> pour chaque thread. Référez-vous à
        <xref linkend="jdbc-thread"/> si vous pensez utiliser les threads car il
        couvre quelques points importants.
       </para>
      </listitem>

      <listitem>
       <para>
        Une fois que vous avez fini d'utiliser
        <classname>Statement</classname> ou
        <classname>PreparedStatement</classname>, vous devez le fermer.
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </sect2>

   <sect2>
    <title>Utiliser l'interface <classname>ResultSet</classname></title>

    <para>
     Points à considérer pour l'utilisation de l'interface
     <classname>ResultSet</classname>&nbsp;:

     <itemizedlist>
      <listitem>
       <para>
        Avant de lire une valeur, vous devez appeler la fonction
        <function>next()</function>. Elle renvoie true s'il existe un résultat
        mais, surtout, elle prépare le traitement de la ligne.
       </para>
      </listitem>

      <listitem>
       <para>
        La spécification <acronym>JDBC</acronym> précise que vous ne devez accéder un
        champ que une fois seulement. Il est plus sûr de se tenir à cette règle bien
qu'actuellement le pilote <productname>PostgreSQL</productname> vous
        autorise à accéder à un champ autant de fois que vous le souhaitez.
       </para>
      </listitem>

      <listitem>
       <para>
        Vous devez fermer un <classname>ResultSet</classname> en appelant
        <function>close()</function> une fois que vous avez fini de
        l'utiliser.
       </para>
      </listitem>

      <listitem>
       <para>
        Lorsque vous faites une autre requête avec le
        <classname>Statement</classname> utilisé pour créer un
        <classname>ResultSet</classname>, l'instance
        <classname>ResultSet</classname> initialement ouverte est fermée
        automatiquement.
       </para>
      </listitem>

     </itemizedlist>
    </para>
   </sect2>
  </sect1>

  <sect1 id="jdbc-update">
   <title>Exécuter des mises à jour</title>

   <para>
    Pour modifier les données (réaliser un <command>INSERT</command>,
    <command>UPDATE</command> ou <command>DELETE</command>), vous utilisez la
    méthode <function>executeUpdate()</function>. Cette méthode est similaire à
    la méthode <function>executeQuery()</function> utilisée pour exécuter une
    instruction <command>SELECT</command> mais elle ne renvoie pas de
    <classname>ResultSet</classname>&nbsp;; à la place, elle renvoie le nombre de
    lignes affectées par l'instruction <command>INSERT</command>,
    <command>UPDATE</command> ou <command>DELETE</command>. <xref
    linkend="jdbc-delete-example"/> illustre cette utilisation.
   </para>

  <example id="jdbc-delete-example">
   <title>Supprimer des lignes dans <acronym>JDBC</acronym></title>
   <para>
     Cet exemple exécute une instruction <command>DELETE</command> simple et
     affiche le nombre de lignes réellement supprimées.
<programlisting>int valeur = 500;
PreparedStatement st = db.prepareStatement("DELETE FROM matable WHERE macolonne
= ?");
st.setInt(1, valeur);
int rowsDeleted = st.executeUpdate();
System.out.println(rowsDeleted + " lignes supprimées");
st.close();
</programlisting>
   </para>
  </example>
  </sect1>


  <sect1 id="jdbc-callproc">
    <title>Appeler des procédures stockées</title>

<para>Le pilote JDBC de <productname>PostgreSQL</productname> supporte
     totalement l'appel de procédures stockées
     <productname>PostgreSQL</productname>.</para>

    <example id="jdbc-call-function">
      <title>Appeler une fonction interne</title>

      <para>Cet exemple montre comment appeler une fonction interne
       de <productname>PostgreSQL</productname>, <command>upper</command>, qui
       convertit simplement l'argument fourni en majuscule.

<programlisting>// Désactive les transactions.
con.setAutoCommit(false);
// Appel de procédure.
CallableStatement upperProc = con.prepareCall("{ ? = call upper( ? ) }");
upperProc.registerOutParameter(1, Types.VARCHAR);
upperProc.setString(2, "minuscule vers majuscule");
upperProc.execute();
String upperCased = upperProc.getString(1);
upperProc.close();
</programlisting>
      </para>
    </example>

    <sect2>
      <title>Utiliser l'interface
       <classname>CallableStatement</classname></title>

      <para>
	Toutes les considérations s'appliquant à
	<classname>Statement</classname> et
	<classname>PreparedStatement</classname> s'appliquent à
	<classname>CallableStatement</classname> mais vous devez considérer une
	restriction supplémentaire&nbsp;:
      </para>

      <itemizedlist>
	<listitem>
	  <para>Vous devez être à l'intérieur d'une transaction pour
      appeler une procédure stockée.</para>
	</listitem>
      </itemizedlist>

    </sect2>

    <sect2>
      <title>Obtenir un <classname>ResultSet</classname> à partir d'une
       procédure stockée</title>
     
      <para>Les procédures stockées de <productname>PostgreSQL</productname>
       peuvent renvoyer des résultats au moyen d'une valeur de type
       <type>refcursor</type>. Un <type>refcursor</type>.</para>

      <para>En extension de l'API JDBC, le pilote JDBC de
       <productname>PostgreSQL</productname> peut renvoyer des valeurs de type
       <type>refcursor</type> comme valeurs
       <classname>ResultSet</classname>.</para>

      <example id="get-refcursor-from-function-call">
	<title>Obtenir des valeurs <type>refcursor</type> à partir d'une
         fonction</title>

	<para>Lors de l'appel d'une fonction renvoyant un
	  <type>refcursor</type>, vous devez convertir le type de retour de
	  <function>getObject</function> à un
	  <classname>ResultSet</classname></para>

<programlisting>// Désactive les transactions.
con.setAutoCommit(false);
// Appel de procédure.
CallableStatement proc = con.prepareCall("{ ? = call fait_requete ( ? ) }");
proc.registerOutParameter(1, Types.Other);
proc.setInt(2, -1);
proc.execute();
ResultSet results = (ResultSet) proc.getObject(1);
while (results.next()) {
  // faire quelque chose avec les résultats...
}
results.close();
proc.close();
</programlisting>
      </example>

      <para>Il est aussi possible de traiter la valeur de 
       retour <type>refcursor</type> comme un type distinct en lui-même. Le
       pilote JDBC fournit la classe
       <classname>org.postgresql.PGRefCursorResultSet</classname> dans ce
       but.</para>

      <example>
	<title>Traiter <type>refcursor</type> comme un type distinct</title>

<programlisting>con.setAutoCommit(false);
CallableStatement proc = con.prepareCall("{ ? = call fait_requete ( ? ) }");
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>Créer et modifier les objets de la base de données</title>

   <para>
    Pour créer, modifier ou supprimer un objet de la base de données comme une 
    table ou une vue, vous utilisez la méthode <function>execute()</function>.
    Cette méthode est similaire à la méthode <function>executeQuery()</function>
    mais elle ne renvoie pas de résultat. <xref linkend="jdbc-drop-table-example"/>
    illustre cette utilisation.
   </para>

  <example id="jdbc-drop-table-example">
   <title>Supprimer une table avec JDBC</title>
   <para>
     Cet exemple supprime une table.
<programlisting>Statement st = db.createStatement();
st.execute("DROP TABLE matable");
st.close();
</programlisting>
   </para>
  </example>
  </sect1>

 <sect1 id="jdbc-binary-data">
  <title>Stocker des données binaires</title>

  <indexterm zone="jdbc-binary-data">
   <primary>bytea</primary>
   <secondary sortas="JDBC">en JDBC</secondary>
  </indexterm>

  <indexterm zone="jdbc-binary-data">
   <primary>gros objets</primary>
   <secondary sortas="JDBC">en JDBC</secondary>
  </indexterm>

  <para>
    <application>PostgreSQL</application> fournit deux façons distinctes de
    stocker des données binaires. Elles peuvent être stockées dans une table en
    utilisant le type de données <type>bytea</type> ou en utilisant la
    fonctionnalité des gros objets qui stockent les données binaires dans une
    table séparée dans un format spécial et se réfère à cette table en stockant
    une valeur de type <type>oid</type> dans votre table.
  </para>

  <para>
    Pour déterminer quelle méthode est appropriée, vous avez besoin de
    comprendre les limitations de chaque méthode. Le type de données
    <type>bytea</type> ne convient pas bien pour stocker de grosses
    quantités de données binaires. Alors qu'une colonne de type
    <type>bytea</type> peut contenir jusqu'à 1&nbsp;Go de données binaires, elle
    demanderait une énorme quantité de mémoire pour traiter une telle valeur. La
    méthode des objets larges convient mieux pour stocker de très grands objets
    mais a ses propres limitations. Spécifiquement, supprimer une ligne
    contenant une référence de gros objet ne supprime pas le gros objet.
    Supprimer celui-ci est une opération qui doit être réalisée séparément. Les
    gros objets ont aussi quelques problèmes de sécurité car toute personne
    connectée à la base de données peut visualiser et/modifier tout gros objet
    même s'il n'a pas le droit de visualiser/mettre à jour la ligne contenant la
    référence au gros objet.
  </para>

  <para>
    La version 7.2 a été la première à disposer d'un pilote
    <acronym>JDBC</acronym> supportant le type de données <type>bytea</type>.
    L'introduction de cette fonctionnalité dans la 7.2 a introduit une
    changement dans le comportement comparé aux précédentes versions. Depuis la
    7.2, les méthodes <function>getBytes()</function>,
    <function>setBytes()</function>, <function>getBinaryStream()</function> et
    <function>setBinaryStream()</function> opèrent sur le type de données
    <type>bytea</type>. En 7.1 et pour les versions précédentes, ces méthodes
    opéraient sur le type de données <type>oid</type> associé avec chaque gros
    objet. Il est possible de revenir à l'ancien comportement de la version 7.1
    en initialisant la propriété <literal>compatible</literal> de l'objet
    <classname>Connection</classname> avec la valeur <literal>7.1</literal>.
  </para>

  <para>
    Pour utiliser le type de données <type>bytea</type>, vous devez simplement
    utiliser les méthodes <function>getBytes()</function>,
    <function>setBytes()</function>,
    <function>getBinaryStream()</function> ou
    <function>setBinaryStream()</function>.
  </para>

  <para>
    Pour utiliser la fonctionnalité des gros objets, vous devez utiliser soit
    la classe <classname>LargeObject</classname> fournie par le pilote
    <acronym>JDBC</acronym> de <application>PostgreSQL</application> soit
    utiliser les méthodes <function>getBLOB()</function> et
    <function>setBLOB()</function>.
  </para>

  <important>
   <para>
    Vous devez accéder aux gros objets à l'intérieur d'un bloc de transaction
    <acronym>SQL</acronym>. Vous pouvez lancer un bloc de transaction en
    appelant <function>setAutoCommit(false)</function>.
   </para>
  </important>

  <note>
   <para>
      Dans une prochaine version du pilote <acronym>JDBC</acronym> driver, les
      méthodes <function>getBLOB()</function> et <function>setBLOB()</function>
      n'interagiront plus avec les gros objets mais fonctionneront avec le type
      de données <type>bytea</type>. Donc, il vous est recommandé d'utiliser
      l'<acronym>API</acronym>  de <classname>LargeObject</classname> si vous
      pensez utiliser des gros objets.
   </para>
  </note>

  <para>
   <xref linkend="jdbc-binary-data-example"/> contient quelques exemples sur le
   traitement de données binaires en utilisant le pilote <acronym>JDBC</acronym> de
   PostgreSQL.
  </para>

  <example id="jdbc-binary-data-example">
   <title>Traiter des données binaires avec <acronym>JDBC</acronym></title>

   <para>
    Par exemple, supposez que vous avez une table contenant des noms de fichiers
    d'images et que vous souhaitez aussi stocker l'image dans une colonne de
    type <type>bytea</type>&nbsp;:
<programlisting>CREATE TABLE images (nomimg text, img bytea);
</programlisting>
   </para>

   <para>
    Pour insérer une image, vous utiliserez&nbsp;:
<programlisting>File file = new File("monimage.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>

    Ici, <function>setBinaryStream()</function> transfère un certain nombre
    d'octets d'un flux dans la colonne de type <type>bytea</type>. Ceci
pourrait aussi être fait en utilisant la méthode
    <function>setBytes()</function> si le contenu de l'image était déjà dans un
    <classname>byte[]</classname>. 
   </para>

   <para>
    Récupérer une image est encore plus simple. (Nous utilisons
    <classname>PreparedStatement</classname>, mais la classe
    <classname>Statement</classname> pourrait très bien la remplacer.)

<programlisting>PreparedStatement ps = con.prepareStatement("SELECT img FROM images WHERE nomimg
= ?");
ps.setString(1, "monimage.gif");
ResultSet rs = ps.executeQuery();
if (rs != NULL) {
    while (rs.next()) {
        byte[] imgBytes = rs.getBytes(1);
        // utiliser les données ici...
    }
    rs.close();
}
ps.close();
</programlisting>
   </para>

   <para>
    Ici, les données binaires ont été récupérées dans un
    <classname>byte[]</classname>. À la place, vous pourriez avoir utilisé un
    objet <classname>InputStream</classname>.
   </para>

   <para>
    Vous pouvez aussi stocker un très gros fichier et vouloir utiliser
    l'<acronym>API</acronym> <classname>LargeObject</classname>  pour stocker le
    fichier&nbsp;:
<programlisting>CREATE TABLE imageslo (nomimg text, oidimg oid);
</programlisting>
   </para>

   <para>
    Pour insérer une image, vous pourriez&nbsp;:
<programlisting>// Tous les appels à l'API LargeObject doivent se faire dans un bloc de
// transaction
conn.setAutoCommit(false);

// Récupérer le gestionnaire des gros objets pour lui faire réaliser les
// opérations
LargeObjectManager lobj =
((org.postgresql.PGConnection)conn).getLargeObjectAPI();

// Créer un nouveau gros objet
int oid = lobj.create(LargeObjectManager.READ | LargeObjectManager.WRITE);

// Ouvrir le gros objet en écriture
LargeObject obj = lobj.open(oid, LargeObjectManager.WRITE);

// Maintenant, ouvrir le fichier
File file = new File("monimage.gif");
FileInputStream fis = new FileInputStream(file);

// Copier les données du fichier dans le gro objet
byte buf[] = new byte[2048];
int s, tl = 0;
while ((s = fis.read(buf, 0, 2048)) > 0) {
    obj.write(buf, 0, s);
    tl += s;
}

// Fermer le gros objet
obj.close();

// Maintenant, insérer la ligne dans 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>
    Pour récupérer l'image du gros objet&nbsp;:

<programlisting>// Tous les appels à l'API LargeObject doivent se faire dans un bloc de
// transaction
conn.setAutoCommit(false);

// Récupérer le gestionnaire des gros objets pour lui faire réaliser les
// opérations
LargeObjectManager lobj =
((org.postgresql.PGConnection)conn).getLargeObjectAPI();

PreparedStatement ps = con.prepareStatement("SELECT oidimg FROM imageslo
WHERE nomimg = ?");
ps.setString(1, "monimage.gif");
ResultSet rs = ps.executeQuery();
if (rs != NULL) {
    while (rs.next()) {
        // Ouvrir le gros objet en lecture
        int oid = rs.getInt(1);
        LargeObject obj = lobj.open(oid, LargeObjectManager.READ);

        // Lire les données
        byte buf[] = new byte[obj.size()];
        obj.read(buf, 0, obj.size());
        // Utiliser les données ici

        // Fermer l'objet
        obj.close();
    }
    rs.close();
}
ps.close();
</programlisting>
   </para>

  </example>
 </sect1>


 <sect1 id="jdbc-ext">
  <title>Extensions <application>PostgreSQL</application> à
    l'<acronym>API</acronym> de <acronym>JDBC</acronym></title>

  <para>
   <productname>PostgreSQL</productname> est un système de bases de données
   extensible. Vous pouvez ajouter vos propres fonctions au serveur, qui seront
   ensuite appelées à partir des requêtes, voire même ajouter vos propres types
   de données. Comme nous les supportons à partir de Java, avec un ensemble
   d'extensions de l'<acronym>API</acronym>, certaines fonctionnalités à
   l'intérieur du c&oelig;ur du pilote standard utilisent en fait ces extensions
   pour implémenter les gros objets, etc.
  </para>

  <sect2>
   <title>Accéder aux Extensions</title>

   <para>
    Pour accéder à certaines des extensions, il faut utiliser
    quelques méthodes supplémentaires dans la classe
    <classname>org.postgresql.PGConnection</classname>. Dans ce cas, vous aurez
    besoin de convertir la valeur de retour de
    <function>Driver.getConnection()</function>. Par exemple&nbsp;:
<programlisting>Connection db = Driver.getConnection(url, username, password);
// ...
// plus tard
Fastpath fp = ((org.postgresql.PGConnection)db).getFastpathAPI();
</programlisting>
   </para>

   <sect3>
    <title>Classe <classname>org.postgresql.PGConnection</classname></title>

<synopsis>public class PGConnection 
</synopsis>

    <para>
     Quelques méthodes supplémentaires sont utilisées pour accéder aux 
     extensions de <productname>PostgreSQL</productname>.
    </para>

    <sect4>
     <title>Méthodes</title>

     <itemizedlist>
      <listitem>
<synopsis>public Fastpath getFastpathAPI() throws SQLException
</synopsis>
       <para>
        Ceci renvoie le <quote>fast-path</quote> de l'<acronym>API</acronym>
        pour la connexion en cours. Il est principalement utilisé par
        l'<acronym>API</acronym> des gros objets.
       </para>

       <para>
        La meilleure façon de l'utiliser est la suivante&nbsp;:
<programlisting>import org.postgresql.fastpath.*;
..
Fastpath fp = ((org.postgresql.PGConnection)myconn).getFastpathAPI();
</programlisting>
        où <varname>myconn</varname> est une <classname>Connection</classname> ouverte sur
        le serveur <productname>PostgreSQL</productname>.
       </para>

       <formalpara>
        <title>Valeur retournée&nbsp;:</title>
        <para>
         Un objet <classname>Fastpath</classname> donnant accès à des fonctions sur le
         serveur <productname>PostgreSQL</productname>.
        </para>
       </formalpara>

       <formalpara>
        <title>Erreur&nbsp;:</title>
        <para>
         <classname>SQLException</classname> par <classname>Fastpath</classname> lors de sa
         première initialisation.
        </para>
       </formalpara>
      </listitem>

      <listitem>
       <para>
<synopsis>public LargeObjectManager getLargeObjectAPI() throws SQLException
</synopsis>
        Ceci renvoie l'<acronym>API</acronym> des gros objets pour la connexion
        en cours.
       </para>

       <para>
        La meilleure façon de l'utiliser est la suivante&nbsp;:
<programlisting>import org.postgresql.largeobject.*;
..
LargeObjectManager lo = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
</programlisting>
        où <varname>myconn</varname> est une <classname>Connection</classname> ouverte sur
        <productname>PostgreSQL</productname>.
       </para>

       <formalpara>
        <title>Valeur retournée&nbsp;:</title>
        <para>
         Un objet <classname>LargeObject</classname> implémentant
         l'<acronym>API</acronym>
        </para>
       </formalpara>

       <formalpara>
        <title>Erreur&nbsp;:</title>
        <para>
         <classname>SQLException</classname> par
         <classname>LargeObject</classname> lors de sa première initialisation
        </para>
       </formalpara>
      </listitem>

      <listitem>
       <para>
<synopsis>public void addDataType(String type, String name)
</synopsis>
        Ceci permet au code client d'ajouter un gestionnaire pour un des types
        de données uniques de <productname>PostgreSQL</productname>.
        Normalement, un type de données inconnu par le pilote est renvoyé par
        <literal>ResultSet.getObject()</literal> comme une instance
        <classname>PGobject</classname>. Cette méthode vous permet d'écrire la classe
         qui étend <classname>PGobject</classname> et indique au pilote le nom du type et
         le nom de la classe à utiliser. Le mauvais côté de ceci est que vous
         devez appeler cette méthode à chaque fois qu'une connexion est faite.
       </para>

       <para>
        La meilleure façon de l'utiliser est la suivante&nbsp;:
<programlisting> ...
((org.postgresql.PGConnection)maconn).addDataType("montype","nom.de.ma.classe");
 ...
</programlisting>
        où <varname>maconn</varname> est une <classname>Connection</classname> ouverte sur
        <productname>PostgreSQL</productname>. La classe gérante doit étendre
        <classname>org.postgresql.util.PGobject</classname>.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>


   <sect3>
    <title>Classe <classname>org.postgresql.Fastpath</classname></title>

<synopsis>public class Fastpath extends Object

java.lang.Object
   |
   +----org.postgresql.fastpath.Fastpath
</synopsis>

    <para>
     <classname>Fastpath</classname> est une <acronym>API</acronym> issue de
     l'interface C de <application>libpq</application>. Elle
     permet à une machine cliente d'exécuter une fonction sur le serveur de bases
     de données. La plupart des programmes clients n'auront pas besoin 
     d'utiliser cette méthode mais elle est fournie car 
     l'<acronym>API</acronym> des gros objets l'utilise.
    </para>

    <para>
     Pour l'utiliser, vous avez besoin d'importer le paquet
     <classname>org.postgresql.fastpath</classname> en utilisant la ligne&nbsp;:
<programlisting>import org.postgresql.fastpath.*;
</programlisting>
     Puis, dans votre code, vous avez besoin d'un objet
     <classname>FastPath</classname>&nbsp;:
<programlisting>Fastpath fp = ((org.postgresql.PGConnection)conn).getFastpathAPI();
</programlisting>
     Ceci renverra une instance associée avec la connexion de la base de données
     que vous utilisez pour lancer des commandes. La conversion de
     <classname>Connection</classname> en
     <classname>org.postgresql.PGConnection</classname> est requise car la fonction
     <function>getFastpathAPI()</function> est une méthode d'extension, et ne fait
     pas partie de <acronym>JDBC</acronym>. Une fois que vous avez une
     instance de <classname>Fastpath</classname>, vous pouvez utiliser les
     méthodes <function>fastpath()</function> pour exécuter une fonction
     serveur.
    </para>

    <formalpara>
     <title>Voir aussi&nbsp;:</title>
     <para>
      <classname>FastpathFastpathArg</classname>,
<classname>LargeObject</classname>
     </para>
    </formalpara>

    <sect4>
     <title>Méthodes</title>

     <itemizedlist>
      <listitem>
<synopsis>public Object fastpath(int fnid,
                       boolean resulttype,
                       FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        Appelle une fonction sur le serveur
        <productname>PostgreSQL</productname>.
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
                <parameter>fnid</parameter> - identifiant de fonction
                <parameter>resulttype</parameter> - vrai si le résultat est un entier,
                 faux sinon
                <parameter>args</parameter> - <classname>FastpathArguments</classname> à
                 passer lors d'un appel à <quote>fast-path</quote>
        </para>
       </formalpara>

       <formalpara>
        <title>Valeur retournée&nbsp;:</title>
        <para>
         NULL si aucune donnée, Integer si le résultat est un entier ou byte[]
         sinon
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public Object fastpath(String name,
                       boolean resulttype,
                       FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        Appelle une fonction sur le serveur
        <productname>PostgreSQL</productname> par son nom.
       </para>

       <note>
        <para>
         Cette correspondance entre le nom de la procédure et son
         identifiant est nécessaire. Elle est habituellement faite dans un 
         appel antérieur à <function>addfunction()</function>. 
         C'est la meilleure méthode d'appel car l'identifiant 
         de fonction peut/pourrait changer entre les
         versions du serveur. Comme exemple de ce fonctionnement, référez-vous à
         org.postgresql.LargeObject
        </para>
       </note>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
                <parameter>name</parameter> - Nom de fonction
                <parameter>resulttype</parameter> - Vrai si le résultat est un entier,
                 faux sinon
                <parameter>args</parameter> - <classname>FastpathArguments</classname> à
                 passer lors d'un appel à <quote>fast-path</quote>
        </para>
       </formalpara>

       <formalpara>
        <title>Valeur retournée&nbsp;:</title>
        <para>
         NULL si aucune donnée, Integer si le résultat est un entier ou byte[]
         sinon
        </para>
       </formalpara>

       <formalpara>
        <title>Voir aussi&nbsp;:</title>
        <para><classname>LargeObject</classname></para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>          
public int getInteger(String name,
                      FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        Cette méthode suppose que la valeur de retour est un Integer.
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
                <parameter>name</parameter> - Nom de la fonction
                <parameter>args</parameter> - Arguments de la fonction
        </para>
       </formalpara>

       <formalpara>
        <title>Valeur retournée&nbsp;:</title>
        <para>résultat entier</para>
       </formalpara>

       <formalpara>
        <title>Erreur&nbsp;:</title>
        <para>
         <classname>SQLException</classname> si une erreur d'accès à la base
          de données survient ou s'il n'y a pas de résultat.
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public byte[] getData(String name,
                      FastpathArg args[]) throws SQLException
</synopsis>
       <para>
        Cette méthode suppose que la valeur de retour est une donnée binaire.
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
                <parameter>name</parameter> - Nom de la fonction
                <parameter>args</parameter> - Arguments de la fonction
        </para>
       </formalpara>

       <formalpara>
        <title>Valeur retournée&nbsp;:</title>
        <para>tableau byte[] contenant le résultat</para>
       </formalpara>

       <formalpara>
        <title>Erreur&nbsp;:</title>
        <para>
         <classname>SQLException</classname> si une erreur d'accès à la base de
          données survient ou s'il n'y a pas de résultat.
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public void addFunction(String name,
                        int fnid)
</synopsis>
       <para>
        Ceci ajoute une fonction dans notre table de recherche. Le code
        utilisateur devrait utiliser la méthode
        <function>addFunctions</function>, qui est basée sur une requête,
        plutôt que sur le codage en dur de l'OID. L'OID d'une fonction n'est
        pas forcément statique, même sur différents serveur utilisant la même
        version.
       </para>
      </listitem>

      <listitem>
<synopsis>public void addFunctions(ResultSet rs) throws SQLException
</synopsis>
       <para>
        Ceci prend un <classname>ResultSet</classname> contenant deux colonnes.
        La première contient le nom de la fonction, la deuxième l'OID. Il lit
        le <classname>ResultSet</classname> complet en chargeant les valeurs
        dans la table des fonctions.
       </para>

       <important>
        <para>
         N'oubliez pas d'utiliser <function>close()</function> sur le
         <classname>ResultSet</classname> après avoir appelé ceci&nbsp;!
        </para>
       </important>

       <note>
        <title>Notes d'implémentation sur les recherches de noms de
         fonction</title>

        <para>
         <productname>PostgreSQL</productname> stocke l'identifiant de la
         fonction et le nom correspondant dans la table <classname>pg_proc</classname>.
         Pour accélérer localement les choses, au lieu d'envoyer une requête
         pour chaque fonction à partir de cette table lorsque nécessaire, un
         <classname>Hashtable</classname> est utilisé. De plus, seuls les requis
         de la fonction sont entrés dans cette table, ceci permettant des temps
         de connexion aussi rapides que possible.
        </para>

        <para>
         La classe <classname>org.postgresql.LargeObject</classname> exécute
         une requête au lancement et passe le <classname>ResultSet</classname>
         renvoyé à la méthode <function>addFunctions()</function>. Une fois ceci
         fait, l'<acronym>API</acronym> des gros objets se réfère aux fonctions
         par nom.
        </para>

        <para>
         Ne pensez pas qu'une conversion manuelle en OID fonctionnerait.
         Pour l'instant, ce sera certainement bon mais cela peut changer lors du
         développement (il y a déjà eu quelques discussions là-dessus pour la 
         version 7.0), donc ceci est implémenté pour empêcher tout problème
         dans le futur.
        </para>
       </note>

       <formalpara>
        <title>Voir aussi&nbsp;:</title>
        <para>
         <classname>LargeObjectManager</classname>
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public int getID(String name) throws SQLException
</synopsis>
       <para>
        Ceci renvoie l'identifiant de la fonction associée à ce nom. Si
        <function>addFunction()</function> ou
        <function>addFunctions()</function> n'ont pas été appelées pour ce nom,
        alors une erreur <classname>SQLException</classname> est renvoyée.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>


   <sect3>
    <title>Classe
<classname>org.postgresql.fastpath.FastpathArg</classname></title>

<synopsis>public class FastpathArg extends Object

java.lang.Object
   |
   +----org.postgresql.fastpath.FastpathArg
</synopsis>

    <para>
     Chaque appel <quote>fast-path</quote> requiert un tableau d'arguments, 
     dont le nombre et le type dépendent de la fonction appelée. 
     Cette classe implémente
     aussi les méthodes nécessaire pour fournir cette fonctionnalité.
    </para>

    <para>
     Pour un exemple sur la façon d'utiliser ceci, référez-vous au paquet
     <classname>org.postgresql.LargeObject</classname>.
    </para>

    <formalpara>
     <title>Voir aussi&nbsp;:</title>
     <para>
      <classname>Fastpath</classname>,
<classname>LargeObjectManager</classname>, <classname>LargeObject</classname>
     </para>
    </formalpara>

    <sect4>
     <title>Constructeurs</title>

     <itemizedlist>
      <listitem>
<synopsis>public FastpathArg(int value)
</synopsis>
       <para>
        Construit un argument consistant en une valeur entière
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
         value - valeur entière à initialiser
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public FastpathArg(byte bytes[])
</synopsis>
       <para>
        Construit un argument consistant en un tableau d'octets
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
         bytes - tableau à stocker
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public FastpathArg(byte buf[],
                   int off,
                   int len)
</synopsis>
       <para>
        Construit un argument consistant en une partie du tableau d'octets
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
         <variablelist>
          <varlistentry>
           <term><parameter>buf</parameter></term>
           <listitem>
            <simpara>tableau source</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term><parameter>off</parameter></term>
           <listitem>
            <simpara>décalage dans le tableau</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term><parameter>len</parameter></term>
           <listitem>
            <simpara>longueur des données à inclure</simpara>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public FastpathArg(String s)
</synopsis>
       <para>
        Construit un argument consistant en une chaîne.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>
  </sect2>


  <sect2>
   <title>Types de données géométriques</title>

   <para>
    <productname>PostgreSQL</productname> dispose d'un ensemble de données
    pouvant stocker des données géométriques dans une table. Ceci inclut des
    points, de lignes et des polygones. Nous supportons ces types en Java avec
    le paquet org.postgresql.geometric. Il contient des classes qui étendent la
    classe org.postgresql.util.PGobject. Référez-vous à cette classe pour plus
    de détails sur l'implémentation de vos propres gestionnaires de types de
    données.
   </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 définition.
             
        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>Gros objets</title>

   <para>
    Les gros objets sont supportés dans la spécification <acronym>JDBC</acronym>
    standard. Néanmoins, cette interface est limitée et l'<acronym>API</acronym>
    fournie par <productname>PostgreSQL</productname> permet des accès directs
    au contenu des objets comme s'il s'agissait d'un fichier local.
   </para>

   <para>
    Le paquet org.postgresql.largeobject fournit à Java l'<acronym>API</acronym>
    des gros objets de l'interface C <application>libpq</application>. Il
    consiste en deux classes, <classname>LargeObjectManager</classname>, gérant
    la création, l'ouverture et la suppression de gros objets, et
    <classname>LargeObject</classname> gérant un objet individuel.
   </para>

   <sect3>
    <title>Classe
<classname>org.postgresql.largeobject.LargeObject</classname></title>

<synopsis>public class LargeObject extends Object

java.lang.Object
   |
   +----org.postgresql.largeobject.LargeObject
</synopsis>

    <para>
     Cette classe implémente l'interface des gros objets dans
     <productname>PostgreSQL</productname>.
    </para>

    <para>
     Elle fournit les méthodes de base pour lancer l'interface, plus une paire
     de méthodes fournissant les classes <classname>InputStream</classname> et
     <classname>OutputStream</classname> pour cet objet.
    </para>

    <para>
     Normalement, un code client pourrait utiliser les méthodes dans
     <classname>BLOB</classname> pour accéder aux gros objets.
    </para>

    <para>
     Néanmoins, quelque fois, un accès bas niveau vers les gros objets est 
     requis, ce qui n'est pas supporté par la spécification
     <acronym>JDBC</acronym>.
    </para>

    <para>
     Référez-vous à org.postgresql.largeobject.LargeObjectManager sur la façon
     d'obtenir un accès à un gros objet ou sur la façon d'en créer un.
    </para>

    <formalpara>
     <title>Voir aussi&nbsp;:</title>
     <para><classname>LargeObjectManager</classname></para>
    </formalpara>

    <sect4>
     <title>Variables</title>

     <variablelist>
      <varlistentry>
       <term>public static final int SEEK_SET</term>
       <listitem>
        <para>Indique un déplacement relatif au début d'un fichier</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>public static final int SEEK_CUR</term>
       <listitem>
        <para>Donne un déplacement à partir de la position actuelle.</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>public static final int SEEK_END</term>
       <listitem>
        <para>Indique un déplacement à partir de la fin du fichier</para>
       </listitem>
      </varlistentry>
     </variablelist>
    </sect4>

    <sect4>
     <title>Méthodes</title>

     <itemizedlist>
      <listitem>
<synopsis>public int getOID()
</synopsis>
       <para>
        Renvoie l'OID de ce <classname>LargeObject</classname>
       </para>
      </listitem>

      <listitem>
<synopsis>public void close() throws SQLException
</synopsis>
       <para>
        Cette méthode ferme l'objet. Vous ne devez pas appeler les méthodes de
        cet objet après avoir appelé cette fonction.
       </para>
      </listitem>

      <listitem>
<synopsis>public byte[] read(int len) throws SQLException
</synopsis>
       <para>
        Lit une partie des données de l'objet et renvoie un tableau de byte[]
       </para>
      </listitem>

      <listitem>
<synopsis>public int read(byte buf[],
                 int off,
                 int len) throws SQLException
</synopsis>
       <para>
        Lit une partie des données de l'objet et les place dans un
        tableau existant
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
         <variablelist>
          <varlistentry>
           <term><parameter>buf</parameter></term>
           <listitem>
            <simpara>tableau de destination</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term><parameter>off</parameter></term>
           <listitem>
            <simpara>décalage dans le tableau</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term><parameter>len</parameter></term>
           <listitem>
            <simpara>nombre d'octets à lire</simpara>
           </listitem>
          </varlistentry>
         </variablelist>
        </para>
       </formalpara>
      </listitem>

      <listitem>
<synopsis>public void write(byte buf[]) throws SQLException
</synopsis>
       <para>
        Écrit un tableau dans l'objet
       </para>
      </listitem>

      <listitem>
<synopsis>public void write(byte buf[],
                  int off,
                  int len) throws SQLException
</synopsis>
       <para>
        Écrit une partie des données du tableau dans l'objet
       </para>

       <formalpara>
        <title>Paramètres&nbsp;:</title>
        <para>
         <variablelist>
          <varlistentry>
           <term><parameter>buf</parameter></term>
           <listitem>
            <simpara>tableau de destination</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term><parameter>off</parameter></term>
           <listitem>
            <simpara>décalage à l'intérieur du tableau</simpara>
           </listitem>
          </varlistentry>

          <varlistentry>
           <term><parameter>len</parameter></term>
           <listitem>
            <simpara>nombre d'octets à écrire</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>Classe
<classname>org.postgresql.largeobject.LargeObjectManager</classname></title>

<synopsis>                                
public class LargeObjectManager extends Object

java.lang.Object
   |
   +----org.postgresql.largeobject.LargeObjectManager
</synopsis>

    <para>
     Cette classe implémente l'interface des gros objets dans
     <productname>PostgreSQL</productname>. Elle fournit les méthodes qui
     permettent au code client de créer, ouvrir et supprimer des gros objets à
     partir de la base de données. Lors de l'ouverture d'un objet, une instance
     de <classname>org.postgresql.largeobject.LargeObject</classname> est
     renvoyée et ses méthodes sont ensuite utilisées pour obtenir l'accès à
     l'objet.
    </para>

    <para>
     Cette classe peut seulement être créée par org.postgresql.PGConnection.
     Pour accéder à cette classe, utilisez la portion de code
     suivant&nbsp;:
<programlisting>import org.postgresql.largeobject.*;
Connection  conn;
LargeObjectManager lobj;
// ... code ouvrant une connexion ...
lobj = ((org.postgresql.PGConnection)myconn).getLargeObjectAPI();
</programlisting>
    </para>

    <para>
     Normalement, on utilise les méthodes
     <classname>BLOB</classname> pour accéder aux gros objets. Néanmoins,
     quelque fois, des accès de bas niveau aux gros objets sont nécessaires
     bien qu'ils ne soient pas supportés par la spécification
     <acronym>JDBC</acronym>.
    </para>

    <para>
     Référez-vous à org.postgresql.largeobject.LargeObject pour savoir comment
     manipuler le contenu d'un gros objet.
    </para>

    <sect4>
     <title>Variables</title>

     <variablelist>
      <varlistentry>
       <term><literal>public static final int WRITE</literal></term>
       <listitem>
        <simpara>Ce mode indique que nous voulons écrire dans un
         objet.</simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><literal>public static final int READ</literal></term>
       <listitem>
        <simpara>Ce mode indique que nous voulons lire un objet.</simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><literal>public static final int READWRITE</literal></term>
       <listitem>
        <simpara>Ce mode est le mode par défaut. Il indique que nous voulons
         lire et écrire dans un gros objet.</simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </sect4>

    <sect4>
     <title>Méthodes</title>

     <itemizedlist>
      <listitem>
<synopsis>public LargeObject open(int oid) throws SQLException
</synopsis>
       <para>
        Ceci ouvre un gros objet existant, suivant son OID. Cette méthode
        suppose que les accès <symbol>READ</symbol> et <symbol>WRITE</symbol> sont requis
        (la valeur par défaut).
       </para>
      </listitem>

      <listitem>
<synopsis>public LargeObject open(int oid,
                        int mode) throws SQLException
</synopsis>
       <para>
        Ceci ouvre un gros objet, suivant son OID, et permet l'initialisation
        du mode d'accès.
       </para>
      </listitem>

      <listitem>
<synopsis>public int create() throws SQLException
</synopsis>
       <para>
        Ceci crée un gros objet, renvoie son OID. Il est par défaut à
        <symbol>READWRITE</symbol> pour les attributs du nouvel objet.
       </para>
      </listitem>

      <listitem>
<synopsis>public int create(int mode) throws SQLException
</synopsis>
       <para>
        Ceci crée un gros objet, renvoie son OID, et initialise le mode
        d'accès.
       </para>
      </listitem>

      <listitem>
<synopsis>public void delete(int oid) throws SQLException
</synopsis>
       <para>          
        Ceci supprime un gros objet.
       </para>
      </listitem>

      <listitem>
<synopsis>public void unlink(int oid) throws SQLException
</synopsis>
       <para>
        Ceci supprime un gros objet. Cette méthode identique à la méthode delete et est
        fournie car l'<acronym>API</acronym> C utilise <quote>unlink</quote>.
       </para>
      </listitem>
     </itemizedlist>
    </sect4>
   </sect3>
  </sect2>

 </sect1>


 <sect1 id="jdbc-thread">
  <title>Utiliser le pilote dans un environnement multithread ou de
   servlet</title>

  <indexterm zone="jdbc-thread">
   <primary>threads</primary>
   <secondary sortas="JDBC">avec JDBC</secondary>
  </indexterm>

  <para>
   Un problème qu'ont beaucoup de pilotes <acronym>JDBC</acronym> est que seul
   le premier thread peut utiliser une <classname>Connection</classname> à la
   fois --- sinon un thread pourrait lancer une requête alors qu'une autre est
   en cours de réception de résultats, ce qui pourrait occasionner une
   confusion.
  </para>

  <para>
   Le pilote <acronym>JDBC</acronym> de <productname>PostgreSQL</productname>
   est compatibles avec les threads. En conséquence, si votre application
   utilise plusieurs threads, alors vous n'avez pas à vous inquiéter des
   algorithmes complexes qui s'assurent qu'un seul thread utilise la base de
   données à la fois.
  </para>

  <para>
   Si un thread tente d'utiliser la connexion alors qu'un autre est en cours
   d'utilisation, il attendra la fin de l'opération en cours par l'autre thread.
   Si l'opération est une requête <acronym>SQL</acronym> standard, alors
   l'opération consiste en l'envoi et en la récupération de
   <classname>ResultSet</classname> (en entier). S'il s'agit d'un appel
   <quote>fast-path</quote> (c'est-à-dire en lisant un bloc d'un gros objet),
   alors il consiste en l'envoi e en la réception des données respectives.
  </para>

  <para>
   Ceci convient pour les applications et les applets mais cela peut causer des
   problèmes de performance avec les servlets. Si vous avez plusieurs threads
   exécutant des requêtes, tous sauf un s'arrêteront. Pour résoudre ceci, il
   vous est conseillé de créer un pool (ensemble) de connexions. Lorsqu'un thread a
   besoin d'utiliser la base de données, il demande au gestionnaire de la classe
   un objet <classname>Connection</classname>. Le gestionnaire donne une
   connexion libre au thread et la marque comme occupée. S'il ne reste plus de
   connexions libres, il en ouvre une. Une fois que le thread a terminé
   d'utiliser la connexion, il la redonne au gestionnaire qui peut alors soit la
   fermer soit l'ajouter de nouveau au pool. Le gestionnaire pourrait aussi
   vérifier que la connexion est toujours vivante et la supprimer du pool
   si elle est morte. Le mauvais côté d'un pool de connexions est que cela
   accroît la charge sur le serveur parce qu'une nouvelle session est créée pour
   chaque objet <classname>Connection</classname>. C'est à vous de voir suivant
   les besoin de vos applications.
  </para>
 </sect1>

 <sect1 id="jdbc-datasource">
  <title>Ensemble de connexions et source de données</title>

  <indexterm zone="jdbc-datasource">
   <primary>ensemble de connexion</primary>
   <secondary sortas="JDBC">avec JDBC</secondary>
  </indexterm>

  <indexterm zone="jdbc-datasource">
   <primary>source de données</primary>
  </indexterm>

  <para>
    <acronym>JDBC</acronym> 2 a introduit des fonctionnalités standard d'ensemble de
    connexions dans une <acronym>API</acronym> supplémentaire connue sous le nom du
    paquet optionnel de <acronym>JDBC</acronym> 2.0 (aussi connue en tant
    qu'extension standard de <acronym>JDBC</acronym> 2.0). Ces fonctionnalités
    ont depuis été inclus dans l'<acronym>API</acronym> au c&oelig;ur de
    <acronym>JDBC</acronym> 3. Le pilote <acronym>JDBC</acronym> de
    <productname>PostgreSQL</productname> supporte ces fonctionnalités s'il a
    été compilé avec le <acronym>JDK</acronym> 1.3.x en combinaison avec le
    paquet optionnel de <acronym>JDBC</acronym> 2.0 (<acronym>JDBC</acronym> 2)
    ou avec le <acronym>JDK</acronym> 1.4 ou une version suivante
    (<acronym>JDBC</acronym> 3). La plupart des serveurs d'applications incluent
    le paquet optionnel de <acronym>JDBC</acronym> 2.0 mais il est aussi
    disponible séparément sur le <ulink
    url="http://java.sun.com/products/jdbc/download.html#spec">site
    de téléchargement <acronym>JDBC</acronym></ulink> de Sun.
   </para>

  <sect2 id="jdbc-ds-intro">
   <title>Aperçu</title>

    <para>
     L'<acronym>API</acronym> <acronym>JDBC</acronym> fournit une interface client et
     serveur pour la gestion de pools de connexions. L'interface client est
     <literal>javax.sql.DataSource</literal>, qui est ce que le code de
     l'application utilisera typiquement pour récupérer une connexion à la base
     de données depuis ce pool. L'interface du serveur est
     <literal>javax.sql.ConnectionPoolDataSource</literal>. C'est la méthode 
     utilisée par la plupart des serveurs d'application pour se créer une interface 
     avec le pilote <acronym>JDBC</acronym>
     de <productname>PostgreSQL</productname>.
    </para>

    <para>
     Dans un environnement avec un serveur d'applications, la configuration du
     serveur d'applications se référera typiquement à l'implémentation
     <literal>ConnectionPoolDataSource</literal> de
     <productname>PostgreSQL</productname> alors que le code composant de
     l'application obtiendra typiquement une implémentation du
     <literal>DataSource</literal> fournie par le serveur d'applications (et non
     pas par <productname>PostgreSQL</productname>).
    </para>

    <para>
     Pour un environnement serveur sans serveur d'applications,
     <productname>PostgreSQL</productname> fournit deux implémentations de
     <literal>DataSource</literal> qu'une application peut utiliser
     directement. Une implémentation réalise la gestion de pool de
     connexions alors qu'une autre fournit des accès à ses connexions via
     l'interface de <literal>DataSource</literal> sans pool. Encore une
     fois, ces implémentations ne doivent pas être utilisées dans un
     environnement de serveur d'application sauf si le serveur d'application ne
     supporte pas l'interface <literal>ConnectionPoolDataSource</literal>.
    </para>
  </sect2>
   
  <sect2 id="jdbc-ds-cpds">
   <title>Serveurs d'application&nbsp;:
    <classname>ConnectionPoolDataSource</classname></title>

   <para>
    <productname>PostgreSQL</productname> inclut une implémentation de
    <classname>ConnectionPoolDataSource</classname> pour
    <acronym>JDBC</acronym> 2 et une pour <acronym>JDBC</acronym> 3,
    comme montré dans <xref linkend="jdbc-ds-cpds-imp-table"/>.
   </para>

  
   <table id="jdbc-ds-cpds-imp-table">
    <title>Implémentations de
     <classname>ConnectionPoolDataSource</classname></title>
  
    <tgroup cols="2">
     <thead>
      <row>
       <entry><acronym>JDBC</acronym></entry>
       <entry>Classe d'implémentation</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>
    Les deux implémentations utilisent le même schéma de configuration.
    <acronym>JDBC</acronym> requiert qu'un
    <classname>ConnectionPoolDataSource</classname> soit configuré via des
    propriétés JavaBean, décrites dans <xref linkend="jdbc-ds-cpds-props"/>, si bien
    qu'il y a des méthodes get et set pour chacune des propriétés.
   </para>

   <table id="jdbc-ds-cpds-props">
    <title>Propriétés de configuration de
     <classname>ConnectionPoolDataSource</classname></title>
  
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Propriété</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
 
     <tbody>
      <row>
       <entry><literal>serverName</literal></entry>
       <entry><type>String</type></entry>
       <entry>Nom d'hôte du serveur de
        bases de données <productname>PostgreSQL</productname></entry>
      </row>
 
      <row>
       <entry><literal>databaseName</literal></entry>
       <entry><type>String</type></entry>
       <entry>Nom de la base de données
        <productname>PostgreSQL</productname></entry>
      </row>
 
      <row>
       <entry><literal>portNumber</literal></entry>
       <entry><type>int</type></entry>
       <entry>
        Port TCP sur lequel  le serveur de bases de données
        <productname>PostgreSQL</productname> écoute (ou 0 pour utiliser 
        le port par défaut)
       </entry>
      </row>
 
      <row>
       <entry><literal>user</literal></entry>
       <entry><type>String</type></entry>
       <entry>Utilisateur utilisé pour réaliser les connexions à la base de 
        données</entry>
      </row>
 
      <row>
       <entry><literal>password</literal></entry>
       <entry><type>String</type></entry>
       <entry>Mot de passe utilisé pour réaliser les connexions à la base de
        données</entry>
      </row>
 
      <row>
       <entry><literal>defaultAutoCommit</literal></entry>
       <entry><type>boolean</type></entry>
       <entry>
        Les connexions doivent-elles activer la validation automatique
        (autocommit) lorsqu'elles sont fournies au demandeur. Par défaut à
        <literal>false</literal> pour désactiver la validation automatique.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>

   <para>
    Beaucoup de serveurs d'application utilisent une syntaxe style propriétés
    pour configurer leurs propriétés, donc il ne sera pas inhabituel d'entrer
    les propriétés avec un bloc de texte. Si le serveur d'application fournit
    un emplacement simple pour saisir toutes les propriétés, elles pourraient être
    listées ensemble comme ceci&nbsp;:
<programlisting>serverName=localhost
databaseName=test
user=testuser
password=testpassword
</programlisting>
    Ou, si les points virgules sont utilisés comme séparateurs au lieu des
retours à la ligne, cela pourrait ressembler à ceci&nbsp;:
<programlisting>serverName=localhost;databaseName=test;user=testuser;password=testpassword
</programlisting>
   </para>

  </sect2>

  <sect2 id="jdbc-ds-ds">
   <title>Applications&nbsp;: <classname>DataSource</classname></title>

    <para><productname>PostgreSQL</productname> inclut deux versions de
     <literal>DataSource</literal> pour <acronym>JDBC</acronym> 2 et deux pour
     <acronym>JDBC</acronym> 3, comme le montre <xref linkend="jdbc-ds-ds-imp"/>.
     Les implémentations ne ferment pas les connexions lorsque le client appelle
     la méthode <literal>close</literal> mais renvoie à la place les connexions
     dans un ensemble de connexions disponibles pour les autres clients. Ceci
     évite une surcharge pour l'ouverture et la fermeture des connexions et
     permet à un grand nombre de clients de partager un petit nombre de
     connexions à la base de données.</para>
     
    <para>L'implémentation des sources de données en pool fournie ici
     ne dispose que de fonctionnalités limitées.
     Entre autres choses, les connexions ne sont jamais fermées jusqu'à ce que
     le pool soit lui-même fermé&nbsp;; il n'existe pas de moyens de diminuer
     le pool. De même, les connexions demandées par les utilisateurs autres
     que celui de l'utilisateur configuré par défaut ne sont pas gérées dans ce
     pool. Beaucoup de serveurs d'application fournissent des
     fonctionnalités plus avancées et utilisent à la place l'implémentation
     <literal>ConnectionPoolDataSource</literal>.</para>

   <table id="jdbc-ds-ds-imp">
    <title>Implémentations de <classname>DataSource</classname></title>
  
    <tgroup cols="3">
     <thead>
      <row>
       <entry><acronym>JDBC</acronym></entry>
       <entry>Gestion en ensemble</entry>
       <entry>Classe d'implémentation</entry>
      </row>
     </thead>
 
     <tbody>
      <row>
       <entry>2</entry>
       <entry>Non</entry>
      
<entry><literal>org.postgresql.jdbc2.optional.SimpleDataSource</literal></entry>
      </row>
 
      <row>
       <entry>2</entry>
       <entry>Oui</entry>
      
<entry><literal>org.postgresql.jdbc2.optional.PoolingDataSource</literal></entry
>
      </row>
 
      <row>
       <entry>3</entry>
       <entry>Non</entry>
      
<entry><literal>org.postgresql.jdbc3.Jdbc3SimpleDataSource</literal></entry>
      </row>
 
      <row>
       <entry>3</entry>
       <entry>Oui</entry>
       <entry><literal>org.postgresql.jdbc3.Jdbc3PoolingDataSource</literal></entry>
      </row>
 
     </tbody>
    </tgroup>
    </table>

    <para>
     Toutes les implémentations utilisent le même schéma de configuration.
     <acronym>JDBC</acronym> impose qu'une <literal>DataSource</literal> soit
     configurée via des propriétés JavaBean, affichées dans <xref
     linkend="jdbc-ds-ds-props"/>, si bien qu'il existe des méthodes get
     et set pour chacune de ces propriétés.
    </para>

    <table id="jdbc-ds-ds-props">
    <title>Propriétés de configuration de <classname>DataSource</classname></title>
  
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Propriété</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
 
     <tbody>
      <row>
       <entry><literal>serverName</literal></entry>
       <entry><type>String</type></entry>
       <entry>Nom d'hôte du serveur de bases de données
        <productname>PostgreSQL</productname></entry>
      </row>
 
      <row>
       <entry><literal>databaseName</literal></entry>
       <entry><type>String</type></entry>
       <entry>Nom de la base de données
        <productname>PostgreSQL</productname></entry>
      </row>
 
      <row>
       <entry><literal>portNumber</literal></entry>
       <entry><type>int</type></entry>
       <entry>Port TCP sur lequel le serveur de bases de données
        <productname>PostgreSQL</productname> est en écoute (ou 0 pour utiliser
         le port par défaut)</entry>
      </row>
 
      <row>
       <entry><literal>user</literal></entry>
       <entry><type>String</type></entry>
       <entry>Utilisateur utilisé pour réaliser les connexions à la base
        de données</entry>
      </row>
 
      <row>
       <entry><literal>password</literal></entry>
       <entry><type>String</type></entry>
       <entry>Mot de passe utilisé pour réaliser les connexions à la base de
        données</entry>
      </row>
     </tbody>
    </tgroup>
    </table>

    <para>Les implémentations de gestion de pools requièrent quelques
     propriétés supplémentaires de configuration, qui sont affichées dans
     <xref linkend="jdbc-ds-ds-xprops"/>.</para>

   <table id="jdbc-ds-ds-xprops">
    <title>Propriétés supplémentaires de configuration des ensembles de
     <classname>DataSource</classname></title>
  
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Propriété</entry>
       <entry>Type</entry>
       <entry>Description</entry>
      </row>
     </thead>
 
     <tbody>
      <row>
       <entry><literal>dataSourceName</literal></entry>
       <entry><type>String</type></entry>
       <entry>Chaque <literal>DataSource</literal> de l'ensemble doit avoir un
        nom unique.</entry>
      </row>
 
      <row>
       <entry><literal>initialConnections</literal></entry>
       <entry><type>int</type></entry>
       <entry>Le nombre de connexions à créer sur la base de données à
        l'initialisation de l'ensemble.</entry>
      </row>
 
      <row>
       <entry><literal>maxConnections</literal></entry>
       <entry><type>int</type></entry>
       <entry>Le nombre maximum de connexions ouvertes sur la base de données.
        Quand plus de connexions sont demandées, l'appelant est bloqué 
        jusqu'une connexion soit disponible dans le pool.</entry>
      </row>
     </tbody>
    </tgroup>
    </table>

    <para><xref linkend="jdbc-ds-example"/> montre un exemple de
     code d'application typique utilisant un <literal>DataSource</literal> de
     l'ensemble.</para>
 
   <example id="jdbc-ds-example">
    <title>Exemple de code pour <literal>DataSource</literal></title>

    <para>
     Le code pour initialiser un <classname>DataSource</classname> de l'ensemble
     pourrait ressembler à ceci&nbsp;:
<programlisting>Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource();
source.setDataSourceName("Une source de données");
source.setServerName("localhost");
source.setDatabaseName("test");
source.setUser("utilisateur_test");
source.setPassword("motdepassetest");
source.setMaxConnections(10);
</programlisting>
      Puis le code utilisant une connexion du pool pourrait ressembler
      à ceci. Notez qu'il est indispensable que les connexions soient
      fermées. Sinon, l'ensemble <quote>manquera</quote> de connexions et
      finira par bloquer tous les clients.
<programlisting>Connection con = NULL;
try {
    con = source.getConnection();
    // utilisez la connexion
} catch (SQLException e) {
    // trace de l'erreur
} finally {
    if (con != NULL) {
        try { con.close(); } catch (SQLException e) {}
    }
}
</programlisting>
    </para>
   </example>
  </sect2>

  <sect2 id="jdbc-jndi">
   <title>Sources de données et <acronym>JNDI</acronym></title>

   <indexterm zone="jdbc-jndi">
    <primary>JNDI</primary>
   </indexterm>

    <para>
     Toutes les implémentations de <literal>ConnectionPoolDataSource</literal>
     et de <literal>DataSource</literal> peuvent être enregistrées dans
     <acronym>JNDI</acronym>. Dans le cas d'une implémentation sans pool de
     connexions, une nouvelle instance est créée à chaque fois que l'objet est
     récupéré à partir de <acronym>JNDI</acronym> avec les mêmes paramètres que
     ceux de l'instance qui avaient été stockés. Pour les implémentations de
     pool, la même instance est récupérée aussi longtemps qu'elle sera
     disponible (c'est-à-dire pas une <acronym>JVM</acronym> différent récupérant
     l'ensemble à partir de <acronym>JNDI</acronym>), sinon une nouvelle instance
     est créée avec les mêmes paramètres.
    </para>

    <para>
     Dans l'environnement du serveur d'application, habituellement, l'instance de
     <literal>DataSource</literal> du serveur d'applications est stockée dans
     <acronym>JNDI</acronym> au lieu de l'implémentation 
     <literal>ConnectionPoolDataSource</literal> de 
     <productname>PostgreSQL</productname>.
    </para>

    <para>
     Dans un environnement applicatif, l'application pourrait stocker le
     <literal>DataSource</literal> dans <acronym>JNDI</acronym> pour qu'elle
     n'ait pas besoin de faire une référence au <literal>DataSource</literal>
     disponible pour tous les composants de l'application qui pourraient en 
     avoir besoin. Un exemple de ceci est montré dans <xref
     linkend="jdbc-ds-jndi"/>.
    </para>

   <example id="jdbc-ds-jndi">
    <title>Exemple de code pour un <classname>DataSource</classname>
     <acronym>JNDI</acronym></title>

    <para>
     Le code de l'application pour initialiser un
     <classname>DataSource</classname> de l'ensemble et pour l'ajouter à
     <acronym>JNDI</acronym> pourrait ressembler à ceci&nbsp;:
<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>
      Puis, le code pour utiliser la connexion de l'ensemble pourrait
      ressembler à ceci&nbsp;:
<programlisting>Connection con = NULL;
try {
    DataSource source = (DataSource)new InitialContext().lookup("DataSource");
    con = source.getConnection();
    // utilisez la connexion
} catch (SQLException e) {
    // tracez l'erreur
} catch (NamingException e) {
    // La source de données n'a pas été trouvée dans JNDI
} finally {
    if (con != NULL) {
        try { con.close(); } catch (SQLException e) {}
    }
}
</programlisting>
    </para>
   </example>
  </sect2>

 </sect1>

 <sect1 id="jdbc-reading">
  <title>Lectures supplémentaires</title>

  <para>
   Si vous ne l'avez pas encore lu, il vous est conseillé de lire la
   documentation de l'<acronym>API</acronym> <acronym>JDBC</acronym> (fournie
   avec le <acronym>JDK</acronym> de Sun) et la spécification
   <acronym>JDBC</acronym>. Les deux sont disponibles à partir de <ulink
   url="http://java.sun.com/products/jdbc/index.html"></ulink>.
  </para>

  <para>
   <ulink url="http://jdbc.postgresql.org"></ulink> contient des informations
   mises à jour mais non incluses dans ce chapitre et offre aussi des pilotes
   pré compilés.
  </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:
-->