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 }