001/* 002 * Copyright 2009-2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2009-2020 Ping Identity Corporation 007 * 008 * Licensed under the Apache License, Version 2.0 (the "License"); 009 * you may not use this file except in compliance with the License. 010 * You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, software 015 * distributed under the License is distributed on an "AS IS" BASIS, 016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 017 * See the License for the specific language governing permissions and 018 * limitations under the License. 019 */ 020/* 021 * Copyright (C) 2009-2020 Ping Identity Corporation 022 * 023 * This program is free software; you can redistribute it and/or modify 024 * it under the terms of the GNU General Public License (GPLv2 only) 025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 026 * as published by the Free Software Foundation. 027 * 028 * This program is distributed in the hope that it will be useful, 029 * but WITHOUT ANY WARRANTY; without even the implied warranty of 030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 031 * GNU General Public License for more details. 032 * 033 * You should have received a copy of the GNU General Public License 034 * along with this program; if not, see <http://www.gnu.org/licenses>. 035 */ 036package com.unboundid.ldap.sdk.persist; 037 038 039 040import com.unboundid.util.StaticUtils; 041 042 043 044/** 045 * This enumeration defines a set of options that indicate how the value of a 046 * field or getter method may be used in the process of constructing a search 047 * filter. The resulting filter will be constructed as a logical AND of 048 * equality components created from the structural object class and any 049 * auxiliary classes, as well as equality components created from the values of 050 * fields with the {@link LDAPField} annotation type and/or the return values of 051 * methods with the {@link LDAPGetter} annotation type. 052 * <BR><BR> 053 * If a class has any fields or getter methods with a filter usage of 054 * {@code REQUIRED}, then all fields and/or getter methods marked as 055 * {@code REQUIRED} must have a non-{@code null} value and will be included in 056 * the filter, and any other fields or getter methods marked as 057 * {@code ALWAYS_ALLOWED} or {@code CONDITIONALLY_ALLOWED} with non-{@code null} 058 * values will be included in the filter as well. 059 * <BR><BR> 060 * If a class does not have any fields or getter methods that are marked 061 * {@code REQUIRED}, then at least one field or getter method marked 062 * {@code ALWAYS_ALLOWED} must have a non-{@code null} value in order to 063 * generate a search filter from that object, and the resulting filter will 064 * contain components for all non-{@code null} fields and/or getter methods 065 * marked {@code ALWAYS_ALLOWED} or {@code CONDITIONALLY_ALLOWED}. If an object 066 * does not have any non-{@code null} fields or getter methods marked 067 * {@code REQUIRED} or {@code ALWAYS_ALLOWED}, then it will not be possible to 068 * generate a search filter from that object. 069 */ 070public enum FilterUsage 071{ 072 /** 073 * Indicates that the associated field or getter method must have a value in 074 * an object in order to be able to generate a search filter from that object. 075 * If an attempt is made to generate a search filter from an object that does 076 * not have a value for the associated field or getter method, then an 077 * exception will be thrown. 078 */ 079 REQUIRED, 080 081 082 083 /** 084 * Indicates that the associated field or getter method may always be included 085 * in a search filter if it has a value, regardless of whether any other 086 * fields or getter methods in the object may have values. If the associated 087 * field or getter method does not have a value, then it will be excluded from 088 * the generated search filter. It is generally recommended that the 089 * corresponding attribute be indexed for equality in the directory server, or 090 * that the server otherwise be configured to perform fast equality searches 091 * for filters containing this attribute. 092 */ 093 ALWAYS_ALLOWED, 094 095 096 097 /** 098 * Indicates that the associated field or getter method may be included in a 099 * generated search filter if it has a non-{@code null} value, and if at least 100 * one field or getter method marked {@code REQUIRED} or 101 * {@code ALWAYS_ALLOWED} has a non-{@code null} value. This usage indicates 102 * that the associated field or getter method may be used to help refine a 103 * search filter, but is not sufficient to be included in a search filter by 104 * itself. 105 */ 106 CONDITIONALLY_ALLOWED, 107 108 109 110 /** 111 * Indicates that the associated field or getter method will never be included 112 * in a search filter generated from an object, regardless of whether it has a 113 * value in that object. 114 */ 115 EXCLUDED; 116 117 118 119 /** 120 * Retrieves the filter usage with the specified name. 121 * 122 * @param name The name of the filter usage to retrieve. It must not be 123 * {@code null}. 124 * 125 * @return The requested filter usage, or {@code null} if no such usage is 126 * defined. 127 */ 128 public static FilterUsage forName(final String name) 129 { 130 switch (StaticUtils.toLowerCase(name)) 131 { 132 case "required": 133 return REQUIRED; 134 case "alwaysallowed": 135 case "always-allowed": 136 case "always_allowed": 137 return ALWAYS_ALLOWED; 138 case "conditionallyallowed": 139 case "conditionally-allowed": 140 case "conditionally_allowed": 141 return CONDITIONALLY_ALLOWED; 142 case "excluded": 143 return EXCLUDED; 144 default: 145 return null; 146 } 147 } 148}