Hosted by SourceForge

Protomatter Free Software version 1.1.6 SourceForge Project Summary Page Released November 23, 2001

Help With Name Recognition!

I'd like to add a "customer list" page of companies, products and other OpenSource projects that are using these libraries. It helps with name recognition for this project, and I'll include links to each "customer" website, so you can get free advertising, too. If you're interested in doing this, just send me an email with who you are, your company or product/project name and URLs if you want. Thanks.

On-Line Links:

• Back Up One Directory
• Javadoc (no frames)

Syslog Links:

• A Whitepaper on Syslog.
• The Syslog FAQ
• Syslog Examples
• An article on Syslog published in JavaWorld.

Download Links:

• Classes (238 K)
• Javadoc (825 K)
• Source (382 K)
• JDOM B7 Classes (106 K)

Third Party Libraries:

Apache Ant
The Apache Ant build tool is required if you want to build the packages yourself. It is not required to run. This release was built using Ant 1.4.

JDom CLasses

The JDom XML API for Java, version B7 is required. It is available from www.jdom.org. You must use B7, as previous versions will not work.
NOTE: This library is only needed if you are using XML files to configure Syslog.

Apache Xerces XML Parser Package

The Apache Xerces XML parser is required for parsing XML configuration information. This version of protomatter was built against version 1.4.4 of the Apache Xerces XML parser, though it may work very well with earlier versions. If you're using a J2EE Application Server, you probably have this requirement covered.
NOTE: This library is only needed if you are using XML files to configure Syslog.

ORO Regular Expression Package

The ORO regular expression package is required. It is now part of the Apache Jakarta project. This version of protomatter was built against version 2.0.4 of the ORO package.
NOTE: This is only needed by the PerClassPolicy and PerChannelPolicy policies when using the Perl5 regular expression matching features, so if you're not using them you won't need the ORO package.

JavaSoft J2EE Packages

If you are building the classes, you'll need the J2EE packages to compile. Specifically, the javax.ejb.*, javax.naming.* and javax.sql.* classes. If you are running with an Application Server (such as BEA WebLogic Server 5.1 or 6.1, you should be just fine).
NOTE: These classes are only needed if you're using the EJB base classes, the DataSource stuff in the JDBC connection pool, or the JMS or RMI loggers in Syslog.

JDK or JRE 1.2 or later

These classes require at least JDK 1.2 to work. Currently, I am developing and compiling under JDK 1.3.1. For more information on JDK and JRE versions for different platforms, please see java.sun.com.

Cleaned up the build.xml file for Ant. It's now nicer about not building some things if you're missing some libraries. It warns what won't be built, and says what library is needed to build it.

com.protomatter.util.*:

• Moved the com.protomatter.util.OpTimer class to this package from the com.protomatter.syslog package. It was moved becuase it really has nothing to do with Syslog, though it works quite well with it. The name was also changed to OpTimer from Timer since JDK 1.3 has a java.util.Timer class, and class name clashes are annoying.

• Added the com.protomatter.util.OpTimerUtil class. This class is a command line application that parses text files for traces left by the com.protomatter.util.OpTimer class and prints aggregate timing information, including pretty ascii-art histograms. Very useful for finding bottlenecks in systems and for general timing analytics.

• Added the com.protomatter.util.Cache interface and the com.protomatter.util.SoftReferenceCache and com.protomatter.util.ExpiringSoftReferenceCache classes, which uses the new SoftReference class in JDK 1.3 to build memory-sensitive caches.

com.protomatter.syslog.*:

• Fixed a contention problem in the PerClassPolicy policy object that was causing messages to be dropped during very high message volumes. Sorry for not giving credit to the person who found the bug -- I lost your email!

• Modified the DatabaseLog so that it will truncate data before attempting to write it to the database. Each field length is configurable (see the JavaDoc for more information). Also, writing the detail column to the database has been delegated to implementations of the DatabaseLogStatementAdapter. This allows different ways of setting large amounts of data, depending on what features the JDBC driver has.

• Changed the internal values for log levels. This was done to make log masks easier to compute and to make it easier to convert to/from text representations of complex log masks. Changing these values and how log masks are interpreted should not affect anyone because the real values of these things were always hidden behind constants. Note: this will affect you if you're using the DatabaseLog logger because it has a reference table containing the explicit values of each level.

• Allow for easier text specifications of log masks. Now, if you want to specify a log mask that lets only INFO and WARNING messages (but nothing else) pass, you can simply say "=INFO,=WARNING" when specifying the log mask. Log masks are easier to calculate in code, also. To do the same as the above using the symbolic constants on the Syslog class, you can do this: "Syslog.INFO | Syslog.WARNING" (using the binary or operator).

• Moved policy checking out of the log() method on loggers and into Syslog itself. It simplifies the code for loggers because the log(...) method will never be called unless the chosen policy has given its blessing.

• Separated XML configuration stuff to its own package. Due to popular demand, the base syslog classes can be compiled without any fancy XML parsers, J2EE classes, etc, etc, etc. All the XML configuration goodies have been placed in their own package: com.protomatter.syslog.xml (You will probably only ever use the SyslogXML class from this package)

  If you were doing this before:

  import com.protomatter.syslog.Syslog;
  ...
  Syslog.configure(new File("blah.xml"));

  now you need to do this:

  import com.protomatter.syslog.xml.SyslogXML;
  ...
  SyslogXML.configure(new File("blah.xml"));
  

  Other than that, configuration is exactly the same as before. If you're using the SyslogT3Startup class to start Syslog from inside WebLogic Server, the you don't need to do anything because the startup class takes care of everything.

  Several users had requested these changes, and they make sense. In some cases, production environments don't want to have the most bleading-edge technologies (like XML, etc) thrown around all over the place. Also, if you're deploying syslog to a Java-enabled toaster or something, you might not want all the extra libraries needed to do XML parsing. In any case, there you go. You can still configure Syslog via an XML file and get a current configuration written back out. You can also still use API calls to configure everything.

  Also, the XML parser used to parse the configuration file can now be specified using the "Syslog.xml.parser" system property. The value of that property (if used) should be set to the full classname of a SAX parser, such as "org.apache.xerces.parsers.SAXParser".

• Added the SyslogInitServlet which allows easy configuration of syslog when a Web Application is loaded by an application server. This makes it easy to integrate Syslog with any application- or web-server that supports initializing servlets on startup (part of the Servlet 2.2 specification).

• Modified the SimpleSyslogTextFormatter formatter so that you can specify the field width for the class name, host name, thread name and channel name sections now.

• Added the Wl6SyslogTextFormatter formatter, which mimics the log output of WebLogic Server 6.x. The other WLS formatter (WlSyslogTextFormatter) mimics the output of WebLogic Server 4.x and 5.x.

• Added the Channel class, which makes it easier to write messages to channels.

• Added the PerChannelPolicy class, which is exactly like the PerClassPolicy extept that it matches regular expression sets against channel names. With the recent emphasis on channels as easy segmentation tools, this class adds a lot of flexability in the channel direction.

   

  Fancy JDK 1.4 Support (at least 1.4 beta 3)

• Added the SyslogHandler class, which is a JDK 1.4 java.util.logging.Handler implementation that routes log messages from the new logging API into Syslog. This is a first pass at an adapter for the new logging API, so it's subject to change (JDK 1.4 isn't even out of beta yet, anyway). As of right now, though, it's pretty much complete unless the new logging API changes before the final release of JDK 1.4.

  This adapter class allows you to use only JDK 1.4 logging API calls have have everything routed to Syslog without including any syslog calls in your code.

  Compiling that class with the rest of the system is a bit tricky, because it needs JDK 1.4, and the JDBC connection pooling code is currently not able to be compiled with JDK 1.4 (extra methods in JDBC). So, if you want to compile it yourself, build everything else with JDK 1.3 and then switch to JDK 1.4 and build the "compile-jdk-14" target in the build file. I'll clean this up, but for now you'll just have to deal with it. The jar file that ships has that class compiled in it.

  Also, at the risk of editorializing here, the new logging API is not very good. There's all kinds of cruft in there and my guess is that it's there because the API tries to satisfy too many people. A couple things that bug me:

  • Why do you need seven log levels? Fine, finer and finest? Huh?
  • Log entries are represented with a LogRecord class, but elsewhere it is called a log message (in the formatter).
  • LogRecord has a getMillis() method instead of something that makes sense, like getTime().
  • An int is used to represent a thread. How about its name?
  • Every object is just about as heavy-weight as it could possibly be, and it looks like object instances are wasted all over the place.
  • The new API is big on segregating things based on subsystem name (by which they almost always mean package), which is not always the best thing to do. I think flexibility is more important.

  And that's just what came to mind in the last few minutes. Still, as a colleague of mine is fond of saying "standard is better than good" -- and the new API is the standard. Still, with the adapter class, you can easily route all messages from the new API into Syslog, where you'll still have full flexibility to route messages into databases, JMS, text files, email, etc.

• Added the JDK14SyslogTextFormatter class, which is a log formatter that uses new APIs included in JDK 1.4 to get the correct class name, method name and file line number for each log call. This is the default text formatter for systems running under JDK 1.4. Check it out -- it's pretty cool.

• Added the JDK14PerClassPolicy class, which is an implementation of the PerClassPolicy policy class. Instead of using the ORO matcher, it uses the new JDK 1.4 regular expression matching classes.

• Added the JDK14PerChannelPolicy class, which is an implementation of the PerChannelPolicy policy class. Instead of using the ORO matcher, it uses the new JDK 1.4 regular expression matching classes.

• Note: This part of Syslog was designed and built against JDK 1.4 beta 3. If the final release of JDK 1.4 has API changes that affect Syslog, I'll release an updated version soon after the officil JDK 1.4 is released.

com.protomatter.pool.*:

• Modified the checkout() method on SimpleObjectPool so that if the beforeObjectPoolObjectCheckout() method on an ObjectPoolObject instance invalidates the pooled object before checkout, it will be evicted from the pool and another object will be used.

com.protomatter.jdbc.pool.*:

• Added the pool.maxCheckoutRefreshAttempts and pool.checkoutRefreshWaitTime configuration params to the JdbcConnectionPool class. It was possible to get into an infinite loop if you had pool.validateOnCheckout set to true and database was gone. The driver just kept trying to refresh the connection forever. Thanks to Ralph Brandes for finding this bug.

• Changed the JdbcConnectionPoolConnection class so that when it initializes, if the getCatalog() method on the underlying connection throws a SQLException we assume that you just can't get the catalog, rather than assuming the connection is broken. Sybase (and possibly other DBs) requires you to install metadata tables and stored procs to get that information, and not everyone wants to do that. Thanks to Davesh Patel for pointing this out.

com.protomatter.j2ee.ejb.*:

• Added the ProtoMessageEJB class which is a base class for Message Driven EJBs (part of the EJB 2.0 spec).

The Future:

Future direction for protomatter will probably (hopefully?) include JMX management beans for Syslog (probably under com.protomatter.syslog.jmx). The idea there is that it would really be nice to use JMX management consoles to configure everything about Syslog from a nice, pretty GUI.

If the logging API changes when the final JDK 1.4 ships, I may have to update quickly with a new release that works with the final JDK 1.4 APIs.

---

Send email to support@protomatter.com if you have questions.
Everything here is ©1998-2001 Nate Sammons (nate@protomatter.com).