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