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