This activity demonstrates the ease with which a program that embeds Derby can be modified for a
client/server implementation that uses the Derby Network
Server.
This activity assumes you have performed the preceding activities
and have a working directory called DERBYTUTOR, and have
copies of the program files from the $DERBY_HOME/demo/programs/workingwithderby/
directory. A basic knowledge of the WwdEmbedded.java program
and experience starting and connecting to the Network Server are helpful.
You will need to use a text editor to create the WwdClient.java
program.
Note: As a convenience, the workingwithderby
directory contains a program WwdClientExample.java
which has already been edited in the appropriate manner. You can use
this program directly as it is, or you can compare the contents of this
program to the WwdClient.java program that you will
construct in this activity, to see how the changes are made.
You will create a
Derby client
program,
WwdClient.java, by changing a few lines of the
WwdEmbedded.java program.
You can run the client program in multiple command shells, allowing simultaneous
update from two or more sources.
You use two command windows (Server-Shell
and Client-Shell) in this activity. You use the Server-Shell to start the Derby Network Server and display
Network Server messages. You use the Client-Shell to edit, compile and run
the newly created WwdClient.java program. You set the CLASSPATH environment
variable in the Client-Shell to support the client JDBC program.
- Create the WwdClient program using the following
steps:
- Open a command window (Client-Shell).
- Change to the DERBYTUTOR directory.
- Make a copy of the WwdEmbedded.java program
called WwdClient.java.
Operating System |
Command |
UNIX
(Korn Shell)
|
cp WwdEmbedded.java WwdClient.java
|
Windows
|
copy WwdEmbedded.java WwdClient.java
|
- Open the WwdClient.java file in a text editor
and update the class name to reflect the new file name:
Original declaration
public class WwdEmbedded
New declaration
public class WwdClient
- Edit the DEFINE VARIABLES SECTION of the program
so that the driver variable contains the name of the Derby client driver class and
the connectionURL variable contains the hostname and port
number of the Network Server.
Original definitions
String driver = "org.apache.derby.jdbc.EmbeddedDriver";
String dbName="jdbcDemoDB";
String connectionURL = "jdbc:derby:" + dbName + ";create=true";
New definitions
String driver = "org.apache.derby.jdbc.ClientDriver";
...
String connectionURL = "jdbc:derby://localhost:1527/" + dbName + ";create=true";
- Compile the application.
javac WwdClient.java
A command prompt appears if the compilation
is successful. The binary file WwdClient.class is created.
If an error message appears, modify the line indicated so that it is identical
to the example. (As noted above, you can compare the contents of your
WwdClient.java against the
WwdClientExample.java program provided in the
workingwithderby directory to verify that your editing was
performed successfully.)
- Set up the client/server environment using the following steps:
- Open a command window (Server-Shell).
- Change to the DERBYTUTOR directory.
- Start the Network Server:
Operating System |
Command |
UNIX
(Korn Shell)
|
java -jar $DERBY_HOME/lib/derbyrun.jar server start
2010-02-11 22:14:03.613 GMT : Security manager
installed using the Basic server security policy.
2010-02-11 22:14:04.278 GMT : Apache Derby Network
Server - 10.6.0.0 - (908506) started and ready to
accept connections on port 1527
|
Windows
|
java -jar %DERBY_HOME%\lib\derbyrun.jar server start
2010-02-11 22:14:03.613 GMT : Security manager
installed using the Basic server security policy.
2010-02-11 22:14:04.278 GMT : Apache Derby Network
Server - 10.6.0.0 - (908506) started and ready to
accept connections on port 1527
|
- Run the client program using the following steps:
- Return to the Client-Shell window.
- If not already set, set the CLASSPATH environment
variable to include the location of the file derbyclient.jar:
Operating System |
Command |
UNIX
(Korn Shell)
|
export CLASSPATH=$DERBY_HOME/lib/derbyclient.jar:.
|
Windows
|
set CLASSPATH=%DERBY_HOME%\lib\derbyclient.jar;.
|
Important: Include the dot (.)
at the end of the command so that your current working directory is included
in the classpath.
- Run the program:
java WwdClient
org.apache.derby.jdbc.ClientDriver loaded.
Connected to database jdbcDemoDB
Enter wish-list item (enter exit to end):
a sunny day
__________________________________________________________
On 2010-02-11 17:11:13.838 I wished for a peppermint stick
On 2010-02-11 17:11:19.381 I wished for a long vacation
On 2010-02-11 17:17:43.521 I wished for a sunny day
__________________________________________________________
Enter wish-list item (enter exit to end):
a new car
__________________________________________________________
On 2010-02-11 17:11:13.838 I wished for a peppermint stick
On 2010-02-11 17:11:19.381 I wished for a long vacation
On 2010-02-11 17:17:43.521 I wished for a sunny day
On 2010-02-11 17:17:48.547 I wished for a new car
__________________________________________________________
Enter wish-list item (enter exit to end):
exit
Closed connection
Getting Started With Derby JDBC program ending.
- Shut down the Network Server:
Operating System |
Command |
UNIX
(Korn Shell)
|
java -jar $DERBY_HOME/lib/derbyrun.jar server shutdown
2010-02-11 22:19:13.475 GMT : Apache Derby Network
Server - 10.6.0.0 - (908506) shutdown
|
Windows
|
java -jar %DERBY_HOME%\lib\derbyrun.jar server shutdown
2010-02-11 22:19:13.475 GMT : Apache Derby Network
Server - 10.6.0.0 - (908506) shutdown
|
The server shutdown confirmation appears
in both command windows.
Activity notes In a client/server environment, the client
program is often used from other computers on the network. Whenever a system
accepts connections from other computers, there is a chance of abuse. To maintain
security, the Derby Network
Server defaults to accepting connections only from clients running on the
local machine (localhost). Before this or any other Derby client program can access
the Network Server from another machine, additional steps should be taken
to secure the Network Server environment. Once secured, the Network Server
can be safely configured to accept connections from other machines. Refer
to the "Network Server security" and "Running the Network Server under the
security manager" sections of the Derby Server and Administration Guide for
important information on securing the Network Server and enabling network
connections.
With the Network Server started, you can run the client
program simultaneously in multiple windows. To demonstrate this, open two
command windows and perform the substeps of the "Run the client program" step
in each window. Both clients will operate without a problem. In contrast,
it would not be possible for a program that uses the embedded driver (for
example, WwdEmbedded.java) to access the database until the
database or the Network Server is shut down.
You may have noticed that
the client program does not shut down the database. This is because the database
is a shared resource in a client/server environment and, in most cases, should
be shut down only when the Network Server is shut down. If multiple clients
are accessing the database and one client shuts down the database, the remaining
clients will encounter a failure the next time they attempt an SQL command.
Derby's two architectures have
caused confusion for some new Derby users,
who mistakenly think that embedded is a single-user configuration. This is
not true. The embedded driver supports multiple simultaneous connections,
performs locking, and provides performance, integrity, and recoverability.
Any application that uses the embedded driver can open multiple Derby connections
and then provide a means for multiple users to interact with the database
on each connection. The Derby Network
Server is an example of such an application.