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