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