org.apache.derby.drda: public class: NetworkServerControl

org.apache.derby.drda
public class: NetworkServerControl [javadoc | source]

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

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
public static final int	DEFAULT_PORTNUMBER

Constructor:

Constructor:
public NetworkServerControl() throws Exception { serverImpl = new NetworkServerControlImpl(); } 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: `Exception` - on error
public NetworkServerControl(String userName, String password) throws Exception { serverImpl = new NetworkServerControlImpl(userName, 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. Parameters: `userName` - The user name for actions requiring authorization. `password` - The password for actions requiring authorization. Throws: `Exception` - on error
public NetworkServerControl(InetAddress address, int portNumber) throws Exception { serverImpl = new NetworkServerControlImpl(address, portNumber); } 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: `Exception` - on error
public NetworkServerControl(InetAddress address, int portNumber, String userName, String password) throws Exception { serverImpl = new NetworkServerControlImpl(address, portNumber, userName, password); } 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: `Exception` - on error

 public NetworkServerControl() throws Exception {
		serverImpl = new NetworkServerControlImpl();
}

new NetworkServerControl() 

is equivalent to calling

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

Throws:

Exception - on error

 public NetworkServerControl(String userName,
    String password) throws Exception {
		serverImpl = new NetworkServerControlImpl(userName, 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.

Parameters:

userName - The user name for actions requiring authorization.

password - The password for actions requiring authorization.

Throws:

Exception - on error

 public NetworkServerControl(InetAddress address,
    int portNumber) throws Exception {
		serverImpl = new NetworkServerControlImpl(address, portNumber);
}

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:

Exception - on error

 public NetworkServerControl(InetAddress address,
    int portNumber,
    String userName,
    String password) throws Exception {
		serverImpl = new NetworkServerControlImpl(address, portNumber,
												  userName, password);
}

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:

Exception - on error

Method from org.apache.derby.drda.NetworkServerControl Summary:
getCurrentProperties, getMaxThreads, getRuntimeInfo, getSysinfo, getTimeSlice, logConnections, main, ping, setClientLocale, setMaxThreads, setTimeSlice, setTraceDirectory, shutdown, start, trace, trace

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from org.apache.derby.drda.NetworkServerControl Detail:
public Properties getCurrentProperties() throws Exception { return serverImpl.getCurrentProperties(); } Get current Network server properties
public int getMaxThreads() throws Exception { String val =serverImpl.getCurrentProperties().getProperty(Property.DRDA_PROP_MAXTHREADS); return Integer.parseInt(val); } Returns the current maxThreads setting for the running Network Server
public String getRuntimeInfo() throws Exception { return serverImpl.runtimeInfo(); } Return detailed session runtime information about sessions, prepared statements, and memory usage for the running Network Server.
public String getSysinfo() throws Exception { return serverImpl.sysinfo(); } Return classpath and version information about the running Network Server.
public int getTimeSlice() throws Exception { String val = serverImpl.getCurrentProperties().getProperty(Property.DRDA_PROP_TIMESLICE); return Integer.parseInt(val); } Return the current timeSlice setting for the running Network Server
public void logConnections(boolean on) throws Exception { serverImpl.logConnections(on); } 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.
public static void main(String[] args) { NetworkServerControlImpl server = null; // // The following variable lets us preserve the error printing behavior // seen before we started installing a security manager. Errors can be // raised as we figure out whether we need to install a security manager // and during the actual installation of the security manager. We need // to print out these errors. The old error printing behavior assumed // that all errors were generated inside NetworkServerControlImpl and // were reported there. // boolean printErrors = true; try { server = new NetworkServerControlImpl(); int command = server.parseArgs( args ); // // In order to run secure-by-default, we install a security manager // if one isn't already installed. This feature is described by DERBY-2196. // if ( needsSecurityManager( server, command ) ) { verifySecurityState( server ); installSecurityManager( server ); } // // From this point on, NetworkServerControlImpl is responsible for // printing errors. // printErrors = false; server.executeWork( command ); } catch (Exception e) { //if there was an error, exit(1) if ((e.getMessage() == null) \|\| !e.getMessage().equals(NetworkServerControlImpl.UNEXPECTED_ERR) \|\| printErrors ) { if (server != null) server.consoleExceptionPrint(e); else e.printStackTrace(); // default output stream is System.out } // else, we've already printed a trace, so just exit. System.exit(1); } System.exit(0); } main routine for NetworkServerControl
public void ping() throws Exception { serverImpl.ping(); } Check if Network Server is started Excecutes and returns without error if the server has started
protected void setClientLocale(String locale) { serverImpl.clientLocale = locale; } set the client locale. Used by servlet for localization
public void setMaxThreads(int max) throws Exception { serverImpl.netSetMaxThreads(max); } 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.
public void setTimeSlice(int timeslice) throws Exception { serverImpl.netSetTimeSlice(timeslice); } Set Network Server connection time slice parameter. This should be set and is only relevant if setMaxThreads > 0.
public void setTraceDirectory(String traceDirectory) throws Exception { serverImpl.sendSetTraceDirectory(traceDirectory); } Set directory for trace files. The directory must be on the machine where the server is running.
public void shutdown() throws Exception { serverImpl.shutdown(); } Shutdown a Network Server. Shuts down the Network Server listening on the port and InetAddress specified in the constructor for this NetworkServerControl object.
public void start(PrintWriter consoleWriter) throws Exception { serverImpl.start(consoleWriter); } 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.
public void trace(boolean on) throws Exception { serverImpl.trace(on); } Turn tracing on or off for the specified connection on the Network Server.
public void trace(int connNum, boolean on) throws Exception { serverImpl.trace(connNum, on); } Turn tracing on or off for all connections on the Network Server.

Method from org.apache.derby.drda.NetworkServerControl Detail:

 public Properties getCurrentProperties() throws Exception {
		return serverImpl.getCurrentProperties();
}

Get current Network server properties

 public int getMaxThreads() throws Exception {
	    String val =serverImpl.getCurrentProperties().getProperty(Property.DRDA_PROP_MAXTHREADS);
		return Integer.parseInt(val);
}

Returns the current maxThreads setting for the running Network Server

 public String getRuntimeInfo() throws Exception {
		return serverImpl.runtimeInfo();
}

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

 public String getSysinfo() throws Exception {
		
		return serverImpl.sysinfo();
}

Return classpath and version information about the running Network Server.

 public int getTimeSlice() throws Exception {
		String val  =
			serverImpl.getCurrentProperties().getProperty(Property.DRDA_PROP_TIMESLICE);
		return Integer.parseInt(val);
}

Return the current timeSlice setting for the running Network Server

 public  void logConnections(boolean on) throws Exception {
		serverImpl.logConnections(on);
}

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.

 public static  void main(String[] args) {
        NetworkServerControlImpl server = null;
        //
        // The following variable lets us preserve the error printing behavior
        // seen before we started installing a security manager. Errors can be
        // raised as we figure out whether we need to install a security manager
        // and during the actual installation of the security manager. We need
        // to print out these errors. The old error printing behavior assumed
        // that all errors were generated inside NetworkServerControlImpl and
        // were reported there.
        //
        boolean                                 printErrors = true;
        try
        {
            server = new NetworkServerControlImpl();
            int     command = server.parseArgs( args );
            //
            // In order to run secure-by-default, we install a security manager
            // if one isn't already installed. This feature is described by DERBY-2196.
            //
            if ( needsSecurityManager( server, command ) )
            {
                verifySecurityState( server );
                installSecurityManager( server );
            }
            //
            // From this point on, NetworkServerControlImpl is responsible for
            // printing errors.
            //
            printErrors = false;
            server.executeWork( command );
        }
        catch (Exception e)
        {
			//if there was an error, exit(1)
			if ((e.getMessage() == null) ||
				!e.getMessage().equals(NetworkServerControlImpl.UNEXPECTED_ERR) ||
				printErrors
			)
			{
				if (server != null)
					server.consoleExceptionPrint(e);
				else
					e.printStackTrace();  // default output stream is System.out
			}
			// else, we've already printed a trace, so just exit.
			System.exit(1);
		}
		System.exit(0);
}

main routine for NetworkServerControl

 public  void ping() throws Exception {
		 serverImpl.ping();
}

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

 protected  void setClientLocale(String locale) {
		serverImpl.clientLocale = locale;
}

set the client locale. Used by servlet for localization

 public  void setMaxThreads(int max) throws Exception {
		serverImpl.netSetMaxThreads(max);
}

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.

 public  void setTimeSlice(int timeslice) throws Exception {
		serverImpl.netSetTimeSlice(timeslice);
}

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

 public  void setTraceDirectory(String traceDirectory) throws Exception {
		serverImpl.sendSetTraceDirectory(traceDirectory);
}

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

 public  void shutdown() throws Exception {
		serverImpl.shutdown();
}

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

 public  void start(PrintWriter consoleWriter) throws Exception {
		serverImpl.start(consoleWriter);
}

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

 public  void trace(boolean on) throws Exception {
		serverImpl.trace(on);
}

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

 public  void trace(int connNum,
    boolean on) throws Exception {
		serverImpl.trace(connNum, on);
}

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