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

This section demonstrates the ease with which a program that embeds Derby can be modified for a client/server implementation using the Derby Network Server. A Derby client program, `WwdClient.java`, is created by changing a few lines of the `WwdEmbedded.java` program. The client program can be run in multiple command shells allowing simultaneous update from two or more sources.

This activity assumes you have performed the preceding activities and so have a working directory called `DERBYDBS`, are familiar with setting the DERBY_HOME and CLASSPATH environment variables 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 Network Server is helpful. You will need to use a text editor to create the `WwdClient.java` program.
Two command windows (`Server-Shell` and `Client-Shell`) are used in this activity. The `Server-Shell` is used to start the Derby Network Server and display Network Server messages. The `Client-Shell` is used to edit, compile and run the newly created `WwdClient.java` program. The CLASSPATH environment variable is set in `Client-Shell` to support the client JDBC program.

1. Create the WwdClient program.
   1. Open a command window that we'll call the `Client-Shell`.
   2. Change directory (`cd`) to the `DERBYDBS` directory.
   3. Make a copy of the `WwdEmbedded.java` program called `WwdClient.java`.
      On Windows platforms:

            copy WwdEmbedded.java WwdClient.java

      On UNIX Korn Shell platforms:

            cp WwdEmbedded.java WwdClient.java

   4. Open the `WwdClient.java` file in your favorite text editor and update the class name to reflect the new filename:

          Original declaration
               public class WwdEmbedded

          New declaration
               public class WwdClient

   5. Edit the DEFINE VARIABLES SECTION of the program so the driver variable contains the name of the Derby Client Driver class and the connectionURL variable contains the hostname and a 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

      Important: Only a command prompt will be displayed if the compilation is successful. The binary file `WwdClient.class` will be created. If a syntax error is displayed, modify the line indicated so it is identical to the example.

      That's all there is to it.

2. Set up the client/server environment.

   Before you run the `WwdClient` program, the Network Server needs to be started.

   1. Open a command window that we'll call the `Server-Shell`.
   2. Change directory (`cd`) to the `DERBYDBS` directory.
   3. Set the DERBY_HOME environment variable.
   4. Start the Network Server:
      On Windows platforms:

            java -jar %DERBY_HOME%\lib\derbynet.jar start

            Apache Derby Network Server - 10.2.1.6 - (452058) started and
             ready to accept connections on port 1527 at 2006-09-22
             00:56:33.091 GMT

      On UNIX Korn Shell platforms:

            java -jar $DERBY_HOME/lib/derbynet.jar start

            Apache Derby Network Server - 10.2.1.6 - (452058) started and
             ready to accept connections on port 1527 at 2006-09-22
             00:56:33.091 GMT

3. Run the client program.
   1. Return to the `Client-Shell` window.
   2. If it is not already defined, set the DERBY_HOME environment variable.
   3. Set the CLASSPATH environment variable to include the location of the file `derbyclient.jar`:
      On Windows platforms:

            set CLASSPATH=%DERBY_HOME%\lib\derbyclient.jar;.

      On UNIX Korn Shell platforms:

            export 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.
   4. 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 2006-09-21 15:11:50.412 I wished for a peppermint stick
          On 2006-09-21 15:12:47.024 I wished for an all expenses paid vacation
          On 2006-09-22 10:08:21.167 I wished for a sunny day
            ________________________________________________________

          Enter wish-list item (enter exit to end):
          a new car

            ________________________________________________________
          On 2006-09-21 15:11:50.412 I wished for a peppermint stick
          On 2006-09-21 15:12:47.024 I wished for an all expenses paid vacation
          On 2006-09-22 10:08:21.167 I wished for a sunny day
          On 2006-09-22 10:08:33.665 I wished for a new car
            ________________________________________________________

          Enter wish-list item (enter exit to end):
          exit

          Closed connection
          Working With Derby JDBC program ending.

4. Shut down the Network Server.
   On Windows platforms:

         java -jar %DERBY_HOME%\lib\derbynet.jar shutdown

         Apache Derby Network Server - 10.2.1.6 - (452058) shutdown
          at 2006-09-22 19:13:51.445 GMT

   On UNIX Korn Shell platforms:

         java -jar $DERBY_HOME/lib/derbynet.jar shutdown

         Apache Derby Network Server - 10.2.1.6 - (452058) shutdown
          at 2006-09-22 19:13:51.445 GMT

   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 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 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 (e.g. `WwdEmbedded`) 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 only be shut down when the Server is shut down. If multiple clients are accessing the database and one 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. They 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 using 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.

Previous topic: Activity 3: Run a JDBC program using the Embedded driver
Next topic: What next with Derby