001/* 002 * Copyright 2009-2018 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2009-2018 Ping Identity Corporation 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 025import com.unboundid.util.StaticUtils; 026 027 028 029/** 030 * This enumeration defines a set of options that indicate how the value of a 031 * field or getter method may be used in the process of constructing a search 032 * filter. The resulting filter will be constructed as a logical AND of 033 * equality components created from the structural object class and any 034 * auxiliary classes, as well as equality components created from the values of 035 * fields with the {@link LDAPField} annotation type and/or the return values of 036 * methods with the {@link LDAPGetter} annotation type. 037 * <BR><BR> 038 * If a class has any fields or getter methods with a filter usage of 039 * {@code REQUIRED}, then all fields and/or getter methods marked as 040 * {@code REQUIRED} must have a non-{@code null} value and will be included in 041 * the filter, and any other fields or getter methods marked as 042 * {@code ALWAYS_ALLOWED} or {@code CONDITIONALLY_ALLOWED} with non-{@code null} 043 * values will be included in the filter as well. 044 * <BR><BR> 045 * If a class does not have any fields or getter methods that are marked 046 * {@code REQUIRED}, then at least one field or getter method marked 047 * {@code ALWAYS_ALLOWED} must have a non-{@code null} value in order to 048 * generate a search filter from that object, and the resulting filter will 049 * contain components for all non-{@code null} fields and/or getter methods 050 * marked {@code ALWAYS_ALLOWED} or {@code CONDITIONALLY_ALLOWED}. If an object 051 * does not have any non-{@code null} fields or getter methods marked 052 * {@code REQUIRED} or {@code ALWAYS_ALLOWED}, then it will not be possible to 053 * generate a search filter from that object. 054 */ 055public enum FilterUsage 056{ 057 /** 058 * Indicates that the associated field or getter method must have a value in 059 * an object in order to be able to generate a search filter from that object. 060 * If an attempt is made to generate a search filter from an object that does 061 * not have a value for the associated field or getter method, then an 062 * exception will be thrown. 063 */ 064 REQUIRED, 065 066 067 068 /** 069 * Indicates that the associated field or getter method may always be included 070 * in a search filter if it has a value, regardless of whether any other 071 * fields or getter methods in the object may have values. If the associated 072 * field or getter method does not have a value, then it will be excluded from 073 * the generated search filter. It is generally recommended that the 074 * corresponding attribute be indexed for equality in the directory server, or 075 * that the server otherwise be configured to perform fast equality searches 076 * for filters containing this attribute. 077 */ 078 ALWAYS_ALLOWED, 079 080 081 082 /** 083 * Indicates that the associated field or getter method may be included in a 084 * generated search filter if it has a non-{@code null} value, and if at least 085 * one field or getter method marked {@code REQUIRED} or 086 * {@code ALWAYS_ALLOWED} has a non-{@code null} value. This usage indicates 087 * that the associated field or getter method may be used to help refine a 088 * search filter, but is not sufficient to be included in a search filter by 089 * itself. 090 */ 091 CONDITIONALLY_ALLOWED, 092 093 094 095 /** 096 * Indicates that the associated field or getter method will never be included 097 * in a search filter generated from an object, regardless of whether it has a 098 * value in that object. 099 */ 100 EXCLUDED; 101 102 103 104 /** 105 * Retrieves the filter usage with the specified name. 106 * 107 * @param name The name of the filter usage to retrieve. It must not be 108 * {@code null}. 109 * 110 * @return The requested filter usage, or {@code null} if no such usage is 111 * defined. 112 */ 113 public static FilterUsage forName(final String name) 114 { 115 switch (StaticUtils.toLowerCase(name)) 116 { 117 case "required": 118 return REQUIRED; 119 case "alwaysallowed": 120 case "always-allowed": 121 case "always_allowed": 122 return ALWAYS_ALLOWED; 123 case "conditionallyallowed": 124 case "conditionally-allowed": 125 case "conditionally_allowed": 126 return CONDITIONALLY_ALLOWED; 127 case "excluded": 128 return EXCLUDED; 129 default: 130 return null; 131 } 132 } 133}