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