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}