0N/A * The contents of this file are subject to the terms of the 0N/A * Common Development and Distribution License, Version 1.0 only 0N/A * (the "License"). You may not use this file except in compliance 0N/A * You can obtain a copy of the license at 0N/A * See the License for the specific language governing permissions 0N/A * and limitations under the License. 0N/A * When distributing Covered Code, include this CDDL HEADER in each 0N/A * file and include the License file at 0N/A * add the following below this CDDL HEADER, with the fields enclosed 873N/A * by brackets "[]" replaced with your own identifying information: 0N/A * Portions Copyright [yyyy] [name of copyright owner] 4129N/A * Copyright 2006-2009 Sun Microsystems, Inc. 6191N/A * Portions copyright 2011-2013 ForgeRock AS 0N/A * This class defines the set of methods and structures that must be 0N/A * implemented by a Directory Server client connection. 1400N/A * The tracer object for the debug logger. 5553N/A * The set of authentication information for this client connection. 4426N/A * Indicates whether a multistage SASL bind is currently in progress 4426N/A * on this client connection. If so, then no other operations 4426N/A * should be allowed until the bind completes. 4426N/A * Indicates if a bind or start TLS request is currently in progress 4426N/A * on this client connection. If so, then no further socket reads 4426N/A * will occur until the request completes. 6191N/A * Indicates whether any necessary finalization work has been done for this 6191N/A /** The set of privileges assigned to this client connection. */ 6191N/A /** The size limit for use with this client connection. */ 6191N/A /** The time limit for use with this client connection. */ 6191N/A /** The lookthrough limit for use with this client connection. */ 6191N/A /** The time that this client connection was established. */ 6191N/A /** The idle time limit for this client connection. */ 6191N/A * The opaque information used for storing intermediate state information 6191N/A * needed across multi-stage SASL binds. 6191N/A * A string representation of the time that this client connection was 6191N/A /** A set of persistent searches registered for this client. */ 6191N/A /** The network group to which the connection belongs to. */ 3853N/A /** Need to evaluate the network group for the first operation. */ 0N/A * Performs the appropriate initialization generic to all client 773N/A * Performs any internal cleanup that may be necessary when this 5553N/A * client connection is disconnected. In 773N/A * this case, it will be used to ensure that the connection is 773N/A * deregistered with the {@code AuthenticatedUsers} manager, and 773N/A * will then invoke the {@code finalizeClientConnection} method. 2095N/A notes=
"This method should only be invoked by connection " +
773N/A // Deregister with the set of authenticated users. 629N/A * Retrieves the time that this connection was established, measured 629N/A * in the number of milliseconds since January 1, 1970 UTC. 629N/A * @return The time that this connection was established, measured 629N/A * in the number of milliseconds since January 1, 1970 UTC. 629N/A * Retrieves a string representation of the time that this 629N/A * connection was established. 629N/A * @return A string representation of the time that this connection 0N/A * Retrieves the unique identifier that has been assigned to this 0N/A * @return The unique identifier that has been assigned to this 0N/A * Retrieves the connection handler that accepted this client 0N/A * @return The connection handler that accepted this client 0N/A * Retrieves the protocol that the client is using to communicate 0N/A * with the Directory Server. 0N/A * @return The protocol that the client is using to communicate 0N/A * with the Directory Server. 0N/A * Retrieves a string representation of the address of the client. 0N/A * @return A string representation of the address of the client. 3853N/A * Retrieves the port number for this connection on the client 3853N/A * @return The port number for this connection on the client system 3853N/A * or -1 if there is no client port associated with this 3853N/A * connection (e.g. internal client). 3853N/A * Retrieves the address and port (if available) of the client 3853N/A * system, separated by a colon. 3853N/A * @return The address and port of the client system, separated by a 0N/A * Retrieves a string representation of the address on the server to 0N/A * which the client connected. 0N/A * @return A string representation of the address on the server to 0N/A * which the client connected. 3853N/A * Retrieves the port number for this connection on the server 3853N/A * @return The port number for this connection on the server system 3853N/A * or -1 if there is no server port associated with this 3853N/A * connection (e.g. internal client). 3853N/A * Retrieves the address and port of the server system, separated by 3853N/A * @return The address and port of the server system, separated by a 2095N/A * Retrieves the {@code java.net.InetAddress} associated with the 2095N/A * @return The {@code java.net.InetAddress} associated with the 2095N/A * remote client system. It may be {@code null} if the 2095N/A * client is not connected over an IP-based connection. 2095N/A * Retrieves the {@code java.net.InetAddress} for the Directory 0N/A * Server system to which the client has established the connection. 2095N/A * @return The {@code java.net.InetAddress} for the Directory 0N/A * Server system to which the client has established the 2095N/A * connection. It may be {@code null} if the client is not 2095N/A * connected over an IP-based connection. 6198N/A * Returns whether the Directory Server believes this connection to be valid 6198N/A * and available for communication. 6198N/A * @return true if the connection is valid, false otherwise 0N/A * Indicates whether this client connection is currently using a 0N/A * secure mechanism to communicate with the server. Note that this 0N/A * may change over time based on operations performed by the client 2095N/A * or server (e.g., it may go from {@code false} to {@code true} if 2095N/A * if the client uses the StartTLS extended operation). 2095N/A * @return {@code true} if the client connection is currently using 2095N/A * a secure mechanism to communicate with the server, or 2366N/A * Retrieves a {@code Selector} that may be used to ensure that 2366N/A * write operations complete in a timely manner, or terminate the 2366N/A * connection in the event that they fail to do so. This is an 2366N/A * optional method for client connections, and the default 2366N/A * implementation returns {@code null} to indicate that the maximum 2366N/A * blocked write time limit is not supported for this connection. 2366N/A * Subclasses that do wish to support this functionality should 2366N/A * return a valid {@code Selector} object. 2366N/A * @return The {@code Selector} that may be used to ensure that 2366N/A * write operations complete in a timely manner, or 2366N/A * {@code null} if this client connection does not support 2366N/A * maximum blocked write time limit functionality. 2366N/A // There will not be a write selector in the default 2366N/A * Retrieves the maximum length of time in milliseconds that 2366N/A * attempts to write data to the client should be allowed to block. 2366N/A * A value of zero indicates there should be no limit. 2366N/A * @return The maximum length of time in milliseconds that attempts 2366N/A * to write data to the client should be allowed to block, 2366N/A * or zero if there should be no limit. 2366N/A // By default, we'll return 0, which indicates that there should 2366N/A // be no maximum time limit. Subclasses should override this if 2366N/A // they want to support a maximum blocked write time limit. 3853N/A * Retrieves the total number of operations performed 3853N/A * @return The total number of operations performed 3853N/A * Indicates whether the network group must be evaluated for 3861N/A * @param operation The operation going to be performed. Bind 3861N/A * operations imply a network group evaluation. 3853N/A * @return boolean indicating if the network group must be evaluated 3861N/A // Connections inside the internal network group MUST NOT 3861N/A // Connections inside the admin network group MUST NOT 3861N/A // If the operation is a BIND, the network group MUST be evaluated 3853N/A * Indicates that the network group will have to be evaluated 3853N/A * @param bool true if the network group must be evaluated 0N/A * Sends a response to the client based on the information in the 0N/A * provided operation. 0N/A * @param operation The operation for which to send the response. 0N/A * Sends the provided search result entry to the client. 0N/A * @param searchOperation The search operation with which the 0N/A * entry is associated. 0N/A * @param searchEntry The search result entry to be sent to 988N/A * @throws DirectoryException If a problem occurs while attempting 988N/A * to send the entry to the client and 988N/A * the search should be terminated. 0N/A * Sends the provided search result reference to the client. 0N/A * @param searchOperation The search operation with which the 0N/A * reference is associated. 0N/A * @param searchReference The search result reference to be sent 2095N/A * @return {@code true} if the client is able to accept referrals, 2095N/A * or {@code false} if the client cannot handle referrals 2095N/A * and no more attempts should be made to send them for the 2095N/A * associated search operation. 988N/A * @throws DirectoryException If a problem occurs while attempting 988N/A * to send the reference to the client 988N/A * and the search should be terminated. 0N/A * Invokes the intermediate response plugins on the provided 0N/A * response message and sends it to the client. 0N/A * @param intermediateResponse The intermediate response message 2095N/A * @return {@code true} if processing on the associated operation 2095N/A * should continue, or {@code false} if not. 0N/A // Invoke the intermediate response plugins for the response 0N/A * Sends the provided intermediate response message to the client. 0N/A * @param intermediateResponse The intermediate response message 2095N/A * @return {@code true} if processing on the associated operation 2095N/A * should continue, or {@code false} if not. 0N/A protected abstract boolean 0N/A * Closes the connection to the client, optionally sending it a 0N/A * message indicating the reason for the closure. Note that the 0N/A * ability to send a notice of disconnection may not be available 403N/A * for all protocols or under all circumstances. Also note that 403N/A * when attempting to disconnect a client connection as a part of 403N/A * operation processing (e.g., within a plugin or other extension), 2095N/A * the {@code disconnectClient} method within that operation should 2095N/A * be called rather than invoking this method directly. 773N/A * All subclasses must invoke the {@code finalizeConnectionInternal} 773N/A * method during the course of processing this method. 0N/A * @param disconnectReason The disconnect reason that provides the 0N/A * generic cause for the disconnect. 0N/A * @param sendNotification Indicates whether to try to provide 0N/A * notification to the client that the 0N/A * connection will be closed. 0N/A * @param message The message to send to the client. It 2095N/A * may be {@code null} if no notification 0N/A * Indicates whether the user associated with this client connection 0N/A * must change their password before they will be allowed to do 2095N/A * @return {@code true} if the user associated with this client 2095N/A * connection must change their password before they will 2095N/A * be allowed to do anything else, or {@code false} if not. 0N/A * Specifies whether the user associated with this client connection 0N/A * must change their password before they will be allowed to do 0N/A * @param mustChangePassword Specifies whether the user associated 0N/A * with this client connection must 0N/A * change their password before they 0N/A * will be allowed to do anything else. 0N/A * Retrieves the set of operations in progress for this client 0N/A * connection. This list must not be altered by any caller. 0N/A * @return The set of operations in progress for this client 0N/A * Retrieves the operation in progress with the specified message 0N/A * @param messageID The message ID of the operation to retrieve. 0N/A * @return The operation in progress with the specified message ID, 2095N/A * or {@code null} if no such operation could be found. 0N/A * Removes the provided operation from the set of operations in 0N/A * progress for this client connection. Note that this does not 0N/A * make any attempt to cancel any processing that may already be in 0N/A * progress for the operation. 0N/A * @param messageID The message ID of the operation to remove from 0N/A * the set of operations in progress. 2095N/A * @return {@code true} if the operation was found and removed from 2095N/A * the set of operations in progress, or {@code false} if 0N/A * Retrieves the set of persistent searches registered for this 0N/A * @return The set of persistent searches registered for this 0N/A * Registers the provided persistent search for this client. Note 0N/A * that this should only be called by 2095N/A * {@code DirectoryServer.registerPersistentSearch} and not through 0N/A * @param persistentSearch The persistent search to register for 0N/A * Deregisters the provided persistent search for this client. Note 0N/A * that this should only be called by 2095N/A * {@code DirectoryServer.deregisterPersistentSearch} and not 0N/A * through any other means. 0N/A * @param persistentSearch The persistent search to deregister for 0N/A * Attempts to cancel the specified operation. 0N/A * @param messageID The message ID of the operation to cancel. 0N/A * @param cancelRequest An object providing additional information 0N/A * about how the cancel should be processed. 0N/A * @return A cancel result that either indicates that the cancel 0N/A * was successful or provides a reason that it was not. 0N/A * Attempts to cancel all operations in progress on this connection. 0N/A * @param cancelRequest An object providing additional information 0N/A * about how the cancel should be processed. 0N/A * Attempts to cancel all operations in progress on this connection 0N/A * except the operation with the specified message ID. 0N/A * @param cancelRequest An object providing additional information 0N/A * about how the cancel should be processed. 0N/A * @param messageID The message ID of the operation that 0N/A * should not be canceled. 0N/A * Retrieves information about the authentication that has been 0N/A * performed for this connection. 0N/A * @return Information about the user that is currently 0N/A * authenticated on this connection. 0N/A * Specifies information about the authentication that has been 0N/A * performed for this connection. 0N/A * @param authenticationInfo Information about the authentication 0N/A * that has been performed for this 0N/A * connection. It should not be 773N/A * Updates the cached entry associated with either the 773N/A * authentication and/or authorization identity with the provided 773N/A * @param oldEntry The user entry currently serving as the 773N/A * @param newEntry The updated entry that should replace the 773N/A * existing entry. It may optionally have a 773N/A * different DN than the old entry. 0N/A * Sets properties in this client connection to indicate that the 0N/A * client is unauthenticated. This includes setting the 0N/A * authentication info structure to an empty default, as well as 0N/A * setting the size and time limit values to their defaults. 3888N/A * Indicate whether the specified authorization entry parameter 3888N/A * has the specified privilege. The method can be used to perform 3888N/A * @param authorizationEntry The authentication entry to use. 3888N/A * @param privilege The privilege to check for. 3888N/A * @return {@code true} if the authentication entry has the 3888N/A * specified privilege, or {@code false} if not. 776N/A * Indicates whether the authenticated client has the specified 776N/A * @param privilege The privilege for which to make the 776N/A * @param operation The operation being processed which needs to 776N/A * make the privilege determination, or 776N/A * {@code null} if there is no associated 776N/A * @return {@code true} if the authenticated client has the 776N/A * specified privilege, or {@code false} if not. 1454N/A // This determination should always be made against the 1454N/A // authentication identity rather than the authorization 776N/A * Indicates whether the authenticate client has all of the 776N/A * specified privileges. 776N/A * @param privileges The array of privileges for which to make the 776N/A * @param operation The operation being processed which needs to 776N/A * make the privilege determination, or 776N/A * {@code null} if there is no associated 776N/A * @return {@code true} if the authenticated client has all of the 776N/A * specified privileges, or {@code false} if not. 1454N/A * Retrieves the set of privileges encoded in the provided entry. 1454N/A * @param entry The entry to use to obtain the privilege 1454N/A * @param isRoot Indicates whether the set of root privileges 1454N/A * should be automatically included in the 1454N/A * @return A set of the privileges that should be assigned. 776N/A // If the name of the privilege is prefixed with a minus 776N/A // sign, then we will take away that privilege from the 776N/A // user. We'll handle that at the end so that we can make 776N/A // sure it's not added back later. 776N/A // FIXME -- Generate an administrative alert. 776N/A // We don't know what privilege to remove, so we'll 776N/A // FIXME -- Generate an administrative alert. 1454N/A * Updates the privileges associated with this client connection 1454N/A * object based on the provided entry for the authentication 1454N/A * @param entry The entry for the authentication identity 1454N/A * associated with this client connection. 1454N/A * @param isRoot Indicates whether the associated user is a root 1454N/A * user and should automatically inherit the root 0N/A * Retrieves an opaque set of information that may be used for 0N/A * processing multi-stage SASL binds. 0N/A * @return An opaque set of information that may be used for 0N/A * processing multi-stage SASL binds. 0N/A * Specifies an opaque set of information that may be used for 0N/A * processing multi-stage SASL binds. 0N/A * @param saslAuthState An opaque set of information that may be 0N/A * used for processing multi-stage SASL 4170N/A * Return the lowest level channel associated with a connection. 4170N/A * This is normally the channel associated with the socket 4170N/A * @return The lowest level channel associated with a connection. 4170N/A // By default, return null, which indicates that there should 4170N/A // be no channel. Subclasses should override this if 4170N/A // they want to support a channel. 4170N/A * Return the Socket channel associated with a connection. 4170N/A * @return The Socket channel associated with a connection. 4170N/A // By default, return null, which indicates that there should 4170N/A // be no socket channel. Subclasses should override this if 4170N/A // they want to support a socket channel. 0N/A * Retrieves the size limit that will be enforced for searches 0N/A * performed using this client connection. 0N/A * @return The size limit that will be enforced for searches 0N/A * performed using this client connection. 0N/A * Specifies the size limit that will be enforced for searches 0N/A * performed using this client connection. 0N/A * @param sizeLimit The size limit that will be enforced for 0N/A * searches performed using this client 1963N/A * Retrieves the maximum length of time in milliseconds that this 1963N/A * client connection will be allowed to remain idle before it should 1963N/A * @return The maximum length of time in milliseconds that this 1963N/A * client connection will be allowed to remain idle before 1963N/A * it should be disconnected. 1963N/A * Specifies the maximum length of time in milliseconds that this 1963N/A * client connection will be allowed to remain idle before it should 1963N/A * @param idleTimeLimit The maximum length of time in milliseconds 1963N/A * that this client connection will be 1963N/A * allowed to remain idle before it should be 96N/A * Retrieves the default maximum number of entries that should 96N/A * checked for matches during a search. 96N/A * @return The default maximum number of entries that should 96N/A * checked for matches during a search. 96N/A * Specifies the default maximum number of entries that should 96N/A * be checked for matches during a search. 96N/A * @param lookthroughLimit The default maximum number of 96N/A * entries that should be check for 96N/A * matches during a search. 0N/A * Retrieves the time limit that will be enforced for searches 0N/A * performed using this client connection. 0N/A * @return The time limit that will be enforced for searches 0N/A * performed using this client connection. 0N/A * Specifies the time limit that will be enforced for searches 0N/A * performed using this client connection. 0N/A * @param timeLimit The time limit that will be enforced for 0N/A * searches performed using this client 629N/A * Retrieves a one-line summary of this client connection in a form 629N/A * that is suitable for including in the monitor entry for the 629N/A * associated connection handler. It should be in a format that is 629N/A * both humand readable and machine parseable (e.g., a 629N/A * space-delimited name-value list, with quotes around the values). 629N/A * @return A one-line summary of this client connection in a form 629N/A * that is suitable for including in the monitor entry for 629N/A * the associated connection handler. 655N/A * Indicates whether the user associated with this client connection 655N/A * should be considered a member of the specified group, optionally 655N/A * evaluated within the context of the provided operation. If an 655N/A * operation is given, then the determination should be made based 655N/A * on the authorization identity for that operation. If the 655N/A * operation is {@code null}, then the determination should be made 655N/A * based on the authorization identity for this client connection. 655N/A * Note that this is a point-in-time determination and the caller 655N/A * must not cache the result. 655N/A * @param group The group for which to make the determination. 655N/A * @param operation The operation to use to obtain the 655N/A * authorization identity for which to make the 655N/A * determination, or {@code null} if the 655N/A * authorization identity should be obtained from 655N/A * this client connection. 655N/A * @return {@code true} if the target user is currently a member of 655N/A * the specified group, or {@code false} if not. 655N/A * @throws DirectoryException If a problem occurs while attempting 655N/A * to make the determination. 655N/A * Retrieves the set of groups in which the user associated with 655N/A * this client connection may be considered to be a member. If an 655N/A * operation is provided, then the determination should be made 655N/A * based on the authorization identity for that operation. If the 655N/A * operation is {@code null}, then it should be made based on the 655N/A * authorization identity for this client connection. Note that 655N/A * this is a point-in-time determination and the caller must not 655N/A * @param operation The operation to use to obtain the 655N/A * authorization identity for which to retrieve 655N/A * the associated groups, or {@code null} if the 655N/A * authorization identity should be obtained from 655N/A * this client connection. 655N/A * @return The set of groups in which the target user is currently 655N/A * @throws DirectoryException If a problem occurs while attempting 655N/A * to make the determination. 756N/A // FIXME -- This probably isn't the most efficient implementation. 824N/A * Retrieves the DN of the key manager provider that should be used 824N/A * for operations requiring access to a key manager. The default 824N/A * implementation returns {@code null} to indicate that no key 3888N/A * manager provider is available, but subclasses should override 824N/A * this method to return a valid DN if they perform operations which 824N/A * may need access to a key manager. 824N/A * @return The DN of the key manager provider that should be used 824N/A * for operations requiring access to a key manager, or 824N/A * {@code null} if there is no key manager provider 824N/A * configured for this client connection. 824N/A // In the default implementation, we'll return null. 824N/A * Retrieves the DN of the trust manager provider that should be 824N/A * used for operations requiring access to a trust manager. The 824N/A * default implementation returns {@code null} to indicate that no 824N/A * trust manager provider is avaialble, but subclasses should 824N/A * override this method to return a valid DN if they perform 824N/A * operations which may need access to a trust manager. 824N/A * @return The DN of the trust manager provider that should be used 824N/A * for operations requiring access to a trust manager, or 824N/A * {@code null} if there is no trust manager provider 824N/A * configured for this client connection. 824N/A // In the default implementation, we'll return null. 867N/A * Retrieves the alias of the server certificate that should be used 867N/A * for operations requiring a server certificate. The default 867N/A * implementation returns {@code null} to indicate that any alias is 867N/A * @return The alias of the server certificate that should be used 867N/A * for operations requring a server certificate, or 867N/A * {@code null} if any alias is acceptable. 867N/A // In the default implementation, we'll return null. 0N/A * Retrieves a string representation of this client connection. 0N/A * @return A string representation of this client connection. 0N/A * Appends a string representation of this client connection to the 0N/A * @param buffer The buffer to which the information should be 1689N/A * Returns the network group to which the connection belongs. 1689N/A * @return the network group attached to the connection 1689N/A * Sets the network group to which the connection belongs. 1689N/A * @param networkGroup the network group to which the 3853N/A // If there is a change, first remove this connection 3853N/A // from the current network group 3853N/A // Then set the new network group 3853N/A // And add the connection to the new ng 3853N/A // The client connection inherits the resource limits 1963N/A * Retrieves the length of time in milliseconds that this client 1963N/A * connection has been idle. 1963N/A * Note that the default implementation will always return zero. 1963N/A * Subclasses associated with connection handlers should override 1963N/A * this method if they wish to provided idle time limit 1963N/A * @return The length of time in milliseconds that this client 1963N/A * connection has been idle. 4134N/A * Return the Security Strength Factor of a client connection. 4134N/A * @return An integer representing the SSF value of a connection. 4426N/A * Indicates a bind or start TLS request processing is finished 4426N/A * and the client connection may start processing data read from 4426N/A * the socket again. This must be called after processing each 4426N/A * bind request in a multistage SASL bind. 4426N/A * Indicates a multistage SASL bind operation is finished and the 4426N/A * client connection may accept additional LDAP messages. 6191N/A * Returns whether this connection is used for inner work not directly 6191N/A * requested by an external client. 6191N/A * @return {@code true} if this is an inner connection, {@code false}