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.IllegalPropertyValueException;
034    import org.opends.server.admin.ManagedObjectDefinition;
035    import org.opends.server.admin.std.meta.PluginCfgDefn.PluginType;
036    import org.opends.server.admin.std.meta.ProfilerPluginCfgDefn.ProfileAction;
037    import org.opends.server.admin.std.server.ProfilerPluginCfg;
038    
039    
040    
041    /**
042     * A client-side interface for reading and modifying Profiler Plugin
043     * settings.
044     * <p>
045     * The Profiler plug-in captures profiling information about
046     * operations performed inside the JVM while the Directory Server is
047     * running.
048     */
049    public interface ProfilerPluginCfgClient extends PluginCfgClient {
050    
051      /**
052       * Get the configuration definition associated with this Profiler Plugin.
053       *
054       * @return Returns the configuration definition associated with this Profiler Plugin.
055       */
056      ManagedObjectDefinition<? extends ProfilerPluginCfgClient, ? extends ProfilerPluginCfg> definition();
057    
058    
059    
060      /**
061       * Gets the "enable-profiling-on-startup" property.
062       * <p>
063       * Indicates whether the profiler plug-in is to start collecting
064       * data automatically when the Directory Server is started.
065       * <p>
066       * This property is read only when the server is started, and any
067       * changes take effect on the next restart. This property is
068       * typically set to "false" unless startup profiling is required,
069       * because otherwise the volume of data that can be collected can
070       * cause the server to run out of memory if it is not turned off in a
071       * timely manner.
072       *
073       * @return Returns the value of the "enable-profiling-on-startup" property.
074       */
075      Boolean isEnableProfilingOnStartup();
076    
077    
078    
079      /**
080       * Sets the "enable-profiling-on-startup" property.
081       * <p>
082       * Indicates whether the profiler plug-in is to start collecting
083       * data automatically when the Directory Server is started.
084       * <p>
085       * This property is read only when the server is started, and any
086       * changes take effect on the next restart. This property is
087       * typically set to "false" unless startup profiling is required,
088       * because otherwise the volume of data that can be collected can
089       * cause the server to run out of memory if it is not turned off in a
090       * timely manner.
091       *
092       * @param value The value of the "enable-profiling-on-startup" property.
093       * @throws IllegalPropertyValueException
094       *           If the new value is invalid.
095       */
096      void setEnableProfilingOnStartup(boolean value) throws IllegalPropertyValueException;
097    
098    
099    
100      /**
101       * Gets the "invoke-for-internal-operations" property.
102       * <p>
103       * Indicates whether the plug-in should be invoked for internal
104       * operations.
105       * <p>
106       * Any plug-in that can be invoked for internal operations must
107       * ensure that it does not create any new internal operatons that can
108       * cause the same plug-in to be re-invoked.
109       *
110       * @return Returns the value of the "invoke-for-internal-operations" property.
111       */
112      boolean isInvokeForInternalOperations();
113    
114    
115    
116      /**
117       * Sets the "invoke-for-internal-operations" property.
118       * <p>
119       * Indicates whether the plug-in should be invoked for internal
120       * operations.
121       * <p>
122       * Any plug-in that can be invoked for internal operations must
123       * ensure that it does not create any new internal operatons that can
124       * cause the same plug-in to be re-invoked.
125       *
126       * @param value The value of the "invoke-for-internal-operations" property.
127       * @throws IllegalPropertyValueException
128       *           If the new value is invalid.
129       */
130      void setInvokeForInternalOperations(Boolean value) throws IllegalPropertyValueException;
131    
132    
133    
134      /**
135       * Gets the "java-class" property.
136       * <p>
137       * Specifies the fully-qualified name of the Java class that
138       * provides the plug-in implementation.
139       *
140       * @return Returns the value of the "java-class" property.
141       */
142      String getJavaClass();
143    
144    
145    
146      /**
147       * Sets the "java-class" property.
148       * <p>
149       * Specifies the fully-qualified name of the Java class that
150       * provides the plug-in implementation.
151       *
152       * @param value The value of the "java-class" property.
153       * @throws IllegalPropertyValueException
154       *           If the new value is invalid.
155       */
156      void setJavaClass(String value) throws IllegalPropertyValueException;
157    
158    
159    
160      /**
161       * Gets the "plugin-type" property.
162       * <p>
163       * Specifies the set of plug-in types for the plug-in, which
164       * specifies the times at which the plug-in is invoked.
165       *
166       * @return Returns the values of the "plugin-type" property.
167       */
168      SortedSet<PluginType> getPluginType();
169    
170    
171    
172      /**
173       * Sets the "plugin-type" property.
174       * <p>
175       * Specifies the set of plug-in types for the plug-in, which
176       * specifies the times at which the plug-in is invoked.
177       *
178       * @param values The values of the "plugin-type" property.
179       * @throws IllegalPropertyValueException
180       *           If one or more of the new values are invalid.
181       */
182      void setPluginType(Collection<PluginType> values) throws IllegalPropertyValueException;
183    
184    
185    
186      /**
187       * Gets the "profile-action" property.
188       * <p>
189       * Specifies the action that should be taken by the profiler.
190       * <p>
191       * A value of "start" causes the profiler thread to start collecting
192       * data if it is not already active. A value of "stop" causes the
193       * profiler thread to stop collecting data and write it to disk, and
194       * a value of "cancel" causes the profiler thread to stop collecting
195       * data and discard anything that has been captured. These operations
196       * occur immediately.
197       *
198       * @return Returns the value of the "profile-action" property.
199       */
200      ProfileAction getProfileAction();
201    
202    
203    
204      /**
205       * Sets the "profile-action" property.
206       * <p>
207       * Specifies the action that should be taken by the profiler.
208       * <p>
209       * A value of "start" causes the profiler thread to start collecting
210       * data if it is not already active. A value of "stop" causes the
211       * profiler thread to stop collecting data and write it to disk, and
212       * a value of "cancel" causes the profiler thread to stop collecting
213       * data and discard anything that has been captured. These operations
214       * occur immediately.
215       *
216       * @param value The value of the "profile-action" property.
217       * @throws IllegalPropertyValueException
218       *           If the new value is invalid.
219       */
220      void setProfileAction(ProfileAction value) throws IllegalPropertyValueException;
221    
222    
223    
224      /**
225       * Gets the "profile-directory" property.
226       * <p>
227       * Specifies the path to the directory where profile information is
228       * to be written. This path may be either an absolute path or a path
229       * that is relative to the root of the OpenDS Directory Server
230       * instance.
231       * <p>
232       * The directory must exist and the Directory Server must have
233       * permission to create new files in it.
234       *
235       * @return Returns the value of the "profile-directory" property.
236       */
237      String getProfileDirectory();
238    
239    
240    
241      /**
242       * Sets the "profile-directory" property.
243       * <p>
244       * Specifies the path to the directory where profile information is
245       * to be written. This path may be either an absolute path or a path
246       * that is relative to the root of the OpenDS Directory Server
247       * instance.
248       * <p>
249       * The directory must exist and the Directory Server must have
250       * permission to create new files in it.
251       *
252       * @param value The value of the "profile-directory" property.
253       * @throws IllegalPropertyValueException
254       *           If the new value is invalid.
255       */
256      void setProfileDirectory(String value) throws IllegalPropertyValueException;
257    
258    
259    
260      /**
261       * Gets the "profile-sample-interval" property.
262       * <p>
263       * Specifies the sample interval in milliseconds to be used when
264       * capturing profiling information in the server.
265       * <p>
266       * When capturing data, the profiler thread sleeps for this length
267       * of time between calls to obtain traces for all threads running in
268       * the JVM.
269       *
270       * @return Returns the value of the "profile-sample-interval" property.
271       */
272      Long getProfileSampleInterval();
273    
274    
275    
276      /**
277       * Sets the "profile-sample-interval" property.
278       * <p>
279       * Specifies the sample interval in milliseconds to be used when
280       * capturing profiling information in the server.
281       * <p>
282       * When capturing data, the profiler thread sleeps for this length
283       * of time between calls to obtain traces for all threads running in
284       * the JVM.
285       *
286       * @param value The value of the "profile-sample-interval" property.
287       * @throws IllegalPropertyValueException
288       *           If the new value is invalid.
289       */
290      void setProfileSampleInterval(long value) throws IllegalPropertyValueException;
291    
292    }