com.unboundid.ldap.sdk.controls

Class PasswordExpiredControl

java.lang.Object

com.unboundid.ldap.sdk.Control

com.unboundid.ldap.sdk.controls.PasswordExpiredControl

All Implemented Interfaces:

DecodeableControl, java.io.Serializable

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class PasswordExpiredControl
extends Control
implements DecodeableControl

This class provides an implementation of the password expired control as described in draft-vchu-ldap-pwd-policy. It may be included in the response for an unsuccessful bind operation to indicate that the reason for the failure is that the target user's password has expired and must be reset before the user will be allowed to authenticate. Some servers may also include this control in a successful bind response to indicate that the authenticated user must change his or her password before being allowed to perform any other operation.

No request control is required to trigger the server to send the password expired response control. If the server supports the use of this control and the corresponding bind operation meets the criteria for this control to be included in the response, then it will be returned to the client.

Example

The following example demonstrates a process that may be used to perform a simple bind to authenticate against the server and handle any password expired or password expiring control that may be included in the response:

 // Send a simple bind request to the directory server.
 BindRequest bindRequest =
      new SimpleBindRequest("uid=test.user,ou=People,dc=example,dc=com",
           "password");
 BindResult bindResult;
 boolean bindSuccessful;
 boolean passwordExpired;
 boolean passwordAboutToExpire;
 try
 {
   bindResult = connection.bind(bindRequest);

   // If we got here, the bind was successful and we know the password was
   // not expired.  However, we shouldn't ignore the result because the
   // password might be about to expire.  To determine whether that is the
   // case, we should see if the bind result included a password expiring
   // control.
   bindSuccessful = true;
   passwordExpired = false;

   PasswordExpiringControl expiringControl =
        PasswordExpiringControl.get(bindResult);
   if (expiringControl != null)
   {
     passwordAboutToExpire = true;
     int secondsToExpiration = expiringControl.getSecondsUntilExpiration();
   }
   else
   {
     passwordAboutToExpire = false;
   }
 }
 catch (LDAPException le)
 {
   // If we got here, then the bind failed.  The failure may or may not have
   // been due to an expired password.  To determine that, we should see if
   // the bind result included a password expired control.
   bindSuccessful = false;
   passwordAboutToExpire = false;
   bindResult = new BindResult(le.toLDAPResult());
   ResultCode resultCode = le.getResultCode();
   String errorMessageFromServer = le.getDiagnosticMessage();

   PasswordExpiredControl expiredControl =
        PasswordExpiredControl.get(le);
   if (expiredControl != null)
   {
     passwordExpired = true;
   }
   else
   {
     passwordExpired = false;
   }
 }
 

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	PASSWORD_EXPIRED_OID The OID (2.16.840.1.113730.3.4.4) for the password expired response control.

Constructor Summary

Constructors

Constructor and Description
PasswordExpiredControl() Creates a new password expired control.
PasswordExpiredControl(java.lang.String oid, boolean isCritical, ASN1OctetString value) Creates a new password expired control with the provided information.

Method Summary

Modifier and Type	Method and Description
PasswordExpiredControl	decodeControl(java.lang.String oid, boolean isCritical, ASN1OctetString value) Creates a new instance of this decodeable control from the provided information.
static PasswordExpiredControl	decodeJSONControl(JSONObject controlObject, boolean strict) Attempts to decode the provided object as a JSON representation of a password expired control.
static PasswordExpiredControl	get(LDAPException exception) Extracts a password expired control from the provided exception.
static PasswordExpiredControl	get(LDAPResult result) Extracts a password expired control from the provided result.
java.lang.String	getControlName() Retrieves the user-friendly name for this control, if available.
JSONObject	toJSONControl() Retrieves a representation of this password expired control as a JSON object.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this LDAP control to the provided buffer.

Methods inherited from class com.unboundid.ldap.sdk.Control

decode, decode, decodeControls, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toString, writeTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PASSWORD_EXPIRED_OID

@NotNull
public static final java.lang.String PASSWORD_EXPIRED_OID

The OID (2.16.840.1.113730.3.4.4) for the password expired response control.

See Also:

Constant Field Values

Constructor Detail

PasswordExpiredControl

public PasswordExpiredControl()

Creates a new password expired control.

PasswordExpiredControl

public PasswordExpiredControl(@NotNull
                              java.lang.String oid,
                              boolean isCritical,
                              @Nullable
                              ASN1OctetString value)
                       throws LDAPException

Creates a new password expired control with the provided information.

Parameters:

oid - The OID for the control.

isCritical - Indicates whether the control should be marked critical.

value - The encoded value for the control. This may be null if no value was provided.

Throws:

LDAPException - If the provided control cannot be decoded as a password expired response control.

Method Detail

decodeControl

@NotNull
public PasswordExpiredControl decodeControl(@NotNull
                                                     java.lang.String oid,
                                                     boolean isCritical,
                                                     @Nullable
                                                     ASN1OctetString value)
                                              throws LDAPException

Creates a new instance of this decodeable control from the provided information.

Specified by:

decodeControl in interface DecodeableControl

Parameters:

oid - The OID for the control.

isCritical - Indicates whether the control should be marked critical.

value - The encoded value for the control. This may be null if no value was provided.

Returns:

The decoded representation of this control.

Throws:

LDAPException - If the provided information cannot be decoded as a valid instance of this decodeable control.

get

@Nullable
public static PasswordExpiredControl get(@NotNull
                                                   LDAPResult result)
                                            throws LDAPException

Extracts a password expired control from the provided result.

Parameters:

result - The result from which to retrieve the password expired control.

Returns:

The password expired control contained in the provided result, or null if the result did not contain a password expired control.

Throws:

LDAPException - If a problem is encountered while attempting to decode the password expired control contained in the provided result.

get

@Nullable
public static PasswordExpiredControl get(@NotNull
                                                   LDAPException exception)
                                            throws LDAPException

Extracts a password expired control from the provided exception.

Parameters:

exception - The exception from which to retrieve the password expired control.

Returns:

The password expired control contained in the provided exception, or null if the exception did not contain a password expired control.

Throws:

LDAPException - If a problem is encountered while attempting to decode the password expired control contained in the provided exception.

getControlName

@NotNull
public java.lang.String getControlName()

Retrieves the user-friendly name for this control, if available. If no user-friendly name has been defined, then the OID will be returned.

Overrides:

getControlName in class Control

Returns:

The user-friendly name for this control, or the OID if no user-friendly name is available.

toJSONControl

@NotNull
public JSONObject toJSONControl()

Retrieves a representation of this password expired control as a JSON object. The JSON object uses the following fields (note that since this control has a fixed value that is always exactly the same for all instances of the control, neither the value-base64 nor value-json fields may be present):

• oid -- A mandatory string field whose value is the object identifier for this control. For the password expired control, the OID is "2.16.840.1.113730.3.4.4".
• control-name -- An optional string field whose value is a human-readable name for this control. This field is only intended for descriptive purposes, and when decoding a control, the oid field should be used to identify the type of control.
• criticality -- A mandatory Boolean field used to indicate whether this control is considered critical.

Overrides:

toJSONControl in class Control

Returns:

A JSON object that contains a representation of this control.

decodeJSONControl

@NotNull
public static PasswordExpiredControl decodeJSONControl(@NotNull
                                                                JSONObject controlObject,
                                                                boolean strict)
                                                         throws LDAPException

Attempts to decode the provided object as a JSON representation of a password expired control.

Parameters:

controlObject - The JSON object to be decoded. It must not be null.

strict - Indicates whether to use strict mode when decoding the provided JSON object. If this is true, then this method will throw an exception if the provided JSON object contains any unrecognized fields. If this is false, then unrecognized fields will be ignored.

Returns:

The password expired control that was decoded from the provided JSON object.

Throws:

LDAPException - If the provided JSON object cannot be parsed as a valid password expired control.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer)

Appends a string representation of this LDAP control to the provided buffer.

Overrides:

toString in class Control

Parameters:

buffer - The buffer to which to append the string representation of this buffer.