001    /*
002     * Copyright 2009-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2009-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.persist;
022    
023    
024    
025    /**
026     * This enumeration defines a set of options that indicate how the value of a
027     * field or getter method may be used in the process of constructing a search
028     * filter.  The resulting filter will be constructed as a logical AND of
029     * equality components created from the structural object class and any
030     * auxiliary classes, as well as equality components created from the values of
031     * fields with the {@link LDAPField} annotation type and/or the return values of
032     * methods with the {@link LDAPGetter} annotation type.
033     * <BR><BR>
034     * If a class has any fields or getter methods with a filter usage of
035     * {@code REQUIRED}, then all fields and/or getter methods marked as
036     * {@code REQUIRED} must have a non-{@code null} value and will be included in
037     * the filter, and any other fields or getter methods marked as
038     * {@code ALWAYS_ALLOWED} or {@code CONDITIONALLY_ALLOWED} with non-{@code null}
039     * values will be included in the filter as well.
040     * <BR><BR>
041     * If a class does not have any fields or getter methods that are marked
042     * {@code REQUIRED}, then at least one field or getter method marked
043     * {@code ALWAYS_ALLOWED} must have a non-{@code null} value in order to
044     * generate a search filter from that object, and the resulting filter will
045     * contain components for all non-{@code null} fields and/or getter methods
046     * marked {@code ALWAYS_ALLOWED} or {@code CONDITIONALLY_ALLOWED}.  If an object
047     * does not have any non-{@code null} fields or getter methods marked
048     * {@code REQUIRED} or {@code ALWAYS_ALLOWED}, then it will not be possible to
049     * generate a search filter from that object.
050     */
051    public enum FilterUsage
052    {
053      /**
054       * Indicates that the associated field or getter method must have a value in
055       * an object in order to be able to generate a search filter from that object.
056       * If an attempt is made to generate a search filter from an object that does
057       * not have a value for the associated field or getter method, then an
058       * exception will be thrown.
059       */
060      REQUIRED,
061    
062    
063    
064      /**
065       * Indicates that the associated field or getter method may always be included
066       * in a search filter if it has a value, regardless of whether any other
067       * fields or getter methods in the object may have values.  If the associated
068       * field or getter method does not have a value, then it will be excluded from
069       * the generated search filter.  It is generally recommended that the
070       * corresponding attribute be indexed for equality in the directory server, or
071       * that the server otherwise be configured to perform fast equality searches
072       * for filters containing this attribute.
073       */
074      ALWAYS_ALLOWED,
075    
076    
077    
078      /**
079       * Indicates that the associated field or getter method may be included in a
080       * generated search filter if it has a non-{@code null} value, and if at least
081       * one field or getter method marked {@code REQUIRED} or
082       * {@code ALWAYS_ALLOWED} has a non-{@code null} value.  This usage indicates
083       * that the associated field or getter method may be used to help refine a
084       * search filter, but is not sufficient to be included in a search filter by
085       * itself.
086       */
087      CONDITIONALLY_ALLOWED,
088    
089    
090    
091      /**
092       * Indicates that the associated field or getter method will never be included
093       * in a search filter generated from an object, regardless of whether it has a
094       * value in that object.
095       */
096      EXCLUDED;
097    }