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    }