001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.admin.std.client; 028 029 030 031 import java.util.Collection; 032 import java.util.SortedSet; 033 import org.opends.server.admin.client.AuthorizationException; 034 import org.opends.server.admin.client.CommunicationException; 035 import org.opends.server.admin.client.ConcurrentModificationException; 036 import org.opends.server.admin.client.IllegalManagedObjectNameException; 037 import org.opends.server.admin.client.ManagedObjectDecodingException; 038 import org.opends.server.admin.client.OperationRejectedException; 039 import org.opends.server.admin.DefaultBehaviorException; 040 import org.opends.server.admin.DefinitionDecodingException; 041 import org.opends.server.admin.IllegalPropertyValueException; 042 import org.opends.server.admin.ManagedObjectDefinition; 043 import org.opends.server.admin.ManagedObjectNotFoundException; 044 import org.opends.server.admin.std.meta.DebugLogPublisherCfgDefn.DefaultDebugCategory; 045 import org.opends.server.admin.std.meta.DebugLogPublisherCfgDefn.DefaultDebugLevel; 046 import org.opends.server.admin.std.server.DebugLogPublisherCfg; 047 import org.opends.server.admin.std.server.DebugTargetCfg; 048 049 050 051 /** 052 * A client-side interface for reading and modifying Debug Log 053 * Publisher settings. 054 * <p> 055 * Debug Log Publishers are responsible for distributing debug log 056 * messages from the debug logger to a destination. 057 */ 058 public interface DebugLogPublisherCfgClient extends LogPublisherCfgClient { 059 060 /** 061 * Get the configuration definition associated with this Debug Log Publisher. 062 * 063 * @return Returns the configuration definition associated with this Debug Log Publisher. 064 */ 065 ManagedObjectDefinition<? extends DebugLogPublisherCfgClient, ? extends DebugLogPublisherCfg> definition(); 066 067 068 069 /** 070 * Gets the "default-debug-category" property. 071 * <p> 072 * The debug message categories to be logged when none of the 073 * defined targets match the message. 074 * 075 * @return Returns the values of the "default-debug-category" property. 076 */ 077 SortedSet<DefaultDebugCategory> getDefaultDebugCategory(); 078 079 080 081 /** 082 * Sets the "default-debug-category" property. 083 * <p> 084 * The debug message categories to be logged when none of the 085 * defined targets match the message. 086 * 087 * @param values The values of the "default-debug-category" property. 088 * @throws IllegalPropertyValueException 089 * If one or more of the new values are invalid. 090 */ 091 void setDefaultDebugCategory(Collection<DefaultDebugCategory> values) throws IllegalPropertyValueException; 092 093 094 095 /** 096 * Gets the "default-debug-level" property. 097 * <p> 098 * The lowest severity level of debug messages to log when none of 099 * the defined targets match the message. 100 * 101 * @return Returns the value of the "default-debug-level" property. 102 */ 103 DefaultDebugLevel getDefaultDebugLevel(); 104 105 106 107 /** 108 * Sets the "default-debug-level" property. 109 * <p> 110 * The lowest severity level of debug messages to log when none of 111 * the defined targets match the message. 112 * 113 * @param value The value of the "default-debug-level" property. 114 * @throws IllegalPropertyValueException 115 * If the new value is invalid. 116 */ 117 void setDefaultDebugLevel(DefaultDebugLevel value) throws IllegalPropertyValueException; 118 119 120 121 /** 122 * Gets the "default-include-throwable-cause" property. 123 * <p> 124 * Indicates whether to include the cause of exceptions in exception 125 * thrown and caught messages logged by default. 126 * 127 * @return Returns the value of the "default-include-throwable-cause" property. 128 */ 129 boolean isDefaultIncludeThrowableCause(); 130 131 132 133 /** 134 * Sets the "default-include-throwable-cause" property. 135 * <p> 136 * Indicates whether to include the cause of exceptions in exception 137 * thrown and caught messages logged by default. 138 * 139 * @param value The value of the "default-include-throwable-cause" property. 140 * @throws IllegalPropertyValueException 141 * If the new value is invalid. 142 */ 143 void setDefaultIncludeThrowableCause(Boolean value) throws IllegalPropertyValueException; 144 145 146 147 /** 148 * Gets the "default-omit-method-entry-arguments" property. 149 * <p> 150 * Indicates whether to include method arguments in debug messages 151 * logged by default. 152 * 153 * @return Returns the value of the "default-omit-method-entry-arguments" property. 154 */ 155 boolean isDefaultOmitMethodEntryArguments(); 156 157 158 159 /** 160 * Sets the "default-omit-method-entry-arguments" property. 161 * <p> 162 * Indicates whether to include method arguments in debug messages 163 * logged by default. 164 * 165 * @param value The value of the "default-omit-method-entry-arguments" property. 166 * @throws IllegalPropertyValueException 167 * If the new value is invalid. 168 */ 169 void setDefaultOmitMethodEntryArguments(Boolean value) throws IllegalPropertyValueException; 170 171 172 173 /** 174 * Gets the "default-omit-method-return-value" property. 175 * <p> 176 * Indicates whether to include the return value in debug messages 177 * logged by default. 178 * 179 * @return Returns the value of the "default-omit-method-return-value" property. 180 */ 181 boolean isDefaultOmitMethodReturnValue(); 182 183 184 185 /** 186 * Sets the "default-omit-method-return-value" property. 187 * <p> 188 * Indicates whether to include the return value in debug messages 189 * logged by default. 190 * 191 * @param value The value of the "default-omit-method-return-value" property. 192 * @throws IllegalPropertyValueException 193 * If the new value is invalid. 194 */ 195 void setDefaultOmitMethodReturnValue(Boolean value) throws IllegalPropertyValueException; 196 197 198 199 /** 200 * Gets the "default-throwable-stack-frames" property. 201 * <p> 202 * Indicates the number of stack frames to include in the stack 203 * trace for method entry and exception thrown messages. 204 * 205 * @return Returns the value of the "default-throwable-stack-frames" property. 206 */ 207 int getDefaultThrowableStackFrames(); 208 209 210 211 /** 212 * Sets the "default-throwable-stack-frames" property. 213 * <p> 214 * Indicates the number of stack frames to include in the stack 215 * trace for method entry and exception thrown messages. 216 * 217 * @param value The value of the "default-throwable-stack-frames" property. 218 * @throws IllegalPropertyValueException 219 * If the new value is invalid. 220 */ 221 void setDefaultThrowableStackFrames(Integer value) throws IllegalPropertyValueException; 222 223 224 225 /** 226 * Gets the "java-class" property. 227 * <p> 228 * The fully-qualified name of the Java class that provides the 229 * Debug Log Publisher implementation. 230 * 231 * @return Returns the value of the "java-class" property. 232 */ 233 String getJavaClass(); 234 235 236 237 /** 238 * Sets the "java-class" property. 239 * <p> 240 * The fully-qualified name of the Java class that provides the 241 * Debug Log Publisher implementation. 242 * 243 * @param value The value of the "java-class" property. 244 * @throws IllegalPropertyValueException 245 * If the new value is invalid. 246 */ 247 void setJavaClass(String value) throws IllegalPropertyValueException; 248 249 250 251 /** 252 * Lists the Debug Targets. 253 * 254 * @return Returns an array containing the names of the Debug 255 * Targets. 256 * @throws ConcurrentModificationException 257 * If this Debug Log Publisher has been removed from the 258 * server by another client. 259 * @throws AuthorizationException 260 * If the server refuses to list the Debug Targets because 261 * the client does not have the correct privileges. 262 * @throws CommunicationException 263 * If the client cannot contact the server due to an 264 * underlying communication problem. 265 */ 266 String[] listDebugTargets() throws ConcurrentModificationException, 267 AuthorizationException, CommunicationException; 268 269 270 271 /** 272 * Gets the named Debug Target. 273 * 274 * @param name 275 * The name of the Debug Target to retrieve. 276 * @return Returns the named Debug Target. 277 * @throws DefinitionDecodingException 278 * If the named Debug Target was found but its type could 279 * not be determined. 280 * @throws ManagedObjectDecodingException 281 * If the named Debug Target was found but one or more of 282 * its properties could not be decoded. 283 * @throws ManagedObjectNotFoundException 284 * If the named Debug Target was not found on the server. 285 * @throws ConcurrentModificationException 286 * If this Debug Log Publisher has been removed from the 287 * server by another client. 288 * @throws AuthorizationException 289 * If the server refuses to retrieve the named Debug 290 * Target because the client does not have the correct 291 * privileges. 292 * @throws CommunicationException 293 * If the client cannot contact the server due to an 294 * underlying communication problem. 295 */ 296 DebugTargetCfgClient getDebugTarget(String name) 297 throws DefinitionDecodingException, ManagedObjectDecodingException, 298 ManagedObjectNotFoundException, ConcurrentModificationException, 299 AuthorizationException, CommunicationException; 300 301 302 303 /** 304 * Creates a new Debug Target. The new Debug Target will initially 305 * not contain any property values (including mandatory properties). 306 * Once the Debug Target has been configured it can be added to the 307 * server using the {@link #commit()} method. 308 * 309 * @param <C> 310 * The type of the Debug Target being created. 311 * @param d 312 * The definition of the Debug Target to be created. 313 * @param name 314 * The name of the new Debug Target. 315 * @param exceptions 316 * An optional collection in which to place any {@link 317 * DefaultBehaviorException}s that occurred whilst 318 * attempting to determine the default values of the Debug 319 * Target. This argument can be <code>null<code>. 320 * @return Returns a new Debug Target configuration instance. 321 * @throws IllegalManagedObjectNameException 322 * If the name of the new Debug Target is invalid. 323 */ 324 <C extends DebugTargetCfgClient> C createDebugTarget( 325 ManagedObjectDefinition<C, ? extends DebugTargetCfg> d, String name, Collection<DefaultBehaviorException> exceptions) throws IllegalManagedObjectNameException; 326 327 328 329 /** 330 * Removes the named Debug Target. 331 * 332 * @param name 333 * The name of the Debug Target to remove. 334 * @throws ManagedObjectNotFoundException 335 * If the Debug Target does not exist. 336 * @throws OperationRejectedException 337 * If the server refuses to remove the Debug Target due to 338 * some server-side constraint which cannot be satisfied 339 * (for example, if it is referenced by another managed 340 * object). 341 * @throws ConcurrentModificationException 342 * If this Debug Log Publisher has been removed from the 343 * server by another client. 344 * @throws AuthorizationException 345 * If the server refuses to remove the Debug Target 346 * because the client does not have the correct privileges. 347 * @throws CommunicationException 348 * If the client cannot contact the server due to an 349 * underlying communication problem. 350 */ 351 void removeDebugTarget(String name) 352 throws ManagedObjectNotFoundException, OperationRejectedException, 353 ConcurrentModificationException, AuthorizationException, 354 CommunicationException; 355 356 }