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