View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements. See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache license, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License. You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the license for the specific language governing permissions and
15   * limitations under the license.
16   */
17  package org.apache.logging.log4j.message;
18  
19  import org.apache.logging.log4j.util.PerformanceSensitive;
20  import org.apache.logging.log4j.util.StringBuilderFormattable;
21  
22  /**
23   * Messages implementing this interface are reused between logging calls.
24   * <p>
25   * If a Message is reusable, downstream components should not hand over this instance to another thread, but extract its
26   * content (via the {@link StringBuilderFormattable#formatTo(StringBuilder)} method) instead.
27   * </p>
28   * @see ReusableMessageFactory
29   * @since 2.6
30   */
31  @PerformanceSensitive("allocation")
32  public interface ReusableMessage extends Message, StringBuilderFormattable {
33  
34      /**
35       * Returns the parameter array that was used to initialize this reusable message and replaces it with the specified
36       * array. The returned parameter array will no longer be modified by this reusable message. The specified array is
37       * now "owned" by this reusable message and can be modified if necessary for the next log event.
38       * </p><p>
39       * ReusableMessages that have no parameters return the specified array.
40       * </p><p>
41       * This method is used by asynchronous loggers to pass the parameter array to a background thread without
42       * allocating new objects.
43       * The actual number of parameters in the returned array can be determined with {@link #getParameterCount()}.
44       * </p>
45       *
46       * @param emptyReplacement the parameter array that can be used for subsequent uses of this reusable message.
47       *         This replacement array must have at least 10 elements (the number of varargs supported by the Logger
48       *         API).
49       * @return the parameter array for the current message content. This may be a vararg array of any length, or it may
50       *         be a reusable array of 10 elements used to hold the unrolled vararg parameters.
51       * @see #getParameterCount()
52       */
53      Object[] swapParameters(Object[] emptyReplacement);
54  
55      /**
56       * Returns the number of parameters that was used to initialize this reusable message for the current content.
57       * <p>
58       * The parameter array returned by {@link #swapParameters(Object[])} may be larger than the actual number of
59       * parameters. Callers should use this method to determine how many elements the array contains.
60       * </p>
61       * @return the current number of parameters
62       */
63      short getParameterCount();
64  
65      /**
66       * Returns an immutable snapshot of the current internal state of this reusable message. The returned snapshot
67       * will not be affected by subsequent modifications of this reusable message.
68       *
69       * @return an immutable snapshot of this message
70       */
71      Message memento();
72  }