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