I386LINUX/util/I386LINUX/doc/postgresql/html/jdbc-datasource.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Connection Pools and Data Sources</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="JDBC Interface"
  16 HREF="jdbc.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="Using the Driver in a Multithreaded or a Servlet Environment"
  19 HREF="jdbc-thread.html"><LINK
  20 REL="NEXT"
  21 TITLE="Further Reading"
  22 HREF="jdbc-reading.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="SECT1"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="jdbc-thread.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="jdbc.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 >Chapter 31. <ACRONYM
  68 CLASS="ACRONYM"
  69 >JDBC</ACRONYM
  70 > Interface</TD
  71 ><TD
  72 WIDTH="10%"
  73 ALIGN="right"
  74 VALIGN="top"
  75 ><A
  76 HREF="jdbc.html"
  77 >Fast Forward</A
  78 ></TD
  79 ><TD
  80 WIDTH="10%"
  81 ALIGN="right"
  82 VALIGN="top"
  83 ><A
  84 HREF="jdbc-reading.html"
  85 ACCESSKEY="N"
  86 >Next</A
  87 ></TD
  88 ></TR
  89 ></TABLE
  90 ><HR
  91 ALIGN="LEFT"
  92 WIDTH="100%"></DIV
  93 ><DIV
  94 CLASS="SECT1"
  95 ><H1
  96 CLASS="SECT1"
  97 ><A
  98 NAME="JDBC-DATASOURCE"
  99 >31.10. Connection Pools and Data Sources</A
 100 ></H1
 101 ><A
 102 NAME="AEN24979"
 103 ></A
 104 ><A
 105 NAME="AEN24982"
 106 ></A
 107 ><P
 108 >    <ACRONYM
 109 CLASS="ACRONYM"
 110 >JDBC</ACRONYM
 111 > 2 introduced standard connection pooling features in an
 112     add-on <ACRONYM
 113 CLASS="ACRONYM"
 114 >API</ACRONYM
 115 > known as the <ACRONYM
 116 CLASS="ACRONYM"
 117 >JDBC</ACRONYM
 118 > 2.0 Optional
 119     Package (also known as the <ACRONYM
 120 CLASS="ACRONYM"
 121 >JDBC</ACRONYM
 122 > 2.0
 123     Standard Extension).  These features have since been included in
 124     the core <ACRONYM
 125 CLASS="ACRONYM"
 126 >JDBC</ACRONYM
 127 > 3 <ACRONYM
 128 CLASS="ACRONYM"
 129 >API</ACRONYM
 130 >.  The
 131     <SPAN
 132 CLASS="PRODUCTNAME"
 133 >PostgreSQL</SPAN
 134 > <ACRONYM
 135 CLASS="ACRONYM"
 136 >JDBC</ACRONYM
 137 > drivers
 138     support these features if it has been compiled with
 139     <ACRONYM
 140 CLASS="ACRONYM"
 141 >JDK</ACRONYM
 142 > 1.3.x in combination with the
 143     <ACRONYM
 144 CLASS="ACRONYM"
 145 >JDBC</ACRONYM
 146 > 2.0 Optional Package
 147     (<ACRONYM
 148 CLASS="ACRONYM"
 149 >JDBC</ACRONYM
 150 > 2), or with <ACRONYM
 151 CLASS="ACRONYM"
 152 >JDK</ACRONYM
 153 > 1.4 or higher
 154     (<ACRONYM
 155 CLASS="ACRONYM"
 156 >JDBC</ACRONYM
 157 > 3).  Most application servers include
 158     the <ACRONYM
 159 CLASS="ACRONYM"
 160 >JDBC</ACRONYM
 161 > 2.0 Optional Package, but it is
 162     also available separately from the Sun
 163     <A
 164 HREF="http://java.sun.com/products/jdbc/download.html#spec"
 165 TARGET="_top"
 166 ><ACRONYM
 167 CLASS="ACRONYM"
 168 >JDBC</ACRONYM
 169 > download site</A
 170 >.
 171    </P
 172 ><DIV
 173 CLASS="SECT2"
 174 ><H2
 175 CLASS="SECT2"
 176 ><A
 177 NAME="JDBC-DS-INTRO"
 178 >31.10.1. Overview</A
 179 ></H2
 180 ><P
 181 >     The <ACRONYM
 182 CLASS="ACRONYM"
 183 >JDBC</ACRONYM
 184 > <ACRONYM
 185 CLASS="ACRONYM"
 186 >API</ACRONYM
 187 > provides a client
 188      and a server interface for connection pooling.  The client
 189      interface is <TT
 190 CLASS="LITERAL"
 191 >javax.sql.DataSource</TT
 192 >,
 193      which is what application code will typically use to
 194      acquire a pooled database connection.  The server interface
 195      is <TT
 196 CLASS="LITERAL"
 197 >javax.sql.ConnectionPoolDataSource</TT
 198 >,
 199      which is how most application servers will interface with
 200      the <SPAN
 201 CLASS="PRODUCTNAME"
 202 >PostgreSQL</SPAN
 203 > <ACRONYM
 204 CLASS="ACRONYM"
 205 >JDBC</ACRONYM
 206 >
 207      driver.
 208     </P
 209 ><P
 210 >     In an application server environment, the
 211      application server configuration will typically refer to
 212      the <SPAN
 213 CLASS="PRODUCTNAME"
 214 >PostgreSQL</SPAN
 215 >
 216      <TT
 217 CLASS="LITERAL"
 218 >ConnectionPoolDataSource</TT
 219 > implementation,
 220      while the application component code will typically acquire a
 221      <TT
 222 CLASS="LITERAL"
 223 >DataSource</TT
 224 > implementation provided by
 225      the application server (not by
 226      <SPAN
 227 CLASS="PRODUCTNAME"
 228 >PostgreSQL</SPAN
 229 >).
 230     </P
 231 ><P
 232 >     For an environment without an application server,
 233      <SPAN
 234 CLASS="PRODUCTNAME"
 235 >PostgreSQL</SPAN
 236 > provides two implementations
 237      of <TT
 238 CLASS="LITERAL"
 239 >DataSource</TT
 240 > which an application can use
 241      directly.  One implementation performs connection pooling,
 242      while the other simply provides access to database connections
 243      through the <TT
 244 CLASS="LITERAL"
 245 >DataSource</TT
 246 > interface without
 247      any pooling.  Again, these implementations should not be used
 248      in an application server environment unless the application
 249      server does not support the
 250      <TT
 251 CLASS="LITERAL"
 252 >ConnectionPoolDataSource</TT
 253 > interface.
 254     </P
 255 ></DIV
 256 ><DIV
 257 CLASS="SECT2"
 258 ><H2
 259 CLASS="SECT2"
 260 ><A
 261 NAME="JDBC-DS-CPDS"
 262 >31.10.2. Application Servers: <CODE
 263 CLASS="CLASSNAME"
 264 >ConnectionPoolDataSource</CODE
 265 ></A
 266 ></H2
 267 ><P
 268 >    <SPAN
 269 CLASS="PRODUCTNAME"
 270 >PostgreSQL</SPAN
 271 > includes one implementation
 272     of <CODE
 273 CLASS="CLASSNAME"
 274 >ConnectionPoolDataSource</CODE
 275 > for
 276     <ACRONYM
 277 CLASS="ACRONYM"
 278 >JDBC</ACRONYM
 279 > 2 and one for <ACRONYM
 280 CLASS="ACRONYM"
 281 >JDBC</ACRONYM
 282 > 3,
 283     as shown in <A
 284 HREF="jdbc-datasource.html#JDBC-DS-CPDS-IMP-TABLE"
 285 >Table 31-1</A
 286 >.
 287    </P
 288 ><DIV
 289 CLASS="TABLE"
 290 ><A
 291 NAME="JDBC-DS-CPDS-IMP-TABLE"
 292 ></A
 293 ><P
 294 ><B
 295 >Table 31-1. <CODE
 296 CLASS="CLASSNAME"
 297 >ConnectionPoolDataSource</CODE
 298 > Implementations</B
 299 ></P
 300 ><TABLE
 301 BORDER="1"
 302 CLASS="CALSTABLE"
 303 ><COL><COL><THEAD
 304 ><TR
 305 ><TH
 306 ><ACRONYM
 307 CLASS="ACRONYM"
 308 >JDBC</ACRONYM
 309 ></TH
 310 ><TH
 311 >Implementation Class</TH
 312 ></TR
 313 ></THEAD
 314 ><TBODY
 315 ><TR
 316 ><TD
 317 >2</TD
 318 ><TD
 319 ><TT
 320 CLASS="LITERAL"
 321 >org.postgresql.jdbc2.optional.ConnectionPool</TT
 322 ></TD
 323 ></TR
 324 ><TR
 325 ><TD
 326 >3</TD
 327 ><TD
 328 ><TT
 329 CLASS="LITERAL"
 330 >org.postgresql.jdbc3.Jdbc3ConnectionPool</TT
 331 ></TD
 332 ></TR
 333 ></TBODY
 334 ></TABLE
 335 ></DIV
 336 ><P
 337 >    Both implementations use the same configuration scheme.
 338     <ACRONYM
 339 CLASS="ACRONYM"
 340 >JDBC</ACRONYM
 341 > requires that a
 342     <CODE
 343 CLASS="CLASSNAME"
 344 >ConnectionPoolDataSource</CODE
 345 > be configured via
 346     JavaBean properties, shown in <A
 347 HREF="jdbc-datasource.html#JDBC-DS-CPDS-PROPS"
 348 >Table 31-2</A
 349 >,
 350     so there are get and set methods for each of these properties.
 351    </P
 352 ><DIV
 353 CLASS="TABLE"
 354 ><A
 355 NAME="JDBC-DS-CPDS-PROPS"
 356 ></A
 357 ><P
 358 ><B
 359 >Table 31-2. <CODE
 360 CLASS="CLASSNAME"
 361 >ConnectionPoolDataSource</CODE
 362 > Configuration Properties</B
 363 ></P
 364 ><TABLE
 365 BORDER="1"
 366 CLASS="CALSTABLE"
 367 ><COL><COL><COL><THEAD
 368 ><TR
 369 ><TH
 370 >Property</TH
 371 ><TH
 372 >Type</TH
 373 ><TH
 374 >Description</TH
 375 ></TR
 376 ></THEAD
 377 ><TBODY
 378 ><TR
 379 ><TD
 380 ><TT
 381 CLASS="LITERAL"
 382 >serverName</TT
 383 ></TD
 384 ><TD
 385 ><TT
 386 CLASS="TYPE"
 387 >String</TT
 388 ></TD
 389 ><TD
 390 ><SPAN
 391 CLASS="PRODUCTNAME"
 392 >PostgreSQL</SPAN
 393 > database server
 394          host name</TD
 395 ></TR
 396 ><TR
 397 ><TD
 398 ><TT
 399 CLASS="LITERAL"
 400 >databaseName</TT
 401 ></TD
 402 ><TD
 403 ><TT
 404 CLASS="TYPE"
 405 >String</TT
 406 ></TD
 407 ><TD
 408 ><SPAN
 409 CLASS="PRODUCTNAME"
 410 >PostgreSQL</SPAN
 411 > database name</TD
 412 ></TR
 413 ><TR
 414 ><TD
 415 ><TT
 416 CLASS="LITERAL"
 417 >portNumber</TT
 418 ></TD
 419 ><TD
 420 ><TT
 421 CLASS="TYPE"
 422 >int</TT
 423 ></TD
 424 ><TD
 425 >        TCP port which the <SPAN
 426 CLASS="PRODUCTNAME"
 427 >PostgreSQL</SPAN
 428 >
 429         database server is listening on (or 0 to use the default port)
 430        </TD
 431 ></TR
 432 ><TR
 433 ><TD
 434 ><TT
 435 CLASS="LITERAL"
 436 >user</TT
 437 ></TD
 438 ><TD
 439 ><TT
 440 CLASS="TYPE"
 441 >String</TT
 442 ></TD
 443 ><TD
 444 >User used to make database connections</TD
 445 ></TR
 446 ><TR
 447 ><TD
 448 ><TT
 449 CLASS="LITERAL"
 450 >password</TT
 451 ></TD
 452 ><TD
 453 ><TT
 454 CLASS="TYPE"
 455 >String</TT
 456 ></TD
 457 ><TD
 458 >Password used to make database connections</TD
 459 ></TR
 460 ><TR
 461 ><TD
 462 ><TT
 463 CLASS="LITERAL"
 464 >defaultAutoCommit</TT
 465 ></TD
 466 ><TD
 467 ><TT
 468 CLASS="TYPE"
 469 >boolean</TT
 470 ></TD
 471 ><TD
 472 >        Whether connections should have autocommit enabled or disabled
 473         when they are supplied to the caller.  The default is
 474         <TT
 475 CLASS="LITERAL"
 476 >false</TT
 477 >, to disable autocommit.
 478        </TD
 479 ></TR
 480 ></TBODY
 481 ></TABLE
 482 ></DIV
 483 ><P
 484 >    Many application servers use a properties-style syntax to
 485     configure these properties, so it would not be unusual to enter
 486     properties as a block of text.  If the application server provides
 487     a single area to enter all the properties, they might be listed
 488     like this:
 489 </P><PRE
 490 CLASS="PROGRAMLISTING"
 491 >serverName=localhost
 492 databaseName=test
 493 user=testuser
 494 password=testpassword</PRE
 495 ><P>
 496     Or, if semicolons are used as separators instead of newlines, it
 497     could look like this:
 498 </P><PRE
 499 CLASS="PROGRAMLISTING"
 500 >serverName=localhost;databaseName=test;user=testuser;password=testpassword</PRE
 501 ><P>
 502    </P
 503 ></DIV
 504 ><DIV
 505 CLASS="SECT2"
 506 ><H2
 507 CLASS="SECT2"
 508 ><A
 509 NAME="JDBC-DS-DS"
 510 >31.10.3. Applications: <CODE
 511 CLASS="CLASSNAME"
 512 >DataSource</CODE
 513 ></A
 514 ></H2
 515 ><P
 516 ><SPAN
 517 CLASS="PRODUCTNAME"
 518 >PostgreSQL</SPAN
 519 > includes two
 520      implementations of <TT
 521 CLASS="LITERAL"
 522 >DataSource</TT
 523 >
 524      for <ACRONYM
 525 CLASS="ACRONYM"
 526 >JDBC</ACRONYM
 527 > 2 and two for <ACRONYM
 528 CLASS="ACRONYM"
 529 >JDBC</ACRONYM
 530 >
 531      3, as shown in <A
 532 HREF="jdbc-datasource.html#JDBC-DS-DS-IMP"
 533 >Table 31-3</A
 534 >.
 535      The pooling implementations do not actually close connections
 536      when the client calls the <TT
 537 CLASS="LITERAL"
 538 >close</TT
 539 > method, but
 540      instead return the connections to a pool of available connections
 541      for other clients to use.  This avoids any overhead of repeatedly
 542      opening and closing connections, and allows a large number of
 543      clients to share a small number of database connections.</P
 544 ><P
 545 >The pooling data-source implementation provided here is not
 546      the most feature-rich in the world.  Among other things,
 547      connections are never closed until the pool itself is closed;
 548      there is no way to shrink the pool.  As well, connections
 549      requested for users other than the default configured user are
 550      not pooled.  Many application servers
 551      provide more advanced pooling features and use the
 552      <TT
 553 CLASS="LITERAL"
 554 >ConnectionPoolDataSource</TT
 555 > implementation
 556      instead.</P
 557 ><DIV
 558 CLASS="TABLE"
 559 ><A
 560 NAME="JDBC-DS-DS-IMP"
 561 ></A
 562 ><P
 563 ><B
 564 >Table 31-3. <CODE
 565 CLASS="CLASSNAME"
 566 >DataSource</CODE
 567 > Implementations</B
 568 ></P
 569 ><TABLE
 570 BORDER="1"
 571 CLASS="CALSTABLE"
 572 ><COL><COL><COL><THEAD
 573 ><TR
 574 ><TH
 575 ><ACRONYM
 576 CLASS="ACRONYM"
 577 >JDBC</ACRONYM
 578 ></TH
 579 ><TH
 580 >Pooling</TH
 581 ><TH
 582 >Implementation Class</TH
 583 ></TR
 584 ></THEAD
 585 ><TBODY
 586 ><TR
 587 ><TD
 588 >2</TD
 589 ><TD
 590 >No</TD
 591 ><TD
 592 ><TT
 593 CLASS="LITERAL"
 594 >org.postgresql.jdbc2.optional.SimpleDataSource</TT
 595 ></TD
 596 ></TR
 597 ><TR
 598 ><TD
 599 >2</TD
 600 ><TD
 601 >Yes</TD
 602 ><TD
 603 ><TT
 604 CLASS="LITERAL"
 605 >org.postgresql.jdbc2.optional.PoolingDataSource</TT
 606 ></TD
 607 ></TR
 608 ><TR
 609 ><TD
 610 >3</TD
 611 ><TD
 612 >No</TD
 613 ><TD
 614 ><TT
 615 CLASS="LITERAL"
 616 >org.postgresql.jdbc3.Jdbc3SimpleDataSource</TT
 617 ></TD
 618 ></TR
 619 ><TR
 620 ><TD
 621 >3</TD
 622 ><TD
 623 >Yes</TD
 624 ><TD
 625 ><TT
 626 CLASS="LITERAL"
 627 >org.postgresql.jdbc3.Jdbc3PoolingDataSource</TT
 628 ></TD
 629 ></TR
 630 ></TBODY
 631 ></TABLE
 632 ></DIV
 633 ><P
 634 >     All the implementations use the same configuration scheme.
 635      <ACRONYM
 636 CLASS="ACRONYM"
 637 >JDBC</ACRONYM
 638 > requires that a
 639      <TT
 640 CLASS="LITERAL"
 641 >DataSource</TT
 642 > be configured via JavaBean
 643      properties, shown in <A
 644 HREF="jdbc-datasource.html#JDBC-DS-DS-PROPS"
 645 >Table 31-4</A
 646 >, so there
 647      are get and set methods for each of these properties.
 648     </P
 649 ><DIV
 650 CLASS="TABLE"
 651 ><A
 652 NAME="JDBC-DS-DS-PROPS"
 653 ></A
 654 ><P
 655 ><B
 656 >Table 31-4. <CODE
 657 CLASS="CLASSNAME"
 658 >DataSource</CODE
 659 > Configuration Properties</B
 660 ></P
 661 ><TABLE
 662 BORDER="1"
 663 CLASS="CALSTABLE"
 664 ><COL><COL><COL><THEAD
 665 ><TR
 666 ><TH
 667 >Property</TH
 668 ><TH
 669 >Type</TH
 670 ><TH
 671 >Description</TH
 672 ></TR
 673 ></THEAD
 674 ><TBODY
 675 ><TR
 676 ><TD
 677 ><TT
 678 CLASS="LITERAL"
 679 >serverName</TT
 680 ></TD
 681 ><TD
 682 ><TT
 683 CLASS="TYPE"
 684 >String</TT
 685 ></TD
 686 ><TD
 687 ><SPAN
 688 CLASS="PRODUCTNAME"
 689 >PostgreSQL</SPAN
 690 > database server
 691          host name</TD
 692 ></TR
 693 ><TR
 694 ><TD
 695 ><TT
 696 CLASS="LITERAL"
 697 >databaseName</TT
 698 ></TD
 699 ><TD
 700 ><TT
 701 CLASS="TYPE"
 702 >String</TT
 703 ></TD
 704 ><TD
 705 ><SPAN
 706 CLASS="PRODUCTNAME"
 707 >PostgreSQL</SPAN
 708 > database name</TD
 709 ></TR
 710 ><TR
 711 ><TD
 712 ><TT
 713 CLASS="LITERAL"
 714 >portNumber</TT
 715 ></TD
 716 ><TD
 717 ><TT
 718 CLASS="TYPE"
 719 >int</TT
 720 ></TD
 721 ><TD
 722 >TCP port which the
 723         <SPAN
 724 CLASS="PRODUCTNAME"
 725 >PostgreSQL</SPAN
 726 > database server is
 727         listening on (or 0 to use the default port)</TD
 728 ></TR
 729 ><TR
 730 ><TD
 731 ><TT
 732 CLASS="LITERAL"
 733 >user</TT
 734 ></TD
 735 ><TD
 736 ><TT
 737 CLASS="TYPE"
 738 >String</TT
 739 ></TD
 740 ><TD
 741 >User used to make database connections</TD
 742 ></TR
 743 ><TR
 744 ><TD
 745 ><TT
 746 CLASS="LITERAL"
 747 >password</TT
 748 ></TD
 749 ><TD
 750 ><TT
 751 CLASS="TYPE"
 752 >String</TT
 753 ></TD
 754 ><TD
 755 >Password used to make database connections</TD
 756 ></TR
 757 ></TBODY
 758 ></TABLE
 759 ></DIV
 760 ><P
 761 >The pooling implementations require some additional
 762       configuration properties, which are shown in <A
 763 HREF="jdbc-datasource.html#JDBC-DS-DS-XPROPS"
 764 >Table 31-5</A
 765 >.</P
 766 ><DIV
 767 CLASS="TABLE"
 768 ><A
 769 NAME="JDBC-DS-DS-XPROPS"
 770 ></A
 771 ><P
 772 ><B
 773 >Table 31-5. Additional Pooling <CODE
 774 CLASS="CLASSNAME"
 775 >DataSource</CODE
 776 > Configuration Properties</B
 777 ></P
 778 ><TABLE
 779 BORDER="1"
 780 CLASS="CALSTABLE"
 781 ><COL><COL><COL><THEAD
 782 ><TR
 783 ><TH
 784 >Property</TH
 785 ><TH
 786 >Type</TH
 787 ><TH
 788 >Description</TH
 789 ></TR
 790 ></THEAD
 791 ><TBODY
 792 ><TR
 793 ><TD
 794 ><TT
 795 CLASS="LITERAL"
 796 >dataSourceName</TT
 797 ></TD
 798 ><TD
 799 ><TT
 800 CLASS="TYPE"
 801 >String</TT
 802 ></TD
 803 ><TD
 804 >Every pooling <TT
 805 CLASS="LITERAL"
 806 >DataSource</TT
 807 > must have a
 808          unique name.</TD
 809 ></TR
 810 ><TR
 811 ><TD
 812 ><TT
 813 CLASS="LITERAL"
 814 >initialConnections</TT
 815 ></TD
 816 ><TD
 817 ><TT
 818 CLASS="TYPE"
 819 >int</TT
 820 ></TD
 821 ><TD
 822 >The number of database connections to be created
 823         when the pool is initialized.</TD
 824 ></TR
 825 ><TR
 826 ><TD
 827 ><TT
 828 CLASS="LITERAL"
 829 >maxConnections</TT
 830 ></TD
 831 ><TD
 832 ><TT
 833 CLASS="TYPE"
 834 >int</TT
 835 ></TD
 836 ><TD
 837 >The maximum number of open database connections to
 838         allow.  When more connections are requested, the caller
 839         will hang until a connection is returned to the pool.</TD
 840 ></TR
 841 ></TBODY
 842 ></TABLE
 843 ></DIV
 844 ><P
 845 ><A
 846 HREF="jdbc-datasource.html#JDBC-DS-EXAMPLE"
 847 >Example 31-9</A
 848 > shows an example of typical application code using a
 849      pooling <TT
 850 CLASS="LITERAL"
 851 >DataSource</TT
 852 >.</P
 853 ><DIV
 854 CLASS="EXAMPLE"
 855 ><A
 856 NAME="JDBC-DS-EXAMPLE"
 857 ></A
 858 ><P
 859 ><B
 860 >Example 31-9. <TT
 861 CLASS="LITERAL"
 862 >DataSource</TT
 863 > Code Example</B
 864 ></P
 865 ><P
 866 >     Code to initialize a pooling <CODE
 867 CLASS="CLASSNAME"
 868 >DataSource</CODE
 869 > might look like this:
 870 </P><PRE
 871 CLASS="PROGRAMLISTING"
 872 >Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource();
 873 source.setDataSourceName("A Data Source");
 874 source.setServerName("localhost");
 875 source.setDatabaseName("test");
 876 source.setUser("testuser");
 877 source.setPassword("testpassword");
 878 source.setMaxConnections(10);</PRE
 879 ><P>
 880       Then code to use a connection from the pool might look
 881       like this.  Note that it is critical that the connections
 882       are eventually closed.  Else the pool will <SPAN
 883 CLASS="QUOTE"
 884 >"leak"</SPAN
 885 > connections and
 886       will eventually lock all the clients out.
 887 </P><PRE
 888 CLASS="PROGRAMLISTING"
 889 >Connection con = null;
 890 try {
 891     con = source.getConnection();
 892     // use connection
 893 } catch (SQLException e) {
 894     // log error
 895 } finally {
 896     if (con != null) {
 897         try { con.close(); } catch (SQLException e) {}
 898     }
 899 }</PRE
 900 ><P>
 901     </P
 902 ></DIV
 903 ></DIV
 904 ><DIV
 905 CLASS="SECT2"
 906 ><H2
 907 CLASS="SECT2"
 908 ><A
 909 NAME="JDBC-JNDI"
 910 >31.10.4. Data Sources and <ACRONYM
 911 CLASS="ACRONYM"
 912 >JNDI</ACRONYM
 913 ></A
 914 ></H2
 915 ><A
 916 NAME="AEN25239"
 917 ></A
 918 ><P
 919 >     All the <TT
 920 CLASS="LITERAL"
 921 >ConnectionPoolDataSource</TT
 922 > and
 923      <TT
 924 CLASS="LITERAL"
 925 >DataSource</TT
 926 > implementations can be stored
 927      in <ACRONYM
 928 CLASS="ACRONYM"
 929 >JNDI</ACRONYM
 930 >.  In the case of the nonpooling
 931      implementations, a new instance will be created every time the
 932      object is retrieved from <ACRONYM
 933 CLASS="ACRONYM"
 934 >JNDI</ACRONYM
 935 >, with the
 936      same settings as the instance that was stored.  For the
 937      pooling implementations, the same instance will be retrieved
 938      as long as it is available (e.g., not a different
 939      <ACRONYM
 940 CLASS="ACRONYM"
 941 >JVM</ACRONYM
 942 > retrieving the pool from
 943      <ACRONYM
 944 CLASS="ACRONYM"
 945 >JNDI</ACRONYM
 946 >), or a new instance with the same
 947      settings created otherwise.
 948     </P
 949 ><P
 950 >     In the application server environment, typically the
 951      application server's <TT
 952 CLASS="LITERAL"
 953 >DataSource</TT
 954 > instance
 955      will be stored in <ACRONYM
 956 CLASS="ACRONYM"
 957 >JNDI</ACRONYM
 958 >, instead of the
 959      <SPAN
 960 CLASS="PRODUCTNAME"
 961 >PostgreSQL</SPAN
 962 >
 963      <TT
 964 CLASS="LITERAL"
 965 >ConnectionPoolDataSource</TT
 966 > implementation.
 967     </P
 968 ><P
 969 >     In an application environment, the application may store
 970      the <TT
 971 CLASS="LITERAL"
 972 >DataSource</TT
 973 > in <ACRONYM
 974 CLASS="ACRONYM"
 975 >JNDI</ACRONYM
 976 >
 977      so that it doesn't have to make a reference to the
 978      <TT
 979 CLASS="LITERAL"
 980 >DataSource</TT
 981 > available to all application
 982      components that may need to use it.  An example of this is
 983      shown in <A
 984 HREF="jdbc-datasource.html#JDBC-DS-JNDI"
 985 >Example 31-10</A
 986 >.
 987     </P
 988 ><DIV
 989 CLASS="EXAMPLE"
 990 ><A
 991 NAME="JDBC-DS-JNDI"
 992 ></A
 993 ><P
 994 ><B
 995 >Example 31-10. <CODE
 996 CLASS="CLASSNAME"
 997 >DataSource</CODE
 998 > <ACRONYM
 999 CLASS="ACRONYM"
1000 >JNDI</ACRONYM
1001 > Code Example</B
1002 ></P
1003 ><P
1004 >     Application code to initialize a pooling <CODE
1005 CLASS="CLASSNAME"
1006 >DataSource</CODE
1007 > and add
1008      it to <ACRONYM
1009 CLASS="ACRONYM"
1010 >JNDI</ACRONYM
1011 > might look like this:
1012 </P><PRE
1013 CLASS="PROGRAMLISTING"
1014 >Jdbc3PoolingDataSource source = new Jdbc3PoolingDataSource();
1015 source.setDataSourceName("A Data Source");
1016 source.setServerName("localhost");
1017 source.setDatabaseName("test");
1018 source.setUser("testuser");
1019 source.setPassword("testpassword");
1020 source.setMaxConnections(10);
1021 new InitialContext().rebind("DataSource", source);</PRE
1022 ><P>
1023       Then code to use a connection from the pool might look
1024       like this:
1025 </P><PRE
1026 CLASS="PROGRAMLISTING"
1027 >Connection con = null;
1028 try {
1029     DataSource source = (DataSource)new InitialContext().lookup("DataSource");
1030     con = source.getConnection();
1031     // use connection
1032 } catch (SQLException e) {
1033     // log error
1034 } catch (NamingException e) {
1035     // DataSource wasn't found in JNDI
1036 } finally {
1037     if (con != null) {
1038         try { con.close(); } catch (SQLException e) {}
1039     }
1040 }</PRE
1041 ><P>
1042     </P
1043 ></DIV
1044 ></DIV
1045 ></DIV
1046 ><DIV
1047 CLASS="NAVFOOTER"
1048 ><HR
1049 ALIGN="LEFT"
1050 WIDTH="100%"><TABLE
1051 SUMMARY="Footer navigation table"
1052 WIDTH="100%"
1053 BORDER="0"
1054 CELLPADDING="0"
1055 CELLSPACING="0"
1056 ><TR
1057 ><TD
1058 WIDTH="33%"
1059 ALIGN="left"
1060 VALIGN="top"
1061 ><A
1062 HREF="jdbc-thread.html"
1063 ACCESSKEY="P"
1064 >Prev</A
1065 ></TD
1066 ><TD
1067 WIDTH="34%"
1068 ALIGN="center"
1069 VALIGN="top"
1070 ><A
1071 HREF="index.html"
1072 ACCESSKEY="H"
1073 >Home</A
1074 ></TD
1075 ><TD
1076 WIDTH="33%"
1077 ALIGN="right"
1078 VALIGN="top"
1079 ><A
1080 HREF="jdbc-reading.html"
1081 ACCESSKEY="N"
1082 >Next</A
1083 ></TD
1084 ></TR
1085 ><TR
1086 ><TD
1087 WIDTH="33%"
1088 ALIGN="left"
1089 VALIGN="top"
1090 >Using the Driver in a Multithreaded or a Servlet Environment</TD
1091 ><TD
1092 WIDTH="34%"
1093 ALIGN="center"
1094 VALIGN="top"
1095 ><A
1096 HREF="jdbc.html"
1097 ACCESSKEY="U"
1098 >Up</A
1099 ></TD
1100 ><TD
1101 WIDTH="33%"
1102 ALIGN="right"
1103 VALIGN="top"
1104 >Further Reading</TD
1105 ></TR
1106 ></TABLE
1107 ></DIV
1108 ></BODY
1109 ></HTML
1110 >