// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
// * with the License.  You may obtain a copy of the License at                                                              *
// *                                                                                                                         *
// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
// *                                                                                                                         *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
// * specific language governing permissions and limitations under the License.                                              *
// ***************************************************************************************************************************
package org.apache.juneau.rest.annotation;

import java.util.logging.*;

import org.apache.juneau.rest.*;

/**
 * Represents a single logging rule for how to handle logging of HTTP requests/responses.
 *
 * <ul class='seealso'>
 *    <li class='jf'>{@link RestContext#REST_callLoggerConfig}
 *    <li class='jf'>{@link RestMethodContext#RESTMETHOD_callLoggerConfig}
 * </ul>
 */
public @interface LoggingRule {

   /**
    * Defines the status codes that match this rule.
    *
    * <p>
    * Possible values:
    * <ul>
    *    <li>A single value (e.g. <js>"404"</js>).
    *    <li>A closed range of values (e.g. <js>"400-499"</js>).
    *    <li>An open range of values (e.g. <js>"400-"</js>, <js>"-299"</js>, <js>">=500"</js>).
    *    <li>The value <js>"*"</js> to match any code.  This is the default value.
    * </ul>
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String codes() default "*";

   /**
    * Specifies whether only debug requests match against this rule.
    *
    * <p>
    * Allows you to tailor logging on debug requests.
    *
    * <p>
    * See the {@link Rest#debug() @Rest(debug)} annotation on details of how to enable debugging.
    *
    * <p>
    * The possible values are (case-insensitive):
    * <ul>
    *    <li><js>"true</js> - Match debug requests only.
    *    <li><js>"false"</js> - Match any requests.
    * </ul>
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String debugOnly() default "false";

   /**
    * Disables logging entirely for this rule.
    *
    * <p>
    * The possible values are (case-insensitive):
    * <ul>
    *    <li><js>"true</js> - Disable logging.
    *    <li><js>"false"</js> (default) - Don't disable logging.
    *    <li><js>"per-request"</js> - Disable logging if No-Trace is set on the request.
    * </ul>
    *
    * <p>
    * The No-Trace setting on a request can be set by adding <c class='snippet'>X-NoTrace: true</c> to the request header.
    * It can also be set programmatically by calling either the {@link RestRequest#setNoTrace(Boolean)} or
    * {@link RestResponse#setNoTrace(Boolean)} methods.
    *
    * <p>
    * Setting this value to <js>"true"</js> is equivalent to setting the level to <js>"off"</js>.
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String disabled() default "false";

   /**
    * Defines Java exceptions that match this rule.
    *
    * <p>
    * Possible values:
    * <ul>
    *    <li>A fully-qualified class name (e.g. <js>"java.lang.StringIndexOutOfBoundsException"</js>).
    *    <li>A simple class name (e.g. <js>"StringIndexOutOfBoundsException"</js>).
    *    <li>A pattern with metacharacters (e.g. <js>"String*Exception"</js>).
    *    <li>Multiple patterns separated by spaces or commas (e.g. <js>"String*Exception, IO*Exception"</js>).
    * </ul>
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String exceptions() default "";

   /**
    * Identifies the logging level at which to log REST calls.
    *
    * <p>
    * See the {@link Level} class for possible values.
    *
    * <p>
    * Values are case-insensitive.
    *
    * <p>
    * If not specified, uses the value specified by the {@link Logging#level() @Logging(level)} annotation value.
    *
    * <p>
    * {@link Level#OFF} can be used to turn off logging.
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String level() default "";

   /**
    * Identifies the level of detail to log on HTTP requests.
    *
    * <p>
    * The possible values are (case-insensitive):
    * <ul>
    *    <li><js>"short</js> (default) - Just the HTTP method and URL.
    *    <li><js>"medium"</js> (default) - Also the URL parameters, body size, and request headers.
    *    <li><js>"long"</js> - Also the request body as UTF-8 and spaced-hex text (debug must be enabled).
    * </ul>
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String req() default "short";

   /**
    * Identifies the level of detail to log on HTTP responses.
    *
    * <p>
    * The possible values are (case-insensitive):
    * <ul>
    *    <li><js>"short</js> (default) - Just the response code.
    *    <li><js>"medium"</js> (default) - Also the body size, response headers, and execution time.
    *    <li><js>"long"</js> - Also the response body as UTF-8 and spaced-hex text (debug must be enabled).
    * </ul>
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String res() default "short";

   /**
    * Shortcut for specifying <js>"long"</js> for {@link #req() @LoggingRule(req)} and {@link #res() @LoggingRule(res)}.
    *
    * <ul class='notes'>
    *    <li>
    *       Supports {@doc RestSvlVariables}
    *       (e.g. <js>"$L{my.localized.variable}"</js>).
    * </ul>
    *
    * <ul class='seealso'>
    *    <li class='link'>{@doc RestLoggingAndDebugging}
    * </ul>
    */
   public String verbose() default "false";
}