# Activity 4: Create and run a JDBC program using the client driver and Network Server

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.

1. Create the `WwdClient` program using the following steps:
   1. Open a command window (Client-Shell).
   2. Change to the `DERBYTUTOR` directory.
   3. Make a copy of the `WwdEmbedded.java` program called `WwdClient.java`, as shown in the following table.

      Table 1. Command to copy the program
      Operating System | Command
      --- | ---
      UNIX (Korn Shell) |
          cp WwdEmbedded.java WwdClient.java
      Windows |
          copy WwdEmbedded.java WwdClient.java

   4. 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

   5. 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";

   6. 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.)
2. Set up the client/server environment using the following steps:
   1. Open a command window (Server-Shell).
   2. Change to the `DERBYTUTOR` directory.
   3. Start the Network Server, as shown in the following table.

      Table 1. Command to start the Network Server
      Operating System | Command
      --- | ---
      UNIX (Korn Shell) |
          java -jar $DERBY_HOME/lib/derbyrun.jar server start
          Fri Sep 14 09:55:23 EDT 2012 : Security
           manager installed using the Basic server
           security policy.
          Fri Sep 14 09:55:24 EDT 2012 : Apache Derby
           Network Server - 10.10.0.0 - (1384314) started
           and ready to accept connections on port 1527
      Windows |
          java -jar %DERBY_HOME%\lib\derbyrun.jar server start
          Fri Sep 14 09:55:23 EDT 2012 : Security
           manager installed using the Basic server
           security policy.
          Fri Sep 14 09:55:24 EDT 2012 : Apache Derby
           Network Server - 10.10.0.0 - (1384314) started
           and ready to accept connections on port 1527

3. Run the client program using the following steps:
   1. Return to the Client-Shell window.
   2. Set the `CLASSPATH` environment variable to include the location of the file `derbyclient.jar` (not `derby.jar` as in the embedded example), as shown in the following table.

      Table 1. Command to set the `CLASSPATH` environment variable
      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.
   3. 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 2012-09-14 09:46:37.77 I wished for a peppermint stick
          On 2012-09-14 09:46:51.654 I wished for a long vacation
          On 2012-09-14 09:56:36.6 I wished for a sunny day
            __________________________________________________
          Enter wish-list item (enter exit to end):
          a new car
            __________________________________________________
          On 2012-09-14 09:46:37.77 I wished for a peppermint stick
          On 2012-09-14 09:46:51.654 I wished for a long vacation
          On 2012-09-14 09:56:36.6 I wished for a sunny day
          On 2012-09-14 09:56:48.367 I wished for a new car
            __________________________________________________
          Enter wish-list item (enter exit to end):
          exit
          Closed connection
          Getting Started With Derby JDBC program ending.

4. Shut down the Network Server, as shown in the following table.

   Table 1. Command to shut down the Network Server
   Operating System | Command
   --- | ---
   UNIX (Korn Shell) |
       java -jar $DERBY_HOME/lib/derbyrun.jar server shutdown
       Fri Sep 14 09:58:12 EDT 2012 : Apache Derby
        Network Server - 10.10.0.0 - (1384314) shutdown
   Windows |
       java -jar %DERBY_HOME%\lib\derbyrun.jar server shutdown
       Fri Sep 14 09:58:12 EDT 2012 : Apache Derby
        Network Server - 10.10.0.0 - (1384314) 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 Derby Security 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.

Parent topic: Self-study tutorial for users new to Derby