001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache license, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the license for the specific language governing permissions and
015 * limitations under the license.
016 */
017package org.apache.logging.log4j.core;
018
019import java.io.Serializable;
020import java.util.Map;
021
022import org.apache.logging.log4j.core.layout.ByteBufferDestination;
023import org.apache.logging.log4j.core.layout.Encoder;
024
025/**
026 * Lays out a {@linkplain LogEvent} in different formats.
027 *
028 * The formats are:
029 * <ul>
030 * <li>
031 * {@code byte[]}</li>
032 * <li>
033 * an implementer of {@linkplain Serializable}, like {@code byte[]}</li>
034 * <li>
035 * {@linkplain String}</li>
036 * <li>
037 * {@linkplain LogEvent}</li>
038 * </ul>
039 * <p>
040 * Since 2.6, Layouts can {@linkplain Encoder#encode(Object, ByteBufferDestination) encode} a {@code LogEvent} directly
041 * to a {@link ByteBufferDestination} without creating temporary intermediary objects.
042 * </p>
043 *
044 * @param <T>
045 *            The {@link Serializable} type returned by {@link #toSerializable(LogEvent)}
046 */
047public interface Layout<T extends Serializable> extends Encoder<LogEvent> {
048
049    /**
050     * Main {@linkplain org.apache.logging.log4j.core.config.plugins.Plugin#elementType() plugin element type} for
051     * Layout plugins.
052     *
053     * @since 2.1
054     */
055    String ELEMENT_TYPE = "layout";
056
057    /**
058     * Returns the format for the layout format.
059     * @return The footer.
060     */
061    byte[] getFooter();
062
063    /**
064     * Returns the header for the layout format.
065     * @return The header.
066     */
067    byte[] getHeader();
068
069    /**
070     * Formats the event suitable for display.
071     *
072     * @param event The Logging Event.
073     * @return The formatted event.
074     */
075    byte[] toByteArray(LogEvent event);
076
077    /**
078     * Formats the event as an Object that can be serialized.
079     *
080     * @param event The Logging Event.
081     * @return The formatted event.
082     */
083    T toSerializable(LogEvent event);
084
085    /**
086     * Returns the content type output by this layout. The base class returns "text/plain".
087     *
088     * @return the content type.
089     */
090    String getContentType();
091
092    /**
093     * Returns a description of the content format.
094     *
095     * @return a Map of key/value pairs describing the Layout-specific content format, or an empty Map if no content
096     * format descriptors are specified.
097     */
098    Map<String, String> getContentFormat();
099}