001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020 package org.apache.directory.shared.ldap.message.extended; 021 022 023 import org.apache.directory.shared.i18n.I18n; 024 import org.apache.directory.shared.ldap.message.ExtendedResponseImpl; 025 import org.apache.directory.shared.ldap.message.ResultCodeEnum; 026 027 028 /** 029 * An extended operation intended for notifying clients of upcoming 030 * disconnection. Here's what <a 031 * href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a> has to say about 032 * it: 033 * 034 * <pre> 035 * Section 4.1.1 (Small snippet on sending NoD) 036 * 037 * If the server receives a PDU from the client in which the LDAPMessage 038 * SEQUENCE tag cannot be recognized, the messageID cannot be parsed, 039 * the tag of the protocolOp is not recognized as a request, or the 040 * encoding structures or lengths of data fields are found to be 041 * incorrect, then the server MUST return the notice of disconnection 042 * described in section 4.4.1, with resultCode protocolError, and 043 * immediately close the connection. In other cases that the server 044 * cannot parse the request received by the client, the server MUST 045 * return an appropriate response to the request, with the resultCode 046 * set to protocolError. 047 * 048 * ... 049 * 050 * 4.4. Unsolicited Notification 051 * 052 * An unsolicited notification is an LDAPMessage sent from the server to 053 * the client which is not in response to any LDAPMessage received by 054 * the server. It is used to signal an extraordinary condition in the 055 * server or in the connection between the client and the server. The 056 * notification is of an advisory nature, and the server will not expect 057 * any response to be returned from the client. 058 * 059 * The unsolicited notification is structured as an LDAPMessage in which 060 * the messageID is 0 and protocolOp is of the extendedResp form. The 061 * responseName field of the ExtendedResponse is present. The LDAPOID 062 * value MUST be unique for this notification, and not be used in any 063 * other situation. 064 * 065 * One unsolicited notification is defined in this document. 066 * 067 * 4.4.1. Notice of Disconnection 068 * 069 * This notification may be used by the server to advise the client that 070 * the server is about to close the connection due to an error 071 * condition. Note that this notification is NOT a response to an 072 * unbind requested by the client: the server MUST follow the procedures 073 * of section 4.3. This notification is intended to assist clients in 074 * distinguishing between an error condition and a transient network 075 * failure. As with a connection close due to network failure, the 076 * client MUST NOT assume that any outstanding requests which modified 077 * the directory have succeeded or failed. 078 * 079 * The responseName is 1.3.6.1.4.1.1466.20036, the response field is 080 * absent, and the resultCode is used to indicate the reason for the 081 * disconnection. 082 * 083 * The following resultCode values are to be used in this notification: 084 * 085 * - protocolError: The server has received data from the client in 086 * which the LDAPMessage structure could not be parsed. 087 * 088 * - strongAuthRequired: The server has detected that an established 089 * underlying security association protecting communication between 090 * the client and server has unexpectedly failed or been compromised. 091 * 092 * - unavailable: This server will stop accepting new connections and 093 * operations on all existing connections, and be unavailable for an 094 * extended period of time. The client may make use of an alternative 095 * server. 096 * 097 * After sending this notice, the server MUST close the connection. 098 * After receiving this notice, the client MUST NOT transmit any further 099 * on the connection, and may abruptly close the connection. 100 * </pre> 101 * 102 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 103 * @version $Rev: 912436 $ 104 */ 105 public class NoticeOfDisconnect extends ExtendedResponseImpl 106 { 107 private static final long serialVersionUID = -4682291068700593492L; 108 109 public static final String EXTENSION_OID = "1.3.6.1.4.1.1466.20036"; 110 111 private static final byte[] EMPTY_RESPONSE = new byte[0]; 112 113 public static final NoticeOfDisconnect UNAVAILABLE = new NoticeOfDisconnect( ResultCodeEnum.UNAVAILABLE ); 114 115 public static final NoticeOfDisconnect PROTOCOLERROR = new NoticeOfDisconnect( ResultCodeEnum.PROTOCOL_ERROR ); 116 117 public static final NoticeOfDisconnect STRONGAUTHREQUIRED = new NoticeOfDisconnect( ResultCodeEnum.STRONG_AUTH_REQUIRED ); 118 119 120 private NoticeOfDisconnect( ResultCodeEnum rcode ) 121 { 122 super( 0, EXTENSION_OID ); 123 124 switch ( rcode ) 125 { 126 case UNAVAILABLE : 127 break; 128 129 case PROTOCOL_ERROR : 130 break; 131 132 case STRONG_AUTH_REQUIRED : 133 break; 134 135 default: 136 throw new IllegalArgumentException( I18n.err( I18n.ERR_04166, ResultCodeEnum.UNAVAILABLE, 137 ResultCodeEnum.PROTOCOL_ERROR, ResultCodeEnum.STRONG_AUTH_REQUIRED ) ); 138 } 139 140 super.getLdapResult().setErrorMessage( rcode.toString() + ": The server will disconnect!" ); 141 super.getLdapResult().setMatchedDn( null ); 142 super.getLdapResult().setResultCode( rcode ); 143 } 144 145 146 // ------------------------------------------------------------------------ 147 // ExtendedResponse Interface Method Implementations 148 // ------------------------------------------------------------------------ 149 150 151 /** 152 * Gets the reponse OID specific encoded response values. 153 * 154 * @return the response specific encoded response values. 155 */ 156 public byte[] getResponse() 157 { 158 return EMPTY_RESPONSE; 159 } 160 161 162 /** 163 * Sets the reponse OID specific encoded response values. 164 * 165 * @param value 166 * the response specific encoded response values. 167 */ 168 public void setResponse( byte[] value ) 169 { 170 throw new UnsupportedOperationException( I18n.err( I18n.ERR_04173 ) ); 171 } 172 173 174 /** 175 * Gets the OID uniquely identifying this extended response (a.k.a. its 176 * name). 177 * 178 * @return the OID of the extended response type. 179 */ 180 public String getResponseName() 181 { 182 return EXTENSION_OID; 183 } 184 185 186 /** 187 * Sets the OID uniquely identifying this extended response (a.k.a. its 188 * name). 189 * 190 * @param oid 191 * the OID of the extended response type. 192 */ 193 public void setResponseName( String oid ) 194 { 195 throw new UnsupportedOperationException( I18n.err( I18n.ERR_04168, EXTENSION_OID ) ); 196 } 197 198 199 public boolean equals( Object obj ) 200 { 201 if ( obj == this ) 202 { 203 return true; 204 } 205 206 if ( obj instanceof NoticeOfDisconnect ) 207 { 208 return true; 209 } 210 211 return false; 212 } 213 }