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