
Administration Commands            create-jdbc-connection-pool(1)

NAME
     create-jdbc-connection-pool - registers the JDBC  connection
     pool

SYNOPSIS
     create-jdbc-connection-pool
     [--terse={true|false}][ --echo={true|false} ]
     [ --interactive={true|false} ] [ --host  host]
     [--port port] [--secure| -s ] [ --user  admin_user]
     [--passwordfile filename] [--help]
     [ --target  target]
     [--datasourceclassname classname] [--restype res_type]
     [--steadypoolsize poolsize] [--maxpoolsize poolsize]
     [--maxwait time] [--poolresize limit]
     [--idletimeout time] [--isolationlevel isolation_level]
     [--isolationguaranteed=true] [--isconnectvalidatereq=false]
     [--validationmethod auto-commit] [--validationtable tablename]
     [--failconnection=false] [--allownoncomponentcallers=false]
     [--nontransactionalconnections=false]
     [--description text] [--property (name=value)
     [:name=value]*] connectionpoolid

DESCRIPTION
     The create-jdbc-connection-pool command registers a new JDBC
     connection  pool  with  the  specified  JDBC connection pool
     name.

     This command is supported in remote mode only.

OPTIONS
     -t --terse                          Indicates that any  out-
                                         put  data  must  be very
                                         concise,       typically
                                         avoiding  human-friendly
                                         sentences  and  favoring
                                         well-formatted  data for
                                         consumption by a script.
                                         Default is false.

     -e --echo                           Setting  to  true   will
                                         echo  the  command  line
                                         statement on  the  stan-
                                         dard  output. Default is
                                         false.

     -I --interactive                    If    set    to     true
                                         (default),    only   the
                                         required        password

Java EE 5           Last change: 30 Jan 2007                    1

Administration Commands            create-jdbc-connection-pool(1)

                                         options are prompted.

     -H --host                           The machine  name  where
                                         the  domain  administra-
                                         tion server is  running.
                                         The   default  value  is
                                         localhost.

     -p --port                           The  HTTP/S   port   for
                                         administration.  This is
                                         the port  to  which  you
                                         should     point    your
                                         browser  in   order   to
                                         manage  the  domain. For
                                         example,
                                         http://localhost:4848.

                                         The default port  number
                                         is 4848.

     -s --secure                         If  set  to  true,  uses
                                         SSL/TLS  to  communicate
                                         with the domain adminis-
                                         tration server.

     -u --user                           The  authorized   domain
                                         administration    server
                                         administrative username.

                                         If  you  have  authenti-
                                         cated  to a domain using
                                         the asadmin  login  com-
                                         mand,  then you need not
                                         specify    the    --user
                                         option   on   subsequent
                                         operations to this  par-
                                         ticular domain.

     --passwordfile                      The       --passwordfile
                                         option   specifies   the
                                         name, including the full
                                         path, of a file contain-
                                         ing the password entries
                                         in  a  specific  format.
                                         The entry for the  pass-
                                         word   must   have   the
                                         AS_ADMIN_         prefix

Java EE 5           Last change: 30 Jan 2007                    2

Administration Commands            create-jdbc-connection-pool(1)

                                         followed by the password
                                         name    in     uppercase
                                         letters.

                                         For example, to  specify
                                         the  domain  administra-
                                         tion  server   password,
                                         use  an  entry  with the
                                         following        format:
                                         AS_ADMIN_PASSWORD=password,
                                         where  password  is  the
                                         actual     administrator
                                         password.  Other   pass-
                                         words that can be speci-
                                         fied             include
                                         AS_ADMIN_MAPPEDPASSWORD,
                                         AS_ADMIN_USERPASSWORD,
                                         and
                                         AS_ADMIN_ALIASPASSWORD.

                                         All remote commands must
                                         specify  the admin pass-
                                         word to authenticate  to
                                         the  domain  administra-
                                         tion   server,    either
                                         through   --passwordfile
                                         or  asadmin  login,   or
                                         interactively   on   the
                                         command   prompt.    The
                                         asadmin   login  command
                                         can  be  used  only   to
                                         specify  the admin pass-
                                         word.  For  other  pass-
                                         words,   that   must  be
                                         specified   for   remote
                                         commands,   use  the  --
                                         passwordfile  or   enter
                                         them   at   the  command
                                         prompt.

                                         If  you  have  authenti-
                                         cated  to a domain using
                                         the asadmin  login  com-
                                         mand,  then you need not
                                         specify the admin  pass-
                                         word   through   the  --
                                         passwordfile  option  on
                                         subsequent operations to
                                         this particular  domain.
                                         However,  this is appli-
                                         cable      only       to
                                         AS_ADMIN_PASSWORD

Java EE 5           Last change: 30 Jan 2007                    3

Administration Commands            create-jdbc-connection-pool(1)

                                         option. You  will  still
                                         need   to   provide  the
                                         other   passwords,   for
                                         example,
                                         AS_ADMIN_USERPASSWORD,
                                         as  and when required by
                                         individual     commands,
                                         such   as   update-file-
                                         user.

                                         For  security   reasons,
                                         passwords  specified  as
                                         an environment  variable
                                         will   not  be  read  by
                                         asadmin.

                                         The  default  value  for
                                         AS_ADMIN_MASTERPASSWORD
                                         is changeit.

     --help                              Displays the  help  text
                                         for the command.

     --target                            This  option  is  depre-
                                         cated.

     --datasourceclassname               The name of the  vendor-
                                         supplied JDBC datasource
                                         resource manager.

     --restype                           The interface  that  the
                                         datasource  class imple-
                                         ments.  Must be  one  of
                                         javax.sql.DataSource,
                                         javax.sql.ConnectionPoolDataSource
                                         or
                                         javax.sql.XADataSource.
                                         It  leads  to  an  error
                                         when this option  has  a
                                         legal   value   and  the
                                         indicated  interface  is
                                         not  implemented  by the
                                         datasource  class.  This
                                         option  has  no  default
                                         value.

Java EE 5           Last change: 30 Jan 2007                    4

Administration Commands            create-jdbc-connection-pool(1)

     --steadypoolsize                    The minimum and  initial
                                         number   of  connections
                                         maintained in the  pool.
                                         The default value is 8.

     --maxpoolsize                       The  maximum  number  of
                                         connections  that can be
                                         created.   The   default
                                         value is 32.

     --maxwait                           The  amount  of  time  a
                                         caller  will wait before
                                         a connection timeout  is
                                         sent.  The default is 60
                                         seconds. A  value  of  0
                                         forces   the  caller  to
                                         wait indefinitely.

     --poolresize                        Quantity  by  which  the
                                         pool  will  scale-up  or
                                         scale-down the number of
                                         connections.   Scale-up:
                                         When  the  pool  has  no
                                         free  connections,  pool
                                         will  scale-up  by  this
                                         quantity.    Scale-down:
                                         All the invalid and idle
                                         connections are removed,
                                         sometimes  resulting  in
                                         removing  connections of
                                         quantity  greater   than
                                         this  value. Steadypool-
                                         size  will  be  ensured.
                                         Possible values are from
                                         0  to  MAX_INTEGER.  The
                                         default value is 2.

     --idletimeout                       The  maximum  time,   in
                                         seconds,  that a connec-
                                         tion can remain idle  in
                                         the   pool.  After  this
                                         time, the implementation
                                         can  close  this connec-
                                         tion. This timeout value
                                         must   be  kept  shorter
                                         than  the  server   side
                                         timeout value to prevent
                                         the   accumulation    of

Java EE 5           Last change: 30 Jan 2007                    5

Administration Commands            create-jdbc-connection-pool(1)

                                         unusable  connections in
                                         the   application.   The
                                         default value is 300.

     --isolationlevel                    The         transaction-
                                         isolation-level  on  the
                                         pooled database  connec-
                                         tions.  This option does
                                         not   have   a   default
                                         value. If not specified,
                                         the pool  operates  with
                                         the   default  isolation
                                         level  that   the   JDBC
                                         driver provides.

                                         You can  set  a  desired
                                         isolation   level  using
                                         one  of   the   standard
                                         transaction    isolation
                                         levels:            read-
                                         uncommitted,       read-
                                         committed,   repeatable-
                                         read,      serializable.
                                         Applications that change
                                         the isolation level on a
                                         pooled  connection  pro-
                                         grammatically  risk pol-
                                         luting  the  pool.  This
                                         could  lead  to  program
                                         errors.

     --isisolationguaranteed             This is applicable  only
                                         when a particular isola-
                                         tion level is  specified
                                         for         transaction-
                                         isolation-level.     The
                                         default value is true.

                                         This option assures that
                                         every  time a connection
                                         is  obtained  from   the
                                         pool, isolation level is
                                         set   to   the   desired
                                         value.  This  could have
                                         some performance  impact
                                         on  some  JDBC  drivers.
                                         Administrators  can  set
                                         this  to  false when the
                                         application   does   not
                                         change  --isolationlevel

Java EE 5           Last change: 30 Jan 2007                    6

Administration Commands            create-jdbc-connection-pool(1)

                                         before   returning   the
                                         connection.

     --isconnectvalidatereq              If set to true,  connec-
                                         tions  are  validated or
                                         checked to see  if  they
                                         are usable before giving
                                         out to the  application.
                                         The   default  value  is
                                         false.

     --validationmethod                  The name of the  valida-
                                         tion  table used to per-
                                         form a query to validate
                                         a connection. Valid set-
                                         tings are:  auto-commit,
                                         meta-data, or table. The
                                         default value  is  auto-
                                         commit.

     --validationtable                   The name of the  valida-
                                         tion  table used to per-
                                         form a query to validate
                                         a connection.

     --failconnection                    If set to true, all con-
                                         nections   in  the  pool
                                         must be  closed  when  a
                                         single  validation check
                                         fails. The default value
                                         is false. One attempt is
                                         made   to   re-establish
                                         failed connections.

     --allownoncomponentcallers          A pool  with  this  pro-
                                         perty  set  to true, can
                                         be used by non-J2EE com-
                                         ponents,  that  is, com-
                                         ponents other than  EJBs
                                         or     Servlets.     The
                                         returned  connection  is
                                         enlisted   automatically
                                         with   the   transaction
                                         context   obtained  from
                                         the transaction manager.

Java EE 5           Last change: 30 Jan 2007                    7

Administration Commands            create-jdbc-connection-pool(1)

     --nontransactionalconnections       A pool  with  this  pro-
                                         perty    set   to   true
                                         returns             non-
                                         transactional    connec-
                                         tions.  This  connection
                                         does  not get  automati-
                                         cally enlisted with  the
                                         transaction manager.

     --description                       Text  providing  details
                                         about the specified JDBC
                                         connection pool.

     --property                          Optional       attribute
                                         name/value   pairs   for
                                         configuring the  connec-
                                         tion pool.

OPERANDS
     connectionpoolid            The name of the JDBC  connection
                                 pool to be created.

EXAMPLES
     Example 1 Using create-jdbc-connection-pool command

       asadmin> create-jdbc-connection-pool --user admin
       --passwordfile passwords.txt --host localhost --port 7070
       --datasourceclassname org.apache.derby.jdbc.ClientDataSource --restype javax.sql.XADataSource
       --property portNumber=1527:password=APP:user=APP:serverName=
       localhost:databaseName=sun-appserv-samples:connectionAttributes=\;
       create\\=true sample_derby_pool
       Command create-jdbc-connection-pool executed successfully

     Where, the sample_derby_pool is created. The escape  charac-
     ter  backslash (\) is used in the ---property option to dis-
     tinguish the semicolon (;). Two backslashes (\\) are used to
     distinguish the equal (=) sign.

EXIT STATUS
     0                           command executed successfully

     1                           error in executing the command

Java EE 5           Last change: 30 Jan 2007                    8

Administration Commands            create-jdbc-connection-pool(1)

SEE ALSO
     delete-jdbc-connection-pool(1),        list-jdbc-connection-
     pools(1)

Java EE 5           Last change: 30 Jan 2007                    9

