Message location release 2.x

README.md

@@ -93,7 +93,23 @@ JIRA issue in the Pull Request.
 
 ## Building From Source
 
-Log4j requires Apache Maven 3.x. To build from source and install to your local Maven repository, execute the following:
+Log4j requires Apache Maven 3.x. Java 9 needs to be installed and present in your `~/.m2/toolchains.xml`. See the following for an example.
+
+ ```$xml
+<toolchains>
+	<toolchain>
+    <type>jdk</type>
+    <provides>
+      <version>9</version>
+    </provides>
+    <configuration>
+      <jdkHome>C:\Program Files\Java\jdk-9.0.1</jdkHome>
+    </configuration>
+	</toolchain>
+</toolchains>
+```
+
+ To build from source and install to your local Maven repository, execute the following:
 
 ```sh
 mvn install

log4j-api/src/main/java/org/apache/logging/log4j/Logger.java

@@ -16,10 +16,7 @@
  */
 package org.apache.logging.log4j;
 
-import org.apache.logging.log4j.message.EntryMessage;
-import org.apache.logging.log4j.message.Message;
-import org.apache.logging.log4j.message.MessageFactory;
-import org.apache.logging.log4j.message.MessageFactory2;
+import org.apache.logging.log4j.message.*;
 import org.apache.logging.log4j.util.MessageSupplier;
 import org.apache.logging.log4j.util.Supplier;
 
@@ -84,6 +81,15 @@ public interface Logger {
      */
     void catching(Level level, Throwable t);
 
+    /**
+     * Logs an exception or error that has been caught to a specific logging level, when the location
+     * of the log statement might be known at compile time.
+     *
+     * @param level The logging Level.
+     * @param t The Throwable.
+     */
+    void catching(StackTraceElement source, Level level, Throwable t);
+
     /**
      * Logs an exception or error that has been caught. Normally, one may wish to provide additional information with an
      * exception while logging it; in these cases, one would not use this method. In other cases where simply logging
@@ -94,6 +100,17 @@ public interface Logger {
      */
     void catching(Throwable t);
 
+    /**
+     * Logs an exception or error that has been caught, when the location of the log statement might be known at
+     * compile time.. Normally, one may wish to provide additional information with an exception while logging it; in
+     * these cases, one would not use this method. In other cases where simply logging the fact that an exception was
+     * swallowed somewhere (e.g., at the top of the stack trace in a {@code main()} method), this method is ideal for
+     * it.
+     *
+     * @param t The Throwable.
+     */
+    void catching(StackTraceElement source, Throwable t);
+
     /**
      * Logs a message with the specific Marker at the {@link Level#DEBUG DEBUG} level.
      *
@@ -2995,6 +3012,21 @@ void log(Level level, String message, Object p0, Object p1, Object p2, Object p3
      */
     <T extends Throwable> T throwing(Level level, T t);
 
+    /**
+     * Logs an exception or error to be thrown, when the location
+     * of the log statement might be known at compile time. This may be coded as:
+     *
+     * <pre>
+     * throw logger.throwing(source, Level.DEBUG, myException);
+     * </pre>
+     *
+     * @param <T> the Throwable type.
+     * @param level The logging Level.
+     * @param t The Throwable.
+     * @return the Throwable.
+     */
+    <T extends Throwable> T throwing(StackTraceElement source, Level level, T t);
+
     /**
      * Logs an exception or error to be thrown. This may be coded as:
      *
@@ -3008,6 +3040,20 @@ void log(Level level, String message, Object p0, Object p1, Object p2, Object p3
      */
     <T extends Throwable> T throwing(T t);
 
+    /**
+     * Logs an exception or error to be thrown, when the location
+     * of the log statement might be known at compile time. This may be coded as:
+     *
+     * <pre>
+     * throw logger.throwing(source, myException);
+     * </pre>
+     *
+     * @param <T> the Throwable type.
+     * @param t The Throwable.
+     * @return the Throwable.
+     */
+    <T extends Throwable> T throwing(StackTraceElement source, T t);
+
     /**
      * Logs a message with the specific Marker at the {@link Level#TRACE TRACE} level.
      *
@@ -3549,6 +3595,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     EntryMessage traceEntry();
 
+    EntryMessage traceEntry(StackTraceElement source);
+
     /**
      * Logs entry to a method along with its parameters. For example,
      *
@@ -3575,6 +3623,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     EntryMessage traceEntry(String format, Object... params);
 
+    EntryMessage traceEntry(StackTraceElement source, String format, Object... params);
+
     /**
      * Logs entry to a method along with its parameters. For example,
      *
@@ -3592,6 +3642,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     EntryMessage traceEntry(Supplier<?>... paramSuppliers);
 
+    EntryMessage traceEntry(StackTraceElement source, Supplier<?>... paramSuppliers);
+
     /**
      * Logs entry to a method along with its parameters. For example,
      *
@@ -3610,6 +3662,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     EntryMessage traceEntry(String format, Supplier<?>... paramSuppliers);
 
+    EntryMessage traceEntry(StackTraceElement source, String format, Supplier<?>... paramSuppliers);
+
     /**
      * Logs entry to a method using a Message to describe the parameters.
      * <pre>
@@ -3633,13 +3687,22 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     EntryMessage traceEntry(Message message);
 
+    EntryMessage traceEntry(StackTraceElement source, Message message);
+
     /**
      * Logs exit from a method. Used for methods that do not return anything.
      *
      * @since 2.6
      */
     void traceExit();
 
+    /**
+     * Logs exit from a method. Used for methods that do not return anything.
+     *
+     * @since
+     */
+    void traceExit(StackTraceElement source);
+
     /**
      * Logs exiting from a method with the result. This may be coded as:
      *
@@ -3655,6 +3718,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     <R> R traceExit(R result);
 
+    <R> R traceExit(StackTraceElement source, R result);
+
     /**
      * Logs exiting from a method with the result. This may be coded as:
      *
@@ -3671,6 +3736,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     <R> R traceExit(String format, R result);
 
+    <R> R traceExit(StackTraceElement source, String format, R result);
+
     /**
      * Logs exiting from a method with no result. Allows custom formatting of the result. This may be coded as:
      *
@@ -3687,6 +3754,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     void traceExit(EntryMessage message);
 
+    void traceExit(StackTraceElement source, EntryMessage message);
+
     /**
      * Logs exiting from a method with the result. Allows custom formatting of the result. This may be coded as:
      *
@@ -3707,6 +3776,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     <R> R traceExit(EntryMessage message, R result);
 
+    <R> R traceExit(StackTraceElement source, EntryMessage message, R result);
+
     /**
      * Logs exiting from a method with the result. Allows custom formatting of the result. This may be coded as:
      *
@@ -3723,6 +3794,8 @@ void trace(String message, Object p0, Object p1, Object p2, Object p3, Object p4
      */
     <R> R traceExit(Message message, R result);
 
+    <R> R traceExit(StackTraceElement source, Message message, R result);
+
     /**
      * Logs a message with the specific Marker at the {@link Level#WARN WARN} level.
      *