001 /*
002 * Copyright 2014-2015 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2015 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 */
021 package com.unboundid.ldap.sdk.unboundidds.controls;
022
023
024
025 import com.unboundid.ldap.sdk.Control;
026 import com.unboundid.ldap.sdk.LDAPException;
027 import com.unboundid.ldap.sdk.ResultCode;
028 import com.unboundid.util.NotMutable;
029 import com.unboundid.util.ThreadSafety;
030 import com.unboundid.util.ThreadSafetyLevel;
031
032 import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*;
033
034
035
036 /**
037 * <BLOCKQUOTE>
038 * <B>NOTE:</B> This class is part of the Commercial Edition of the UnboundID
039 * LDAP SDK for Java. It is not available for use in applications that
040 * include only the Standard Edition of the LDAP SDK, and is not supported for
041 * use in conjunction with non-UnboundID products.
042 * </BLOCKQUOTE>
043 * This class provides a request control which may be used to request that the
044 * Directory Proxy Server return the backend set IDs for the entry-balancing
045 * backend set(s) in which an operation was processed successfully. It may be
046 * used in conjunction with the route to backend set request control in order
047 * to specify which backend set(s) should be used to process an operation.
048 * <BR><BR>
049 * This control may be used for a number of different kinds of requests,
050 * including:
051 * <UL>
052 * <LI>If an add request includes a get backend set ID request control, the
053 * add response will include a get backend set ID response control if the
054 * entry was successfully added to an entry-balanced data set.</LI>
055 * <LI>If a simple bind request includes a get backend set ID request control,
056 * the bind response will include a get backend set ID response control if
057 * the authentication was successful and the entry for the authenticated
058 * user exists in an entry-balanced data set. This control is currently
059 * not supported for use with SASL bind operations.</LI>
060 * <LI>If a compare request includes a get backend set ID request control, the
061 * compare response will include a get backend set ID response control if
062 * the result code is either COMPARE_TRUE or COMPARE_FALSE and the target
063 * entry exists in an entry-balanced data set.</LI>
064 * <LI>If a delete request includes a get backend set ID request control, the
065 * delete response will include a get backend set ID response control if
066 * the entry was successfully removed from an entry-balanced data
067 * set.</LI>
068 * <LI>If an atomic multi-update extended request includes a get backend set
069 * ID request control and the request is successfully processed through an
070 * entry-balancing request processor, then the extended response will
071 * include a get backend set ID response control. A non-atomic
072 * multi-update extended request should not include the get backend set ID
073 * request control in the extended operation itself, but may be attached
074 * to any or all of the requests inside the multi-update operation, in
075 * which case the server will return a multi-update response control
076 * attached to the corresponding successful responses.</LI>
077 * <LI>If an extended request includes a get backend set ID request control
078 * and that request is successfully processed by a proxied extended
079 * operation handler, then the extended response will include a get
080 * backend set ID response control indicating the backend set(s) that
081 * returned a success result during internal processing. Note that if the
082 * same extended request was processed by multiple entry-balancing
083 * request processors (i.e., if the deployment includes multiple
084 * entry-balanced subtrees), then the extended response may include a
085 * separate get backend set ID response control for each entry-balancing
086 * request processor used to process the request.</LI>
087 * <LI>If a modify request includes a get backend set ID request control, the
088 * modify response will include a get backend set ID response control if
089 * the entry was successfully modified in an entry-balanced data set.</LI>
090 * <LI>If a modify DN request includes a get backend set ID request control,
091 * the modify DN response will include a get backend set ID response
092 * control if the entry was successfully moved and/or renamed in an
093 * entry-balanced data set.</LI>
094 * <LI>If a modify DN request includes a get backend set ID request control,
095 * the modify DN response will include a get backend set ID response
096 * control if the entry was successfully moved and/or renamed in an
097 * entry-balanced data set.</LI>
098 * <LI>If a search request includes a get backend set ID request control, any
099 * search result entries retrieved from an entry-balanced data set will
100 * include a get backend set ID response control. The search result done
101 * message will not include a get backend set ID response control.</LI>
102 * </UL>
103 *
104 * Note the response for any operation involving an entry that exists outside of
105 * an entry-balanced dat set will not include a get backend set ID response
106 * control. Similarly, the response for any non-successful operation may not
107 * include a get backend set ID response control even if it involved processing
108 * in one or more backend sets. Also note that even if an entry exists in
109 * multiple backend sets (i.e., because it is at or above the balancing point),
110 * the get backend set ID response control may only include one backend set ID
111 * if only one backend set was accessed during the course of processing the
112 * operation.
113 * <BR><BR>
114 * The get backend set ID request control has an OID of
115 * "1.3.6.1.4.1.30221.2.5.33" and no value. It is recommended that the control
116 * be non-critical so that the associated operation may still be processed even
117 * if the target server does not support this control (and note that even if
118 * the server supports the control, the server may not return a response control
119 * if the operation was not successful or did not access entry-balanced data).
120 *
121 * @see GetBackendSetIDResponseControl
122 * @see RouteToBackendSetRequestControl
123 */
124 @NotMutable()
125 @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
126 public final class GetBackendSetIDRequestControl
127 extends Control
128 {
129 /**
130 * The OID (1.3.6.1.4.1.30221.2.5.33) for the get backend set ID request
131 * control.
132 */
133 public static final String GET_BACKEND_SET_ID_REQUEST_OID =
134 "1.3.6.1.4.1.30221.2.5.33";
135
136
137
138 /**
139 * The serial version UID for this serializable class.
140 */
141 private static final long serialVersionUID = 7874405591825684773L;
142
143
144
145 /**
146 * Creates a new get backend set ID request control. It will not be marked
147 * critical.
148 */
149 public GetBackendSetIDRequestControl()
150 {
151 this(false);
152 }
153
154
155
156 /**
157 * Creates a new get backend set ID request control with the specified
158 * criticality.
159 *
160 * @param isCritical Indicates whether this control should be marked
161 * critical.
162 */
163 public GetBackendSetIDRequestControl(final boolean isCritical)
164 {
165 super(GET_BACKEND_SET_ID_REQUEST_OID, isCritical, null);
166 }
167
168
169
170 /**
171 * Creates a new get backend set ID request control which is decoded from the
172 * provided generic control.
173 *
174 * @param control The generic control to be decoded as a get backend set ID
175 * request control.
176 *
177 * @throws LDAPException If the provided control cannot be decoded as a get
178 * backend set ID request control.
179 */
180 public GetBackendSetIDRequestControl(final Control control)
181 throws LDAPException
182 {
183 super(control);
184
185 if (control.hasValue())
186 {
187 throw new LDAPException(ResultCode.DECODING_ERROR,
188 ERR_GET_BACKEND_SET_ID_REQUEST_HAS_VALUE.get());
189 }
190 }
191
192
193
194 /**
195 * {@inheritDoc}
196 */
197 @Override()
198 public String getControlName()
199 {
200 return INFO_CONTROL_NAME_GET_BACKEND_SET_ID_REQUEST.get();
201 }
202
203
204
205 /**
206 * {@inheritDoc}
207 */
208 @Override()
209 public void toString(final StringBuilder buffer)
210 {
211 buffer.append("GetBackendSetIDRequestControl(isCritical=");
212 buffer.append(isCritical());
213 buffer.append(')');
214 }
215 }