001/*
002 * Copyright 2014-2018 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2018 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.controls;
022
023
024
025import com.unboundid.util.StaticUtils;
026import com.unboundid.util.ThreadSafety;
027import com.unboundid.util.ThreadSafetyLevel;
028
029
030
031/**
032 * This enum defines the set of count types that may be used in a matching entry
033 * count response control.
034 * <BR>
035 * <BLOCKQUOTE>
036 *   <B>NOTE:</B>  This class, and other classes within the
037 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
038 *   supported for use against Ping Identity, UnboundID, and Alcatel-Lucent 8661
039 *   server products.  These classes provide support for proprietary
040 *   functionality or for external specifications that are not considered stable
041 *   or mature enough to be guaranteed to work in an interoperable way with
042 *   other types of LDAP servers.
043 * </BLOCKQUOTE>
044 */
045@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
046public enum MatchingEntryCountType
047{
048  /**
049   * The count type that indicates that the server was able to determine the
050   * exact number of entries matching the search criteria and examined them to
051   * exclude any entries that would not be returned to the client in the course
052   * of processing a normal search with the same criteria.
053   */
054  EXAMINED_COUNT((byte) 0x80),
055
056
057
058  /**
059   * The count type that indicates that the server was able to determine the
060   * exact number of entries matching the search criteria, but did not examine
061   * them to exclude any entries that might not actually be returned to the
062   * client in the course of processing a normal search with the same criteria
063   * (e.g., entries that the requester doesn't have permission to access, or
064   * entries like LDAP subentries, replication conflict entries, or soft-deleted
065   * entries that are returned only for special types of requests).
066   */
067  UNEXAMINED_COUNT((byte) 0x81),
068
069
070
071  /**
072   * The count type that indicates that the server was unable to determine the
073   * exact number of entries matching the search criteria, but was able to
074   * determine an upper bound for the number of matching entries.
075   */
076  UPPER_BOUND((byte) 0x82),
077
078
079
080  /**
081   * The count type that indicates that the server was unable to make any
082   * meaningful determination about the number of entries matching the search
083   * criteria.
084   */
085  UNKNOWN((byte) 0x83);
086
087
088
089  // The BER type that corresponds to this enum value.
090  private final byte berType;
091
092
093
094  /**
095   * Creates a new count type value with the provided information.
096   *
097   * @param  berType  The BER type that corresponds to this enum value.
098   */
099  MatchingEntryCountType(final byte berType)
100  {
101    this.berType = berType;
102  }
103
104
105
106  /**
107   * Retrieves the BER type for this count type value.
108   *
109   * @return  The BER type for this count type value.
110   */
111  public byte getBERType()
112  {
113    return berType;
114  }
115
116
117
118  /**
119   * Indicates whether this matching entry count type is considered more
120   * specific than the provided count type.  The following order of precedence,
121   * from most specific to least specific, will be used:
122   * <OL>
123   *   <LI>EXAMINED_COUNT</LI>
124   *   <LI>UNEXAMINED_COUNT</LI>
125   *   <LI>UPPER_BOUND</LI>
126   *   <LI>UNKNOWN</LI>
127   * </OL>
128   *
129   * @param  t  The matching entry count type value to compare against this
130   *            matching entry count type.  It must not be {@code null}.
131   *
132   * @return  {@code true} if the provided matching entry count type value is
133   *          considered more specific than this matching entry count type, or
134   *          {@code false} if the provided count type is the same as or less
135   *          specific than this count type.
136   */
137  public boolean isMoreSpecificThan(final MatchingEntryCountType t)
138  {
139    switch (this)
140    {
141      case EXAMINED_COUNT:
142        return (t != EXAMINED_COUNT);
143
144      case UNEXAMINED_COUNT:
145        return ((t != EXAMINED_COUNT) && (t != UNEXAMINED_COUNT));
146
147      case UPPER_BOUND:
148        return ((t != EXAMINED_COUNT) && (t != UNEXAMINED_COUNT) &&
149                (t != UPPER_BOUND));
150
151      case UNKNOWN:
152      default:
153        return false;
154    }
155  }
156
157
158
159  /**
160   * Indicates whether this matching entry count type is considered less
161   * specific than the provided count type.  The following order of precedence,
162   * from most specific to least specific, will be used:
163   * <OL>
164   *   <LI>EXAMINED_COUNT</LI>
165   *   <LI>UNEXAMINED_COUNT</LI>
166   *   <LI>UPPER_BOUND</LI>
167   *   <LI>UNKNOWN</LI>
168   * </OL>
169   *
170   * @param  t  The matching entry count type value to compare against this
171   *            matching entry count type.  It must not be {@code null}.
172   *
173   * @return  {@code true} if the provided matching entry count type value is
174   *          considered less specific than this matching entry count type, or
175   *          {@code false} if the provided count type is the same as or more
176   *          specific than this count type.
177   */
178  public boolean isLessSpecificThan(final MatchingEntryCountType t)
179  {
180    switch (this)
181    {
182      case UNKNOWN:
183        return (t != UNKNOWN);
184
185      case UPPER_BOUND:
186        return ((t != UNKNOWN) && (t != UPPER_BOUND));
187
188      case UNEXAMINED_COUNT:
189        return ((t != UNKNOWN) && (t != UPPER_BOUND) &&
190                (t != UNEXAMINED_COUNT));
191
192      case EXAMINED_COUNT:
193      default:
194        return false;
195    }
196  }
197
198
199
200  /**
201   * Retrieves the count type value for the provided BER type.
202   *
203   * @param  berType  The BER type for the count type value to retrieve.
204   *
205   * @return  The count type value that corresponds to the provided BER type, or
206   *          {@code null} if there is no corresponding count type value.
207   */
208  public static MatchingEntryCountType valueOf(final byte berType)
209  {
210    for (final MatchingEntryCountType t : values())
211    {
212      if (t.berType == berType)
213      {
214        return t;
215      }
216    }
217
218    return null;
219  }
220
221
222
223  /**
224   * Retrieves the matching entry count type with the specified name.
225   *
226   * @param  name  The name of the matching entry count type to retrieve.  It
227   *               must not be {@code null}.
228   *
229   * @return  The requested matching entry count type, or {@code null} if no
230   *          such type is defined.
231   */
232  public static MatchingEntryCountType forName(final String name)
233  {
234    switch (StaticUtils.toLowerCase(name))
235    {
236      case "examinedcount":
237      case "examined-count":
238      case "examined_count":
239        return EXAMINED_COUNT;
240      case "unexaminedcount":
241      case "unexamined-count":
242      case "unexamined_count":
243        return UNEXAMINED_COUNT;
244      case "upperbound":
245      case "upper-bound":
246      case "upper_bound":
247        return UPPER_BOUND;
248      case "unknown":
249        return UNKNOWN;
250      default:
251        return null;
252    }
253  }
254}