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