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-2018 Ping Identity Corporation 026 */ 027package com.unboundid.directory.sdk.common.types; 028 029 030 031import java.io.File; 032import java.util.List; 033import java.util.Map; 034import java.util.Set; 035import java.util.UUID; 036 037import com.unboundid.directory.sdk.ds.api.ChangeListener; 038import com.unboundid.directory.sdk.common.api.DiskSpaceConsumer; 039import com.unboundid.directory.sdk.common.api.MonitorProvider; 040import com.unboundid.directory.sdk.common.api.ServerShutdownListener; 041import com.unboundid.directory.sdk.common.api.ServerThread; 042import com.unboundid.directory.sdk.common.config.GenericConfig; 043import com.unboundid.directory.sdk.common.schema.Schema; 044import com.unboundid.directory.sdk.ds.types.RegisteredChangeListener; 045import com.unboundid.directory.sdk.proxy.types.Location; 046import com.unboundid.ldap.sdk.ChangeType; 047import com.unboundid.ldap.sdk.DN; 048import com.unboundid.ldap.sdk.Filter; 049import com.unboundid.ldap.sdk.LDAPConnection; 050import com.unboundid.ldap.sdk.LDAPConnectionOptions; 051import com.unboundid.ldap.sdk.LDAPConnectionPool; 052import com.unboundid.ldap.sdk.LDAPException; 053import com.unboundid.ldap.sdk.LDAPInterface; 054import com.unboundid.util.NotExtensible; 055import com.unboundid.util.ThreadSafety; 056import com.unboundid.util.ThreadSafetyLevel; 057 058 059 060/** 061 * This interface may be used to obtain information about the server in 062 * which an extension is running. 063 */ 064@NotExtensible() 065@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 066public interface ServerContext 067{ 068 /** 069 * Retrieves the compact name of the server vendor. The returned name will 070 * not have any spaces. 071 * 072 * @return The compact name of the server vendor. 073 */ 074 String getShortVendorName(); 075 076 077 078 /** 079 * Retrieves the full name of the server vendor. The returned name may 080 * contain spaces. 081 * 082 * @return The full name of the server vendor. 083 */ 084 String getFullVendorName(); 085 086 087 088 /** 089 * Retrieves the compact name of the server. The returned name will not have 090 * any spaces. 091 * 092 * @return The compact name of the server. 093 */ 094 String getCompactProductName(); 095 096 097 098 /** 099 * Retrieves the package name of the server that is used for defining the 100 * server package ZIP file and root directory. The returned name will not 101 * have any spaces. 102 * 103 * @return The package name of the server. 104 */ 105 String getPackageName(); 106 107 108 109 /** 110 * Retrieves the full name of the server. The returned name may contain 111 * spaces. 112 * 113 * @return The full name of the server. 114 */ 115 String getFullProductName(); 116 117 118 119 /** 120 * Retrieves the base name of the server which is generally the full 121 * product name without the vendor information. The returned name may 122 * contain spaces. 123 * 124 * @return The full name of the server. 125 */ 126 String getBasicProductName(); 127 128 129 130 /** 131 * Retrieves the major version number for the server. The major version 132 * number is the first number which appears in the full version string (e.g., 133 * for a version string of "1.2.3.4-beta5", the major version number is 1). 134 * 135 * @return The major version number for the server. 136 */ 137 int getMajorVersionNumber(); 138 139 140 141 /** 142 * Retrieves the minor version number for the server. The minor version 143 * number is the second number which appears in the full version string (e.g., 144 * for a version string of "1.2.3.4-beta5", the minor version number is 2). 145 * 146 * @return The minor version number for the server. 147 */ 148 int getMinorVersionNumber(); 149 150 151 152 /** 153 * Retrieves the point version number for the server. The point version 154 * number is the third number which appears in the full version string (e.g., 155 * for a version string of "1.2.3.4-beta5", the point version number is 3). 156 * 157 * @return The point version number for the server. 158 */ 159 int getPointVersionNumber(); 160 161 162 163 /** 164 * Retrieves the patch version number for the server. The patch version 165 * number is the fourth number which appears in the full version string (e.g., 166 * for a version string of "1.2.3.4-beta5", the patch version number is 4). 167 * 168 * @return The point version number for the server. 169 */ 170 int getPatchVersionNumber(); 171 172 173 174 /** 175 * Retrieves a string that is the concatenation of the major, minor, 176 * point, and patch version numbers of the server. 177 * 178 * @return the server's version number string. 179 */ 180 String getVersionNumber(); 181 182 183 184 /** 185 * Retrieves a string that is the concatenation of the product name, the 186 * major, minor, point, and patch version numbers of the server and any 187 * any other unique version information. 188 * 189 * @return the server's full version number string. 190 */ 191 String getFullVersion(); 192 193 194 195 /** 196 * Retrieves the version qualifier string for the server. The version 197 * qualifier is an optional string which may provide additional information 198 * about the server version. If a version qualifier is present, then it will 199 * immediately follow the patch version number (e.g., for a version string of 200 * "1.2.3.4-beta5", the version qualifier is "-beta5"). 201 * 202 * @return The version qualifier for the server, or an empty string if no 203 * version qualifier is defined. 204 */ 205 String getVersionQualifier(); 206 207 208 209 /** 210 * Retrieves a value which identifies the source revision (in the 211 * version control system used to hold the server source code) from which the 212 * server was built. 213 * 214 * @return The source revision identifier for the server. 215 */ 216 String getSourceRevision(); 217 218 219 220 /** 221 * Indicates whether the server is in the process of starting up. 222 * 223 * @return {@code true} if the server is in the process of starting up, or 224 * {@code false} if not. 225 */ 226 boolean isStarting(); 227 228 229 230 /** 231 * Indicates whether the server is currently running. 232 * 233 * @return {@code true} if the server is running, or {@code false} if not. 234 */ 235 boolean isRunning(); 236 237 238 239 /** 240 * Indicates whether the server is in the process of shutting down. 241 * 242 * @return {@code true} if the server is in the process of shutting down, or 243 * {@code false} if not. 244 */ 245 boolean isShuttingDown(); 246 247 248 249 /** 250 * Retrieves the time that the server was started. The value returned will 251 * be an offset in milliseconds since 12:00 a.m. on January 1, 1970. 252 * 253 * @return The time that the server was started. 254 */ 255 long getStartTime(); 256 257 258 259 /** 260 * Retrieves a compact ID that was generated at the time the server was 261 * started. It is not guaranteed to be unique among all instances of the 262 * server, but is guaranteed to be unique across all invocations of a single 263 * server installation. This is suitable for inclusion in log messages and 264 * can help differentiate operations with the same connection ID and operation 265 * ID across server restarts. 266 * 267 * @return A compact ID that was generated at the time the server was 268 * started. 269 */ 270 String getStartupID(); 271 272 273 274 /** 275 * Retrieves a unique identifier that was generated at the time the server was 276 * started. It will be unique across all server instances and all invocations 277 * of the same instance. 278 * 279 * @return A unique identifier that was generated at the time the server was 280 * started. 281 */ 282 UUID getStartupUUID(); 283 284 285 286 /** 287 * Retrieves the instance name that has been assigned to the server. 288 * 289 * @return The instance name that has been assigned to the server. 290 */ 291 String getInstanceName(); 292 293 294 295 296 /** 297 * Retrieves the location that has been assigned to the server, if any. 298 * 299 * @return The location that has been assigned to the server, or 300 * {@code null} if no location has been assigned. 301 */ 302 Location getLocation(); 303 304 305 306 /** 307 * Retrieves the path to the server root directory. 308 * 309 * @return The path to the server root directory. 310 */ 311 File getServerRoot(); 312 313 314 315 /** 316 * Retrieves a ToolExecutor that can be used to internally execute select 317 * command line utilities. 318 * 319 * @return A ToolExecutor that can be used to internally execute select 320 * command line utilities. 321 */ 322 ToolExecutor getToolExecutor(); 323 324 325 326 /** 327 * Indicates whether the extension is running in a server that has Directory 328 * Server functionality available. 329 * 330 * @return {@code true} if Directory Server functionality is available, or 331 * {@code false} if not. 332 */ 333 boolean isDirectoryFunctionalityAvailable(); 334 335 336 337 /** 338 * Indicates whether the extension is running in a server that has Directory 339 * Proxy Server functionality available. 340 * 341 * @return {@code true} if Directory Proxy Server functionality is available, 342 * or {@code false} if not. 343 */ 344 boolean isDirectoryProxyFunctionalityAvailable(); 345 346 347 348 /** 349 * Indicates whether the extension is running in a server that has 350 * Data Sync Server functionality available. 351 * 352 * @return {@code true} if Data Sync Server functionality is 353 * available, or {@code false} if not. 354 */ 355 boolean isSyncFunctionalityAvailable(); 356 357 358 359 /** 360 * Retrieves an internal connection that is authenticated as a root user 361 * that is not subject to access control. 362 * <BR><BR> 363 * During operation processing, this connection is considered a root 364 * connection that is both internal and secure. 365 * <BR><BR> 366 * Note that the returned connection will use the client connection policy 367 * defined as the default policy for internal operations. If you have access 368 * to a {@code ClientContext} and wish to use the client connection policy 369 * associated with that connection, use the 370 * {@link ClientContext#getInternalRootConnection(boolean)} method. 371 * 372 * @return An internal connection that is authenticated as a root user. 373 */ 374 InternalConnection getInternalRootConnection(); 375 376 377 378 /** 379 * Retrieves an internal connection that is authenticated as the specified 380 * user. Operations on the connection may be subject to access control based 381 * on the privileges associated with the specified user. 382 * <BR><BR> 383 * During operation processing, this connection is considered a user 384 * connection that is both internal and secure. 385 * <BR><BR> 386 * Note that the returned connection will use the client connection policy 387 * defined as the default policy for internal operations. If you have access 388 * to a {@code ClientContext} and wish to use the client connection policy 389 * associated with that connection, use the 390 * {@link ClientContext#getInternalConnection(String,boolean)} method. 391 * 392 * @param dn The DN of the user as whom the connection should be 393 * authenticated. It may be {@code null} or empty if the 394 * connection should be unauthenticated. 395 * 396 * @return An internal connection that is authenticated as the specified 397 * user. 398 * 399 * @throws LDAPException If a problem occurs while attempting to 400 * authenticate as the specified user. 401 */ 402 InternalConnection getInternalConnection(final String dn) 403 throws LDAPException; 404 405 406 407 /** 408 * Retrieves a client connection that is authenticated as a root user 409 * and is not subject to access control. 410 * <BR><BR> 411 * This method should be used when the connection will be used on behalf of 412 * some external client, and allows you to indicate whether the external 413 * client has a secure connection. This information is used by some of the 414 * internal security controls, such as password policies, which may reject 415 * password change operations if they are not over a secure connection, for 416 * example. 417 * <BR><BR> 418 * During operation processing, this connection is considered a root 419 * connection that is external and optionally secure, depending on the 420 * {@code isClientSecure} parameter. 421 * 422 * @param isClientSecure Whether the external client is connected over a 423 * secure channel. 424 * 425 * @return A client connection that is authenticated as a root user. 426 */ 427 LDAPInterface getClientRootConnection(final boolean isClientSecure); 428 429 430 431 /** 432 * Retrieves a client connection that is authenticated as the specified 433 * user. Operations on the connection may be subject to access control based 434 * on the privileges associated with the specified user. 435 * <BR><BR> 436 * This method should be used when the connection will be used on behalf of 437 * some external client, and allows you to indicate whether the external 438 * client has a secure connection. This information is used by some of the 439 * internal security controls, such as password policies, which may reject 440 * password change operations if they are not over a secure connection, for 441 * example. 442 * <BR><BR> 443 * During operation processing, this connection is considered a user 444 * connection that is external and optionally secure, depending on the 445 * {@code isClientSecure} parameter. 446 * 447 * @param dn The DN of the user as whom the connection should be 448 * authenticated. It may be {@code null} or empty if the 449 * connection should be unauthenticated. 450 * 451 * @param isClientSecure Whether the external client is connected over a 452 * secure channel. 453 * 454 * @return An internal connection that is authenticated as the specified 455 * user. 456 * 457 * @throws LDAPException If a problem occurs while attempting to 458 * authenticate as the specified user. 459 */ 460 LDAPInterface getClientConnection(final String dn, 461 final boolean isClientSecure) 462 throws LDAPException; 463 464 465 466 /** 467 * Retrieves a reference to the server schema. 468 * 469 * @return A reference to the server schema. 470 */ 471 Schema getSchema(); 472 473 474 475 /** 476 * Registers the provided OID with the server so that it will appear in the 477 * supportedControl attribute of the server's root DSE. This method should 478 * only be used by extensions which implement some level of support for that 479 * control (e.g., a pre-parse plugin which performs all necessary processing 480 * from the control and removes it from the request so that it will not be 481 * seen and potentially rejected by the core server). 482 * 483 * @param oid The OID to be registered. 484 */ 485 void registerSupportedControlOID(final String oid); 486 487 488 489 /** 490 * Deregisters the provided OID with the server so that it will no longer 491 * appear in the supportedControl attribute of the server's root DSE. 492 * 493 * @param oid The OID to be deregistered. 494 */ 495 void deregisterSupportedControlOID(final String oid); 496 497 498 499 /** 500 * Registers the provided change listener with the server so that it may be 501 * notified of any changes matching the provided criteria. 502 * 503 * @param listener The change listener to be registered with the server. 504 * It must not be {@code null}. 505 * @param changeTypes The types of changes for which the listener should be 506 * registered. It may be {@code null} or empty to 507 * indicate that the listener should be registered for 508 * all types of changes. 509 * @param baseDNs The set of base DNs for which the listener should be 510 * registered. It may be {@code null} or empty to 511 * indicate that the listener should be registered for 512 * changes processed anywhere in the server. 513 * @param filter A filter which may be used to restrict the set of 514 * changes for which the listener is notified. If a 515 * filter is provided, then only changes in which the 516 * target entry matches the given filter (either before 517 * or after the change was processed) will be notified. 518 * It may be {@code null} to indicate that the contents 519 * of the entry should not be considered. 520 * 521 * @return An object representing the change listener that has been 522 * registered with the server. 523 * 524 * @throws LDAPException If a problem is encountered while attempting to 525 * register the provided change listener (e.g., if any 526 * of the base DNs cannot be parsed as a valid DN). 527 */ 528 RegisteredChangeListener registerChangeListener(final ChangeListener listener, 529 final Set<ChangeType> changeTypes, 530 final List<String> baseDNs, 531 final Filter filter) 532 throws LDAPException; 533 534 535 536 /** 537 * Deregisters the provided change listener with the server. This will have 538 * no effect if the provided listener is not registered. 539 * 540 * @param listener The change listener to be deregistered. It must not be 541 * {@code null}. 542 */ 543 void deregisterChangeListener(final RegisteredChangeListener listener); 544 545 546 547 /** 548 * Registers the provided disk space consumer with the server. 549 * 550 * @param consumer The disk space consumer to be registered with the server. 551 * It must not be {@code null}. 552 * 553 * @return An object representing the disk space consumer that has been 554 * registered with the server. 555 */ 556 RegisteredDiskSpaceConsumer registerDiskSpaceConsumer( 557 final DiskSpaceConsumer consumer); 558 559 560 561 /** 562 * Deregisters the provided disk space consumer with the server. This will no 563 * no effect if the provided consumer is not registered. 564 * 565 * @param consumer The disk space consumer to be deregistered with the 566 * server. It must not be {@code null}. 567 */ 568 void deregisterDiskSpaceConsumer(final RegisteredDiskSpaceConsumer consumer); 569 570 571 572 /** 573 * Registers the provided listener to be notified when the server shutdown 574 * process has begun. 575 * 576 * @param listener The server shutdown listener to be registered. It must 577 * not be {@code null}. 578 * 579 * @return An object representing the shutdown listener that has been 580 * registered with the server. 581 */ 582 RegisteredServerShutdownListener registerShutdownListener( 583 final ServerShutdownListener listener); 584 585 586 587 /** 588 * Deregisters the provided server shutdown listener with the server. This 589 * will have no effect if the provided listener is not registered. 590 * 591 * @param listener The server shutdown listener to be deregistered. It must 592 * not be {@code null}. 593 */ 594 void deregisterShutdownListener( 595 final RegisteredServerShutdownListener listener); 596 597 598 599 /** 600 * Registers the given monitor provider with the server. It is important that 601 * this monitor provider has a unique instance name across all monitor 602 * providers in the server. If there is already a monitor provider registered 603 * with the same instance name, an {@link IllegalStateException} will be 604 * thrown. 605 * <p> 606 * The generated monitor entry will have a DN in the following format: 607 * <code>cn={monitor-instance-name} [from {extension-type}:{extension-name}], 608 * cn=monitor</code> and it will contain three auto-generated attributes: 609 * <code>ds-extension-monitor-name</code>, <code>ds-extension-type</code>, and 610 * <code>ds-extension-name</code>. Note: the {extension-type} and 611 * {extension-name} are from the extension which owns this ServerContext 612 * instance, not from the given MonitorProvider object. 613 * <p> 614 * The specified monitor provider does not need any server-side configuration, 615 * and the configuration-related methods 616 * (<code>initalizeMonitorProvider()</code>, 617 * <code>finalizeMonitorProvider()</code>, 618 * <code>defineConfigArguments()</code>, 619 * <code>isConfigurationAcceptable()</code>, 620 * <code>applyConfiguration()</code>) do not need to be implemented because 621 * they will not be called. 622 * <p> 623 * When an extension is disabled, all of its registered monitor 624 * providers will automatically deregister themselves from the server. 625 * You can also manually deregister them using 626 * {@link #deregisterMonitorProvider(RegisteredMonitorProvider)} or 627 * {@link #deregisterAllMonitorProviders()}. 628 * 629 * @param provider The monitor provider instance to be registered. It 630 * must not be {@code null}. 631 * @param config The configuration object from the extension that is 632 * registering the given monitor provider. This is required so 633 * that the monitor entry can be given a unique DN which 634 * includes the name of the extension that registered it. 635 * 636 * @return An object representing the monitor provider that has been 637 * registered with the server. 638 */ 639 RegisteredMonitorProvider registerMonitorProvider( 640 final MonitorProvider provider, 641 final GenericConfig config); 642 643 644 645 /** 646 * Deregisters the given monitor provider with the server. This will have no 647 * effect if the given monitor provider is not registered. 648 * 649 * @param provider The monitor provider instance to be registered. It 650 * must not be {@code null}. 651 */ 652 void deregisterMonitorProvider(final RegisteredMonitorProvider provider); 653 654 655 656 /** 657 * Deregisters all the monitor providers that were registered with the server 658 * by this instance of {@link ServerContext}. This can be useful during 659 * cleanup or if you want to clear out all the existing monitor data from a 660 * given extension and register new monitor providers. 661 * <p> 662 * This will be called automatically when your extension is unloaded or 663 * disabled. 664 */ 665 void deregisterAllMonitorProviders(); 666 667 668 669 /** 670 * Creates a new thread to run within the server. The thread will not be 671 * started. 672 * 673 * @param name The name to use for the thread. It must not be 674 * {@code null} or empty. 675 * @param serverThread The class providing the logic for the thread. It 676 * must not be {@code null}. 677 * 678 * @return The thread that has been created but not yet started. 679 */ 680 Thread createThread(final ServerThread serverThread, final String name); 681 682 683 684 /** 685 * Writes a message to the server error log. 686 * 687 * @param severity The severity to use for the log message. It must not be 688 * {@code null}. 689 * @param message The message to be logged. It must not be {@code null}. 690 */ 691 void logMessage(final LogSeverity severity, final String message); 692 693 694 695 /** 696 * Generates an administrative alert notification. 697 * 698 * @param severity The severity to use for the alert notification. It must 699 * not be {@code null}. 700 * @param message The message to be used for the alert notification. It 701 * must not be {@code null}. 702 */ 703 void sendAlert(final AlertSeverity severity, final String message); 704 705 706 707 /** 708 * Generates an administrative alert notification. 709 * 710 * @param alertTypeName The name to use to identify the alert type. Each 711 * kind of alert must have a distinct name and all 712 * alerts with this alert type must always be used with 713 * the same severity and OID values. Alert type names 714 * must start with a lowercase ASCII letter and must 715 * contain only lowercase ASCII letters, numeric 716 * digits, and dashes. 717 * @param severity The severity to use for the alert notification. 718 * It must not be {@code null}. 719 * @param alertTypeOID The numeric OID for the alert type. It must not be 720 * {@code null}, and it must be a valid numeric OID. 721 * The same OID must always be used for the associated 722 * alert type, and each different alert type must have 723 * a unique OID. 724 * @param message The message to be used for the alert notification. 725 * It must not be {@code null}. 726 * 727 * @throws LDAPException If the provided information cannot be used to 728 * generate a valid alert (e.g., if the alert type 729 * name does not meet the naming constraints or has 730 * already been used with a different severity and/or 731 * OID, or if the OID has already been used with a 732 * different alert type). 733 */ 734 void sendAlert(final String alertTypeName, final AlertSeverity severity, 735 final String alertTypeOID, final String message) 736 throws LDAPException; 737 738 739 740 /** 741 * Generates an administrative alert and updates the server's general monitor 742 * entry to list the specified alert type as a degraded alert type. Once the 743 * condition that triggered the server to be considered degraded has been 744 * resolved, the {@link DegradedAlertType#setResolved} method should be used 745 * to remove the alert type from the list of degraded alert types. 746 * <BR><BR> 747 * If a server has one or more unavailable alert types, it will be considered 748 * unavailable for use by products which make use of this information. If a 749 * server does not have any unavailable alert types but has one or more 750 * degraded alert types, then it will be considered degraded and less 751 * desirable for use by products which make use of this information. 752 * 753 * @param alertTypeName The name to use to identify the alert type. Each 754 * kind of alert must have a distinct name and all 755 * alerts with this alert type must always be used with 756 * the same severity and OID values. Alert type names 757 * must start with a lowercase ASCII letter and must 758 * contain only lowercase ASCII letters, numeric 759 * digits, and dashes. 760 * @param severity The severity to use for the alert notification. 761 * It must not be {@code null}. 762 * @param alertTypeOID The numeric OID for the alert type. It must not be 763 * {@code null}, and it must be a valid numeric OID. 764 * The same OID must always be used for the associated 765 * alert type, and each different alert type must have 766 * a unique OID. 767 * @param message The message to be used for the alert notification. 768 * It must not be {@code null}. 769 * 770 * @return An object that may be used to obtain information about the alert 771 * type and indicate that the degraded condition has been resolved. 772 * 773 * @throws LDAPException If the provided information cannot be used to 774 * generate a valid alert (e.g., if the alert type 775 * name does not meet the naming constraints or has 776 * already been used with a different severity and/or 777 * OID, or if the OID has already been used with a 778 * different alert type). 779 */ 780 DegradedAlertType sendDegradedAlertNotification(final String alertTypeName, 781 final AlertSeverity severity, 782 final String alertTypeOID, 783 final String message) 784 throws LDAPException; 785 786 787 788 /** 789 * Generates an administrative alert and updates the server's general monitor 790 * entry to list the specified alert type as an unavailable alert type. Once 791 * the condition that triggered the server to be considered unavailable has 792 * been resolved, the {@link UnavailableAlertType#setResolved} method should 793 * be used to remove the alert type from the list of unavailable alert types. 794 * <BR><BR> 795 * If a server has one or more unavailable alert types, it will be considered 796 * unavailable for use by products which make use of this information. If a 797 * server does not have any unavailable alert types but has one or more 798 * degraded alert types, then it will be considered degraded and less 799 * desirable for use by products which make use of this information. 800 * 801 * @param alertTypeName The name to use to identify the alert type. Each 802 * kind of alert must have a distinct name and all 803 * alerts with this alert type must always be used with 804 * the same severity and OID values. Alert type names 805 * must start with a lowercase ASCII letter and must 806 * contain only lowercase ASCII letters, numeric 807 * digits, and dashes. 808 * @param severity The severity to use for the alert notification. 809 * It must not be {@code null}. 810 * @param alertTypeOID The numeric OID for the alert type. It must not be 811 * {@code null}, and it must be a valid numeric OID. 812 * The same OID must always be used for the associated 813 * alert type, and each different alert type must have 814 * a unique OID. 815 * @param message The message to be used for the alert notification. 816 * It must not be {@code null}. 817 * 818 * @return An object that may be used to obtain information about the alert 819 * type and indicate that the unavailable condition has been 820 * resolved. 821 * 822 * @throws LDAPException If the provided information cannot be used to 823 * generate a valid alert (e.g., if the alert type 824 * name does not meet the naming constraints or has 825 * already been used with a different severity and/or 826 * OID, or if the OID has already been used with a 827 * different alert type). 828 */ 829 UnavailableAlertType sendUnavailableAlertNotification( 830 final String alertTypeName, 831 final AlertSeverity severity, 832 final String alertTypeOID, final String message) 833 throws LDAPException; 834 835 836 837 /** 838 * Indicates whether debugging is enabled in the server. 839 * <BR><BR> 840 * Note that debug messages written by Server SDK extensions will be handled 841 * in the same way as debug messages generated in other areas of the server. 842 * However, the "Server SDK Extension Debug Logger" may be used to easily 843 * obtain only debug messages generated by Server SDK extensions, suppressing 844 * all messages generated in other areas of the server. 845 * 846 * @return {@code true} if debugging is enabled in the server, or 847 * {@code false} if not. 848 */ 849 boolean debugEnabled(); 850 851 852 853 /** 854 * Writes a debug message indicating that the provided exception has been 855 * caught. 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 has been caught. 864 */ 865 void debugCaught(final Throwable t); 866 867 868 869 /** 870 * Writes a debug message indicating that the provided exception will be 871 * thrown. 872 * <BR><BR> 873 * Note that debug messages written by Server SDK extensions will be handled 874 * in the same way as debug messages generated in other areas of the server. 875 * However, the "Server SDK Extension Debug Logger" may be used to easily 876 * obtain only debug messages generated by Server SDK extensions, suppressing 877 * all messages generated in other areas of the server. 878 * 879 * @param t The exception that will be thrown. 880 */ 881 void debugThrown(final Throwable t); 882 883 884 885 /** 886 * Writes a debug message with an error severity. 887 * <BR><BR> 888 * Note that debug messages written by Server SDK extensions will be handled 889 * in the same way as debug messages generated in other areas of the server. 890 * However, the "Server SDK Extension Debug Logger" may be used to easily 891 * obtain only debug messages generated by Server SDK extensions, suppressing 892 * all messages generated in other areas of the server. 893 * 894 * @param message The message to be debugged. 895 */ 896 void debugError(final String message); 897 898 899 900 /** 901 * Writes a debug message with a warning severity. 902 * <BR><BR> 903 * Note that debug messages written by Server SDK extensions will be handled 904 * in the same way as debug messages generated in other areas of the server. 905 * However, the "Server SDK Extension Debug Logger" may be used to easily 906 * obtain only debug messages generated by Server SDK extensions, suppressing 907 * all messages generated in other areas of the server. 908 * 909 * @param message The message to be debugged. 910 */ 911 void debugWarning(final String message); 912 913 914 915 /** 916 * Writes a debug message with an informational severity. 917 * <BR><BR> 918 * Note that debug messages written by Server SDK extensions will be handled 919 * in the same way as debug messages generated in other areas of the server. 920 * However, the "Server SDK Extension Debug Logger" may be used to easily 921 * obtain only debug messages generated by Server SDK extensions, suppressing 922 * all messages generated in other areas of the server. 923 * 924 * @param message The message to be debugged. 925 */ 926 void debugInfo(final String message); 927 928 929 930 /** 931 * Writes a debug message with a verbose severity. 932 * <BR><BR> 933 * Note that debug messages written by Server SDK extensions will be handled 934 * in the same way as debug messages generated in other areas of the server. 935 * However, the "Server SDK Extension Debug Logger" may be used to easily 936 * obtain only debug messages generated by Server SDK extensions, suppressing 937 * all messages generated in other areas of the server. 938 * 939 * @param message The message to be debugged. 940 */ 941 void debugVerbose(final String message); 942 943 944 945 /** 946 * Retrieves a connection that is established and (if appropriate) 947 * authenticated to the specified LDAP External server. This will be a 948 * newly-created connection that is not used for any other purpose, and the 949 * caller is responsible for closing that connection when it is no longer 950 * needed. 951 * 952 * @param ldapExternalServerCfgObjectName The name of the configuration 953 * object for the LDAP external 954 * server to which the connection 955 * should be established. It must 956 * not be {@code null}. 957 * @param connectionOptions The set of options to use for the 958 * connection that is established. 959 * It may be {@code null} if a 960 * default set of options should be 961 * used. 962 * 963 * @return The newly-created LDAP connection. 964 * 965 * @throws LDAPException If it is not possible to establish a connection to 966 * the target servers. 967 */ 968 LDAPConnection getLDAPExternalServerConnection( 969 final String ldapExternalServerCfgObjectName, 970 final LDAPConnectionOptions connectionOptions) 971 throws LDAPException; 972 973 974 975 /** 976 * Retrieves a connection pool with connections to the specified server. This 977 * will be a newly-created connection pool that is not used for any other 978 * purpose, and the caller is responsible for closing that connection pool 979 * when it is no longer needed. 980 * 981 * @param ldapExternalServerCfgObjectName The name of the configuration 982 * object for the LDAP external 983 * server to which the connections 984 * should be established. It must 985 * not be {@code null}. 986 * @param connectionOptions The set of options to use for the 987 * connection that is established. 988 * It may be {@code null} if a 989 * default set of options should be 990 * used. 991 * @param initialConnections The initial number of connections 992 * to attempt to establish. It must 993 * be greater than or equal to zero. 994 * @param maxConnections The maximum number of connections 995 * that should be established and 996 * unused in the pool at any time. 997 * It must be greater than or equal 998 * to {@code initialConnections}, and 999 * it must not be zero. 1000 * @param throwOnConnectFailure Indicates whether to throw an 1001 * {@code LDAPException} if an error 1002 * is encountered while attempting to 1003 * connect or authenticate any of the 1004 * initial connections. If this is 1005 * {@code false} and none of the 1006 * initial connections can be 1007 * established (or if the initial 1008 * number of connections is zero), 1009 * then the pool will be returned 1010 * without any connections. 1011 * 1012 * @return The newly-created LDAP connection pool. 1013 * 1014 * @throws LDAPException If it is not possible to establish a pool of 1015 * connections to the specified LDAP external server. 1016 */ 1017 LDAPConnectionPool getLDAPExternalServerConnectionPool( 1018 final String ldapExternalServerCfgObjectName, 1019 final LDAPConnectionOptions connectionOptions, 1020 final int initialConnections, 1021 final int maxConnections, 1022 final boolean throwOnConnectFailure) 1023 throws LDAPException; 1024 1025 1026 1027 /** 1028 * Retrieves the plaintext representation of the specified obscured value from 1029 * the server configuration. Obscured values may be used to allow extensions 1030 * to store potentially sensitive information (for example, credentials needed 1031 * to access some external system) in the configuration in a manner that will 1032 * prevent them from being stored in the clear or displayed in the clear in 1033 * administrative interfaces. If a server extension needs to be configured 1034 * with potentially sensitive information, it is recommended that each piece 1035 * of sensitive information be stored as an obscured value, and that the 1036 * extension be configured with the names of the relevant obscured values. 1037 * 1038 * @param obscuredValueConfigObjectName The name of the configuration object 1039 * for the obscured value to retrieve. 1040 * It must not be {@code null}. 1041 * 1042 * @return The plaintext representation of the specified obscured value from 1043 * the server configuration. 1044 * 1045 * @throws LDAPException If the provided name does not reference an obscured 1046 * value that is defined in the server configuration. 1047 */ 1048 String getObscuredValue(final String obscuredValueConfigObjectName) 1049 throws LDAPException; 1050 1051 1052 1053 /** 1054 * Returns a ValueConstructor built from the provided value template. A 1055 * ValueConstructor can be used to construct string values from a template 1056 * that can reference attributes on an entry. 1057 * 1058 * @param constructedValueTemplate The constructed value pattern. See 1059 * {@link ValueConstructor} for details on 1060 * the syntax for the template. 1061 * 1062 * @return A ValueConstructor based on the provided template. 1063 * 1064 * @throws LDAPException If the provided value template is invalid. 1065 */ 1066 ValueConstructor createValueConstructor(final String constructedValueTemplate) 1067 throws LDAPException; 1068 1069 1070 1071 /** 1072 * Retrieves the group defined in the specified entry. 1073 * 1074 * @param groupDN The DN of the entry containing the group to retrieve. It 1075 * must not be {@code null}. 1076 * 1077 * @return The group defined in the specified entry. 1078 * 1079 * @throws LDAPException If the specified entry does not exist, if it exists 1080 * but does not represent a group, or if a problem is 1081 * encountered while retrieving the group. 1082 */ 1083 Group getGroup(final String groupDN) 1084 throws LDAPException; 1085 1086 1087 1088 /** 1089 * Retrieves the set of groups in which the specified user is a member, 1090 * indexed by group DN. 1091 * 1092 * @param userDN The DN of the user for whom to retrieve the 1093 * associated groups. It must not be 1094 * {@code null}. 1095 * @param directMembershipOnly Indicates whether to only consider the user a 1096 * member of the group if that user is directly 1097 * named as a member of the group. If this 1098 * parameter is {@code true}, then the method 1099 * will return {@code true} only if the user is 1100 * directly listed as a member of the group, and 1101 * will not included dynamic or nested 1102 * membership. If this parameter is 1103 * {@code false}, then the method will return 1104 * {@code true} if the user is a direct member 1105 * of the group, is a member of a dynamic group 1106 * in which the user matches the membership 1107 * criteria, or if the user is a member of a 1108 * nested group. 1109 * 1110 * @return A map of the groups in which the specified user is a member, or an 1111 * empty map if the specified user is not a member of any groups. 1112 * 1113 * @throws LDAPException If the specified user does not exist or if a 1114 * problem is encountered while attempting to retrieve 1115 * the groups in which the user is a member. 1116 */ 1117 Map<DN,Group> getGroupsForUser(final String userDN, 1118 final boolean directMembershipOnly) 1119 throws LDAPException; 1120 1121 1122 1123 /** 1124 * Indicates whether the specified user has the indicated privilege. The set 1125 * of defined privileges may be found in the privilege-list.html and 1126 * privilege-list.csv files in the server docs directory. 1127 * 1128 * @param userDN The DN of the user for whom to make the 1129 * determination. It must not be {@code null}. 1130 * @param privilegeName The name of the privilege for which to make the 1131 * determination. It must not be {@code null}. 1132 * 1133 * @return {@code true} if the specified user has the indicated privilege, or 1134 * {@code false} if not. 1135 * 1136 * @throws LDAPException If the specified user does not exist, if the 1137 * indicated privilege is not defined in the server, 1138 * or if a problem is encountered while trying to make 1139 * the determination. 1140 */ 1141 boolean hasPrivilege(final String userDN, final String privilegeName) 1142 throws LDAPException; 1143 1144 1145 1146 /** 1147 * Retrieves the names of the privileges held by the specified user. The set 1148 * of defined privileges may be found in the privilege-list.html and 1149 * privilege-list.csv files in the server docs directory. 1150 * 1151 * @param userDN The DN of the user for whom to retrieve the privileges. It 1152 * must not be {@code null}. 1153 * 1154 * @return The names of the privileges held by the specified user, or an 1155 * empty set if the user does not have any privileges. 1156 * 1157 * @throws LDAPException If the specified user does not exist, or if a 1158 * problem is encountered while attempting to retrieve 1159 * the user's privileges. 1160 */ 1161 Set<String> getPrivilegeNames(final String userDN) 1162 throws LDAPException; 1163 1164 1165 1166 /** 1167 * Reload the key and trust manager providers associated with any HTTP 1168 * connection handlers.that provide support for HTTPS. This can cause any 1169 * changes to the certificates in those stores to be applied to the running 1170 * instance without the need to disable and re-enable the connection handler 1171 * or to restart the server. Note that this reload does have the potential 1172 * to interfere with the ability for clients to resume a TLS session created 1173 * before the reload was invoked. 1174 * 1175 * @throws LDAPException If an error occurs. 1176 */ 1177 void reloadHTTPConnectionHandlerCertificates() 1178 throws LDAPException; 1179}