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