001/*
002 * Copyright 2014-2023 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2014-2023 Ping Identity Corporation
007 *
008 * Licensed under the Apache License, Version 2.0 (the "License");
009 * you may not use this file except in compliance with the License.
010 * You may obtain a copy of the License at
011 *
012 *    http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020/*
021 * Copyright (C) 2014-2023 Ping Identity Corporation
022 *
023 * This program is free software; you can redistribute it and/or modify
024 * it under the terms of the GNU General Public License (GPLv2 only)
025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
026 * as published by the Free Software Foundation.
027 *
028 * This program is distributed in the hope that it will be useful,
029 * but WITHOUT ANY WARRANTY; without even the implied warranty of
030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
031 * GNU General Public License for more details.
032 *
033 * You should have received a copy of the GNU General Public License
034 * along with this program; if not, see <http://www.gnu.org/licenses>.
035 */
036package com.unboundid.ldap.sdk.unboundidds.controls;
037
038
039
040import com.unboundid.util.NotNull;
041import com.unboundid.util.Nullable;
042import com.unboundid.util.StaticUtils;
043import com.unboundid.util.ThreadSafety;
044import com.unboundid.util.ThreadSafetyLevel;
045
046
047
048/**
049 * This enum defines the set of count types that may be used in a matching entry
050 * count response control.
051 * <BR>
052 * <BLOCKQUOTE>
053 *   <B>NOTE:</B>  This class, and other classes within the
054 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
055 *   supported for use against Ping Identity, UnboundID, and
056 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
057 *   for proprietary functionality or for external specifications that are not
058 *   considered stable or mature enough to be guaranteed to work in an
059 *   interoperable way with other types of LDAP servers.
060 * </BLOCKQUOTE>
061 */
062@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
063public enum MatchingEntryCountType
064{
065  /**
066   * The count type that indicates that the server was able to determine the
067   * exact number of entries matching the search criteria and examined them to
068   * exclude any entries that would not be returned to the client in the course
069   * of processing a normal search with the same criteria.
070   */
071  EXAMINED_COUNT((byte) 0x80),
072
073
074
075  /**
076   * The count type that indicates that the server was able to determine the
077   * exact number of entries matching the search criteria, but did not examine
078   * them to exclude any entries that might not actually be returned to the
079   * client in the course of processing a normal search with the same criteria
080   * (e.g., entries that the requester doesn't have permission to access, or
081   * entries like LDAP subentries, replication conflict entries, or soft-deleted
082   * entries that are returned only for special types of requests).
083   */
084  UNEXAMINED_COUNT((byte) 0x81),
085
086
087
088  /**
089   * The count type that indicates that the server was unable to determine the
090   * exact number of entries matching the search criteria, but was able to
091   * determine an upper bound for the number of matching entries.
092   */
093  UPPER_BOUND((byte) 0x82),
094
095
096
097  /**
098   * The count type that indicates that the server was unable to make any
099   * meaningful determination about the number of entries matching the search
100   * criteria.
101   */
102  UNKNOWN((byte) 0x83);
103
104
105
106  // The BER type that corresponds to this enum value.
107  private final byte berType;
108
109
110
111  /**
112   * Creates a new count type value with the provided information.
113   *
114   * @param  berType  The BER type that corresponds to this enum value.
115   */
116  MatchingEntryCountType(final byte berType)
117  {
118    this.berType = berType;
119  }
120
121
122
123  /**
124   * Retrieves the BER type for this count type value.
125   *
126   * @return  The BER type for this count type value.
127   */
128  public byte getBERType()
129  {
130    return berType;
131  }
132
133
134
135  /**
136   * Indicates whether this matching entry count type is considered more
137   * specific than the provided count type.  The following order of precedence,
138   * from most specific to least specific, will be used:
139   * <OL>
140   *   <LI>EXAMINED_COUNT</LI>
141   *   <LI>UNEXAMINED_COUNT</LI>
142   *   <LI>UPPER_BOUND</LI>
143   *   <LI>UNKNOWN</LI>
144   * </OL>
145   *
146   * @param  t  The matching entry count type value to compare against this
147   *            matching entry count type.  It must not be {@code null}.
148   *
149   * @return  {@code true} if the provided matching entry count type value is
150   *          considered more specific than this matching entry count type, or
151   *          {@code false} if the provided count type is the same as or less
152   *          specific than this count type.
153   */
154  public boolean isMoreSpecificThan(@NotNull final MatchingEntryCountType t)
155  {
156    switch (this)
157    {
158      case EXAMINED_COUNT:
159        return (t != EXAMINED_COUNT);
160
161      case UNEXAMINED_COUNT:
162        return ((t != EXAMINED_COUNT) && (t != UNEXAMINED_COUNT));
163
164      case UPPER_BOUND:
165        return ((t != EXAMINED_COUNT) && (t != UNEXAMINED_COUNT) &&
166                (t != UPPER_BOUND));
167
168      case UNKNOWN:
169      default:
170        return false;
171    }
172  }
173
174
175
176  /**
177   * Indicates whether this matching entry count type is considered less
178   * specific than the provided count type.  The following order of precedence,
179   * from most specific to least specific, will be used:
180   * <OL>
181   *   <LI>EXAMINED_COUNT</LI>
182   *   <LI>UNEXAMINED_COUNT</LI>
183   *   <LI>UPPER_BOUND</LI>
184   *   <LI>UNKNOWN</LI>
185   * </OL>
186   *
187   * @param  t  The matching entry count type value to compare against this
188   *            matching entry count type.  It must not be {@code null}.
189   *
190   * @return  {@code true} if the provided matching entry count type value is
191   *          considered less specific than this matching entry count type, or
192   *          {@code false} if the provided count type is the same as or more
193   *          specific than this count type.
194   */
195  public boolean isLessSpecificThan(@NotNull final MatchingEntryCountType t)
196  {
197    switch (this)
198    {
199      case UNKNOWN:
200        return (t != UNKNOWN);
201
202      case UPPER_BOUND:
203        return ((t != UNKNOWN) && (t != UPPER_BOUND));
204
205      case UNEXAMINED_COUNT:
206        return ((t != UNKNOWN) && (t != UPPER_BOUND) &&
207                (t != UNEXAMINED_COUNT));
208
209      case EXAMINED_COUNT:
210      default:
211        return false;
212    }
213  }
214
215
216
217  /**
218   * Retrieves the count type value for the provided BER type.
219   *
220   * @param  berType  The BER type for the count type value to retrieve.
221   *
222   * @return  The count type value that corresponds to the provided BER type, or
223   *          {@code null} if there is no corresponding count type value.
224   */
225  @Nullable()
226  public static MatchingEntryCountType valueOf(final byte berType)
227  {
228    for (final MatchingEntryCountType t : values())
229    {
230      if (t.berType == berType)
231      {
232        return t;
233      }
234    }
235
236    return null;
237  }
238
239
240
241  /**
242   * Retrieves the matching entry count type with the specified name.
243   *
244   * @param  name  The name of the matching entry count type to retrieve.  It
245   *               must not be {@code null}.
246   *
247   * @return  The requested matching entry count type, or {@code null} if no
248   *          such type is defined.
249   */
250  @Nullable()
251  public static MatchingEntryCountType forName(@NotNull final String name)
252  {
253    switch (StaticUtils.toLowerCase(name))
254    {
255      case "examinedcount":
256      case "examined-count":
257      case "examined_count":
258        return EXAMINED_COUNT;
259      case "unexaminedcount":
260      case "unexamined-count":
261      case "unexamined_count":
262        return UNEXAMINED_COUNT;
263      case "upperbound":
264      case "upper-bound":
265      case "upper_bound":
266        return UPPER_BOUND;
267      case "unknown":
268        return UNKNOWN;
269      default:
270        return null;
271    }
272  }
273}