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-2012 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 }