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