001: /*
002:
003: Derby - Class org.apache.derby.drda.NetworkServerControl
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to You under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.drda;
023:
024: import java.io.PrintWriter;
025: import java.net.InetAddress;
026: import java.util.Properties;
027: import org.apache.derby.iapi.reference.Property;
028:
029: import org.apache.derby.impl.drda.NetworkServerControlImpl;
030:
031: /**
032: NetworkServerControl provides the ability to start a Network Server or
033: connect to a running Network Server to shutdown, configure or retreive
034: diagnostic information. With the exception of ping, these commands
035: can only be performed from the machine on which the server is running.
036: Commands can be performed from the command line with the following
037: arguments:
038:
039: <P>
040: <UL>
041: <LI>start [-h <host>] [-p <portnumber>]: This starts the network
042: server on the port/host specified or on localhost, port 1527 if no
043: host/port is specified and no properties are set to override the
044: defaults. By default Network Server will only listen for
045: connections from the machine on which it is running.
046: Use -h 0.0.0.0 to listen on all interfaces or -h <hostname> to listen
047: on a specific interface on a multiple IP machine. </LI>
048:
049: <LI>shutdown [-h <host>][-p <portnumber>]: This shutdowns the network server on the host and port specified or on the local host and port
050: 1527(default) if no host or port is specified. </LI>
051:
052: <LI>ping [-h <host>] [-p <portnumber>]
053: This will test whether the Network Server is up.
054: </LI>
055:
056: <LI>sysinfo [-h <host>] [-p <portnumber>]: This prints
057: classpath and version information about the Network Server,
058: the JVM and the Derby engine.
059:
060: <LI>runtimeinfo [-h <host] [-p <portnumber]: This prints
061: extensive debbugging information about sessions, threads,
062: prepared statements, and memory usage for the running Network Server.
063: </LI>
064:
065: <LI>logconnections {on | off} [-h <host>] [-p <portnumber>]:
066: This turns logging of connections on or off.
067: Connections are logged to derby.log.
068: Default is off.</LI>
069:
070: <LI>maxthreads <max> [-h <host>][-p <portnumber>]:
071: This sets the maximum number of threads that can be used for connections.
072: Default 0 (unlimitted).
073: </LI>
074:
075: <LI>timeslice <milliseconds> [-h <host>][-p <portnumber>]:
076: This sets the time each session can have using a connection thread
077: before yielding to a waiting session. Default is 0 (no yeild).
078:
079: </LI>
080:
081: <LI>trace {on | off} [-s <session id>] [-h <host>] [-p <portnumber>]:
082: This turns drda tracing on or off for the specified session or if no
083: session is specified for all sessions. Default is off</LI>
084:
085:
086: <LI>tracedirectory <tracedirectory> [-h <host>] [-p <portnumber>]:
087: This changes where new trace files will be placed.
088: For sessions with tracing already turned on,
089: trace files remain in the previous location.
090: Default is derby.system.home, if it is set.
091: Otherwise the default is the current directory.</LI>
092:
093: </UL>
094: <P>Properties can be set in the derby.properties file or on the command line.
095: Properties on the command line take precedence over properties in the
096: derby.properties file. Arguments on the command line take precedence
097: over properties.
098: The following is a list of properties that can be set for
099: NetworkServerControl:
100:
101: <UL><LI>derby.drda.portNumber=<port number>: This property
102: indicates which port should be used for the Network Server. </LI>
103:
104: <LI>derby.drda.host=<host name or ip address >: This property
105: indicates the ip address to which NetworkServerControl should connect
106:
107: <LI>derby.drda.traceDirectory=<trace directory>: This property
108: indicates where to put trace files. </LI>
109:
110: <LI>derby.drda.traceAll=true: This property turns on tracing for
111: all sessions. Default is tracing is off.</LI>
112:
113: <LI>derby.drda.logConnections=true: This property turns on logging
114: of connections. Default is connections are not logged.</LI>
115:
116: <LI>derby.drda.minThreads=<value>: If this property
117: is set, the <value> number of threads will be created when the Network Server is
118: booted. </LI>
119:
120: <LI>derby.drda.maxThreads=<value>: If this property
121: is set, the <value> is the maximum number of connection threads that will be
122: created. If a session starts when there are no connection threads available
123: and the maximum number of threads has been reached, it will wait until a
124: conection thread becomes available. </LI>
125:
126: <LI>derby.drda.timeSlice=<milliseconds>: If this property
127: is set, the connection threads will not check for waiting sessions until the
128: current session has been working for <milliseconds>.
129: A value of 0 causes the thread to work on the current session until the
130: session exits. If this property is not set, the default value is 0. </LI>
131:
132: </LI>
133:
134: <P><B>Examples.</B>
135:
136: <P>This is an example of shutting down the server on port 1621.
137: <PRE>
138: java org.apache.derby.drda.NetworkServerControl shutdown -p 1621
139: </PRE>
140:
141: <P>This is an example of turning tracing on for session 3
142: <PRE>
143: java org.apache.derby.drda.NetworkServerControl trace on -s 3
144: </PRE>
145:
146: <P>This is an example of starting and then shutting down the network
147: server on port 1621 on machine myhost
148: <PRE>
149: java org.apache.derby.drda.NetworkServerControl start -h myhost -p 1621
150: java org.apache.derby.drda.NetworkServerControl shutdown -h myhost -p 1621
151: </PRE>
152:
153: <P> This is an example of starting and shutting down the Network Server in the example
154: above with the API.
155: <PRE>
156:
157: NetworkServerControl serverControl = new NetworkServerControl(InetAddress.getByName("myhost"),1621)
158:
159: serverControl.shutdown();
160: </PRE>
161:
162:
163: */
164:
165: public class NetworkServerControl {
166:
167: public final static int DEFAULT_PORTNUMBER = 1527;
168: private NetworkServerControlImpl serverImpl;
169:
170: // constructor
171:
172: /**
173: *
174: * Creates a NetworkServerControl object that is configured to control
175: * a Network Server on a specified port and InetAddress.
176: *<P>
177: * <B> Examples: </B>
178: * <P>
179: * To configure for port 1621 and listen on the loopback address:
180: *<PRE>
181: * NetworkServerControl util = new
182: * NetworkServerControl(InetAddress.getByName("localhost"), 1621);
183: * </PRE>
184: *
185: * @param address The IP address of the Network Server host.
186: * address cannot be null.
187:
188: * @param portNumber port number server is to used. If <= 0,
189: * default port number is used
190: *
191: * @throws Exception on error
192: */
193: public NetworkServerControl(InetAddress address, int portNumber)
194: throws Exception {
195:
196: serverImpl = new NetworkServerControlImpl(address, portNumber);
197:
198: }
199:
200: /**
201: *
202: * Creates a NetworkServerControl object that is configured to control
203: * a Network Server on the default host(localhost)
204: * and the default port(1527) unless derby.drda.portNumber and
205: * derby.drda.host are set.
206: * <P><PRE>
207: * new NetworkServerControl()
208: *
209: * is equivalent to calling
210: *
211: * new NetworkServerControl(InetAddress.getByName("localhost"),1527);
212: * </PRE>
213: *
214: * @throws Exception on error
215: */
216: public NetworkServerControl() throws Exception {
217:
218: serverImpl = new NetworkServerControlImpl();
219:
220: }
221:
222: /**
223: * main routine for NetworkServerControl
224: *
225: * @param args array of arguments indicating command to be executed.
226: * See class comments for more information
227: */
228: public static void main(String args[]) {
229: NetworkServerControlImpl server = null;
230: try {
231: server = new NetworkServerControlImpl();
232: server.executeWork(args);
233: } catch (Exception e) {
234: //if there was an error, exit(1)
235: if ((e.getMessage() == null)
236: || !e.getMessage().equals(
237: NetworkServerControlImpl.UNEXPECTED_ERR)) {
238: if (server != null)
239: server.consoleExceptionPrint(e);
240: else
241: e.printStackTrace(); // default output stream is System.out
242: }
243: // else, we've already printed a trace, so just exit.
244: System.exit(1);
245: }
246: System.exit(0);
247:
248: }
249:
250: /**********************************************************************
251: * Public NetworkServerControl commands
252: * The server commands throw exceptions for errors, so that users can handle
253: * them themselves.
254: ************************************************************************
255: **/
256:
257: /** Start a Network Server
258: * This method will launch a separate thread and start Network Server.
259: * This method may return before the server is ready to accept connections.
260: * Use the ping method to verify that the server has started.
261: *
262: * <P>
263: * Note: an alternate method to starting the Network Server with the API,
264: * is to use the derby.drda.startNetworkServer property in
265: * cloudscape.properties.
266: *
267: *
268: * @param consoleWriter PrintWriter to which server console will be
269: * output. Null will disable console output.
270: *
271: * @exception Exception if there is an error starting the server.
272: *
273: * @see #shutdown
274: */
275: public void start(PrintWriter consoleWriter) throws Exception {
276: serverImpl.start(consoleWriter);
277: }
278:
279: /**
280: * Shutdown a Network Server.
281: * Shuts down the Network Server listening on the port and InetAddress
282: * specified in the constructor for this NetworkServerControl object.
283: *
284: * @exception Exception throws an exception if an error occurs
285: */
286: public void shutdown() throws Exception {
287: serverImpl.shutdown();
288: }
289:
290: /**
291: * Check if Network Server is started
292: * Excecutes and returns without error if the server has started
293: *
294: * @exception Exception throws an exception if an error occurs
295: */
296: public void ping() throws Exception {
297: serverImpl.ping();
298: }
299:
300: /**
301: * Turn tracing on or off for the specified connection
302: * on the Network Server.
303: *
304: * @param on true to turn tracing on, false to turn tracing off.
305: *
306: * @exception Exception throws an exception if an error occurs
307: */
308: public void trace(boolean on) throws Exception {
309: serverImpl.trace(on);
310: }
311:
312: /**
313: * Turn tracing on or off for all connections on the Network Server.
314: *
315: * @param connNum connection number. Note: Connection numbers will print
316: * in the Derby error log if logConnections is on
317: * @param on true to turn tracing on, false to turn tracing off.
318: *
319: * @exception Exception throws an exception if an error occurs
320: */
321: public void trace(int connNum, boolean on) throws Exception {
322: serverImpl.trace(connNum, on);
323: }
324:
325: /**
326: * Turn logging connections on or off. When logging is turned on a message is
327: * written to the Derby error log each time a connection
328: * is made.
329: *
330: * @param on true to turn on, false to turn off
331: *
332: * @exception Exception throws an exception if an error occurs
333: */
334: public void logConnections(boolean on) throws Exception {
335: serverImpl.logConnections(on);
336: }
337:
338: /**
339: * Set directory for trace files. The directory must be on the machine
340: * where the server is running.
341: *
342: * @param traceDirectory directory for trace files on machine
343: * where server is running
344: *
345: * @exception Exception throws an exception if an error occurs
346: */
347: public void setTraceDirectory(String traceDirectory)
348: throws Exception {
349: serverImpl.sendSetTraceDirectory(traceDirectory);
350: }
351:
352: /**
353: * Return classpath and version information about the running
354: * Network Server.
355: *
356: * @return sysinfo output
357: * @exception Exception throws an exception if an error occurs
358: */
359: public String getSysinfo() throws Exception {
360:
361: return serverImpl.sysinfo();
362: }
363:
364: /**
365: * Return detailed session runtime information about sessions,
366: * prepared statements, and memory usage for the running Network Server.
367: *
368: * @return run time information
369: * @exception Exception throws an exception if an error occurs
370: */
371: public String getRuntimeInfo() throws Exception {
372: return serverImpl.runtimeInfo();
373: }
374:
375: /**
376: * Set Network Server maxthread parameter. This is the maximum number
377: * of threads that will be used for JDBC client connections. setTimeSlice
378: * should also be set so that clients will yield appropriately.
379: *
380: * @param max maximum number of connection threads.
381: * If <= 0, connection threads will be created when
382: * there are no free connection threads.
383: *
384: * @exception Exception throws an exception if an error occurs
385: * @see #setTimeSlice
386: */
387: public void setMaxThreads(int max) throws Exception {
388: serverImpl.netSetMaxThreads(max);
389: }
390:
391: /** Returns the current maxThreads setting for the running Network Server
392: *
393: * @return maxThreads setting
394: * @exception Exception throws an exception if an error occurs
395: * @see #setMaxThreads
396: */
397: public int getMaxThreads() throws Exception {
398: String val = serverImpl.getCurrentProperties().getProperty(
399: Property.DRDA_PROP_MAXTHREADS);
400:
401: return Integer.parseInt(val);
402: }
403:
404: /**
405: * Set Network Server connection time slice parameter.
406: * This should be set and is only relevant if setMaxThreads > 0.
407: *
408: * @param timeslice number of milliseconds given to each session before yielding to
409: * another session, if <=0, never yield.
410: *
411: * @exception Exception throws an exception if an error occurs
412: * @see #setMaxThreads
413: */
414: public void setTimeSlice(int timeslice) throws Exception {
415: serverImpl.netSetTimeSlice(timeslice);
416: }
417:
418: /** Return the current timeSlice setting for the running Network Server
419: *
420: * @return timeSlice setting
421: * @exception Exception throws an exception if an error occurs
422: * @see #setTimeSlice
423: */
424: public int getTimeSlice() throws Exception {
425: String val = serverImpl.getCurrentProperties().getProperty(
426: Property.DRDA_PROP_TIMESLICE);
427: return Integer.parseInt(val);
428: }
429:
430: /**
431: * Get current Network server properties
432: *
433: * @return Properties object containing Network server properties
434: * @exception Exception throws an exception if an error occurs
435: */
436: public Properties getCurrentProperties() throws Exception {
437: return serverImpl.getCurrentProperties();
438: }
439:
440: /** Protected methods ***/
441:
442: /***
443: * set the client locale. Used by servlet for localization
444: * @param locale Locale to use
445: *
446: */
447:
448: protected void setClientLocale(String locale) {
449: serverImpl.clientLocale = locale;
450: }
451: }
|