NetworkServerControl


1   /*
2   
3      Derby - Class org.apache.derby.drda.NetworkServerControl
4   
5      Licensed to the Apache Software Foundation (ASF) under one or more
6      contributor license agreements.  See the NOTICE file distributed with
7      this work for additional information regarding copyright ownership.
8      The ASF licenses this file to You under the Apache License, Version 2.0
9      (the "License"); you may not use this file except in compliance with
10     the License.  You may obtain a copy of the License at
11  
12        http://www.apache.org/licenses/LICENSE-2.0
13  
14     Unless required by applicable law or agreed to in writing, software
15     distributed under the License is distributed on an "AS IS" BASIS,
16     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17     See the License for the specific language governing permissions and
18     limitations under the License.
19  
20   */
21  
22  package org.apache.derby.drda;
23  
24  import java.io.PrintWriter  ;
25  import java.net.InetAddress  ;
26  import java.util.Properties  ;
27  import org.apache.derby.iapi.reference.Property;
28  
29  import org.apache.derby.impl.drda.NetworkServerControlImpl;
30  
31  /** 
32      NetworkServerControl provides the ability to start a Network Server or 
33      connect to a running Network Server to shutdown, configure or retreive 
34      diagnostic information.  With the exception of ping, these commands 
35      can  only be performed from the  machine on which the server is running.  
36      Commands can be performed from  the command line with the following 
37      arguments:
38  
39      <P>
40      <UL>
41      <LI>start [-h &lt;host>] [-p &lt;portnumber>]:  This starts the network
42      server on the port/host specified or on localhost, port 1527 if no
43      host/port is specified and no properties are set to override the 
44      defaults. By default Network Server will only listen for 
45      connections from the machine on which it is running. 
46      Use -h 0.0.0.0 to listen on all interfaces or -h &lt;hostname> to listen 
47      on a specific interface on a  multiple IP machine. </LI>
48  
49      <LI>shutdown [-h &lt;host>][-p &lt;portnumber>]: This shutdowns the network     server on the host and port specified or on the local host and port 
50      1527(default) if no host or port is specified.  </LI> 
51  
52      <LI>ping [-h &lt;host>] [-p &lt;portnumber>] 
53      This will test whether the Network Server is up.
54      </LI>
55  
56      <LI>sysinfo [-h &lt;host>] [-p &lt;portnumber>]:  This prints 
57      classpath and version information about the Network Server, 
58      the JVM and the Derby engine. 
59  
60      <LI>runtimeinfo [-h &lt;host] [-p &lt;portnumber]: This prints
61      extensive debbugging information about sessions, threads, 
62      prepared statements, and memory usage for the running Network Server.
63      </LI>
64  
65      <LI>logconnections {on | off} [-h &lt;host>] [-p &lt;portnumber>]:  
66      This turns logging of connections on or off.  
67      Connections are logged to derby.log. 
68      Default is off.</LI>
69  
70      <LI>maxthreads &lt;max> [-h &lt;host>][-p &lt;portnumber>]:  
71      This sets the maximum number of threads that can be used for connections. 
72      Default 0 (unlimitted).
73      </LI>
74  
75      <LI>timeslice &lt;milliseconds> [-h &lt;host>][-p &lt;portnumber>]: 
76      This sets the time each session can have using a connection thread 
77      before yielding to a waiting session. Default is 0 (no yeild).
78      
79      </LI>
80  
81      <LI>trace {on | off} [-s &lt;session id>] [-h &lt;host>] [-p &lt;portnumber>]: 
82      This turns drda tracing on or off for the specified session or if no 
83      session is  specified for all sessions. Default is off</LI>
84  
85  
86      <LI>tracedirectory &lt;tracedirectory> [-h &lt;host>] [-p &lt;portnumber>]: 
87      This changes where new trace files will be placed. 
88      For sessions with tracing already turned on,  
89      trace files remain in the previous location. 
90      Default is derby.system.home, if it is set. 
91      Otherwise the default is the current directory.</LI>
92  
93      </UL>
94      <P>Properties can be set in the derby.properties file or on the command line.
95      Properties on the command line take precedence over properties in the 
96      derby.properties file.  Arguments on the command line take precedence
97      over properties. 
98      The following is a list of properties that can be set for 
99      NetworkServerControl:
100 
101     <UL><LI>derby.drda.portNumber=&lt;port number>: This property 
102     indicates which port should be used for the Network Server. </LI>
103 
104     <LI>derby.drda.host=&lt;host name  or ip address >: This property 
105     indicates the ip address to which NetworkServerControl should connect 
106 
107     <LI>derby.drda.traceDirectory=&lt;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=&lt;value>: If this property
117     is set, the &lt;value> number of threads will be created when the Network Server is
118     booted. </LI>
119 
120     <LI>derby.drda.maxThreads=&lt;value>: If this property
121     is set, the &lt;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=&lt;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 &lt;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 
168     
169     public final static int DEFAULT_PORTNUMBER = 1527;
170     private NetworkServerControlImpl serverImpl;
171 
172     // constructor
173 
174     /**
175      * 
176      * Creates a NetworkServerControl object that is configured to control
177      * a Network Server on a  specified port and InetAddress.
178      *<P>
179      * <B> Examples: </B>
180      * <P>
181      * To configure for port 1621 and listen on the loopback address:
182      *<PRE>
183      *  NetworkServerControl  util = new
184      * NetworkServerControl(InetAddress.getByName("localhost"), 1621);
185      * </PRE>
186      *
187      * @param address     The IP address of the Network Server host.
188      *                     address cannot be null.
189 
190      * @param portNumber  port number server is to used. If <= 0,
191      *                    default port number is used
192      *                       
193      * @throws             Exception on error
194      */
195     public NetworkServerControl(InetAddress   address,int portNumber) throws Exception  
196     {
197         
198         serverImpl = new NetworkServerControlImpl(address, 
199                                         portNumber);
200 
201     }
202     
203 
204     /**
205      * 
206      * Creates a NetworkServerControl object that is configured to control
207      * a Network Server on the default host(localhost)
208      * and the default port(1527) unless derby.drda.portNumber and 
209      * derby.drda.host are set.
210      * <P><PRE>
211      * new NetworkServerControl() 
212      *
213      * is equivalent to calling
214      *
215      * new NetworkServerControl(InetAddress.getByName("localhost"),1527);
216      * </PRE>
217      *
218      * @throws             Exception on error
219      */
220     public NetworkServerControl() throws Exception  
221     {
222         
223         serverImpl = new NetworkServerControlImpl();
224 
225     }
226     
227     
228     /**
229      * main routine for NetworkServerControl
230      *
231      * @param args  array of arguments indicating command to be executed.
232      * See class comments for more information
233      */
234     public static void main(String   args[]) {
235         NetworkServerControlImpl server = null;
236         try
237         {
238             server = new NetworkServerControlImpl();
239             server.executeWork(args);
240         }
241         catch (Exception   e)
242         {
243             //if there was an error, exit(1)
244             if ((e.getMessage() == null) ||
245                 !e.getMessage().equals(NetworkServerControlImpl.UNEXPECTED_ERR))
246             {
247                 if (server != null)
248                     server.consoleExceptionPrint(e);
249                 else
250                     e.printStackTrace();  // default output stream is System.out
251             }
252             // else, we've already printed a trace, so just exit.
253             System.exit(1);
254         }
255         System.exit(0);
256         
257     }
258 
259     /**********************************************************************
260      * Public NetworkServerControl  commands
261      * The server commands throw exceptions for errors, so that users can handle
262      * them themselves.
263      ************************************************************************
264      **/
265 
266     /** Start a Network Server
267      *  This method will launch a separate thread and start Network Server.
268      *  This method  may return before the server is ready to accept connections.
269      *  Use the ping method to verify that the server has started.
270      *
271      * <P>
272      *  Note: an alternate method to starting the Network Server with the API,
273      *  is to use the derby.drda.startNetworkServer property in 
274      *  cloudscape.properties.
275      *  
276      * 
277      * @param consoleWriter   PrintWriter to which server console will be 
278      *                        output. Null will disable console output. 
279      *
280      * @exception Exception if there is an error starting the server.
281      *
282      * @see #shutdown
283      */
284     public void start(PrintWriter   consoleWriter) throws Exception  
285     {
286         serverImpl.start(consoleWriter);
287     }
288 
289     
290 
291     /**
292      * Shutdown a Network Server.
293      * Shuts down the Network Server listening on the port and InetAddress
294      * specified in the constructor for this NetworkServerControl object.
295      *
296      * @exception Exception throws an exception if an error occurs
297      */
298     public void shutdown()
299         throws Exception  
300     {
301         serverImpl.shutdown();
302     }
303 
304     /**
305      * Check if Network Server is started
306      * Excecutes and returns without error if the server has started
307      *
308      * @exception Exception throws an exception if an error occurs
309      */
310     public void  ping() throws Exception  
311     {
312          serverImpl.ping();
313     }
314 
315     /**
316      * Turn tracing on or off for the specified connection 
317      * on the Network Server.
318      *
319      * @param on true to turn tracing on, false to turn tracing off.
320      *
321      * @exception Exception throws an exception if an error occurs
322      */
323     public void trace(boolean on)
324         throws Exception  
325     {
326         serverImpl.trace(on);
327     }
328 
329 
330     /**
331      * Turn tracing on or off for all connections on the Network Server.
332      *
333      * @param connNum connection number. Note: Connection numbers will print
334      *                in the Derby error log if logConnections is on
335      * @param on true to turn tracing on, false to turn tracing off.
336      *
337      * @exception Exception throws an exception if an error occurs
338      */
339     public void trace(int connNum, boolean on)
340         throws Exception  
341     {
342         serverImpl.trace(connNum, on);
343     }
344 
345     /**
346      * Turn logging connections on or off. When logging is turned on a message is
347      * written to the Derby error log each time a connection 
348      * is made.
349      *
350      * @param on            true to turn on, false to turn  off
351      *
352      * @exception Exception throws an exception if an error occurs
353      */
354     public void logConnections(boolean on)
355         throws Exception  
356     {
357         serverImpl.logConnections(on);
358     }
359 
360     /**
361      * Set directory for trace files. The directory must be on the machine
362      * where the server is running.
363      *
364      * @param traceDirectory    directory for trace files on machine 
365      *                          where server is running
366      *
367      * @exception Exception throws an exception if an error occurs
368      */
369     public void setTraceDirectory(String   traceDirectory)
370         throws Exception  
371     {
372         serverImpl.sendSetTraceDirectory(traceDirectory);
373     }
374 
375     /**
376      * Return classpath and version information about the running 
377      * Network Server. 
378      *
379      * @return sysinfo output
380      * @exception Exception throws an exception if an error occurs
381      */
382     public String   getSysinfo()
383         throws Exception  
384     {
385         
386         return serverImpl.sysinfo();
387     }
388 
389     /**
390      * Return detailed session runtime information about sessions,
391      * prepared statements, and memory usage for the running Network Server. 
392      *
393      * @return run time information
394      * @exception Exception throws an exception if an error occurs
395      */
396     public String   getRuntimeInfo()
397         throws Exception  
398     {
399         return serverImpl.runtimeInfo();
400     }
401 
402 
403     /**
404      * Set Network Server maxthread parameter.  This is the maximum number 
405      * of threads that will be used for JDBC client connections.   setTimeSlice
406      * should also be set so that clients will yield appropriately.
407      *
408      * @param max       maximum number of connection threads.
409      *                  If <= 0, connection threads will be created when 
410      *                  there are no free connection threads.
411      *
412      * @exception Exception throws an exception if an error occurs
413      * @see #setTimeSlice
414      */
415     public void setMaxThreads(int max) throws Exception  
416     {
417         serverImpl.netSetMaxThreads(max);
418     }
419 
420 
421     /** Returns the current maxThreads setting for the running Network Server
422      * 
423      * @return maxThreads setting 
424      * @exception Exception throws an exception if an error occurs
425      * @see #setMaxThreads
426      */
427     public int getMaxThreads() throws Exception  
428     {
429         String   val =serverImpl.getCurrentProperties().getProperty(Property.DRDA_PROP_MAXTHREADS);
430 
431         
432         return Integer.parseInt(val);
433     }
434 
435     /**
436      * Set Network Server connection time slice parameter.  
437      * This should be set and is only relevant if setMaxThreads > 0.
438      *
439      * @param timeslice number of milliseconds given to each session before yielding to 
440      *                      another session, if <=0, never yield. 
441      *
442      * @exception Exception throws an exception if an error occurs
443      * @see #setMaxThreads
444      */
445     public void setTimeSlice(int timeslice) throws Exception  
446     {
447         serverImpl.netSetTimeSlice(timeslice);
448     }
449 
450     /** Return the current timeSlice setting for the running Network Server
451      * 
452      * @return timeSlice  setting
453      * @exception Exception throws an exception if an error occurs
454      * @see #setTimeSlice
455      */
456     public int getTimeSlice() throws Exception  
457     {
458         String   val  =
459             serverImpl.getCurrentProperties().getProperty(Property.DRDA_PROP_TIMESLICE);
460         return Integer.parseInt(val);
461     }
462 
463 
464 
465     /**
466      * Get current Network server properties
467      *
468      * @return Properties object containing Network server properties
469      * @exception Exception throws an exception if an error occurs
470      */
471     public Properties   getCurrentProperties() throws Exception  
472     {
473         return serverImpl.getCurrentProperties();
474     }
475 
476     /** Protected methods ***/
477 
478     /***
479      * set the client locale. Used by servlet for localization
480      * @param locale  Locale to use
481      *
482      */
483           
484     protected void setClientLocale(String   locale)
485     {
486         serverImpl.clientLocale = locale;
487     }
488 }
489 
490 
491 
492 
493 
494
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags