Derby Server and Administration Guide

Apache Software FoundationDerby Server and Administration GuideApache Derby

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

Related information

License

The Apache License, Version 2.0


                               Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use,
      reproduction, and distribution as defined by Sections 1 through
      9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized
      by the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under
      common control with that entity. For the purposes of this
      definition, "control" means (i) the power, direct or indirect,
      to cause the direction or management of such entity, whether by
      contract or otherwise, or (ii) ownership of fifty percent (50%)
      or more of the outstanding shares, or (iii) beneficial ownership
      of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making
      modifications, including but not limited to software source code,
      documentation source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or
      Object form, that is based on (or derived from) the Work and
      for which the editorial revisions, annotations, elaborations,
      or other modifications represent, as a whole, an original work
      of authorship.  For the purposes of this License, Derivative
      Works shall not include works that remain separable from, or
      merely link (or bind by name) to the interfaces of, the Work
      and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or
      additions to that Work or Derivative Works thereof, that is
      intentionally submitted to Licensor for inclusion in the Work
      by the copyright owner or by an individual or Legal Entity
      authorized to submit on behalf of the copyright owner. For the
      purposes of this definition,
      "submitted" means any form of electronic, verbal, or written
      communication sent to the Licensor or its representatives,
      including but not limited to communication on electronic mailing
      lists, source code control systems, and issue tracking systems
      that are managed by, or on behalf of, the Licensor for the
      purpose of discussing and improving the Work, but excluding
      communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a
      Contribution."

      "Contributor" shall mean Licensor and any individual or Legal
      Entity on behalf of whom a Contribution has been received by
      Licensor and subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions
      of this License, each Contributor hereby grants to You a
      perpetual, worldwide, non-exclusive, no-charge, royalty-free,
      irrevocable copyright license to reproduce, prepare Derivative
      Works of, publicly display, publicly perform, sublicense, and
      distribute the Work and such Derivative Works in Source or
      Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have
      made, use, offer to sell, sell, import, and otherwise transfer
      the Work, where such license applies only to those patent claims
      licensable by such Contributor that are necessarily infringed by
      their Contribution(s) alone or by combination of their
      Contribution(s) with the Work to which such Contribution(s) was
      submitted. If You institute patent litigation against any entity
      (including a cross-claim or counterclaim in a lawsuit) alleging
      that the Work or a Contribution incorporated within the Work
      constitutes direct or contributory patent infringement, then any
      patent licenses granted to You under this License for that Work
      shall terminate as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute
          must include a readable copy of the attribution notices
          contained within such NOTICE file, excluding those notices
          that do not pertain to any part of the Derivative Works, in
          at least one of the following places: within a NOTICE text
          file distributed as part of the Derivative Works; within the
          Source form or documentation, if provided along with the
          Derivative Works; or, within a display generated by the
          Derivative Works, if and wherever such third-party notices
          normally appear. The contents of the NOTICE file are for
          informational purposes only and do not modify the License.
          You may add Your own attribution notices within Derivative
          Works that You distribute, alongside or as an addendum to
          the NOTICE text from the Work, provided that such additional
          attribution notices cannot be construed as modifying the
          License.

      You may add Your own copyright statement to Your modifications
      and may provide additional or different license terms and
      conditions for use, reproduction, or distribution of Your
      modifications, or for any such Derivative Works as a whole,
      provided Your use, reproduction, and distribution of the Work
      otherwise complies with the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state
      otherwise, any Contribution intentionally submitted for
      inclusion in the Work by You to the Licensor shall be under the
      terms and conditions of this License, without any additional
      terms or conditions.  Notwithstanding the above, nothing herein
      shall supersede or modify the terms of any separate license
      agreement you may have executed with Licensor regarding such
      Contributions.

   6. Trademarks. This License does not grant permission to use the
      trade names, trademarks, service marks, or product names of the
      Licensor, except as required for reasonable and customary use
      in describing the origin of the Work and reproducing the content
      of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or
      conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
      FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
      determining the appropriateness of using or redistributing the
      Work and assume any risks associated with Your exercise of
      permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and
      grossly negligent acts) or agreed to in writing, shall any
      Contributor be liable to You for damages, including any direct,
      indirect, special, incidental, or consequential damages of any
      character arising as a result of this License or out of the use
      or inability to use the Work (including but not limited to
      damages for loss of goodwill, work stoppage, computer failure or
      malfunction, or any and all other commercial damages or losses),
      even if such Contributor has been advised of the possibility of
      such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by
      reason of your accepting any such warranty or additional
      liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

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

About this guide

This section describes who this guide is for as well as how to use it.

Purpose of this guide

This guide explains how to use Derby in a multiple-client environment. It also provides information that a server administrator might need to keep Derby running with a high level of performance and reliability in a server framework or in a multiple-client application server environment (When running in embedded mode, Derby databases typically do not need any administration).

To connect multiple clients with Derby, you can embed Derby in a server framework that you choose, or you can use the Derby Network Server. This guide describes these options.

Audience

The first part of this guide is intended for developers of client/server and multiple-client applications. The second part of this guide is intended for administrators.

How this guide is organized

This guide includes the following two parts:

Part one: Derby Server Guide

•		Derby in a multi-user environment Describes the different options for embedding Derby in a server framework and explains the Network Server option.
•		Using the Network Server with preexisting Derby applications Describes how to change existing Derby applications to work with the Network Server.
•		Managing the Derby Network Server Describes how to use shell scripts, the command line, and the Network Server API to manage the Network Server.
•		Managing the Derby Network Server remotely by using the servlet interface Describes how to use the servlet interface to manage the Network Server.
•		Derby Network Server advanced topics Describes advanced topics for Derby Network Server users.

Part two: Derby Administration Guide

•		Checking database consistency Describes how to check the consistency of Derby databases.
•		Backing up and restoring databases Describes how to back up a database when it is online.
•		Logging on a separate device Describes how to put a database's log on a separate device, which can improve the performance of large databases.
•		Obtaining locking information Describes how to get detailed information about locking status.
•		Reclaiming unused space Describes how to identify and reclaim unused space in tables and related indexes.

Part one: Derby Server Guide

This part of the guide explains the Derby Network Server and other server frameworks.

Derby in a multi-user environment

This section describes how to use Derby in a multi-user (or "server") environment.

Derby in a server framework

In a sense, Derby is always an embedded product. You can embed it in an application in which users access the database from a single JVM or you can embed it in a server framework (an application that allows users from different JVMs to connect to Derby simultaneously). When Derby is embedded in an application, the local JDBC driver calls the local Derby database. When Derby is embedded in a server framework, the server framework's connectivity software provides data to multiple client JDBC applications over a network or the Internet.

For local or remote multi-user connectivity (multiple users who access Derby from different JVMs), use the Derby Network Server. If you require features that are not included in the Network Server, you can embed the basic Derby product in another server framework.

Connectivity configurations

There are several ways to embed Derby in a server framework:

Use the Network Server

This is the easiest way to provide connectivity to multiple users who are accessing Derby databases from different JVMs. The Derby Network Server provides this kind of connectivity to Derby databases within a single system or over a network.

Purchase another server framework

You can use Derby within many server frameworks, such as IBM WebSphere Application Server.

Write your own framework

Derby's flexibility allows other configurations as well. For example, rather than embedding Derby in a server that communicates with a client that uses JDBC, you can embed Derby within a servlet in a web server that communicates with a browser using HTTP.

Multiple-client features available in Derby

Derby contains some features that are useful for developing multi-user applications.

Row-level locking:

To support multi-user access, Derby utilizes row-level locking. However, you can configure Derby to use table-level locking in environments that have few concurrent transactions (for example, a read-only database) . Table-level locking is preferable if there are few or no writes to the server, while row-level locking is essential for good performance if many clients write to the server concurrently. The Derby optimizer tunes lock choice for queries automatically.

Multiple concurrency levels:

Derby supports SERIALIZABLE (RR), REPEATABLE (RS), READ COMMITTED (CS), and READ UNCOMMITTED (UR) isolation levels.

CS (the default isolation level) provides the best balance between concurrency and consistency in multiple-client environments.

RS provides less consistency than RR but allows more concurrency.

RR provides greatest consistency.

UR provides maximum concurrency, if uncommitted values are allowed in the query. It is typically used if approximate results are acceptable.

See "Types and Scope of Locks in Derby Systems" in the Derby Developer's Guide for more information.

Multi-connection and multi-threading:

Derby allows multiple simultaneous connections to a database, even in embedded mode. Derby is also fully multi-threaded, and you can have multiple threads active at the same time. However, JDBC semantics impose some limitations on multi-threading. See the Derby Developer's Guide for more information.

Administrative tools:

Derby provides some tools and features to assist database administrators, including:

•		Consistency checker
•		Online backup
•		The ability to put a database's log on a separate device

These tools and features are discussed in part two of this guide. See the sections in that part for more information.

The Derby Network Server

The Derby Network Server provides multi-user connectivity to Derby databases within a single system or over a network. The Network Server uses the standard Distributed Relational Database Architecture (DRDA) protocol to receive and reply to queries from clients. Databases are accessed through the Derby Network Server by using the Derby Network Client driver.

The Network Server is a solution for multiple JVMs that connect to the database, unlike the embedded scenario where only one JVM runs as part of the system. When Derby is embedded in a single-JVM application, the embedded JDBC driver calls the local Derby database. When Derby is embedded in a server framework, the server framework's connectivity software provides data to multiple client JDBC applications over a network or the Internet.

To run the Derby Network Server, you need to install the following files:

•		On the server side, install derby.jar and derbynet.jar.
•		On the client side, install derbyclient.jar.

There are several ways to manage the Derby Network Server, including:

•		Through the command line
•		By using .bat and .ksh scripts
•		Through the servlet interface
•		With your own Java program (written using the Network Server API)
•		By setting Network Server properties

Using the Network Server with preexisting Derby applications explains how to change existing Java applications that currently run against Derby in embedded mode to run against the Derby Network Server.

Managing the Derby Network Server explains how to manage the Network Server by using the command line, including starting and stopping it.

Managing the Derby Network Server remotely by using the servlet interface explains how to use the servlet interface to manage the Network Server.

Derby Network Server advanced topics contains advanced topics for Derby Network Server users.

Because of the differences in JDBC drivers that are used, you might encounter differences in functionality when running Derby in the Network Server framework as opposed to running it embedded in a user application. Refer to Using the Network Server with preexisting Derby applications for a complete list of the differences between embedded and Network Server configurations.

Embedded servers

Because Derby is written in Java, you have great flexibility in how you choose to configure your deployment. For example, you can run Derby, the JDBC server framework, and another application in the same JVM as a single process.

How to start an embedded server from an application

In one thread, the embedding application starts the local JDBC driver for its own access.

/*
    If you are running on JDK 1.6 or higher, then you do not
    need to invoke Class.forName(). In that environment, the
    EmbeddedDriver loads automatically.
*/
Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();
Connection conn = DriverManager.getConnection(
    "jdbc:derby:sample");

In another thread, the same application starts the server framework to allow remote access. Starting the server framework from within the application allows both the server and the application to run in the same JVM.

Embedded server example

You can start the Network Server in another thread automatically when Derby starts by setting the derby.drda.startNetworkServer property (see Setting Network Server properties), or you can start it by using a program. The following example shows how to start the Network Server by using a program:

import org.apache.derby.drda.NetworkServerControl;
import java.net.InetAddress;
NetworkServerControl server = new NetworkServerControl
	(InetAddress.getByName("localhost"),1527);
server.start(null);

The program that starts the Network Server can access the database by using either the embedded driver or the Network Client driver. The server framework's attempt to boot the local JDBC driver is ignored because it has already been booted within the application's JVM. The server framework simply accesses the instance of Derby that is already booted. There is no conflict between the application and the server framework.

The remote client can then connect through the Derby client driver:

String nsURL="jdbc:derby://localhost:1527/sample";  
java.util.Properties props = new java.util.Properties();
props.put("user","usr");
props.put("password","pwd");

/*
    If you are running on JDK 1.6 or higher, then you do not
    need to invoke Class.forName(). In that environment, the
    EmbeddedDriver loads automatically.
*/
Class.forName("org.apache.derby.jdbc.ClientDriver").newInstance();
Connection conn = DriverManager.getConnection(nsURL, props);

/*interact with Derby*/
Statement s = conn.createStatement();

ResultSet rs = s.executeQuery(
"SELECT * FROM HotelBookings");

About this guide and the Network Server documentation

This guide assumes that you are familiar with Derby features and tuning. Before reading this guide, you should first learn about basic Derby functionality by reading the Derby Developer's Guide. Also, because multi-user environments typically have performance and tuning issues, you should read Tuning Derby.

Using the Network Server with preexisting Derby applications

You must modify Java applications that currently run against Derby in embedded mode so that they work with the Derby Network Server. The topics in this section discuss these changes.

The Network Server and JVMs

The Derby Network Server is compatible with Java(TM) 2 Platform, Standard Edition, v 1.4.2 (J2SE) and above.

Installing required jar files and adding them to the classpath

To use the Network Server and network client driver, add the following jar file to your server classpath:

•

derbyrun.jar

Adding this file to your classpath has the effect of including all of the Derby classes in your classpath. These classes are in the following jar files, which you can also add to your classpath separately:

•		derbynet.jar This jar file contains the Network Server code. It must be in your classpath to start the Network Server.
•		derby.jar This jar file contains the Derby database engine code. It must be in the classpath in order for the Network Server to access Derby databases. derby.jar is included in the Class-Path attribute of derbynet.jar's manifest file. If you have derbynet.jar in the classpath and derby.jar is in the same directory as derbynet.jar, it is not necessary to include derby.jar explicitly.
•		derbyclient.jar This jar file contains the Derby Network Client JDBC driver that is necessary for communication with the Network Server. It must be in the classpath of the application on the client side in order to access Derby databases over a network.

All of the jar files are in the $DERBY_HOME/lib directory.

Derby provides script files for setting the classpath to work with the Network Server. The scripts are located in the $DERBY_HOME/bin directory.

•		setNetworkClientCP.bat (Windows)
•		setNetworkClientCP (UNIX)
•		setNetworkServerCP.bat (Windows)
•		setNetworkServerCP (UNIX)

See Managing the Derby Network Server and Getting Started with Derby for more information on setting the classpath.

Starting the Network Server

To start the Network Server, you can invoke a script, a jar file, or a class.

> Important: Note that you should always properly shut down the Network Server after use, because failure to do so might result in unpredictable side-effects, such as blocked ports on the server.

You are strongly urged to enable user authentication when you run a Network Server. For details on how to configure user authentication, please consult the "Working with user authentication" section in the Developer's Guide. You are also urged to install a Java security manager with a customized security policy. For details on how to do this, see Customizing the Network Server's security policy.

You can start the Network Server in any of the following ways:

•

If you are relatively new to the Java programming language, follow the instructions in "Setting up your environment" in Getting Started with Derby to set the DERBY_HOME and JAVA_HOME environment variables and to add DERBY_HOME/bin to your path. Then use the startNetworkServer.bat script to start the Network Server on Windows machines and the startNetworkServer script to start the Network Server on UNIX systems. These scripts are located in $DERBY_HOME/bin, where $DERBY_HOME is the directory where you installed Derby.

You can run NetworkServerControl commands only from the host that started the Network Server.

Operating System

Command

Windows

set DERBY_HOME=C:\derby
set JAVA_HOME=C:\Program Files\Java\jdk1.5.0_10
set PATH=%DERBY_HOME%\bin;%PATH%
startNetworkServer

UNIX (Korn Shell)

export DERBY_HOME=/opt/derby
export JAVA_HOME=/usr/j2se
export PATH="$DERBY_HOME/bin:$PATH"
startNetworkServer

•

If you are a regular Java user but are new to Derby, set the DERBY_HOME environment variable, then use a java command to invoke the derbyrun.jar or derbynet.jar file:

Operating System

Command

Windows

set DERBY_HOME=C:\derby
java -jar %DERBY_HOME%\lib\derbyrun.jar server start
or
java -jar %DERBY_HOME%\lib\derbynet.jar start

UNIX (Korn Shell)

export DERBY_HOME=/opt/derby
java -jar $DERBY_HOME/lib/derbyrun.jar server start
or
java -jar $DERBY_HOME/lib/derbynet.jar start

To see the command syntax, invoke derbyrun.jar server or derbynet.jar with no arguments.

•

If you are familiar with both the Java programming language and Derby, you have already set DERBY_HOME. Set your classpath to include the Derby jar files. Then use a java command to invoke the NetworkServerControl class directly.

Operating System	Command
Windows	%DERBY_HOME%\bin\setNetworkServerCP java org.apache.derby.drda.NetworkServerControl start
UNIX (Korn Shell)	$DERBY_HOME/bin/setNetworkServerCP java org.apache.derby.drda.NetworkServerControl start

The default system directory is the directory in which Derby was started. (See the Derby Developer's Guide for more information about the default system directory.)

You can specify a different host or port number when you start the Network Server by specifying an option to the command.

•		Specify a port number other than the default (1527) by using the -p portnumber option, as shown in the following example: java org.apache.derby.drda.NetworkServerControl start -p 1368
•		Specify a specific interface (host name or IP address) to listen on other than the default (localhost) by using the -h option, as shown in the following example: $DERBY_HOME/bin/startNetworkServer -h myhost -p 1368 where myhost is the host name or IP address. Remember: Before using the -h option, you should run under the Java security manager with a customized security policy and you should enable user authentication.

By default, the Network Server will listen to requests only on the loopback address, which means that it will only accept connections from the local host.

Starting the Network Server from a Java application

Note that you should always properly shut down the Network Server after use, because failure to do so might result in unpredictable side-effects, such as blocked ports on the server.

There are two ways to start the Network Server from a Java application.

•		You can include the following line in the derby.properties file: derby.drda.startNetworkServer=true This starts the server on the default port, 1527, listening on localhost (all interfaces). To specify a different port or a specific interface in the derby.properties file, include the following lines, respectively: derby.drda.portNumber=1110 derby.drda.host=myhost You can also specify the startNetworkServer and portNumber properties by using a Java command: java -Dderby.drda.startNetworkServer=true -Dderby.drda.portNumber=1110 -Dderby.drda.host=myhost yourApp
•		You can use the NetworkServerControl API to start the Network Server from a separate thread within a Java application: NetworkServerControl server = new NetworkServerControl(); server.start (null);

Starting the Network Server on IPv6/Ipv4 dual stack Windows machines

The following JVM properties need to be added to the command when starting the server on IPv6/Ipv4 dual stack Windows machines:

-Djava.net.preferIPv4Stack=false
-Djava.net.preferIPv6Addresses=true

Shutting down the Network Server

To shut down a Network Server, you can invoke a script, a jar file, or a class.

The scripts to shut down a Network Server are located in the $DERBY_HOME/bin directory.

> Important: If user authentication is enabled, you must specify a valid Derby user name and password; if the user authentication check fails, you'll see an authentication error and the running server remains intact. Note that Derby does not yet restrict the shutdown privilege to specific users: the server can be shut down by any user on the server machine who presents valid credentials.

•		To shut down the Network Server by using the scripts provided for Windows systems, use: stopNetworkServer.bat [-h hostname] [-p portnumber] [-user username] [-password password]
•		To shut down the Network Server by using the scripts provided for UNIX systems, use: stopNetworkServer [-h hostname] [-p portnumber] [-user username] [-password password]

Shutting down by using the command line

From the command line, you can shut down a Network Server by invoking a jar file or a class.

Note that you need to provide user credential arguments to shut down a server running with user authentication.

•

To shut down the Network Server by invoking a jar file from the $DERBY_HOME/lib directory, use:

java -jar derbyrun.jar server shutdown [-h <hostname>] [-p <portnumber>] [-user <username>] [-password <password>]

java -jar derbyrun.jar shutdown [-h <hostname>] [-p <portnumber>] [-user <username>] [-password <password>]

•

To shut down the Network Server by invoking a class, use:

java org.apache.derby.drda.NetworkServerControl shutdown [-h <hostname>] [-p <portnumber>] [-user <username>] [-password <password>]

Shutting down by using the API

You can use the NetworkServerControl API to shut down the Network Server from within a Java application. The name of the method that you use to shutdown the Network Server is shutdown().

For example, the following command shuts down the Network Server running on the current machine using the default port number (1527):


NetworkServerControl server = new NetworkServerControl();
server.shutdown();

To shut down a server running with user authentication, you need to use a NetworkServerControl instance created with user credentials:


NetworkServerControl server = new NetworkServerControl(username, password);
server.shutdown();

Obtaining system information

You can obtain information about the Network Server, such as version and current property values, Java information, and Derby database server information, by using the sysinfo utility. The sysinfo utility is available from scripts, the command line, the NetworkServerControl API, and through the servlet interface.

The following scripts are located in the $DERBY_HOME/bin directory. Before running these scripts, make sure that the Derby Network Server is started.

•		Run the following script to obtain information about the Network Server on a Windows system: NetworkServerControl.bat sysinfo [-h hostname][-p portnumber]
•		Run the following script to obtain information about the Network Server on a UNIX system: NetworkServerControl sysinfo [-h hostname] [-p portnumber]

For more information on the sysinfo utility, see the Derby Tools and Utilities Guide.

You can also use Java Management Extensions (JMX) technology to obtain system information. For details, visit the wiki page http://wiki.apache.org/db-derby/DerbyJMX and refer to the API documentation for the packages org.apache.derby.mbeans and org.apache.derby.mbeans.drda. For information on JMX technology, see http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/.

Obtaining system information by using the command line

To run sysinfo from the command line, use a command like one of the following while the Network Server is running:

java -jar $DERBY_HOME/lib/derbyrun.jar server sysinfo
  [-h hostname][-p portnumber]

java org.apache.derby.drda.NetworkServerControl sysinfo 
  [-h hostname][-p portnumber]

Administrative commands such as sysinfo can only execute on the host where the server was started, even if the server was started with the -h option.

Obtaining system information by using the API

The sysinfo method produces the same information as the sysinfo command. The signature for this method is

String getSysinfo();

For example:

NetworkServerControl serverControl = new NetworkServerControl();
String myinfo = serverControl.getSysinfo();

The getSysinfo() method returns information about the Network Server that is running on the current machine on the default port number (1527).

Obtaining Network Server runtime information:

Use the runtimeinfo command or getRuntimeInfo method to get memory usage and current session information about the Network Server including user, database, and prepared statement information.

•		To run runtimeinfo from the command line: java org.apache.derby.drda.NetworkServerControl runtimeinfo [-h <hostname>][<-p portnumber>]
•		The getRuntimeInfo method returns the same information as the runtimeinfo command. The signature for the getRuntimeInfo method is String getRuntimeInfo(). For example: NetworkServerControl serverControl = new NetworkServerControl(); String myinfo = serverControl.getRuntimeInfo();

Obtaining Network Server properties by using the getCurrent Properties method:

The getCurrentProperties method is a Java method that you can use to obtain information about the Network Server. It returns a Properties object with the value of all the Network Server properties as they are currently set.

The signature of this method is:

Properties getCurrentProperties();

For example:

NetworkServerControl server = new NetworkServerControl();
Properties p = server.getCurrentProperties();
p.list(System.out);
System.out.println(p.getProperty("derby.drda.host"));

As shown in the previous example, you can look up the current properties and then work with individual properties if needed by using various APIs on the Properties class. You can also print out all the properties by using the Properties.list() method.

See Managing the Derby Network Server remotely by using the servlet interface for information about obtaining system information using the servlet interface.

Accessing the Network Server by using the network client driver

When connecting to the Network Server, your application needs to load a driver and connection URL that is specific to the Network Server. In addition, you must specify a user name and password if you are using authentication.

The driver that you need to access the Network Server is:

org.apache.derby.jdbc.ClientDriver

The syntax of the URL that is required to access the Network Server is:

jdbc:derby://<server>[:<port>]/
<databaseName>[;<URL attribute>=<value> [;...]]

where the <URL attribute> is either a Derby embedded or network client attribute.

Table 1. Standard JDBC DataSource properties

Property	Type	Description	URL attribute	Notes
databaseName	String	The name of the database. This property is required.	'	This property is also available using EmbeddedDataSource.
dataSourceName	String	The data source name.	'	This property is also available using EmbeddedDataSource.
description	String	A description of the data source.	'	This property is also available using EmbeddedDataSource.
user	String	The user's account name.	user	Default is APP. This property is also available using EmbeddedDataSource.
password	String	The user's database password.	password	This property is also available using EmbeddedDataSource.
serverName	String	The host name or TCP/IP address where the server is listening for requests.	'	Default is "localhost".
portNumber	Integer	The port number where the server is listening for requests.	'	Default is "1527".

Table 2. Client-specific DataSource properties

Property	Type	Description	URL attribute	Notes
traceFile	String	The filename for tracing output. Setting this property turns on tracing. See Network client tracing.	traceFile	'
traceDirectory	String	The directory for the tracing output. Each connection will send output to a separate file. Setting this property turns on tracing. See Network client tracing.	traceDirectory	'
traceLevel	Integer	The level of client tracing if traceFile or traceDirectory are set.	traceLevel	The default is TRACE_ALL.
traceFileAppend	Boolean	Value is true if tracing output should append to the existing trace file.	traceFileAppend	The default is false.
securityMechanism	Integer	The security mechanism. See Network client security.	securityMechanism	The default is USER_ONLY _SECURITY.
retrieveMessageText	Boolean	Retrieve message text from the server. A stored procedure is called to retrieve the message text with each SQLException and might start a new unit of work. Set this property to false if you do not want the performance impact or when starting new units of work.	retrieveMessageText	The default is true.
ssl	String	The SSL mode for the client connection. See Network encryption and authentication with SSL/TLS	ssl	The default is off.

Table 3. Server-Specific DataSource properties

Property	Type	Description	URL attributes	Notes
connectionAttributes	String	Set to the list of Derby embedded connection attributes separated by semicolons.	Various	This property is also available using EmbeddedDataSource. See the Derby Reference Manual for more information about the various connection attributes.
createDatabase	String	If set to "create", create the database specified with databaseName property.	create	This property is also available using EmbeddedDataSource. See the Derby Reference Manual for more information. Similar to setting connectionAttribute to "create=true". Only "create" is allowed, other values equate to null. The result of conflicting settings of createDatabase, shutdownDatabase and connectionAttributes is undefined.
shutdownDatabase	String	If set to "shutdown", shutdown the database specified with databaseName property.	shutdown	This property is also available using EmbeddedDataSource. See the Derby Reference Manual for more information. Similar to setting connectionAttribute to "shutdown=true". Only "shutdown" is allowed, other values equate to null. The result of conflicting settings of createDatabase, shutdownDatabase and connectionAttributes is undefined. If authentication and sqlAuthorization are both enabled, database shutdown is restricted to the database owner.