Source for java.util.logging.SocketHandler

   1: /* SocketHandler.java -- a class for publishing log messages to network sockets
   2:    Copyright (C) 2002 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.util.logging;
  40: 
  41: 
  42: /**
  43:  * A <code>SocketHandler</code> publishes log records to
  44:  * a TCP/IP socket.
  45:  *
  46:  * <p><strong>Configuration:</strong> Values of the subsequent
  47:  * <code>LogManager</code> properties are taken into consideration
  48:  * when a <code>SocketHandler</code> is initialized.
  49:  * If a property is not defined, or if it has an invalid
  50:  * value, a default is taken without an exception being thrown.
  51:  *
  52:  * <ul>
  53:  *
  54:  * <li><code>java.util.SocketHandler.level</code> - specifies
  55:  *     the initial severity level threshold. Default value:
  56:  *     <code>Level.ALL</code>.</li>
  57:  *
  58:  * <li><code>java.util.SocketHandler.filter</code> - specifies
  59:  *     the name of a Filter class. Default value: No Filter.</li>
  60:  *
  61:  * <li><code>java.util.SocketHandler.formatter</code> - specifies
  62:  *     the name of a Formatter class. Default value:
  63:  *     <code>java.util.logging.XMLFormatter</code>.</li>
  64:  *
  65:  * <li><code>java.util.SocketHandler.encoding</code> - specifies
  66:  *     the name of the character encoding. Default value:
  67:  *     the default platform encoding.</li>
  68:  *
  69:  * <li><code>java.util.SocketHandler.host</code> - specifies
  70:  *     the name of the host to which records are published.
  71:  *     There is no default value for this property; if it is
  72:  *     not set, the SocketHandler constructor will throw
  73:  *     an exception.</li>
  74:  *
  75:  * <li><code>java.util.SocketHandler.port</code> - specifies
  76:  *     the TCP/IP port to which records are published.
  77:  *     There is no default value for this property; if it is
  78:  *     not set, the SocketHandler constructor will throw
  79:  *     an exception.</li>
  80:  *
  81:  * </ul>
  82:  *
  83:  * @author Sascha Brawer (brawer@acm.org)
  84:  */
  85: public class SocketHandler
  86:   extends StreamHandler
  87: {
  88:   /**
  89:    * Constructs a <code>SocketHandler</code> that publishes log
  90:    * records to a TCP/IP socket.  Tthe initial configuration is
  91:    * determined by the <code>LogManager</code> properties described
  92:    * above.
  93:    *
  94:    * @throws java.io.IOException if the connection to the specified
  95:    *         network host and port cannot be established.
  96:    *
  97:    * @throws java.lang.IllegalArgumentException if either the
  98:    *         <code>java.util.logging.SocketHandler.host</code>
  99:    *         or <code>java.util.logging.SocketHandler.port</code>
 100:    *         LogManager properties is not defined, or specifies
 101:    *         an invalid value.
 102:    */
 103:   public SocketHandler()
 104:     throws java.io.IOException
 105:   {
 106:     this(LogManager.getLogManager().getProperty("java.util.logging.SocketHandler.host"),
 107:      getPortNumber());
 108:   }
 109: 
 110:     
 111:   /**
 112:    * Constructs a <code>SocketHandler</code> that publishes log
 113:    * records to a TCP/IP socket.  With the exception of the internet
 114:    * host and port, the initial configuration is determined by the
 115:    * <code>LogManager</code> properties described above.
 116:    *
 117:    * @param host the Internet host to which log records will be
 118:    *        forwarded.
 119:    *
 120:    * @param port the port at the host which will accept a request
 121:    *        for a TCP/IP connection.
 122:    *
 123:    * @throws java.io.IOException if the connection to the specified
 124:    *         network host and port cannot be established.
 125:    *
 126:    * @throws java.lang.IllegalArgumentException if either
 127:    *         <code>host</code> or <code>port</code> specify
 128:    *         an invalid value.
 129:    */
 130:   public SocketHandler(String host, int port)
 131:     throws java.io.IOException
 132:   {
 133:     super(createSocket(host, port),
 134:       "java.util.logging.SocketHandler",
 135:       /* default level */ Level.ALL,
 136:       /* formatter */ null,
 137:       /* default formatter */ XMLFormatter.class);
 138:   }
 139: 
 140: 
 141:   /**
 142:    * Retrieves the port number from the java.util.logging.SocketHandler.port
 143:    * LogManager property.
 144:    *
 145:    * @throws IllegalArgumentException if the property is not defined or
 146:    *         does not specify an integer value.
 147:    */
 148:   private static int getPortNumber()
 149:   {
 150:     try {
 151:       return Integer.parseInt(LogManager.getLogManager().getProperty("java.util.logging.SocketHandler.port"));
 152:     } catch (Exception ex) {
 153:       throw new IllegalArgumentException();
 154:     }
 155:   }
 156: 
 157: 
 158:   /**
 159:    * Creates an OutputStream for publishing log records to an Internet
 160:    * host and port.  This private method is a helper for use by the
 161:    * constructor of SocketHandler.
 162:    *
 163:    * @param host the Internet host to which log records will be
 164:    *        forwarded.
 165:    *
 166:    * @param port the port at the host which will accept a request
 167:    *        for a TCP/IP connection.
 168:    *
 169:    * @throws java.io.IOException if the connection to the specified
 170:    *         network host and port cannot be established.
 171:    *
 172:    * @throws java.lang.IllegalArgumentException if either
 173:    *         <code>host</code> or <code>port</code> specify
 174:    *         an invalid value.
 175:    */
 176:   private static java.io.OutputStream createSocket(String host, int port)
 177:     throws java.io.IOException, java.lang.IllegalArgumentException
 178:   {
 179:     java.net.Socket  socket;
 180: 
 181:     if ((host == null) || (port < 1))
 182:       throw new IllegalArgumentException();
 183: 
 184:     socket = new java.net.Socket(host, port);
 185: 
 186:     socket.shutdownInput();
 187: 
 188:     /* The architecture of the logging framework provides replaceable
 189:      * formatters.  Because these formatters perform their task by
 190:      * returning one single String for each LogRecord to be formatted,
 191:      * there is no need to buffer.
 192:      */
 193:     socket.setTcpNoDelay(true);
 194: 
 195:     return socket.getOutputStream();
 196:   }
 197: 
 198: 
 199:   /**
 200:    * Publishes a <code>LogRecord</code> to the network socket,
 201:    * provided the record passes all tests for being loggable.
 202:    * In addition, all data that may have been buffered will
 203:    * be forced to the network stream.
 204:    *
 205:    * <p>Most applications do not need to call this method directly.
 206:    * Instead, they will use a {@link Logger} instance, which will
 207:    * create LogRecords and distribute them to registered handlers.
 208:    *
 209:    * <p>In case of an I/O failure, the <code>ErrorManager</code>
 210:    * of this <code>SocketHandler</code> will be informed, but the caller
 211:    * of this method will not receive an exception.
 212:    *
 213:    * @param record the log event to be published.
 214:    */
 215:   public void publish(LogRecord record)
 216:   {
 217:     super.publish(record);
 218:     flush();
 219:   }
 220: }
 221: