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: [email protected]
>> For additional commands, e-mail: [email protected]
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [email protected]
> For additional commands, e-mail: [email protected]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
