001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming.ldap;
019:
020: import javax.naming.NamingException;
021: import javax.naming.directory.DirContext;
022:
023: /**
024: * An <code>LdapContext</code> is used when LDAPv3 extended operations and/or
025: * controls are required.
026: * <p>
027: * Extended operations are dealt with by the <code>extendedOperation</code>
028: * method. All other methods relate to the use of controls. Controls are extra
029: * information provided to or from an LDAP v3 server. Controls are either of the
030: * type <code>Request</code> or <code>Response</code>. There is a special
031: * type of request controls known as connection controls.
032: * </p>
033: * <p>
034: * Connection controls are used by a service provider when connecting or
035: * reconnecting to an LDAP server. These are associated with connections and are
036: * inherited by derived <code>Context</code>. It should be noted however that
037: * subsequent changes to a derived <code>Context</code>'s own connection
038: * controls has no impact on the <code>Context</code> from which it inherited.
039: * There are a number of environment properties which relate specifically to
040: * LDAP service providers. The one which is important here is:
041: * <code>java.naming.ldap.control.connect</code> which holds the array of
042: * connection controls for a <code>Context</code>. Service providers rely on
043: * this to pass on the connection controls to derived <code>Context</code>.
044: * </p>
045: * <p>
046: * Request controls are used by a service provider when performing operations
047: * other than connecting or reconnecting. These are referred to as Context
048: * Request Controls as they relate to the specific <code>Context</code>
049: * instance. It must be noted that, unlike connection controls, they are not
050: * inherited. Connection and request controls being split like this allows
051: * service provider implementations to pool connections.
052: * </p>
053: * <p>
054: * Response controls are generated by an LDAPv3 server.
055: * </p>
056: *
057: * @see DirContext
058: */
059: public interface LdapContext extends DirContext {
060:
061: /**
062: * This is set to the environment property java.naming.factory.control.
063: */
064: static final String CONTROL_FACTORIES = "java.naming.factory.control"; //$NON-NLS-1$
065:
066: /**
067: * Deals with extended operations of LDAPv3.
068: *
069: * @param e
070: * an extended request
071: * @return an extended response for the supplied request
072: * @throws NamingException
073: * If an error is encountered.
074: */
075: ExtendedResponse extendedOperation(ExtendedRequest e)
076: throws NamingException;
077:
078: /**
079: * Creates a new instance of <code>LdapContext</code> using the supplied
080: * controls.
081: *
082: * @param ac
083: * an array of controls
084: * @return a new <code>LdapContext</code> instance
085: * @throws NamingException
086: * If an error is encountered.
087: */
088: LdapContext newInstance(Control[] ac) throws NamingException;
089:
090: /**
091: * Reconnects using the supplied controls.
092: *
093: * @param ac
094: * an array of controls
095: * @throws NamingException
096: * If an error is encountered.
097: */
098: void reconnect(Control[] ac) throws NamingException;
099:
100: /**
101: * Gets an array of connection controls.
102: *
103: * @return an array of connection controls
104: * @throws NamingException
105: * If an error is encountered.
106: */
107: Control[] getConnectControls() throws NamingException;
108:
109: /**
110: * Sets the request controls.
111: *
112: * @param ac
113: * an array of request controls
114: * @throws NamingException
115: * If an error is encountered.
116: */
117: void setRequestControls(Control[] ac) throws NamingException;
118:
119: /**
120: * Gets the request controls.
121: *
122: * @return an array of request controls
123: * @throws NamingException
124: * If an error is encountered.
125: */
126: Control[] getRequestControls() throws NamingException;
127:
128: /**
129: * Gets the response controls.
130: *
131: * @return an array of response controls
132: * @throws NamingException
133: * If an error is encountered.
134: */
135: Control[] getResponseControls() throws NamingException;
136:
137: }
|