001/* 002 * Copyright 2007-2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2007-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) 2008-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.controls; 037 038 039 040import com.unboundid.ldap.sdk.Control; 041import com.unboundid.ldap.sdk.LDAPException; 042import com.unboundid.ldap.sdk.ResultCode; 043import com.unboundid.util.NotMutable; 044import com.unboundid.util.ThreadSafety; 045import com.unboundid.util.ThreadSafetyLevel; 046 047import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 048 049 050 051/** 052 * This class provides an implementation of the subtree delete request control 053 * as defined in draft-armijo-ldap-treedelete. This can be used to delete an 054 * entry and all subordinate entries in a single operation. 055 * <BR><BR> 056 * Normally, if an entry has one or more subordinates, a directory server will 057 * refuse to delete it by rejecting the request with a 058 * {@link ResultCode#NOT_ALLOWED_ON_NONLEAF} result. In such cases, it is 059 * necessary to first recursively remove all of its subordinates before the 060 * target entry can be deleted. However, this subtree delete request control 061 * can be used to request that the server remove the entry and all subordinates 062 * as a single operation. For servers that support this control, it is 063 * generally much more efficient and convenient than removing all of the 064 * subordinate entries one at a time. 065 * <BR><BR> 066 * <H2>Example</H2> 067 * The following example demonstrates the use of the subtree delete control: 068 * <PRE> 069 * // First, try to delete an entry that has children, but don't include the 070 * // subtree delete control. This delete attempt should fail, and the 071 * // "NOT_ALLOWED_ON_NONLEAF" result is most appropriate if the failure reason 072 * // is that the entry has subordinates. 073 * DeleteRequest deleteRequest = 074 * new DeleteRequest("ou=entry with children,dc=example,dc=com"); 075 * LDAPResult resultWithoutControl; 076 * try 077 * { 078 * resultWithoutControl = connection.delete(deleteRequest); 079 * // We shouldn't get here because the delete should fail. 080 * } 081 * catch (LDAPException le) 082 * { 083 * // This is expected because the entry has children. 084 * resultWithoutControl = le.toLDAPResult(); 085 * ResultCode resultCode = le.getResultCode(); 086 * String errorMessageFromServer = le.getDiagnosticMessage(); 087 * } 088 * LDAPTestUtils.assertResultCodeEquals(resultWithoutControl, 089 * ResultCode.NOT_ALLOWED_ON_NONLEAF); 090 * 091 * // Update the delete request to include the subtree delete request control 092 * // and try again. 093 * deleteRequest.addControl(new SubtreeDeleteRequestControl()); 094 * LDAPResult resultWithControl; 095 * try 096 * { 097 * resultWithControl = connection.delete(deleteRequest); 098 * // The delete should no longer be rejected just because the target entry 099 * // has children. 100 * } 101 * catch (LDAPException le) 102 * { 103 * // The delete still failed for some other reason. 104 * resultWithControl = le.toLDAPResult(); 105 * ResultCode resultCode = le.getResultCode(); 106 * String errorMessageFromServer = le.getDiagnosticMessage(); 107 * } 108 * LDAPTestUtils.assertResultCodeEquals(resultWithControl, ResultCode.SUCCESS); 109 * </PRE> 110 */ 111@NotMutable() 112@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 113public final class SubtreeDeleteRequestControl 114 extends Control 115{ 116 /** 117 * The OID (1.2.840.113556.1.4.805) for the subtree delete request control. 118 */ 119 public static final String SUBTREE_DELETE_REQUEST_OID = 120 "1.2.840.113556.1.4.805"; 121 122 123 124 /** 125 * The serial version UID for this serializable class. 126 */ 127 private static final long serialVersionUID = 3748121547717081961L; 128 129 130 131 /** 132 * Creates a new subtree delete request control. The control will not be 133 * marked critical. 134 */ 135 public SubtreeDeleteRequestControl() 136 { 137 super(SUBTREE_DELETE_REQUEST_OID, false, null); 138 } 139 140 141 142 /** 143 * Creates a new subtree delete request control. 144 * 145 * @param isCritical Indicates whether the control should be marked 146 * critical. 147 */ 148 public SubtreeDeleteRequestControl(final boolean isCritical) 149 { 150 super(SUBTREE_DELETE_REQUEST_OID, isCritical, null); 151 } 152 153 154 155 /** 156 * Creates a new subtree delete request control which is decoded from the 157 * provided generic control. 158 * 159 * @param control The generic control to be decoded as a subtree delete 160 * request control. 161 * 162 * @throws LDAPException If the provided control cannot be decoded as a 163 * subtree delete request control. 164 */ 165 public SubtreeDeleteRequestControl(final Control control) 166 throws LDAPException 167 { 168 super(control); 169 170 if (control.hasValue()) 171 { 172 throw new LDAPException(ResultCode.DECODING_ERROR, 173 ERR_SUBTREE_DELETE_HAS_VALUE.get()); 174 } 175 } 176 177 178 179 /** 180 * {@inheritDoc} 181 */ 182 @Override() 183 public String getControlName() 184 { 185 return INFO_CONTROL_NAME_SUBTREE_DELETE_REQUEST.get(); 186 } 187 188 189 190 /** 191 * {@inheritDoc} 192 */ 193 @Override() 194 public void toString(final StringBuilder buffer) 195 { 196 buffer.append("SubtreeDeleteRequestControl(isCritical="); 197 buffer.append(isCritical()); 198 buffer.append(')'); 199 } 200}