001/*
002 * Copyright 2009-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2009-2014 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 */
021package 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 */
051public 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}