logging-log4j-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nick Williams <nicho...@nicholaswilliams.net>
Subject Re: Three things I couldn't find on the Log4j 2 Site
Date Sun, 24 Mar 2013 23:11:35 GMT
Yikes. This could take some getting used to. For years the Tomcat mailing list has drilled
"top posting is bad" into my head, and then I come here and top posting is all y'all do. :-P

Understood that the community makes the decisions. I have been contributing to the Tomcat
project for a while now, so I get that concept. But since I'm new to this list, I thought
the community HERE might already have an idea when they wanted to release.

Based on your responses to 1) and 2), it sounds like it won't be a big risk to use Log4j 2
in my chapter. If they already use Log4j and don't want to switch, they're not going to read
that chapter anyway. If they don't use Log4j or are interested in upgrading, there it is.
Sounds like, chances are, it should be out before the end of the year.

Thanks for pointing out where the JavaDoc is. That is WAY not obvious. It would definitely
be a site improvement to add some more obvious navigation...

As for your responses to my API/Commons/SLF4J question:
- Something I read on the site last night seemed to indicate that using the Log4j API directly
had better performance than using it through SLF4J or Commons, enough that it was worth mentioning.
Unfortunately, I can't find it today. :-/
- Maybe a better question to know the answer to is: Which situation would yield me better
performance? If I chose the Log4j 2 API and later decided to switch to a different implementation
behind the API, or if I chose the SLF4J API outright with the Log4j 2 implementation? Opportunity
cost and all that. That might not be an easy question to answer.
- I think I like the Log4j 2 API better than Commons or SLF4J. I would definitely still use
Commons or SLF4J in a library, but in an application? Hmmm.

ON LEVELS, ENUMS and INTs:

Please don't convert the Level back to an int :-). The compile safety that comes with an enum
far outweighs the convenience of an int. In fact, the ONLY advantage I can see to using an
int is the fact that enums have a fixed set of values. HOWEVER, there's a way around this!
This might be better suited for the development list, but the conversation is already going,
so here are my compromise proposals. Either 1 or 2:

1) Change Level to be a "manual enum" like they used to be before Java added enums. You can
drop this in today and A) not change the API at all, making this a safe change, B) allow users
to add more levels, AND C) maintain the compile safety given to us by enums! My proposed code
for this is below.

2) Create a "public interface Level" with name(), intLevel(), ordinal(), isAtLeastAsSpecificAs(),
etc, just like what's on the enum now. Then, change the existing Level enum to "public enum
Levels implements Level." This is a common pattern (off the top of my head, CloseCode/CloseCodes
from Java WebSocket API is an example). It has the advantage that the existing Levels will
still be an enum (not sure how much that gains us over option 1) but the disadvantage that
you have to provide some static interface in the Level interface to aggregate all of the Levels
with all of the custom Level implementations. Personally, I prefer option 1. Easier, no API
changes.

With either option, any developer that implements their own Level will need to construct exactly
one instance of their class and do so before Log4j picks up its configuration (easily done
in static initializer).

Here's my example code for option 1. It should work perfectly and keep both sides happy (IMO).

public abstract class Level implements Comparable<Level>, Serializable
{
    public static final Level OFF;
    public static final Level FATAL;
    public static final Level ERROR;
    public static final Level WARN;
    public static final Level INFO;
    public static final Level DEBUG;
    public static final Level TRACE;
    public static final Level ALL;

    private static final long serialVersionUID = 0L;
    private static final Hashtable<String, Level> map;
    private static final TreeMap<Integer, Level> values;
    private static final Object constructorLock;

    static {
        // static variables must be constructed in certain order
        constructorLock = new Object();
        map = new Hashtable<String, Level>();
        values = new TreeMap<Integer, Level>();
        OFF = new Level("OFF", 0) {};
        FATAL = new Level("FATAL", 100) {};
        ERROR = new Level("ERROR", 200) {};
        WARN = new Level("WARN", 300) {};
        INFO = new Level("INFO", 400) {};
        DEBUG = new Level("DEBUG", 500) {};
        TRACE = new Level("TRACE", 600) {};
        ALL = new Level("ALL", Integer.MAX_VALUE) {};
    }

    private static int ordinals;

    private final String name;
    private final int intLevel;
    private final int ordinal;

    protected Level(String name, int intLevel) {
        if(name == null || name.length() == 0)
            throw new IllegalArgumentException("Illegal null Level constant");
        if(intLevel < 0)
            throw new IllegalArgumentException("Illegal Level int less than zero.");
        synchronized (Level.constructorLock) {
            if(Level.map.containsKey(name.toUpperCase()))
                throw new IllegalArgumentException("Duplicate Level constant [" + name + "].");
            if(Level.values.containsKey(intLevel))
                throw new IllegalArgumentException("Duplicate Level int [" + intLevel + "].");
            this.name = name;
            this.intLevel = intLevel;
            this.ordinal = Level.ordinals++;
            Level.map.put(name.toUpperCase(), this);
            Level.values.put(intLevel, this);
        }
    }

    public int intLevel() {
        return this.intLevel;
    }

    public boolean isAtLeastAsSpecificAs(final Level level) {
        return this.intLevel <= level.intLevel;
    }

    public boolean isAtLeastAsSpecificAs(final int level) {
        return this.intLevel <= level;
    }

    public boolean lessOrEqual(final Level level) {
        return this.intLevel <= level.intLevel;
    }

    public boolean lessOrEqual(final int level) {
        return this.intLevel <= level;
    }

    @Override
    @SuppressWarnings("CloneDoesntCallSuperClone")
    public Level clone() throws CloneNotSupportedException {
        throw new CloneNotSupportedException();
    }

    @Override
    public int compareTo(Level other) {
        return intLevel < other.intLevel ? -1 : (intLevel > other.intLevel ? 1 : 0);
    }

    @Override
    public boolean equals(Object other) {
        return other instanceof Level && other == this;
    }

    public Class<Level> getDeclaringClass() {
        return Level.class;
    }

    @Override
    public int hashCode() {
        return this.name.hashCode();
    }

    public String name() {
        return this.name;
    }

    public int ordinal() {
        return this.ordinal;
    }

    @Override
    public String toString() {
        return this.name;
    }

    public static Level toLevel(String name) {
        return Level.toLevel(name, Level.DEBUG);
    }

    public static Level toLevel(String name, Level defaultLevel) {
        if(name == null)
            return defaultLevel;
        name = name.toUpperCase();
        if(Level.map.containsKey(name))
            return Level.map.get(name);
        return defaultLevel;
    }

    public static Level[] values() {
        return Level.values.values().toArray(new Level[Level.values.size()]);
    }

    public static Level valueOf(String name) {
        if(name == null)
            throw new IllegalArgumentException("Unknown level constant [" + name + "].");
        name = name.toUpperCase();
        if(Level.map.containsKey(name))
            return Level.map.get(name);
        throw new IllegalArgumentException("Unknown level constant [" + name + "].");
    }

    public static <T extends Enum<T>> T valueOf(Class<T> enumType, String
name) {
        return Enum.valueOf(enumType, name);
    }

    // for deserialization
    protected final Object readResolve() throws ObjectStreamException {
        return Level.valueOf(this.name);
    }
}


On Mar 24, 2013, at 3:22 PM, Ralph Goers wrote:

> First, while I've done a lot of the work up until this point Apache is a place where
the community makes the decisions. 
> 
> 1) How stable is the API?  We recently had requests to add at least one log(level, ....)
method to the API.  That will probably be done. We have also had a request to convert the
Level from an enum back to an int.  I'd like more community input on that one.  It is likely
new Message types may be added but other than that I don't see the API changing much.
> 
> 2) My hope would be to see GA this summer, but again, it is up to the community.
> 
> 3) Each Log4j 2 component is a maven sub-project. The javadoc for each is there.  For
example, under "Components" click on API. Then under "Project Documentation" click on "Project
Reports" and then Javadocs.  The pattern is the same for each component.
> 
> 4a) I would actually recommend SLF4J over Commons Logging if the application is looking
for an independent logging API.  
>  b) Again, many applications want an independent API. That is why they choose Commons
Logging or SLF4J.  As you noted, Log4j 2's API is not intended as a replacement for SLF4J
but as a way for Log4j 2 users to know what is the public stuff they can safely code to and
what is part of the implementation and thus, more likely to change.
> c) The commons logging bridge provides the binding between Commons Logging and Log4j
2.  
> 
> Ralph
> 
> 
> On Mar 24, 2013, at 1:08 AM, Nick Williams wrote:
> 
>> I've been a Log4j 1 user for years and I love it. I'm currently writing a book for
Java EE 7 + Spring Framework 4 development and one of my chapters is on application logging.
I was going to cover Log4j 1 and then I stumbled upon Log4j 2. It looks like a serious improvement
over Log4j 1 and I'm quite excited about it. There are three important things that I couldn't
find on the site (I read the entire manual, and looked at what I thought were all of the pages,
but it's possible I've missing something). I'm hoping someone here can sort it out for me:
>> 
>> 1) How stable is the API at this point? I understand the hazards of beta software,
but are we talking "it could be drastically different in six months" or "chances are it won't
change much from here on out?" I don't expect a precise answer, just some guidance.
>> 
>> 2) What is the /projected/ GA date? I know that dates are never certain with open
source software, and I don't expect somebody to tell me that it'll be GA on July 21, 2013.
But are we talking weeks, months, or upwards of a year? If my book goes to press in November
of this year, do I risk that Log4j 2 isn't out by that time if I include it?
>> 
>> 3) Where is the darned JavaDoc API documentation? I'm quite used to how easy it is
to find in the Commons, on the Tomcat site, and on the Log4j 1 site (there's a big link that
says "JavaDoc" in the sidebar). But I was rather flabbergasted by the fact that I couldn't
find any on the Log4j 2 site. Specifically, I'm looking for the JavaDoc pages for the API,
the Implementation, and the Commons Logging Bridge.
>> 
>> Also, I have a general question about the API versus Commons Logging. For years my
understanding, reading, and training have told me to use Commons Logging so that the underlying
implementation could be easily switched out if needed (even though I have never strayed from
Log4j). However, with Log4j 2 it looks like the API being separated from the Implementation
makes this an unnecessary step, and could cause performance to suffer. So, I wonder:
>> 
>> A) How important is using Commons Logging as a facade in front of Log4j anymore?
It sounds like it matters less now, and could cause performance to suffer.
>> 
>> B) Should libraries still use Commons Logging, but applications start using the Log4j
2 API instead?
>> 
>> C) Will my existing libraries using Commons Logging 1.1 play nicely with Log4j 2?
Or will they struggle to find a facility to log with? Do I need the Commons Logging Bridge
to make these existing libraries log properly (that's what it sounds like, but I want to make
sure)?
>> 
>> Thanks in advance for any answers I receive!
>> 
>> Nick
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: log4j-user-unsubscribe@logging.apache.org
>> For additional commands, e-mail: log4j-user-help@logging.apache.org
>> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: log4j-user-unsubscribe@logging.apache.org
> For additional commands, e-mail: log4j-user-help@logging.apache.org
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-user-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-user-help@logging.apache.org


Mime
View raw message