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