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