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 }