001/*
002 * Copyright 2015-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2019 Ping Identity Corporation
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021package com.unboundid.ldap.sdk.unboundidds;
022
023
024
025import com.unboundid.ldap.sdk.Entry;
026import com.unboundid.ldap.sdk.LDAPException;
027import com.unboundid.ldap.sdk.LDAPInterface;
028import com.unboundid.ldap.sdk.RootDSE;
029import com.unboundid.util.NotMutable;
030import com.unboundid.util.ThreadSafety;
031import com.unboundid.util.ThreadSafetyLevel;
032
033
034
035/**
036 * This class provides an enhanced implementation of the {@link RootDSE} class
037 * that provides access to additional attributes that may be included in the
038 * root DSE of a Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 server.
039 * <BR>
040 * <BLOCKQUOTE>
041 *   <B>NOTE:</B>  This class, and other classes within the
042 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
043 *   supported for use against Ping Identity, UnboundID, and
044 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
045 *   for proprietary functionality or for external specifications that are not
046 *   considered stable or mature enough to be guaranteed to work in an
047 *   interoperable way with other types of LDAP servers.
048 * </BLOCKQUOTE>
049 */
050@NotMutable()
051@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
052public final class UnboundIDRootDSE
053       extends RootDSE
054{
055  /**
056   * The name of the attribute that provides a digest of the base configuration
057   * for the software version the server is currently running.
058   */
059  public static final String ATTR_BASELINE_CONFIG_DIGEST =
060       "baselineConfigurationDigest";
061
062
063
064  /**
065   * The name of the attribute that provides a digest of the configuration model
066   * for the software version the server is currently running.
067   */
068  public static final String ATTR_CONFIG_MODEL_DIGEST =
069       "configurationModelDigest";
070
071
072
073  /**
074   * The name of the attribute that provides a the unique instance name for the
075   * server instance.
076   */
077  public static final String ATTR_INSTANCE_NAME = "ds-instance-name";
078
079
080
081  /**
082   * The name of the attribute that includes the DNs of the private naming
083   * contexts defined in the server.  These are base DNs that provide some
084   * content in the UnboundID server, but do not house user-provided data that
085   * is expected to be accessed by normal clients.
086   */
087  public static final String ATTR_PRIVATE_NAMING_CONTEXTS =
088       "ds-private-naming-contexts";
089
090
091
092  /**
093   * The name of the attribute that includes unique identifier generated at
094   * server startup, and can be used to determine whether an instance has been
095   * restarted.
096   */
097  public static final String ATTR_STARTUP_UUID = "startupUUID";
098
099
100
101  /**
102   * The name of the attribute that includes the one-time password delivery
103   * mechanisms supported for use in the server.
104   */
105  public static final String ATTR_SUPPORTED_OTP_DELIVERY_MECHANISM =
106       "ds-supported-otp-delivery-mechanism";
107
108
109
110  /**
111   * The set of request attributes to use when attempting to retrieve the server
112   * root DSE.  It will attempt to retrieve all operational attributes if the
113   * server supports that capability, but will also attempt to retrieve specific
114   * attributes by name in case it does not.
115   */
116  private static final String[] REQUEST_ATTRS;
117  static
118  {
119    final String[] superAttrs = RootDSE.REQUEST_ATTRS;
120    REQUEST_ATTRS = new String[superAttrs.length + 6];
121    System.arraycopy(superAttrs, 0, REQUEST_ATTRS, 0, superAttrs.length);
122
123    int i = superAttrs.length;
124    REQUEST_ATTRS[i++] = ATTR_BASELINE_CONFIG_DIGEST;
125    REQUEST_ATTRS[i++] = ATTR_CONFIG_MODEL_DIGEST;
126    REQUEST_ATTRS[i++] = ATTR_INSTANCE_NAME;
127    REQUEST_ATTRS[i++] = ATTR_PRIVATE_NAMING_CONTEXTS;
128    REQUEST_ATTRS[i++] = ATTR_STARTUP_UUID;
129    REQUEST_ATTRS[i++] = ATTR_SUPPORTED_OTP_DELIVERY_MECHANISM;
130  }
131
132
133
134  /**
135   * The serial version UID for this serializable class.
136   */
137  private static final long serialVersionUID = 2555047334281707615L;
138
139
140
141  /**
142   * Creates a new UnboundID root DSE object from the information in the
143   * provided entry.
144   *
145   * @param  rootDSEEntry  The entry to use to create this UnboundID root DSE
146   *                       object.  It must not be {@code null}.
147   */
148  public UnboundIDRootDSE(final Entry rootDSEEntry)
149  {
150    super(rootDSEEntry);
151  }
152
153
154
155  /**
156   * Retrieves the root DSE from an UnboundID server using the provided
157   * connection.
158   *
159   * @param  connection  The connection to use to retrieve the server root DSE.
160   *
161   * @return The UnboundID server root DSE, or {@code null} if it is not
162   *          available (e.g., the client does not have permission to read the
163   *          entry).
164   *
165   * @throws LDAPException  If a problem occurs while attempting to retrieve
166   *                         the server root DSE.
167   */
168  public static UnboundIDRootDSE getRootDSE(final LDAPInterface connection)
169       throws LDAPException
170  {
171    final Entry rootDSEEntry = connection.getEntry("", REQUEST_ATTRS);
172    if (rootDSEEntry == null)
173    {
174      return null;
175    }
176
177    return new UnboundIDRootDSE(rootDSEEntry);
178  }
179
180
181
182  /**
183   * Retrieves a digest of the baseline configuration for the software version
184   * the server is currently running.
185   *
186   * @return The server's baseline configuration digest, or {@code null} if
187   *          that information is not available.
188   */
189  public String getBaselineConfigurationDigest()
190  {
191    return getAttributeValue(ATTR_BASELINE_CONFIG_DIGEST);
192  }
193
194
195
196  /**
197   * Retrieves a digest of the configuration model for the software version the
198   * server is currently running.
199   *
200   * @return The server's configuration model digest, or {@code null} if that
201   *          information is not available.
202   */
203  public String getConfigurationModelDigest()
204  {
205    return getAttributeValue(ATTR_CONFIG_MODEL_DIGEST);
206  }
207
208
209
210  /**
211   * Retrieves the unique name assigned to the server instance.
212   *
213   * @return The unique name assigned to the server instance, or {@code null}
214   *          if that information is not available.
215   */
216  public String getInstanceName()
217  {
218    return getAttributeValue(ATTR_INSTANCE_NAME);
219  }
220
221
222
223  /**
224   * Retrieves the DNs of the private naming contexts, which identify base DNs
225   * for content in the server that is not intended to be accessed by normal
226   * clients but instead provides some alternate function like administration
227   * or monitoring.
228   *
229   * @return The DNs of the private naming contexts, or {@code null} if that
230   *          information is not available.
231   */
232  public String[] getPrivateNamingContexts()
233  {
234    return getAttributeValues(ATTR_PRIVATE_NAMING_CONTEXTS);
235  }
236
237
238
239  /**
240   * Retrieves a unique identifier that the server generated at startup and can
241   * be used to determine whether a server has been restarted.
242   *
243   * @return The server's startup UUID, or {@code null} if that information is
244   *          not available.
245   */
246  public String getStartupUUID()
247  {
248    return getAttributeValue(ATTR_STARTUP_UUID);
249  }
250
251
252
253  /**
254   * Retrieves the names of the supported one-time password delivery mechanisms.
255   *
256   * @return The names of the supported one-time password delivery mechanisms,
257   *          or {@code null} if that information is not available.
258   */
259  public String[] getSupportedOTPDeliveryMechanisms()
260  {
261    return getAttributeValues(ATTR_SUPPORTED_OTP_DELIVERY_MECHANISM);
262  }
263
264
265
266  /**
267   * Indicates whether the directory server indicates that it supports the
268   * specified one-time password delivery mechanism.
269   *
270   * @param  mechanismName  The name of the delivery mechanism for which to make
271   *                        the determination.  It must not be {@code null}.
272   *
273   * @return  {@code true} if the server indicates that it supports the
274   *          specified one-time password delivery mechanism, or {@code false}
275   *          if it does not.
276   */
277  public boolean supportsOTPDeliveryMechanism(final String mechanismName)
278  {
279    return hasAttributeValue(ATTR_SUPPORTED_OTP_DELIVERY_MECHANISM,
280         mechanismName);
281  }
282}