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