Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -------------------------------------------------------------------------------------------- Network Server System Test Readme 1) Description 2) Packaging 3) How to run 4) Settings 5) Known issues 6) Future work DESCRIPTION: ============ The Network Server System Test (NsTest) is a configurable long running system test for various Derby features running under the network server(or embedded) mode. The test uses a single table having all the supported data types as columns with multiple clients performing Insert/Update/Delete and Select operations. The table has a delete trigger which populates a similar table when fired. On regular intervals the test also performs back-up/restore and re-encryption. The test follows the suggested usage of JDBC with liberal use of PreparedStatements and closing of respective objects when not in use. The test starts off by using preset number of Initialzer threads (INIT_THREADS=6) to begin loading the tables. Once loaded, each invocation of the test uses 71 clients with the following distribution to peform various operations on the database: 1 - A single back-up/restore/re-encrypt thread 15 - Tester1 threads keeps the connection to the database open forever 45 - Tester2 threads frequently opens and closed based on a random choice 10 - Tester3 threads opens/closes the connection to the database after each query To increase the number of client either: (a) Update the above settings to teh desired number (b) Invoke multiple instances of the test in separate VMs with the System property 'derby.nstest.backupRestore' set to 'false' for all the instances except one. This will set the Backup/Restore/Re-Encryption thread to be started only once. Option (b) works best to avoid any single point of test failure and losing the entire test run artifacts. The test has been particularly useful in detecting increased memory usage, locking etc. and also verifies the expected behaviour when all the different Derby features are used in conjunction. PACKAGING: ========== The test resides under the org.apache.derbyTesting.systen.nstest package. The main class to invoke is org.apache.derbyTesting.system.nstest.NsTest. Currently all the variable settings used in the test are set in this class. The user threads reside in the 'tester' package while some initializer and generic utility classes belong to 'init' and 'utils' package. HOW TO RUN: =========== Usage: java org.apache.derbyTesting.system.nstest.NsTest [ DerbyClient | Embedded [ small ] ] If no arguments are specified, the test defaults to a client/server configuration (DerbyClient) The following flags can be set: -Dderby.nstest.backupRestore=false Turns off backup, restore, and re-encryption. -Dderby.nstest.outputFile=fileName Redirects output and errors to a file. -Dderby.nstest.justCountErrors=true Makes the test run quietly at steady-state, counting errors, and printing a summary at the end. -Dderby.nstest.durationInMinutes=$number Run for this number of minutes. The main class to invoke is org.apache.derbyTesting.system.nstest.NsTest. This class takes a String argument of "DerbyClient"/"Embedded", default is DerbyClient. The test requires the Network Server to be started on port 1900 to begin the run. To start the NW Server as a thread in the same VM, set the START_SERVER_IN_SAME_VM to true, useful for a small test setup. To turn off Backup/Restore/Re-Encryption, set the System property 'derby.nstest.backupRestore' to 'false', default is 'true'. To run the test can be run with a smaller configuration, add the parameter 'small'. This can only be used as the 2nd parameter, so you'll need to add DerbyClient or Embedded as the first parameter, then add small as the second. EXIT CRITERIA ============= 1. There should not be any fatal failures 2. No unwanted lock time outs or deadlocks SETTINGS: ========= Almost all the variable settings for this test reside in the org.apache.derbyTesting.system.nstest.NsTest class. The main ones are as follows: INIT_THREADS = Initializer threads MAX_INITIAL_ROWS = Initial set of rows inserted before test begins MAX_ITERATIONS = Each client does these many transactions in the test MAX_LOW_STRESS_ROWS = Num of rows worked over in a transaction MAX_OPERATIONS_PER_CONN = Num of transaction batches made by a client before closing the connection NUMTESTER1 = Number of Tester1 testers NUMTESTER2 = Number of Tester2 testers NUMTESTER3 = Number of Tester3 testers NUM_HIGH_STRESS_ROWS = Maximum rows to be selected NUM_UNTOUCHED_ROWS = Number of rows on which Update/Delete operations are not performed START_SERVER_IN_SAME_VM= Set to true/false to start Network Server in the same VM. The System property 'derby.nstest.backupRestore' can be set to false for turning off Backup/Restore/Re-Encryption. By default the Backup/Restore/Re-Encryption thread is always started. KNOWN ISSUES: ============= EXPECTED ERRORS: ================ The test expects and catches the following errors (so seeing them in derby.log is expected): - XBM06; see BackupRestoreReEncryptTester.java - trying to access restored db with old encryption pwd: ERROR XBM06: Startup failed. An encrypted database cannot be accessed without the correct boot password. - 40XL1; there are time-outs expected on update and inserts. This is because of the high number of actions. Note that these are reported as a FAIL in the test output, but are likely ok. - XJ040; see BackupRestoreReEncryptTester.java - the sqlstate is not always available in derby.log, but you'll see the message: java.sql.SQLException: Failed to start database 'restoredir\nstestdb' with class loader sun.misc.Launcher$AppClassLoader@40614061, see the next exception for details. FUTURE WORK: ============ - Move location of test variables from NsTest.java to a common area - Ability to start the NW Server as a separate process passing independent VM args - Ability to run using JUnit test runners - Use larger BLOB/CLOB sizes - Other Derby feature integration testing - Work on reporting