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