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 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
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 * docs/licenses/cddl.txt. 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 2010-2014 UnboundID Corp.
026 */
027 package com.unboundid.directory.sdk.common.types;
028
029
030
031 import java.io.File;
032 import java.util.List;
033 import java.util.Set;
034 import java.util.UUID;
035
036 import com.unboundid.directory.sdk.ds.api.ChangeListener;
037 import com.unboundid.directory.sdk.common.api.DiskSpaceConsumer;
038 import com.unboundid.directory.sdk.common.api.MonitorProvider;
039 import com.unboundid.directory.sdk.common.api.ServerShutdownListener;
040 import com.unboundid.directory.sdk.common.api.ServerThread;
041 import com.unboundid.directory.sdk.common.config.GenericConfig;
042 import com.unboundid.directory.sdk.common.schema.Schema;
043 import com.unboundid.directory.sdk.ds.types.RegisteredChangeListener;
044 import com.unboundid.ldap.sdk.ChangeType;
045 import com.unboundid.ldap.sdk.Filter;
046 import com.unboundid.ldap.sdk.LDAPException;
047 import com.unboundid.ldap.sdk.LDAPInterface;
048 import com.unboundid.util.NotExtensible;
049 import com.unboundid.util.ThreadSafety;
050 import com.unboundid.util.ThreadSafetyLevel;
051
052
053
054 /**
055 * This interface may be used to obtain information about the server in
056 * which an extension is running.
057 */
058 @NotExtensible()
059 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
060 public interface ServerContext
061 {
062 /**
063 * Retrieves the compact name of the server vendor. The returned name will
064 * not have any spaces.
065 *
066 * @return The compact name of the server vendor.
067 */
068 String getShortVendorName();
069
070
071
072 /**
073 * Retrieves the full name of the server vendor. The returned name may
074 * contain spaces.
075 *
076 * @return The full name of the server vendor.
077 */
078 String getFullVendorName();
079
080
081
082 /**
083 * Retrieves the compact name of the server. The returned name will not have
084 * any spaces.
085 *
086 * @return The compact name of the server.
087 */
088 String getCompactProductName();
089
090
091
092 /**
093 * Retrieves the package name of the server that is used for defining the
094 * server package ZIP file and root directory. The returned name will not
095 * have any spaces.
096 *
097 * @return The package name of the server.
098 */
099 String getPackageName();
100
101
102
103 /**
104 * Retrieves the full name of the server. The returned name may contain
105 * spaces.
106 *
107 * @return The full name of the server.
108 */
109 String getFullProductName();
110
111
112
113 /**
114 * Retrieves the base name of the server which is generally the full
115 * product name without the vendor information. The returned name may
116 * contain spaces.
117 *
118 * @return The full name of the server.
119 */
120 String getBasicProductName();
121
122
123
124 /**
125 * Retrieves the major version number for the server. The major version
126 * number is the first number which appears in the full version string (e.g.,
127 * for a version string of "1.2.3.4-beta5", the major version number is 1).
128 *
129 * @return The major version number for the server.
130 */
131 int getMajorVersionNumber();
132
133
134
135 /**
136 * Retrieves the minor version number for the server. The minor version
137 * number is the second number which appears in the full version string (e.g.,
138 * for a version string of "1.2.3.4-beta5", the minor version number is 2).
139 *
140 * @return The minor version number for the server.
141 */
142 int getMinorVersionNumber();
143
144
145
146 /**
147 * Retrieves the point version number for the server. The point version
148 * number is the third number which appears in the full version string (e.g.,
149 * for a version string of "1.2.3.4-beta5", the point version number is 3).
150 *
151 * @return The point version number for the server.
152 */
153 int getPointVersionNumber();
154
155
156
157 /**
158 * Retrieves the patch version number for the server. The patch version
159 * number is the fourth number which appears in the full version string (e.g.,
160 * for a version string of "1.2.3.4-beta5", the patch version number is 4).
161 *
162 * @return The point version number for the server.
163 */
164 int getPatchVersionNumber();
165
166
167
168 /**
169 * Retrieves a string that is the concatenation of the major, minor,
170 * point, and patch version numbers of the server.
171 *
172 * @return the server's version number string.
173 */
174 String getVersionNumber();
175
176
177
178 /**
179 * Retrieves a string that is the concatenation of the product name, the
180 * major, minor, point, and patch version numbers of the server and any
181 * any other unique version information.
182 *
183 * @return the server's full version number string.
184 */
185 String getFullVersion();
186
187
188
189 /**
190 * Retrieves the version qualifier string for the server. The version
191 * qualifier is an optional string which may provide additional information
192 * about the server version. If a version qualifier is present, then it will
193 * immediately follow the patch version number (e.g., for a version string of
194 * "1.2.3.4-beta5", the version qualifier is "-beta5").
195 *
196 * @return The version qualifier for the server, or an empty string if no
197 * version qualifier is defined.
198 */
199 String getVersionQualifier();
200
201
202
203 /**
204 * Retrieves a value which identifies the source revision (in the
205 * version control system used to hold the server source code) from which the
206 * server was built.
207 *
208 * @return The source revision identifier for the server.
209 */
210 String getSourceRevision();
211
212
213
214 /**
215 * Indicates whether the server is in the process of starting up.
216 *
217 * @return {@code true} if the server is in the process of starting up, or
218 * {@code false} if not.
219 */
220 boolean isStarting();
221
222
223
224 /**
225 * Indicates whether the server is currently running.
226 *
227 * @return {@code true} if the server is running, or {@code false} if not.
228 */
229 boolean isRunning();
230
231
232
233 /**
234 * Indicates whether the server is in the process of shutting down.
235 *
236 * @return {@code true} if the server is in the process of shutting down, or
237 * {@code false} if not.
238 */
239 boolean isShuttingDown();
240
241
242
243 /**
244 * Retrieves the time that the server was started. The value returned will
245 * be an offset in milliseconds since 12:00 a.m. on January 1, 1970.
246 *
247 * @return The time that the server was started.
248 */
249 long getStartTime();
250
251
252
253 /**
254 * Retrieves a compact ID that was generated at the time the server was
255 * started. It is not guaranteed to be unique among all instances of the
256 * server, but is guaranteed to be unique across all invocations of a single
257 * server installation. This is suitable for inclusion in log messages and
258 * can help differentiate operations with the same connection ID and operation
259 * ID across server restarts.
260 *
261 * @return A compact ID that was generated at the time the server was
262 * started.
263 */
264 String getStartupID();
265
266
267
268 /**
269 * Retrieves a unique identifier that was generated at the time the server was
270 * started. It will be unique across all server instances and all invocations
271 * of the same instance.
272 *
273 * @return A unique identifier that was generated at the time the server was
274 * started.
275 */
276 UUID getStartupUUID();
277
278
279
280 /**
281 * Retrieves the instance name that has been assigned to the server.
282 *
283 * @return The instance name that has been assigned to the server.
284 */
285 String getInstanceName();
286
287
288
289
290 /**
291 * Retrieves the path to the server root directory.
292 *
293 * @return The path to the server root directory.
294 */
295 File getServerRoot();
296
297
298
299 /**
300 * Retrieves a ToolExecutor that can be used to internally execute select
301 * command line utilities.
302 *
303 * @return A ToolExecutor that can be used to internally execute select
304 * command line utilities.
305 */
306 ToolExecutor getToolExecutor();
307
308
309
310 /**
311 * Indicates whether the extension is running in a server that has Directory
312 * Server functionality available.
313 *
314 * @return {@code true} if Directory Server functionality is available, or
315 * {@code false} if not.
316 */
317 boolean isDirectoryFunctionalityAvailable();
318
319
320
321 /**
322 * Indicates whether the extension is running in a server that has Directory
323 * Proxy Server functionality available.
324 *
325 * @return {@code true} if Directory Proxy Server functionality is available,
326 * or {@code false} if not.
327 */
328 boolean isDirectoryProxyFunctionalityAvailable();
329
330
331
332 /**
333 * Indicates whether the extension is running in a server that has
334 * Synchronization Server functionality available.
335 *
336 * @return {@code true} if Synchronization Server functionality is available,
337 * or {@code false} if not.
338 */
339 boolean isSyncFunctionalityAvailable();
340
341
342
343 /**
344 * Retrieves an internal connection that is authenticated as a root user
345 * that is not subject to access control.
346 * <BR><BR>
347 * During operation processing, this connection is considered a root
348 * connection that is both internal and secure.
349 * <BR><BR>
350 * Note that the returned connection will use the client connection policy
351 * defined as the default policy for internal operations. If you have access
352 * to a {@code ClientContext} and wish to use the client connection policy
353 * associated with that connection, use the
354 * {@link ClientContext#getInternalRootConnection(boolean)} method.
355 *
356 * @return An internal connection that is authenticated as a root user.
357 */
358 InternalConnection getInternalRootConnection();
359
360
361
362 /**
363 * Retrieves an internal connection that is authenticated as the specified
364 * user. Operations on the connection may be subject to access control based
365 * on the privileges associated with the specified user.
366 * <BR><BR>
367 * During operation processing, this connection is considered a user
368 * connection that is both internal and secure.
369 * <BR><BR>
370 * Note that the returned connection will use the client connection policy
371 * defined as the default policy for internal operations. If you have access
372 * to a {@code ClientContext} and wish to use the client connection policy
373 * associated with that connection, use the
374 * {@link ClientContext#getInternalConnection(String,boolean)} method.
375 *
376 * @param dn The DN of the user as whom the connection should be
377 * authenticated. It may be {@code null} or empty if the
378 * connection should be unauthenticated.
379 *
380 * @return An internal connection that is authenticated as the specified
381 * user.
382 *
383 * @throws LDAPException If a problem occurs while attempting to
384 * authenticate as the specified user.
385 */
386 InternalConnection getInternalConnection(final String dn)
387 throws LDAPException;
388
389
390
391 /**
392 * Retrieves a client connection that is authenticated as a root user
393 * and is not subject to access control.
394 * <BR><BR>
395 * This method should be used when the connection will be used on behalf of
396 * some external client, and allows you to indicate whether the external
397 * client has a secure connection. This information is used by some of the
398 * internal security controls, such as password policies, which may reject
399 * password change operations if they are not over a secure connection, for
400 * example.
401 * <BR><BR>
402 * During operation processing, this connection is considered a root
403 * connection that is external and optionally secure, depending on the
404 * {@code isClientSecure} parameter.
405 *
406 * @param isClientSecure Whether the external client is connected over a
407 * secure channel.
408 *
409 * @return A client connection that is authenticated as a root user.
410 */
411 LDAPInterface getClientRootConnection(final boolean isClientSecure);
412
413
414
415 /**
416 * Retrieves a client connection that is authenticated as the specified
417 * user. Operations on the connection may be subject to access control based
418 * on the privileges associated with the specified user.
419 * <BR><BR>
420 * This method should be used when the connection will be used on behalf of
421 * some external client, and allows you to indicate whether the external
422 * client has a secure connection. This information is used by some of the
423 * internal security controls, such as password policies, which may reject
424 * password change operations if they are not over a secure connection, for
425 * example.
426 * <BR><BR>
427 * During operation processing, this connection is considered a user
428 * connection that is external and optionally secure, depending on the
429 * {@code isClientSecure} parameter.
430 *
431 * @param dn The DN of the user as whom the connection should be
432 * authenticated. It may be {@code null} or empty if the
433 * connection should be unauthenticated.
434 *
435 * @param isClientSecure Whether the external client is connected over a
436 * secure channel.
437 *
438 * @return An internal connection that is authenticated as the specified
439 * user.
440 *
441 * @throws LDAPException If a problem occurs while attempting to
442 * authenticate as the specified user.
443 */
444 LDAPInterface getClientConnection(final String dn,
445 final boolean isClientSecure)
446 throws LDAPException;
447
448
449
450 /**
451 * Retrieves a reference to the server schema.
452 *
453 * @return A reference to the server schema.
454 */
455 Schema getSchema();
456
457
458
459 /**
460 * Registers the provided OID with the server so that it will appear in the
461 * supportedControl attribute of the server's root DSE. This method should
462 * only be used by extensions which implement some level of support for that
463 * control (e.g., a pre-parse plugin which performs all necessary processing
464 * from the control and removes it from the request so that it will not be
465 * seen and potentially rejected by the core server).
466 *
467 * @param oid The OID to be registered.
468 */
469 void registerSupportedControlOID(final String oid);
470
471
472
473 /**
474 * Deregisters the provided OID with the server so that it will no longer
475 * appear in the supportedControl attribute of the server's root DSE.
476 *
477 * @param oid The OID to be deregistered.
478 */
479 void deregisterSupportedControlOID(final String oid);
480
481
482
483 /**
484 * Registers the provided change listener with the server so that it may be
485 * notified of any changes matching the provided criteria.
486 *
487 * @param listener The change listener to be registered with the server.
488 * It must not be {@code null}.
489 * @param changeTypes The types of changes for which the listener should be
490 * registered. It may be {@code null} or empty to
491 * indicate that the listener should be registered for
492 * all types of changes.
493 * @param baseDNs The set of base DNs for which the listener should be
494 * registered. It may be {@code null} or empty to
495 * indicate that the listener should be registered for
496 * changes processed anywhere in the server.
497 * @param filter A filter which may be used to restrict the set of
498 * changes for which the listener is notified. If a
499 * filter is provided, then only changes in which the
500 * target entry matches the given filter (either before
501 * or after the change was processed) will be notified.
502 * It may be {@code null} to indicate that the contents
503 * of the entry should not be considered.
504 *
505 * @return An object representing the change listener that has been
506 * registered with the server.
507 *
508 * @throws LDAPException If a problem is encountered while attempting to
509 * register the provided change listener (e.g., if any
510 * of the base DNs cannot be parsed as a valid DN).
511 */
512 RegisteredChangeListener registerChangeListener(final ChangeListener listener,
513 final Set<ChangeType> changeTypes,
514 final List<String> baseDNs,
515 final Filter filter)
516 throws LDAPException;
517
518
519
520 /**
521 * Deregisters the provided change listener with the server. This will have
522 * no effect if the provided listener is not registered.
523 *
524 * @param listener The change listener to be deregistered. It must not be
525 * {@code null}.
526 */
527 void deregisterChangeListener(final RegisteredChangeListener listener);
528
529
530
531 /**
532 * Registers the provided disk space consumer with the server.
533 *
534 * @param consumer The disk space consumer to be registered with the server.
535 * It must not be {@code null}.
536 *
537 * @return An object representing the disk space consumer that has been
538 * registered with the server.
539 */
540 RegisteredDiskSpaceConsumer registerDiskSpaceConsumer(
541 final DiskSpaceConsumer consumer);
542
543
544
545 /**
546 * Deregisters the provided disk space consumer with the server. This will no
547 * no effect if the provided consumer is not registered.
548 *
549 * @param consumer The disk space consumer to be deregistered with the
550 * server. It must not be {@code null}.
551 */
552 void deregisterDiskSpaceConsumer(final RegisteredDiskSpaceConsumer consumer);
553
554
555
556 /**
557 * Registers the provided listener to be notified when the server shutdown
558 * process has begun.
559 *
560 * @param listener The server shutdown listener to be registered. It must
561 * not be {@code null}.
562 *
563 * @return An object representing the shutdown listener that has been
564 * registered with the server.
565 */
566 RegisteredServerShutdownListener registerShutdownListener(
567 final ServerShutdownListener listener);
568
569
570
571 /**
572 * Deregisters the provided server shutdown listener with the server. This
573 * will have no effect if the provided listener is not registered.
574 *
575 * @param listener The server shutdown listener to be deregistered. It must
576 * not be {@code null}.
577 */
578 void deregisterShutdownListener(
579 final RegisteredServerShutdownListener listener);
580
581
582
583 /**
584 * Registers the given monitor provider with the server. It is important that
585 * this monitor provider has a unique instance name across all monitor
586 * providers in the server. If there is already a monitor provider registered
587 * with the same instance name, an {@link IllegalStateException} will be
588 * thrown.
589 * <p>
590 * The generated monitor entry will have a DN in the following format:
591 * <code>cn={monitor-instance-name} [from {extension-type}:{extension-name}],
592 * cn=monitor</code> and it will contain three auto-generated attributes:
593 * <code>ds-extension-monitor-name</code>, <code>ds-extension-type</code>, and
594 * <code>ds-extension-name</code>. Note: the {extension-type} and
595 * {extension-name} are from the extension which owns this ServerContext
596 * instance, not from the given MonitorProvider object.
597 * <p>
598 * The specified monitor provider does not need any server-side configuration,
599 * and the configuration-related methods
600 * (<code>initalizeMonitorProvider()</code>,
601 * <code>finalizeMonitorProvider()</code>,
602 * <code>defineConfigArguments()</code>,
603 * <code>isConfigurationAcceptable()</code>,
604 * <code>applyConfiguration()</code>) do not need to be implemented because
605 * they will not be called.
606 * <p>
607 * When an extension is disabled, all of its registered monitor
608 * providers will automatically deregister themselves from the server.
609 * You can also manually deregister them using
610 * {@link #deregisterMonitorProvider(RegisteredMonitorProvider)} or
611 * {@link #deregisterAllMonitorProviders()}.
612 *
613 * @param provider The monitor provider instance to be registered. It
614 * must not be {@code null}.
615 * @param config The configuration object from the extension that is
616 * registering the given monitor provider. This is required so
617 * that the monitor entry can be given a unique DN which
618 * includes the name of the extension that registered it.
619 *
620 * @return An object representing the monitor provider that has been
621 * registered with the server.
622 */
623 RegisteredMonitorProvider registerMonitorProvider(
624 final MonitorProvider provider,
625 final GenericConfig config);
626
627
628
629 /**
630 * Deregisters the given monitor provider with the server. This will have no
631 * effect if the given monitor provider is not registered.
632 *
633 * @param provider The monitor provider instance to be registered. It
634 * must not be {@code null}.
635 */
636 void deregisterMonitorProvider(final RegisteredMonitorProvider provider);
637
638
639
640 /**
641 * Deregisters all the monitor providers that were registered with the server
642 * by this instance of {@link ServerContext}. This can be useful during
643 * cleanup or if you want to clear out all the existing monitor data from a
644 * given extension and register new monitor providers.
645 * <p>
646 * This will be called automatically when your extension is unloaded or
647 * disabled.
648 */
649 void deregisterAllMonitorProviders();
650
651
652
653 /**
654 * Creates a new thread to run within the server. The thread will not be
655 * started.
656 *
657 * @param name The name to use for the thread. It must not be
658 * {@code null} or empty.
659 * @param serverThread The class providing the logic for the thread. It
660 * must not be {@code null}.
661 *
662 * @return The thread that has been created but not yet started.
663 */
664 Thread createThread(final ServerThread serverThread, final String name);
665
666
667
668 /**
669 * Writes a message to the server error log.
670 *
671 * @param severity The severity to use for the log message. It must not be
672 * {@code null}.
673 * @param message The message to be logged. It must not be {@code null}.
674 */
675 void logMessage(final LogSeverity severity, final String message);
676
677
678
679 /**
680 * Generates an administrative alert notification.
681 *
682 * @param severity The severity to use for the alert notification. It must
683 * not be {@code null}.
684 * @param message The message to be used for the alert notification. It
685 * must not be {@code null}.
686 */
687 void sendAlert(final AlertSeverity severity, final String message);
688
689
690
691 /**
692 * Generates an administrative alert notification.
693 *
694 * @param alertTypeName The name to use to identify the alert type. Each
695 * kind of alert must have a distinct name and all
696 * alerts with this alert type must always be used with
697 * the same severity and OID values. Alert type names
698 * must start with a lowercase ASCII letter and must
699 * contain only lowercase ASCII letters, numeric
700 * digits, and dashes.
701 * @param severity The severity to use for the alert notification.
702 * It must not be {@code null}.
703 * @param alertTypeOID The numeric OID for the alert type. It must not be
704 * {@code null}, and it must be a valid numeric OID.
705 * The same OID must always be used for the associated
706 * alert type, and each different alert type must have
707 * a unique OID.
708 * @param message The message to be used for the alert notification.
709 * It must not be {@code null}.
710 *
711 * @throws LDAPException If the provided information cannot be used to
712 * generate a valid alert (e.g., if the alert type
713 * name does not meet the naming constraints or has
714 * already been used with a different severity and/or
715 * OID, or if the OID has already been used with a
716 * different alert type).
717 */
718 void sendAlert(final String alertTypeName, final AlertSeverity severity,
719 final String alertTypeOID, final String message)
720 throws LDAPException;
721
722
723
724 /**
725 * Generates an administrative alert and updates the server's general monitor
726 * entry to list the specified alert type as a degraded alert type. Once the
727 * condition that triggered the server to be considered degraded has been
728 * resolved, the {@link DegradedAlertType#setResolved} method should be used
729 * to remove the alert type from the list of degraded alert types.
730 * <BR><BR>
731 * If a server has one or more unavailable alert types, it will be considered
732 * unavailable for use by products which make use of this information. If a
733 * server does not have any unavailable alert types but has one or more
734 * degraded alert types, then it will be considered degraded and less
735 * desirable for use by products which make use of this information.
736 *
737 * @param alertTypeName The name to use to identify the alert type. Each
738 * kind of alert must have a distinct name and all
739 * alerts with this alert type must always be used with
740 * the same severity and OID values. Alert type names
741 * must start with a lowercase ASCII letter and must
742 * contain only lowercase ASCII letters, numeric
743 * digits, and dashes.
744 * @param severity The severity to use for the alert notification.
745 * It must not be {@code null}.
746 * @param alertTypeOID The numeric OID for the alert type. It must not be
747 * {@code null}, and it must be a valid numeric OID.
748 * The same OID must always be used for the associated
749 * alert type, and each different alert type must have
750 * a unique OID.
751 * @param message The message to be used for the alert notification.
752 * It must not be {@code null}.
753 *
754 * @return An object that may be used to obtain information about the alert
755 * type and indicate that the degraded condition has been resolved.
756 *
757 * @throws LDAPException If the provided information cannot be used to
758 * generate a valid alert (e.g., if the alert type
759 * name does not meet the naming constraints or has
760 * already been used with a different severity and/or
761 * OID, or if the OID has already been used with a
762 * different alert type).
763 */
764 DegradedAlertType sendDegradedAlertNotification(final String alertTypeName,
765 final AlertSeverity severity,
766 final String alertTypeOID,
767 final String message)
768 throws LDAPException;
769
770
771
772 /**
773 * Generates an administrative alert and updates the server's general monitor
774 * entry to list the specified alert type as an unavailable alert type. Once
775 * the condition that triggered the server to be considered unavailable has
776 * been resolved, the {@link UnavailableAlertType#setResolved} method should
777 * be used to remove the alert type from the list of unavailable alert types.
778 * <BR><BR>
779 * If a server has one or more unavailable alert types, it will be considered
780 * unavailable for use by products which make use of this information. If a
781 * server does not have any unavailable alert types but has one or more
782 * degraded alert types, then it will be considered degraded and less
783 * desirable for use by products which make use of this information.
784 *
785 * @param alertTypeName The name to use to identify the alert type. Each
786 * kind of alert must have a distinct name and all
787 * alerts with this alert type must always be used with
788 * the same severity and OID values. Alert type names
789 * must start with a lowercase ASCII letter and must
790 * contain only lowercase ASCII letters, numeric
791 * digits, and dashes.
792 * @param severity The severity to use for the alert notification.
793 * It must not be {@code null}.
794 * @param alertTypeOID The numeric OID for the alert type. It must not be
795 * {@code null}, and it must be a valid numeric OID.
796 * The same OID must always be used for the associated
797 * alert type, and each different alert type must have
798 * a unique OID.
799 * @param message The message to be used for the alert notification.
800 * It must not be {@code null}.
801 *
802 * @return An object that may be used to obtain information about the alert
803 * type and indicate that the unavailable condition has been
804 * resolved.
805 *
806 * @throws LDAPException If the provided information cannot be used to
807 * generate a valid alert (e.g., if the alert type
808 * name does not meet the naming constraints or has
809 * already been used with a different severity and/or
810 * OID, or if the OID has already been used with a
811 * different alert type).
812 */
813 UnavailableAlertType sendUnavailableAlertNotification(
814 final String alertTypeName,
815 final AlertSeverity severity,
816 final String alertTypeOID, final String message)
817 throws LDAPException;
818
819
820
821 /**
822 * Indicates whether debugging is enabled in the server.
823 * <BR><BR>
824 * Note that debug messages written by Server SDK extensions will be handled
825 * in the same way as debug messages generated in other areas of the server.
826 * However, the "Server SDK Extension Debug Logger" may be used to easily
827 * obtain only debug messages generated by Server SDK extensions, suppressing
828 * all messages generated in other areas of the server.
829 *
830 * @return {@code true} if debugging is enabled in the server, or
831 * {@code false} if not.
832 */
833 boolean debugEnabled();
834
835
836
837 /**
838 * Writes a debug message indicating that the provided exception has been
839 * caught.
840 * <BR><BR>
841 * Note that debug messages written by Server SDK extensions will be handled
842 * in the same way as debug messages generated in other areas of the server.
843 * However, the "Server SDK Extension Debug Logger" may be used to easily
844 * obtain only debug messages generated by Server SDK extensions, suppressing
845 * all messages generated in other areas of the server.
846 *
847 * @param t The exception that has been caught.
848 */
849 void debugCaught(final Throwable t);
850
851
852
853 /**
854 * Writes a debug message indicating that the provided exception will be
855 * thrown.
856 * <BR><BR>
857 * Note that debug messages written by Server SDK extensions will be handled
858 * in the same way as debug messages generated in other areas of the server.
859 * However, the "Server SDK Extension Debug Logger" may be used to easily
860 * obtain only debug messages generated by Server SDK extensions, suppressing
861 * all messages generated in other areas of the server.
862 *
863 * @param t The exception that will be thrown.
864 */
865 void debugThrown(final Throwable t);
866
867
868
869 /**
870 * Writes a debug message with an error severity.
871 * <BR><BR>
872 * Note that debug messages written by Server SDK extensions will be handled
873 * in the same way as debug messages generated in other areas of the server.
874 * However, the "Server SDK Extension Debug Logger" may be used to easily
875 * obtain only debug messages generated by Server SDK extensions, suppressing
876 * all messages generated in other areas of the server.
877 *
878 * @param message The message to be debugged.
879 */
880 void debugError(final String message);
881
882
883
884 /**
885 * Writes a debug message with a warning severity.
886 * <BR><BR>
887 * Note that debug messages written by Server SDK extensions will be handled
888 * in the same way as debug messages generated in other areas of the server.
889 * However, the "Server SDK Extension Debug Logger" may be used to easily
890 * obtain only debug messages generated by Server SDK extensions, suppressing
891 * all messages generated in other areas of the server.
892 *
893 * @param message The message to be debugged.
894 */
895 void debugWarning(final String message);
896
897
898
899 /**
900 * Writes a debug message with an informational severity.
901 * <BR><BR>
902 * Note that debug messages written by Server SDK extensions will be handled
903 * in the same way as debug messages generated in other areas of the server.
904 * However, the "Server SDK Extension Debug Logger" may be used to easily
905 * obtain only debug messages generated by Server SDK extensions, suppressing
906 * all messages generated in other areas of the server.
907 *
908 * @param message The message to be debugged.
909 */
910 void debugInfo(final String message);
911
912
913
914 /**
915 * Writes a debug message with a verbose severity.
916 * <BR><BR>
917 * Note that debug messages written by Server SDK extensions will be handled
918 * in the same way as debug messages generated in other areas of the server.
919 * However, the "Server SDK Extension Debug Logger" may be used to easily
920 * obtain only debug messages generated by Server SDK extensions, suppressing
921 * all messages generated in other areas of the server.
922 *
923 * @param message The message to be debugged.
924 */
925 void debugVerbose(final String message);
926 }