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.opends.server.admin.std.client;
017
018
019
020import java.util.Collection;
021import org.opends.server.admin.client.AuthorizationException;
022import org.opends.server.admin.client.CommunicationException;
023import org.opends.server.admin.client.ConcurrentModificationException;
024import org.opends.server.admin.client.IllegalManagedObjectNameException;
025import org.opends.server.admin.client.ManagedObjectDecodingException;
026import org.opends.server.admin.client.OperationRejectedException;
027import org.opends.server.admin.DefinitionDecodingException;
028import org.opends.server.admin.ManagedObjectDefinition;
029import org.opends.server.admin.ManagedObjectNotFoundException;
030import org.opends.server.admin.PropertyException;
031import org.opends.server.admin.std.server.DebugLogPublisherCfg;
032import org.opends.server.admin.std.server.DebugTargetCfg;
033
034
035
036/**
037 * A client-side interface for reading and modifying Debug Log
038 * Publisher settings.
039 * <p>
040 * Debug Log Publishers are responsible for distributing debug log
041 * messages from the debug logger to a destination.
042 */
043public interface DebugLogPublisherCfgClient extends LogPublisherCfgClient {
044
045  /**
046   * Get the configuration definition associated with this Debug Log Publisher.
047   *
048   * @return Returns the configuration definition associated with this Debug Log Publisher.
049   */
050  ManagedObjectDefinition<? extends DebugLogPublisherCfgClient, ? extends DebugLogPublisherCfg> definition();
051
052
053
054  /**
055   * Gets the "default-debug-exceptions-only" property.
056   * <p>
057   * Indicates whether only logs with exception should be logged.
058   *
059   * @return Returns the value of the "default-debug-exceptions-only" property.
060   */
061  boolean isDefaultDebugExceptionsOnly();
062
063
064
065  /**
066   * Sets the "default-debug-exceptions-only" property.
067   * <p>
068   * Indicates whether only logs with exception should be logged.
069   *
070   * @param value The value of the "default-debug-exceptions-only" property.
071   * @throws PropertyException
072   *           If the new value is invalid.
073   */
074  void setDefaultDebugExceptionsOnly(Boolean value) throws PropertyException;
075
076
077
078  /**
079   * Gets the "default-include-throwable-cause" property.
080   * <p>
081   * Indicates whether to include the cause of exceptions in exception
082   * thrown and caught messages logged by default.
083   *
084   * @return Returns the value of the "default-include-throwable-cause" property.
085   */
086  boolean isDefaultIncludeThrowableCause();
087
088
089
090  /**
091   * Sets the "default-include-throwable-cause" property.
092   * <p>
093   * Indicates whether to include the cause of exceptions in exception
094   * thrown and caught messages logged by default.
095   *
096   * @param value The value of the "default-include-throwable-cause" property.
097   * @throws PropertyException
098   *           If the new value is invalid.
099   */
100  void setDefaultIncludeThrowableCause(Boolean value) throws PropertyException;
101
102
103
104  /**
105   * Gets the "default-omit-method-entry-arguments" property.
106   * <p>
107   * Indicates whether to include method arguments in debug messages
108   * logged by default.
109   *
110   * @return Returns the value of the "default-omit-method-entry-arguments" property.
111   */
112  boolean isDefaultOmitMethodEntryArguments();
113
114
115
116  /**
117   * Sets the "default-omit-method-entry-arguments" property.
118   * <p>
119   * Indicates whether to include method arguments in debug messages
120   * logged by default.
121   *
122   * @param value The value of the "default-omit-method-entry-arguments" property.
123   * @throws PropertyException
124   *           If the new value is invalid.
125   */
126  void setDefaultOmitMethodEntryArguments(Boolean value) throws PropertyException;
127
128
129
130  /**
131   * Gets the "default-omit-method-return-value" property.
132   * <p>
133   * Indicates whether to include the return value in debug messages
134   * logged by default.
135   *
136   * @return Returns the value of the "default-omit-method-return-value" property.
137   */
138  boolean isDefaultOmitMethodReturnValue();
139
140
141
142  /**
143   * Sets the "default-omit-method-return-value" property.
144   * <p>
145   * Indicates whether to include the return value in debug messages
146   * logged by default.
147   *
148   * @param value The value of the "default-omit-method-return-value" property.
149   * @throws PropertyException
150   *           If the new value is invalid.
151   */
152  void setDefaultOmitMethodReturnValue(Boolean value) throws PropertyException;
153
154
155
156  /**
157   * Gets the "default-throwable-stack-frames" property.
158   * <p>
159   * Indicates the number of stack frames to include in the stack
160   * trace for method entry and exception thrown messages.
161   *
162   * @return Returns the value of the "default-throwable-stack-frames" property.
163   */
164  int getDefaultThrowableStackFrames();
165
166
167
168  /**
169   * Sets the "default-throwable-stack-frames" property.
170   * <p>
171   * Indicates the number of stack frames to include in the stack
172   * trace for method entry and exception thrown messages.
173   *
174   * @param value The value of the "default-throwable-stack-frames" property.
175   * @throws PropertyException
176   *           If the new value is invalid.
177   */
178  void setDefaultThrowableStackFrames(Integer value) throws PropertyException;
179
180
181
182  /**
183   * Gets the "java-class" property.
184   * <p>
185   * The fully-qualified name of the Java class that provides the
186   * Debug Log Publisher implementation.
187   *
188   * @return Returns the value of the "java-class" property.
189   */
190  String getJavaClass();
191
192
193
194  /**
195   * Sets the "java-class" property.
196   * <p>
197   * The fully-qualified name of the Java class that provides the
198   * Debug Log Publisher implementation.
199   *
200   * @param value The value of the "java-class" property.
201   * @throws PropertyException
202   *           If the new value is invalid.
203   */
204  void setJavaClass(String value) throws PropertyException;
205
206
207
208  /**
209   * Lists the Debug Targets.
210   *
211   * @return Returns an array containing the names of the Debug
212   *         Targets.
213   * @throws ConcurrentModificationException
214   *           If this Debug Log Publisher has been removed from the
215   *           server by another client.
216   * @throws AuthorizationException
217   *           If the server refuses to list the Debug Targets because
218   *           the client does not have the correct privileges.
219   * @throws CommunicationException
220   *           If the client cannot contact the server due to an
221   *           underlying communication problem.
222   */
223  String[] listDebugTargets() throws ConcurrentModificationException,
224      AuthorizationException, CommunicationException;
225
226
227
228  /**
229   * Gets the named Debug Target.
230   *
231   * @param name
232   *           The name of the Debug Target to retrieve.
233   * @return Returns the named Debug Target.
234   * @throws DefinitionDecodingException
235   *           If the named Debug Target was found but its type could
236   *           not be determined.
237   * @throws ManagedObjectDecodingException
238   *           If the named Debug Target was found but one or more of
239   *           its properties could not be decoded.
240   * @throws ManagedObjectNotFoundException
241   *           If the named Debug Target was not found on the server.
242   * @throws ConcurrentModificationException
243   *           If this Debug Log Publisher has been removed from the
244   *           server by another client.
245   * @throws AuthorizationException
246   *           If the server refuses to retrieve the named Debug
247   *           Target because the client does not have the correct
248   *           privileges.
249   * @throws CommunicationException
250   *           If the client cannot contact the server due to an
251   *           underlying communication problem.
252   */
253  DebugTargetCfgClient getDebugTarget(String name)
254      throws DefinitionDecodingException, ManagedObjectDecodingException,
255      ManagedObjectNotFoundException, ConcurrentModificationException,
256      AuthorizationException, CommunicationException;
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 AuthorizationException
302   *           If the server refuses to remove the Debug Target
303   *           because the client does not have the correct privileges.
304   * @throws CommunicationException
305   *           If the client cannot contact the server due to an
306   *           underlying communication problem.
307   */
308  void removeDebugTarget(String name)
309      throws ManagedObjectNotFoundException, OperationRejectedException,
310      ConcurrentModificationException, AuthorizationException,
311      CommunicationException;
312
313}