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