Sun Microsystems Logo

 

 
 

Sun[tm] ONE Application Server 7 Samples
Using PointBase with the Samples


Sun ONE Application Server 7 includes the PointBase Network Server version 4.2 database as part of the installable components except when the application server is installed as part of a Solaris 9 installation.

When PointBase is installed as part of an application server installation, a prepopulated database file containing tables and data for all of the database oriented sample applications is included in the installation. Additionally, the PointBase Type 4 JDBC[tm] driver is included in the application server environment. During installation of the application server, PointBase is installed in the following location:

<appserver_install_dir>/pointbase/

The documentation for the database is available at:

<appserver_install_dir>/pointbase/docs/

This document describes several aspects of working with the PointBase server and Sun ONE Application Server:

  » Installing and Configuring PointBase Server (if not already installed)
  » Creating Your Own PointBase Runtime Environment (optional)
  » Starting PointBase
  » Stopping PointBase
  » Executing SQL Statements with PointBase
  » Registering JDBC Resources and Defining Connection Pools

Installing and Configuring PointBase Server (if not already installed)

PointBase is not installed when either the application server is installed as part of a Solaris 9 installation or, during installation of the application server, the PointBase component was deselected as a component to be installed.

To determine if pointbase is installed and configured to work with sample applications, check your application server installation for the following directory:

<appserver_install_dir>/pointbase/

If PointBase exists in your application server installation, see the Starting PointBase section for details on starting the database server.

To install and configure PointBase for use with the sample applications, follow these steps:

  1. Download and Install PointBase Server and Client Products
  2. Update Sample Ant Files
  3. Copy Samples PointBase Database Files
  4. Add PointBase Type 4 JDBC[tm] Driver to Application Server's Classpath

1. Download and Install PointBase Server and Client Products

Download the PointBase evaluation software from http://www.pointbase.com.

Install at least the PointBase Server and Client products on your system. The Pointbase Client product includes the PointBase Type 4 JDBC driver.

2. Update Sample Ant Files

2 a. Edit the common.properties file under the <appserver_install_dir>/samples/ directory and set the com.sun.aas.pointbaseRoot property to the PointBase installation directory.

2 b. Next, edit the common.xml file under the <appserver_install_dir>/samples/ directory and modify the db.classpath property to specify the appropriate name and location of the PointBase tools and client JAR files.

In the following section of the common.xml file, replace the client_tools/ subdirectory with the name of the subdirectory under which the tools and client JAR files reside and modify the name of the JAR files as appropriate:

<!-- pointbase properties -->
<property name="db.driver" value="com.pointbase.jdbc.jdbcUniversalDriver"/>
<property name="db.root" value="${com.sun.aas.pointbaseRoot}"/>
<property name="db.url" value="jdbc:pointbase:server://localhost/sun-appserv-samples"/>
<property name="db.classpath" value="${db.root}/client_tools/lib/pbtools42RE.jar;${db.root}/client_tools/lib/pbclient42RE.jar"/>

For example, these JAR file are located under the lib/ directory of a PointBase 4.3 installation.

<!-- pointbase properties -->
<property name="db.driver" value="com.pointbase.jdbc.jdbcUniversalDriver"/>
<property name="db.root" value="${com.sun.aas.pointbaseRoot}"/>
<property name="db.url" value="jdbc:pointbase:server://localhost/sun-appserv-samples"/>
<property name="db.classpath" value="${db.root}/lib/pbtools43.jar;${db.root}/lib/pbclient43.jar"/>

3. Copy Samples PointBase Database Files

The samples component of Sun ONE Application Server 7 contains a prepopulated PointBase database file for the sample applications. If you do not intent to share your PointBase installation with other users, you must copy the prepopulated database files from the samples area to the PointBase product installation area.

If you intend to share the PointBase installation with other users, then you will learn how to create your own PointBase runtime environment in the next section. If this is the case, then proceed to the next step to add the PointBase JDBC driver to your application server's classpath.

To copy the prepopulated database files to your PointBase installation, copy the files contained in the following directory:

<appserver_install_dir>/samples/pointbase/databases/*

to:

<pointbase_install_dir>/databases/

This operation will copy the files named sun-appserv-samples$1.wal and sun-appserv-samples.dbn to the PointBase installation area.

4. Add PointBase Type 4 JDBC Driver to Server Application Server's Classpath

Copy the PointBase Type 4 JDBC driver library from the PointBase installation directory to the lib/ directory of your application server instance. For example:

.../domains/domain1/server1/lib/

You can find the JDBC driver under <pointbase_install_dir>/lib/. The driver is named pbclientnn.jar where nn represents the version of PointBase.

Restart the application server to make the server aware of the driver.

Alternatively, you can specify the location of the PointBase driver in the Classpath Suffix field in the application server's configuration. Start the administrative console and access the application server instance's JVM Settings -> Path Settings area to make this change.

Creating Your Own PointBase Runtime Environment (optional)

If you are either sharing your application server installation with other users or your system user ID does not have write permissions to the area in which PointBase is installed (which is typically the case when the application server is installed by the root user on UNIX systems and you are using a non-root user ID), you should make a copy of the pre-built PointBase databases and the PointBase Server startup script.

You can create your own copy of the PointBase Server environment by following these steps:

1. Create a directory named pointbase/ in your own area of the system.

2. Copy the prepopulated PointBase database files from the samples installation area to your own PointBase area.

To copy the prepopulated database files to your own PointBase installation, copy the files contained in the following directory:

<appserver_install_dir>/samples/pointbase/databases/*

to:

<personal_pointbase_dir>/pointbase/databases/

This operation will copy the files named sun-appserv-samples$1.wal and sun-appserv-samples.dbn to the your own PointBase area.

3. Copy the the following files from the PointBase installation area to <personal_pointbase_dir>/pointbase/ directory:

Files Comments

StartServer.sh or StartServer.bat

Start up script containing port number on which the PointBase Server listens. Please edit the files, if you want to make any modifications.
pointbase.ini Initialization file specifying location of database files. Please edit the file, if you want to make any modifications.

If PointBase was installed as part of the application server installation, these files are located at:

<appserver_install_dir>/pointbase/server/

If you downloaded an installed the evaluation distribution of PointBase, these files are located at:

<pointbase_install_dir>/tools/server/

4. Edit the StartServer.sh or StartServer.bat script to specify a port number that does not conflict with other running instances of the PointBase Server.

Using a Non-default Port Number: If you change the port number on which the PointBase Server listens from the default value of 9092, you must modify the JDBC Connection Pool properties to reflect the non-default port number. Otherwise the application server will not be able to contact your copy of the PointBase Server.

The dataBaseName property specified for the JDBC Connection Pool must be changed from:

jdbc:pointbase:server://localhost/sun-appserv-samples

to:

jdbc:pointbase:server://localhost:<port>/sun-appserv-samples

Where <port> is the port number specified in the StartServer script.

If you do not use the default port of 9092, then you should modify the db.port property in the common.xml file.

Now you are ready to start the PointBase Server from your own directory area.

Starting PointBase

The database server can be easily started by performing one of the following actions:

Windows Platforms:

PointBase installed with the application server: Start -> Programs -> Sun Microsystems -> Sun ONE Application Server 7 -> Start PointBase

PointBase downloaded and installed separately: <pointbase_install_dir>/tools/server/startserver.bat

UNIX Platforms:

PointBase installed with the application server: <appserver_install_dir>/pointbase/server/StartServer.sh

PointBase downloaded and installed separately: <pointbase_install_dir>/tools/server/startserver.sh

Alternatively, if you copied the PointBase Server files to your own directory, execute the StartServer script from that location.

Once you execute the startup script, you will see the following text in either a command window or at the UNIX terminal prompt:

    Server started, listening on port 9092, display level: 0 ...
    >

To stop the server, enter quit at the > prompt.

Don't Need A Console Window? On UNIX, if you want to run the PointBase server in the background, you can edit the StartServer.sh script and place the option "/noconsole" at the end of the command line.

.../java -classpath ./lib/pbserver42RE.jar com.pointbase.net.netServer /port:9092 /noconsole

The jar file pbserver42RE.jar is for PointBase 4.2 installation. You may have to use different jar file depending upon your PointBase installation.

Use "&" at the end of the StartServer.sh command to run the server in the background.

./StartServer.sh &
[1] 26418

See the PointBase server documentation in the following location for more information on starting and stopping the server:

<pointbase_install_dir>/docs/


Stopping PointBase

To stop the server, enter quit at the > prompt.

Executing SQL Statements with PointBase

The PointBase database installed with the application server is prepopulated with data for all sample applications. In some of the samples, you may need to remove, recreate and repopulate tables. The easiest means of performing these tasks is to use the PointBase Console GUI to execute SQL statements found in the .sql files within the src/sql/ directory of each sample application.

To start the Console, follow these instructions:

Windows Platforms:

PointBase installed with the application server: Execute <appserver_install_dir>\pointbase\client_tools\PB_console.bat

PointBase downloaded and installed separately: <pointbase_install_dir>\tools\server\startconsole.bat

UNIX Platforms:

PointBase installed with the application server: Execute <appserver_install_dir>/pointbase/client_tools/PB_console.sh

PointBase downloaded and installed separately: <pointbase_install_dir>/tools/server/startconsole.sh

The Console appears as follows:

To connect to the database, select DBA -> Connect to Database

Enter the following information for the samples database installed with the application server:

  • Driver: use the default value as provided.
  • URL: jdbc:pointbase://localhost/sun-appserv-samples
  • User and Password: use values as appropriate for the sample of interest:
Sample User Password
Java Pet Store petstore petstore
opc opc
supplier supplier
JDBC samples jdbc jdbc
Lifecycle samples lifecycle lifecycle
CMP samples cmp cmp
Distributed transactions transactions transactions
BMP samples bmp bmp
Smartticket 1.1.1 smarticket smarticket
Duke's Bank dukesbank dukesbank
Connectors cci cci

Once connected to the database, you can enter SQL statements in the top portion of the window and the results can be viewed in the lower portion. SQL statements can be entered individually or as a sequence of statements from a file.

If a single statement has to be executed, then enter the SQL statement and select the menu option SQL -> Execute to execute the statement.

If a sequence of statements is to be executed, use the menu option SQL -> Execute all.

To use a .sql file, as provided with the sample applications, select File -> Open and open the .sql file of interest. If the .sql file contains an exit; statement, you should remove this statement to avoid exiting from the Console when executing statements read from the .sql file.

Review the PointBase documentation for more information on the PointBase console. The documentation is available at <pointbase_install_dir>/docs/.

Registering JDBC Resources and Defining Connection Pools

Refer to the Getting Started Guide for details on defining JDBC Connecton Pools for PointBase through the application server's administrative console.

As an advanced topic, you can reveiw the samples common.xml and build.xml files to learn how to use the asadmin command line interface (CLI) to define JDBC resources and connection pools.