org.apache.derby.drda
Class NetworkServerControl

java.lang.Object
  org.apache.derby.drda.NetworkServerControl

public class NetworkServerControl
extends java.lang.Object

NetworkServerControl provides the ability to start a Network Server or connect to a running Network Server to shutdown, configure or retreive diagnostic information. With the exception of ping, these commands can only be performed from the machine on which the server is running. Commands can be performed from the command line with the following arguments:

• start [-h <host>] [-p <portnumber>] [-ssl <sslmode>]: This starts the network server on the port/host specified or on localhost, port 1527 if no host/port is specified and no properties are set to override the defaults. By default Network Server will only listen for connections from the machine on which it is running. Use -h 0.0.0.0 to listen on all interfaces or -h <hostname> to listen on a specific interface on a multiple IP machine. For documentation on <sslmode>, consult the Server and Administration Guide.
• shutdown [-h <host>][-p <portnumber>] [-ssl <sslmode>] [-user <username>] [-password <password>]: This shutdowns the network server with given user credentials on the host and port specified or on the local host and port 1527(default) if no host or port is specified.
• ping [-h <host>] [-p <portnumber>] [-ssl <sslmode>] This will test whether the Network Server is up.
• sysinfo [-h <host>] [-p <portnumber>] [-ssl <sslmode>]: This prints classpath and version information about the Network Server, the JVM and the Derby engine.
• runtimeinfo [-h <host] [-p <portnumber] [-ssl <sslmode>]: This prints extensive debbugging information about sessions, threads, prepared statements, and memory usage for the running Network Server.
• logconnections {on | off} [-h <host>] [-p <portnumber>] [-ssl <sslmode>]: This turns logging of connections on or off. Connections are logged to derby.log. Default is off.
• maxthreads <max> [-h <host>][-p <portnumber>] [-ssl <sslmode>]: This sets the maximum number of threads that can be used for connections. Default 0 (unlimitted).
• timeslice <milliseconds> [-h <host>][-p <portnumber>] [-ssl <sslmode>]: This sets the time each session can have using a connection thread before yielding to a waiting session. Default is 0 (no yeild).
• trace {on | off} [-s <session id>] [-h <host>] [-p <portnumber>] [-ssl <sslmode>]: This turns drda tracing on or off for the specified session or if no session is specified for all sessions. Default is off
• tracedirectory <tracedirectory> [-h <host>] [-p <portnumber>] [-ssl <sslmode>]: This changes where new trace files will be placed. For sessions with tracing already turned on, trace files remain in the previous location. Default is derby.system.home, if it is set. Otherwise the default is the current directory.

Properties can be set in the derby.properties file or on the command line. Properties on the command line take precedence over properties in the derby.properties file. Arguments on the command line take precedence over properties. The following is a list of properties that can be set for NetworkServerControl:

• derby.drda.portNumber=<port number>: This property indicates which port should be used for the Network Server.
• derby.drda.host=<host name or ip address >: This property indicates the ip address to which NetworkServerControl should connect.
• derby.drda.traceDirectory=<trace directory>: This property indicates where to put trace files.
• derby.drda.traceAll=true: This property turns on tracing for all sessions. Default is tracing is off.
• derby.drda.logConnections=true: This property turns on logging of connections. Default is connections are not logged.
• derby.drda.minThreads=<value>: If this property is set, the <value> number of threads will be created when the Network Server is booted.
• derby.drda.maxThreads=<value>: If this property is set, the <value> is the maximum number of connection threads that will be created. If a session starts when there are no connection threads available and the maximum number of threads has been reached, it will wait until a conection thread becomes available.
• derby.drda.timeSlice=<milliseconds>: If this property is set, the connection threads will not check for waiting sessions until the current session has been working for <milliseconds>. A value of 0 causes the thread to work on the current session until the session exits. If this property is not set, the default value is 0.
• derby.drda.sslMode=<sslmode>: This property sets the SSL mode of the server.

Examples.

This is an example of shutting down the server on port 1621.

 
    java org.apache.derby.drda.NetworkServerControl shutdown -p 1621
    

This is an example of turning tracing on for session 3

    java org.apache.derby.drda.NetworkServerControl  trace on -s 3 
    

This is an example of starting and then shutting down the network server on port 1621 on machine myhost

    java org.apache.derby.drda.NetworkServerControl  start -h myhost -p 1621
    java org.apache.derby.drda.NetworkServerControl  shutdown -h myhost -p 1621
    

This is an example of starting and shutting down the Network Server in the example above with the API.

    NetworkServerControl serverControl = new NetworkServerControl(InetAddress.getByName("myhost"),1621)

    serverControl.shutdown();
    

Field Summary

static int	DEFAULT_PORTNUMBER
private static java.lang.String	DERBY_HOSTNAME_WILDCARD
private static java.lang.String	DERBYNET_JAR
private static java.lang.String	IPV6_HOSTNAME_WILDCARD
private static java.lang.String	POLICY_FILE_PROPERTY
private static java.lang.String	POLICY_FILENAME
private NetworkServerControlImpl	serverImpl
private static java.lang.String	SOCKET_PERMISSION_HOSTNAME_WILDCARD

Constructor Summary

NetworkServerControl()
Creates a NetworkServerControl object that is configured to control a Network Server on the default host(localhost) and the default port(1527) unless derby.drda.portNumber and derby.drda.host are set.

NetworkServerControl(java.net.InetAddress address, int portNumber)
Creates a NetworkServerControl object that is configured to control a Network Server on a specified port and InetAddress.

NetworkServerControl(java.net.InetAddress address, int portNumber, java.lang.String userName, java.lang.String password)
Creates a NetworkServerControl object that is configured to control a Network Server on a specified port and InetAddress with given user credentials.

NetworkServerControl(java.lang.String userName, java.lang.String password)
Creates a NetworkServerControl object that is configured to control a Network Server on the default host and the default port with given user credentials.

Method Summary

private static java.lang.String	getCodeSourcePrefix(NetworkServerControlImpl server) Find the url of the library directory which holds derby.jar and derbynet.jar.
java.util.Properties	getCurrentProperties() Get current Network server properties
private static java.lang.String	getHostNameForSocketPermission(NetworkServerControlImpl server) Get the hostname as a value suitable for substituting into the default server policy file.
int	getMaxThreads() Returns the current maxThreads setting for the running Network Server
private static java.lang.String	getPolicyFileURL() Get the URL of the policy file.
java.lang.String	getRuntimeInfo() Return detailed session runtime information about sessions, prepared statements, and memory usage for the running Network Server.
java.lang.String	getSysinfo() Return classpath and version information about the running Network Server.
int	getTimeSlice() Return the current timeSlice setting for the running Network Server
private static boolean	hostnamesEqual(java.lang.String left, java.lang.String right)
private static void	installSecurityManager(NetworkServerControlImpl server) Install a SecurityManager governed by the Basic startup policy.
private static boolean	isIPV6Address(java.lang.String hostname)
void	logConnections(boolean on) Turn logging connections on or off.
static void	main(java.lang.String[] args) main routine for NetworkServerControl
private static boolean	needsSecurityManager(NetworkServerControlImpl server, int command) Return true if we need to install a Security Manager.
void	ping() Check if Network Server is started Excecutes and returns without error if the server has started
protected void	setClientLocale(java.lang.String locale) set the client locale.
void	setMaxThreads(int max) Set Network Server maxthread parameter.
void	setTimeSlice(int timeslice) Set Network Server connection time slice parameter.
void	setTraceDirectory(java.lang.String traceDirectory) Set directory for trace files.
void	shutdown() Shutdown a Network Server.
void	start(java.io.PrintWriter consoleWriter) Start a Network Server This method will launch a separate thread and start Network Server.
void	trace(boolean on) Turn tracing on or off for the specified connection on the Network Server.
void	trace(int connNum, boolean on) Turn tracing on or off for all connections on the Network Server.
private static void	verifySecurityState(NetworkServerControlImpl server) Verify that all prerequisites are met before bringing up a security manager.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PORTNUMBER

public static final int DEFAULT_PORTNUMBER

See Also:

Constant Field Values

DERBYNET_JAR

private static final java.lang.String DERBYNET_JAR

See Also:

Constant Field Values

POLICY_FILENAME

private static final java.lang.String POLICY_FILENAME

See Also:

Constant Field Values

POLICY_FILE_PROPERTY

private static final java.lang.String POLICY_FILE_PROPERTY

See Also:

Constant Field Values

DERBY_HOSTNAME_WILDCARD

private static final java.lang.String DERBY_HOSTNAME_WILDCARD

See Also:

Constant Field Values

IPV6_HOSTNAME_WILDCARD

private static final java.lang.String IPV6_HOSTNAME_WILDCARD

See Also:

Constant Field Values

SOCKET_PERMISSION_HOSTNAME_WILDCARD

private static final java.lang.String SOCKET_PERMISSION_HOSTNAME_WILDCARD

See Also:

Constant Field Values

serverImpl

private NetworkServerControlImpl serverImpl

Constructor Detail

NetworkServerControl

public NetworkServerControl(java.net.InetAddress address,
                            int portNumber,
                            java.lang.String userName,
                            java.lang.String password)
                     throws java.lang.Exception

Creates a NetworkServerControl object that is configured to control a Network Server on a specified port and InetAddress with given user credentials.

Parameters:

address - The IP address of the Network Server host. address cannot be null.

portNumber - port number server is to used. If <= 0, default port number is used

userName - The user name for actions requiring authorization.

password - The password for actions requiring authorization.

Throws:

java.lang.Exception - on error

NetworkServerControl

public NetworkServerControl(java.lang.String userName,
                            java.lang.String password)
                     throws java.lang.Exception

Creates a NetworkServerControl object that is configured to control a Network Server on the default host and the default port with given user credentials.

Parameters:

userName - The user name for actions requiring authorization.

password - The password for actions requiring authorization.

Throws:

java.lang.Exception - on error

NetworkServerControl

public NetworkServerControl(java.net.InetAddress address,
                            int portNumber)
                     throws java.lang.Exception

Creates a NetworkServerControl object that is configured to control a Network Server on a specified port and InetAddress.

Examples:

To configure for port 1621 and listen on the loopback address:

  NetworkServerControl  util = new
 NetworkServerControl(InetAddress.getByName("localhost"), 1621);
 

Parameters:

address - The IP address of the Network Server host. address cannot be null.

portNumber - port number server is to used. If <= 0, default port number is used

Throws:

java.lang.Exception - on error

NetworkServerControl

public NetworkServerControl()
                     throws java.lang.Exception

Creates a NetworkServerControl object that is configured to control a Network Server on the default host(localhost) and the default port(1527) unless derby.drda.portNumber and derby.drda.host are set.

 new NetworkServerControl() 

 is equivalent to calling

 new NetworkServerControl(InetAddress.getByName("localhost"),1527);
 

Throws:

java.lang.Exception - on error

Method Detail

main

public static void main(java.lang.String[] args)

main routine for NetworkServerControl

Parameters:

args - array of arguments indicating command to be executed. See class comments for more information

start

public void start(java.io.PrintWriter consoleWriter)
           throws java.lang.Exception

Start a Network Server This method will launch a separate thread and start Network Server. This method may return before the server is ready to accept connections. Use the ping method to verify that the server has started.

Note: an alternate method to starting the Network Server with the API, is to use the derby.drda.startNetworkServer property in derby.properties.

Parameters:

consoleWriter - PrintWriter to which server console will be output. Null will disable console output.

Throws:

java.lang.Exception - if there is an error starting the server.

See Also:

shutdown()

shutdown

public void shutdown()
              throws java.lang.Exception

Shutdown a Network Server. Shuts down the Network Server listening on the port and InetAddress specified in the constructor for this NetworkServerControl object.

Throws:

java.lang.Exception - throws an exception if an error occurs

ping

public void ping()
          throws java.lang.Exception

Check if Network Server is started Excecutes and returns without error if the server has started

Throws:

java.lang.Exception - throws an exception if an error occurs

trace

public void trace(boolean on)
           throws java.lang.Exception

Turn tracing on or off for the specified connection on the Network Server.

Parameters:

on - true to turn tracing on, false to turn tracing off.

Throws:

java.lang.Exception - throws an exception if an error occurs

trace

public void trace(int connNum,
                  boolean on)
           throws java.lang.Exception

Turn tracing on or off for all connections on the Network Server.

Parameters:

connNum - connection number. Note: Connection numbers will print in the Derby error log if logConnections is on

on - true to turn tracing on, false to turn tracing off.

Throws:

java.lang.Exception - throws an exception if an error occurs

logConnections

public void logConnections(boolean on)
                    throws java.lang.Exception

Turn logging connections on or off. When logging is turned on a message is written to the Derby error log each time a connection is made.

Parameters:

on - true to turn on, false to turn off

Throws:

java.lang.Exception - throws an exception if an error occurs

setTraceDirectory

public void setTraceDirectory(java.lang.String traceDirectory)
                       throws java.lang.Exception

Set directory for trace files. The directory must be on the machine where the server is running.

Parameters:

traceDirectory - directory for trace files on machine where server is running

Throws:

java.lang.Exception - throws an exception if an error occurs

getSysinfo

public java.lang.String getSysinfo()
                            throws java.lang.Exception

Return classpath and version information about the running Network Server.

Returns:

sysinfo output

Throws:

java.lang.Exception - throws an exception if an error occurs

getRuntimeInfo

public java.lang.String getRuntimeInfo()
                                throws java.lang.Exception

Return detailed session runtime information about sessions, prepared statements, and memory usage for the running Network Server.

Returns:

run time information

Throws:

java.lang.Exception - throws an exception if an error occurs

setMaxThreads

public void setMaxThreads(int max)
                   throws java.lang.Exception

Set Network Server maxthread parameter. This is the maximum number of threads that will be used for JDBC client connections. setTimeSlice should also be set so that clients will yield appropriately.

Parameters:

max - maximum number of connection threads. If <= 0, connection threads will be created when there are no free connection threads.

Throws:

java.lang.Exception - throws an exception if an error occurs

See Also:

setTimeSlice(int)

getMaxThreads

public int getMaxThreads()
                  throws java.lang.Exception

Returns the current maxThreads setting for the running Network Server

Returns:

maxThreads setting

Throws:

java.lang.Exception - throws an exception if an error occurs

See Also:

setMaxThreads(int)

setTimeSlice

public void setTimeSlice(int timeslice)
                  throws java.lang.Exception

Set Network Server connection time slice parameter. This should be set and is only relevant if setMaxThreads > 0.

Parameters:

timeslice - number of milliseconds given to each session before yielding to another session, if <=0, never yield.

Throws:

java.lang.Exception - throws an exception if an error occurs

See Also:

setMaxThreads(int)

getTimeSlice

public int getTimeSlice()
                 throws java.lang.Exception

Return the current timeSlice setting for the running Network Server

Returns:

timeSlice setting

Throws:

java.lang.Exception - throws an exception if an error occurs

See Also:

setTimeSlice(int)

getCurrentProperties

public java.util.Properties getCurrentProperties()
                                          throws java.lang.Exception

Get current Network server properties

Returns:

Properties object containing Network server properties

Throws:

java.lang.Exception - throws an exception if an error occurs

setClientLocale

protected void setClientLocale(java.lang.String locale)

set the client locale. Used by servlet for localization

Parameters:

locale - Locale to use

needsSecurityManager

private static boolean needsSecurityManager(NetworkServerControlImpl server,
                                            int command)
                                     throws java.lang.Exception

Return true if we need to install a Security Manager. All of the following must apply. See DERBY-2196.

• The VM was booted with NetworkServerContro.main() as the entry point. This is handled by the fact that this method is only called by main().
• The VM isn't already running a SecurityManager.
• The command must be "start".
• The customer didn't specify the -noSecurityManager flag on the startup command line.

Throws:

java.lang.Exception

verifySecurityState

private static void verifySecurityState(NetworkServerControlImpl server)
                                 throws java.lang.Exception

Verify that all prerequisites are met before bringing up a security manager. See DERBY-2196. If prerequisites aren't met, raise an exception which explains how to get up and running. At one point, we were going to require that authentication be enabled before bringing up a security manager. This, however, gave rise to incompatibilities. See DERBY-2757. Currently, this method is a nop.

Throws:

java.lang.Exception

installSecurityManager

private static void installSecurityManager(NetworkServerControlImpl server)
                                    throws java.lang.Exception

Install a SecurityManager governed by the Basic startup policy. See DERBY-2196.

Throws:

java.lang.Exception

getHostNameForSocketPermission

private static java.lang.String getHostNameForSocketPermission(NetworkServerControlImpl server)
                                                        throws java.lang.Exception

Get the hostname as a value suitable for substituting into the default server policy file. The special wildcard valuse "0.0.0.0" and "::" are forced to be "*" since that is the wildcard hostname understood by SocketPermission. SocketPermission does not understand the "0.0.0.0" and "::" wildcards. IPV6 addresses are enclosed in square brackets. This logic arose from two JIRAs: DERBY-2811 and DERBY-2874.

Throws:

java.lang.Exception

hostnamesEqual

private static boolean hostnamesEqual(java.lang.String left,
                                      java.lang.String right)

isIPV6Address

private static boolean isIPV6Address(java.lang.String hostname)

getCodeSourcePrefix

private static java.lang.String getCodeSourcePrefix(NetworkServerControlImpl server)
                                             throws java.lang.Exception

Find the url of the library directory which holds derby.jar and derbynet.jar. The Basic policy assumes that both jar files live in the same directory.

Throws:

java.lang.Exception

getPolicyFileURL

private static java.lang.String getPolicyFileURL()
                                          throws java.lang.Exception

Get the URL of the policy file. Typically, this will be some pointer into derbynet.jar.

Throws:

java.lang.Exception