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