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 }