001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.rest.annotation; 014 015import java.util.logging.*; 016 017import org.apache.juneau.rest.*; 018 019/** 020 * Represents a single logging rule for how to handle logging of HTTP requests/responses. 021 * 022 * <ul class='seealso'> 023 * <li class='jf'>{@link RestContext#REST_callLoggerConfig} 024 * <li class='jf'>{@link RestMethodContext#RESTMETHOD_callLoggerConfig} 025 * </ul> 026 */ 027public @interface LoggingRule { 028 029 /** 030 * Defines the status codes that match this rule. 031 * 032 * <p> 033 * Possible values: 034 * <ul> 035 * <li>A single value (e.g. <js>"404"</js>). 036 * <li>A closed range of values (e.g. <js>"400-499"</js>). 037 * <li>An open range of values (e.g. <js>"400-"</js>, <js>"-299"</js>, <js>">=500"</js>). 038 * <li>The value <js>"*"</js> to match any code. This is the default value. 039 * </ul> 040 * 041 * <ul class='notes'> 042 * <li> 043 * Supports {@doc DefaultRestSvlVariables} 044 * (e.g. <js>"$L{my.localized.variable}"</js>). 045 * </ul> 046 * 047 * <ul class='seealso'> 048 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 049 * </ul> 050 */ 051 public String codes() default "*"; 052 053 /** 054 * Specifies whether only debug requests match against this rule. 055 * 056 * <p> 057 * Allows you to tailor logging on debug requests. 058 * 059 * <p> 060 * See the {@link Rest#debug() @Rest(debug)} annotation on details of how to enable debugging. 061 * 062 * <p> 063 * The possible values are (case-insensitive): 064 * <ul> 065 * <li><js>"true</js> - Match debug requests only. 066 * <li><js>"false"</js> - Match any requests. 067 * </ul> 068 * 069 * <ul class='notes'> 070 * <li> 071 * Supports {@doc DefaultRestSvlVariables} 072 * (e.g. <js>"$L{my.localized.variable}"</js>). 073 * </ul> 074 * 075 * <ul class='seealso'> 076 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 077 * </ul> 078 */ 079 public String debugOnly() default "false"; 080 081 /** 082 * Disables logging entirely for this rule. 083 * 084 * <p> 085 * The possible values are (case-insensitive): 086 * <ul> 087 * <li><js>"true</js> - Disable logging. 088 * <li><js>"false"</js> (default) - Don't disable logging. 089 * <li><js>"per-request"</js> - Disable logging if No-Trace is set on the request. 090 * </ul> 091 * 092 * <p> 093 * The No-Trace setting on a request can be set by adding <c class='snippet'>X-NoTrace: true</c> to the request header. 094 * It can also be set programmatically by calling either the {@link RestRequest#setNoTrace(Boolean)} or 095 * {@link RestResponse#setNoTrace(Boolean)} methods. 096 * 097 * <p> 098 * Setting this value to <js>"true"</js> is equivalent to setting the level to <js>"off"</js>. 099 * 100 * <ul class='notes'> 101 * <li> 102 * Supports {@doc DefaultRestSvlVariables} 103 * (e.g. <js>"$L{my.localized.variable}"</js>). 104 * </ul> 105 * 106 * <ul class='seealso'> 107 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 108 * </ul> 109 */ 110 public String disabled() default "false"; 111 112 /** 113 * Defines Java exceptions that match this rule. 114 * 115 * <p> 116 * Possible values: 117 * <ul> 118 * <li>A fully-qualified class name (e.g. <js>"java.lang.StringIndexOutOfBoundsException"</js>). 119 * <li>A simple class name (e.g. <js>"StringIndexOutOfBoundsException"</js>). 120 * <li>A pattern with metacharacters (e.g. <js>"String*Exception"</js>). 121 * <li>Multiple patterns separated by spaces or commas (e.g. <js>"String*Exception, IO*Exception"</js>). 122 * </ul> 123 * 124 * <ul class='notes'> 125 * <li> 126 * Supports {@doc DefaultRestSvlVariables} 127 * (e.g. <js>"$L{my.localized.variable}"</js>). 128 * </ul> 129 * 130 * <ul class='seealso'> 131 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 132 * </ul> 133 */ 134 public String exceptions() default ""; 135 136 /** 137 * Identifies the logging level at which to log REST calls. 138 * 139 * <p> 140 * See the {@link Level} class for possible values. 141 * 142 * <p> 143 * Values are case-insensitive. 144 * 145 * <p> 146 * If not specified, uses the value specified by the {@link Logging#level() @Logging(level)} annotation value. 147 * 148 * <p> 149 * {@link Level#OFF} can be used to turn off logging. 150 * 151 * <ul class='notes'> 152 * <li> 153 * Supports {@doc DefaultRestSvlVariables} 154 * (e.g. <js>"$L{my.localized.variable}"</js>). 155 * </ul> 156 * 157 * <ul class='seealso'> 158 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 159 * </ul> 160 */ 161 public String level() default ""; 162 163 /** 164 * Identifies the level of detail to log on HTTP requests. 165 * 166 * <p> 167 * The possible values are (case-insensitive): 168 * <ul> 169 * <li><js>"short</js> (default) - Just the HTTP method and URL. 170 * <li><js>"medium"</js> (default) - Also the URL parameters, body size, and request headers. 171 * <li><js>"long"</js> - Also the request body as UTF-8 and spaced-hex text (debug must be enabled). 172 * </ul> 173 * 174 * <ul class='notes'> 175 * <li> 176 * Supports {@doc DefaultRestSvlVariables} 177 * (e.g. <js>"$L{my.localized.variable}"</js>). 178 * </ul> 179 * 180 * <ul class='seealso'> 181 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 182 * </ul> 183 */ 184 public String req() default "short"; 185 186 /** 187 * Identifies the level of detail to log on HTTP responses. 188 * 189 * <p> 190 * The possible values are (case-insensitive): 191 * <ul> 192 * <li><js>"short</js> (default) - Just the response code. 193 * <li><js>"medium"</js> (default) - Also the body size, response headers, and execution time. 194 * <li><js>"long"</js> - Also the response body as UTF-8 and spaced-hex text (debug must be enabled). 195 * </ul> 196 * 197 * <ul class='notes'> 198 * <li> 199 * Supports {@doc DefaultRestSvlVariables} 200 * (e.g. <js>"$L{my.localized.variable}"</js>). 201 * </ul> 202 * 203 * <ul class='seealso'> 204 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 205 * </ul> 206 */ 207 public String res() default "short"; 208 209 /** 210 * Shortcut for specifying <js>"long"</js> for {@link #req() @LoggingRule(req)} and {@link #res() @LoggingRule(res)}. 211 * 212 * <ul class='notes'> 213 * <li> 214 * Supports {@doc DefaultRestSvlVariables} 215 * (e.g. <js>"$L{my.localized.variable}"</js>). 216 * </ul> 217 * 218 * <ul class='seealso'> 219 * <li class='link'>{@doc juneau-rest-server.LoggingAndDebugging} 220 * </ul> 221 */ 222 public String verbose() default "false"; 223}