001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2010-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.common.types; 028 029 030 031 import com.unboundid.asn1.ASN1OctetString; 032 import com.unboundid.ldap.sdk.BindResult; 033 import com.unboundid.ldap.sdk.ExtendedRequest; 034 import com.unboundid.ldap.sdk.ExtendedResult; 035 import com.unboundid.ldap.sdk.LDAPException; 036 import com.unboundid.ldap.sdk.LDAPInterface; 037 import com.unboundid.ldap.sdk.SimpleBindRequest; 038 import com.unboundid.util.NotExtensible; 039 import com.unboundid.util.ThreadSafety; 040 import com.unboundid.util.ThreadSafetyLevel; 041 042 043 044 /** 045 * This interface defines a set of methods that may be used to perform internal 046 * operations within the server. 047 */ 048 @NotExtensible() 049 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE) 050 public interface InternalConnection 051 extends LDAPInterface 052 { 053 /** 054 * Processes a simple bind request with the provided DN and password. 055 * <BR><BR> 056 * The LDAP protocol specification forbids clients from attempting to perform 057 * a bind on a connection in which one or more other operations are already in 058 * progress. If a bind is attempted while any operations are in progress, 059 * then the directory server may or may not abort processing for those 060 * operations, depending on the type of operation and how far along the 061 * server has already gotten while processing that operation (unless the bind 062 * request is one that will not cause the server to attempt to change the 063 * identity of this connection, for example by including the retain identity 064 * request control in the bind request). It is recommended that all active 065 * operations be abandoned, canceled, or allowed to complete before attempting 066 * to perform a bind on an active connection. 067 * 068 * @param bindDN The bind DN for the bind operation. 069 * @param password The password for the simple bind operation. 070 * 071 * @return The result of processing the bind operation. 072 * 073 * @throws LDAPException If the server rejects the bind request, or if a 074 * problem occurs while sending the request or reading 075 * the response. 076 */ 077 BindResult bind(final String bindDN, final String password) 078 throws LDAPException; 079 080 081 082 /** 083 * Processes the provided bind request. 084 * <BR><BR> 085 * The LDAP protocol specification forbids clients from attempting to perform 086 * a bind on a connection in which one or more other operations are already in 087 * progress. If a bind is attempted while any operations are in progress, 088 * then the directory server may or may not abort processing for those 089 * operations, depending on the type of operation and how far along the 090 * server has already gotten while processing that operation (unless the bind 091 * request is one that will not cause the server to attempt to change the 092 * identity of this connection, for example by including the retain identity 093 * request control in the bind request). It is recommended that all active 094 * operations be abandoned, canceled, or allowed to complete before attempting 095 * to perform a bind on an active connection. 096 * 097 * @param bindRequest The bind request to be processed. It must not be 098 * {@code null}. 099 * 100 * @return The result of processing the bind operation. 101 * 102 * @throws LDAPException If the server rejects the bind request, or if a 103 * problem occurs while sending the request or reading 104 * the response. 105 */ 106 BindResult bind(final SimpleBindRequest bindRequest) 107 throws LDAPException; 108 109 110 111 /** 112 * Processes an extended operation with the provided request OID. Note that 113 * when processing an extended operation, the server will never throw an 114 * exception for a failed response -- only when there is a problem sending the 115 * request or reading the response. It is the responsibility of the caller to 116 * determine whether the operation was successful. 117 * 118 * @param requestOID The OID for the extended request to process. It must 119 * not be {@code null}. 120 * 121 * @return The extended result object that provides information about the 122 * result of the request processing. It may or may not indicate that 123 * the operation was successful. Note that the extended result will 124 * always be a generic result, even if the LDAP SDK normally returns 125 * a specific subclass. 126 * 127 * @throws LDAPException If a problem occurs while sending the request or 128 * reading the response. 129 */ 130 ExtendedResult processExtendedOperation(final String requestOID) 131 throws LDAPException; 132 133 134 135 /** 136 * Processes an extended operation with the provided request OID and value. 137 * Note that when processing an extended operation, the server will never 138 * throw an exception for a failed response -- only when there is a problem 139 * sending the request or reading the response. It is the responsibility of 140 * the caller to determine whether the operation was successful. 141 * 142 * @param requestOID The OID for the extended request to process. It must 143 * not be {@code null}. 144 * @param requestValue The encoded value for the extended request to 145 * process. It may be {@code null} if there does not 146 * need to be a value for the requested operation. 147 * 148 * @return The extended result object that provides information about the 149 * result of the request processing. It may or may not indicate that 150 * the operation was successful. Note that the extended result will 151 * always be a generic result, even if the LDAP SDK normally returns 152 * a specific subclass. 153 * 154 * @throws LDAPException If a problem occurs while sending the request or 155 * reading the response. 156 */ 157 ExtendedResult processExtendedOperation(final String requestOID, 158 final ASN1OctetString requestValue) 159 throws LDAPException; 160 161 162 163 /** 164 * Processes the provided extended request. Note that when processing an 165 * extended operation, the server will never throw an exception for a failed 166 * response -- only when there is a problem sending the request or reading the 167 * response. It is the responsibility of the caller to determine whether the 168 * operation was successful. 169 * 170 * @param extendedRequest The extended request to be processed. It must not 171 * be {@code null}. 172 * 173 * @return The extended result object that provides information about the 174 * result of the request processing. It may or may not indicate that 175 * the operation was successful. Note that the extended result will 176 * always be a generic result, even if the LDAP SDK normally returns 177 * a specific subclass. 178 * 179 * @throws LDAPException If a problem occurs while sending the request or 180 * reading the response. 181 */ 182 ExtendedResult processExtendedOperation(final ExtendedRequest extendedRequest) 183 throws LDAPException; 184 }