001 /* 002 * Copyright 2007-2014 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005 /* 006 * Copyright (C) 2008-2014 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; 022 023 024 025 import com.unboundid.asn1.ASN1Integer; 026 027 028 029 /** 030 * This class provides an API that is used to represent an LDAP bind request. 031 * It should be extended by subclasses that provide the logic for processing 032 * specific types of bind operations (e.g., simple binds, and the various SASL 033 * mechanisms). 034 * <BR><BR> 035 * It is strongly recommended that all bind request types which implement the 036 * rebind capability be made immutable. If this is not done, then changes made 037 * to a bind request object may alter the authentication/authorization identity 038 * and/or credentials associated with that request so that a rebind request 039 * created from it will not match the original request used to authenticate on a 040 * connection. Note, however, that it is not threadsafe to use the same 041 * {@code BindRequest} object to attempt to bind concurrently over multiple 042 * connections. 043 * <BR><BR> 044 * Note that even though this class is marked with the @Extensible annotation 045 * type, it should not be directly subclassed by third-party code. Only the 046 * {@code SASLBindRequest} subclass is actually intended to be extended by 047 * third-party code. 048 */ 049 public abstract class BindRequest 050 extends LDAPRequest 051 { 052 /** 053 * The pre-encoded ASN.1 element used to represent the protocol version. 054 */ 055 protected static final ASN1Integer VERSION_ELEMENT = new ASN1Integer(3); 056 057 058 059 /** 060 * The serial version UID for this serializable class. 061 */ 062 private static final long serialVersionUID = -1509925217235385907L; 063 064 065 066 /** 067 * Creates a new bind request with the provided set of controls. 068 * 069 * @param controls The set of controls to include in this bind request. 070 */ 071 protected BindRequest(final Control[] controls) 072 { 073 super(controls); 074 } 075 076 077 078 /** 079 * Sends this bind request to the target server over the provided connection 080 * and returns the corresponding response. 081 * 082 * @param connection The connection to use to send this bind request to the 083 * server and read the associated response. 084 * @param depth The current referral depth for this request. It should 085 * always be one for the initial request, and should only 086 * be incremented when following referrals. 087 * 088 * @return The bind response read from the server. 089 * 090 * @throws LDAPException If a problem occurs while sending the request or 091 * reading the response. 092 */ 093 @Override() 094 protected abstract BindResult process(final LDAPConnection connection, 095 final int depth) 096 throws LDAPException; 097 098 099 100 /** 101 * {@inheritDoc} 102 */ 103 @Override() 104 public final OperationType getOperationType() 105 { 106 return OperationType.BIND; 107 } 108 109 110 111 /** 112 * Retrieves a human-readable string that describes the type of bind request. 113 * 114 * @return A human-readable string that describes the type of bind request. 115 */ 116 public abstract String getBindType(); 117 118 119 120 /** 121 * {@inheritDoc} 122 */ 123 public abstract BindRequest duplicate(); 124 125 126 127 /** 128 * {@inheritDoc} 129 */ 130 public abstract BindRequest duplicate(final Control[] controls); 131 132 133 134 /** 135 * Retrieves a bind request that may be used to re-bind using the same 136 * credentials authentication type and credentials as previously used to 137 * perform the initial bind. This may be used in an attempt to automatically 138 * re-establish a connection that is lost, or potentially when following a 139 * referral to another directory instance. 140 * <BR><BR> 141 * It is recommended that all bind request types which implement this 142 * capability be implemented so that the elements needed to create a new 143 * request are immutable. If this is not done, then changes made to a bind 144 * request object may alter the authentication/authorization identity and/or 145 * credentials associated with that request so that a rebind request created 146 * from it will not match the original request used to authenticate on a 147 * connection. 148 * 149 * @param host The address of the directory server to which the connection 150 * is established. 151 * @param port The port of the directory server to which the connection is 152 * established. 153 * 154 * @return A bind request that may be used to re-bind using the same 155 * authentication type and credentials as previously used to perform 156 * the initial bind, or {@code null} to indicate that automatic 157 * re-binding is not supported for this type of bind request. 158 */ 159 public BindRequest getRebindRequest(final String host, final int port) 160 { 161 return null; 162 } 163 }