001/*
002 * Copyright 2014-2020 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2014-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) 2015-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.unboundidds.controls;
037
038
039
040import com.unboundid.util.StaticUtils;
041import com.unboundid.util.ThreadSafety;
042import com.unboundid.util.ThreadSafetyLevel;
043
044
045
046/**
047 * This enum defines the options that may be specified to indicate whether and
048 * when to acquire an exclusive lock in the target backend when processing a
049 * transaction.
050 * <BR>
051 * <BLOCKQUOTE>
052 *   <B>NOTE:</B>  This class, and other classes within the
053 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
054 *   supported for use against Ping Identity, UnboundID, and
055 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
056 *   for proprietary functionality or for external specifications that are not
057 *   considered stable or mature enough to be guaranteed to work in an
058 *   interoperable way with other types of LDAP servers.
059 * </BLOCKQUOTE>
060 *
061 * @see TransactionSettingsRequestControl
062 */
063@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
064public enum TransactionSettingsBackendLockBehavior
065{
066  /**
067   * Indicates that the server should not make any attempt to acquire an
068   * exclusive lock in the target backend, whether during the initial attempt or
069   * a subsequent retry.  This will allow the highest level of concurrency for
070   * operations within the backend, but may increase the risk of lock conflicts
071   * between transactions in a server processing many operations concurrently.
072   * This risk may be mitigated by indicating that the transaction should be
073   * retried one or more times.
074   */
075  DO_NOT_ACQUIRE(0),
076
077
078
079  /**
080   * Indicates that if the server is unable to successfully commit the
081   * associated transaction after one or more attempts without holding an
082   * exclusive lock in the target backend, then it should make one more attempt
083   * after acquiring the lock.  This will avoid the need to acquire the lock
084   * unless the maximum number of attempts have been unsuccessful without it.
085   */
086  ACQUIRE_AFTER_RETRIES(1),
087
088
089
090  /**
091   * Indicates that if the server is unable to successfully commit the
092   * associated transaction after the first attempt without holding an exclusive
093   * lock in the target backend, then it should make one or more
094   * additional attempts (as specified by the requested number of retries) after
095   * acquiring the lock.  This will avoid the need to acquire the lock for
096   * operations that can be completed on the first attempt without it.
097   */
098  ACQUIRE_BEFORE_RETRIES(2),
099
100
101
102  /**
103   * Indicates that the server should acquire an exclusive lock in the target
104   * backend before performing any backend processing for the operation.  This
105   * will limit concurrency, as the backend will not be able to process any
106   * other operation while the associated operation is in progress, but this
107   * will also minimize the chance of a thread deadlock or lock timeout as a
108   * result of a conflict between database interactions from multiple
109   * simultaneous operations.
110   */
111  ACQUIRE_BEFORE_INITIAL_ATTEMPT(3);
112
113
114
115  // The integer value for this backend lock behavior.
116  private final int intValue;
117
118
119
120  /**
121   * Creates a new transaction settings backend lock behavior with the provided
122   * integer value.
123   *
124   * @param  intValue  The integer value for this backend lock behavior.
125   */
126  TransactionSettingsBackendLockBehavior(final int intValue)
127  {
128    this.intValue = intValue;
129  }
130
131
132
133  /**
134   * Retrieves the integer value for this transaction settings backend lock
135   * behavior value.
136   *
137   * @return  The integer value for this transaction settings backend lock
138   *          behavior value.
139   */
140  public int intValue()
141  {
142    return intValue;
143  }
144
145
146
147  /**
148   * Retrieves the backend lock behavior value with the specified integer value.
149   *
150   * @param  intValue  The integer value for the backend lock behavior to
151   *                   retrieve.
152   *
153   * @return  The backend lock behavior value with the specified integer value,
154   *          or {@code null} if there is no such backend lock behavior value.
155   */
156  public static TransactionSettingsBackendLockBehavior
157                     valueOf(final int intValue)
158  {
159    for (final TransactionSettingsBackendLockBehavior v : values())
160    {
161      if (v.intValue == intValue)
162      {
163        return v;
164      }
165    }
166
167    return null;
168  }
169
170
171
172  /**
173   * Retrieves the transaction settings backend lock behavior with the specified
174   * name.
175   *
176   * @param  name  The name of the transaction settings backend lock behavior to
177   *               retrieve.  It must not be {@code null}.
178   *
179   * @return  The requested transaction settings backend lock behavior, or
180   *          {@code null} if no such behavior is defined.
181   */
182  public static TransactionSettingsBackendLockBehavior forName(
183                                                            final String name)
184  {
185    switch (StaticUtils.toLowerCase(name))
186    {
187      case "donotacquire":
188      case "do-not-acquire":
189      case "do_not_acquire":
190        return DO_NOT_ACQUIRE;
191      case "acquireafterretries":
192      case "acquire-after-retries":
193      case "acquire_after_retries":
194        return ACQUIRE_AFTER_RETRIES;
195      case "acquirebeforeretries":
196      case "acquire-before-retries":
197      case "acquire_before_retries":
198        return ACQUIRE_BEFORE_RETRIES;
199      case "acquirebeforeinitialattempt":
200      case "acquire-before-initial-attempt":
201      case "acquire_before_initial_attempt":
202        return ACQUIRE_BEFORE_INITIAL_ATTEMPT;
203      default:
204        return null;
205    }
206  }
207}