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