jespa.examples

Class WordPressAccount

java.lang.Object

java.util.AbstractMap<K,V>

java.util.HashMap

jespa.security.Properties

jespa.examples.WordPressAccount

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map, Account

public class WordPressAccount
extends jespa.security.Properties
implements Account

The Account implementation for the WordPressSecurityProvider which is used to create, update and delete accounts and set or change passwords on accounts in a WordPress MySQL database. An object of this type is returned by WordPressSecurityProvider.getAccount(java.lang.String, java.lang.String[]).

The update method should not be called on the default Account object returned by SecurityProvider.getAccount when using a null account name. If an Account object is constructed from exported data, it's contents may not be current which, depending on the implementation, can result in unexpected update behavior. Using a non-null account name with SecurityProvider.getAccount will ensure that the Account object has current data.

The methods getProperty and setProperty should be favored over get and put so that the implementation has a single point at which to intercept, modify or validate data.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields inherited from class jespa.security.Properties

DUPLICATE_REFERENCE, NO_PROPERTY

Fields inherited from interface jespa.security.Account

ALL_ATTRS

Constructor Summary

Constructors

Constructor and Description
WordPressAccount(WordPressSecurityProvider provider, java.lang.String acctname)

Method Summary

Modifier and Type	Method and Description
void	changePassword(char[] oldpassword, char[] newpassword) Changes the password for this account to the new password only if the old password is correct.
void	create() Create a new account in the WordPress database with all of the attributes of this object.
void	create(java.lang.String[] attrs) Create a new account in the WordPress database with selected attribute values of this object.
void	delete() Delete an existing account in the WordPress database.
java.lang.Object	getProperty(java.lang.String name, java.lang.Object def) Retrieve account attribtues and properties of this account instance.
boolean	isMemberOf(java.lang.String role) Returns true if this account has the specified role.
void	setPassword(char[] password) Set the password for this account to the supplied value in the WordPress database.
void	setProperty(java.lang.String name, java.lang.Object obj) Set account attributes and properties of this account instance.
void	update() Insert, update or delete attributes on an existing account in the WordPress database with all attribute values of this object.
void	update(java.lang.String[] attrs) Insert, update or delete attributes on an existing account in the WordPress database with selected attribute values of this object.

Methods inherited from class jespa.security.Properties

decodeObject, encodeObject, getEncryptedProperty, getFilteredProperties, getFilteredProperties, getProperty, getPropertyAsBoolean, getPropertyAsLong, setEncryptedProperty

Methods inherited from class java.util.HashMap

clear, clone, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface jespa.security.Account

getProperty

Methods inherited from interface java.util.Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Constructor Detail

WordPressAccount

public WordPressAccount(WordPressSecurityProvider provider,
                        java.lang.String acctname)
                 throws SecurityProviderException

Throws:

SecurityProviderException

Method Detail

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object obj)
                 throws SecurityProviderException

Set account attributes and properties of this account instance.

Note: Calling this method will not commit account attributes to the WordPress database. Only methods like create() or update(String[]) will actually INSERT, UPDATE and DELETE data in the WordPress database.

This method may canonicalize the supplied name to a suitable user_login name by remove a domain component (such as from WP5\alice or alice@wp5.busicorp.local to just alice). See the Account Name Canonicalization section in the WordPressSecurityProvider API documentation for details.

This method validates the user_login attribute using the regular expression defined by the WordPressSecurityProvider property account.name.regex which by default is "\S+" to indicate that the user_login must consist entirely of one or more non-space characters.

Specified by:

setProperty in interface Account

Overrides:

setProperty in class jespa.security.Properties

Parameters:

name - The name of the property or attribute to set. If this parameter is user_login, validation is performed.

obj - The value of the property or attribute being set.

Throws:

SecurityProviderException - if the user_login attribute is set and it either fails validation or contains a domain component that does not match configured domain properties.

getProperty

public java.lang.Object getProperty(java.lang.String name,
                                    java.lang.Object def)
                             throws SecurityProviderException

Retrieve account attribtues and properties of this account instance.

Note: This object will only contain attributes populated by previous operations including, but not limited to, the WordPressSecurityProvider.getAccount(java.lang.String, java.lang.String[]) and setProperty(java.lang.String, java.lang.Object) methods.

In addition to account attributes, this method also supports the following properties:

Additional properties supported

Property Name	Description
capabilities	A read-only constructed property that retrieves a Map representing the wp_capabilities from the wp_usermeta table for this account. By default, this Map should contain a "1" (the PHP representation of true) keyed by the name of the role the account is in.

Consider the following code fragment that retrieves and prints elements of the capabilities property:

Map capabilities = (Map)acct.getProperty("capabilities").
if (capabilities != null) {
        Iterator iter = capabilities.iterator();
        while (iter.hasNext()) {
                System.out.println(iter.next());
        }
}

Print all keys of the capabilities Map.

This getProperty method should be favored over the get method so that the implementation can intercept or construct values such as the above mentioned capabilities property.

Specified by:

getProperty in interface Account

Overrides:

getProperty in class jespa.security.Properties

Parameters:

name - The name of the property or attribute to retrieve.

def - The default value to return if the named property or attribute is not set.

Returns:

the value of the named attribute or property

Throws:

SecurityProviderException

create

public void create(java.lang.String[] attrs)
            throws SecurityProviderException

Create a new account in the WordPress database with selected attribute values of this object.

See the create() method description for additional information.

Specified by:

create in interface Account

Parameters:

attrs - A list of attribute names limiting the attributes to be created.

Throws:

SecurityProviderException - if the user_login or user_email attributes are not present or if an SQL error occurs.

create

public void create()
            throws SecurityProviderException

Create a new account in the WordPress database with all of the attributes of this object.

WordPressSecurityProvider wpsp = new WordPressSecurityProvider(props);
try {
    WordPressAccount acct = new WordPressAccount(wpsp, acctname);
    acct.setProperty("user_email", email) ;
    acct.create();
    acct.setPassword(password.toCharArray());
} finally {
    wpsp.dispose();
} 

Creating a WordPress account using the WordPressSecurityProvider and WordPressAccount classes.

Some notes regarding the above example are:

• The user_email attribute is required.
• If the password is to be set, it must be set after create is called and not before.

Unless set otherwise or filtered out using create(String[]), the following default attributes and values will be added:

Default attributes of WordPressAccount

Attribute Name	Default Value
user_nicename	user_login
display_name	user_login
nickname	user_login
rich_editing	true
comment_shortcuts	false
admin_color	fresh
wp_capabilities	a:1:{s:10:"subscriber";b:1;}

This method is equivalent to create(Account.ALL_ATTRS).

Specified by:

create in interface Account

Throws:

SecurityProviderException - if the user_login or user_email attributes are not present or if an SQL error occurs.

update

public void update(java.lang.String[] attrs)
            throws SecurityProviderException

Insert, update or delete attributes on an existing account in the WordPress database with selected attribute values of this object. Only the attributes specified with the attrs parameter will be updated.

All attributes being updated must first be retrieved with a method like WordPressSecurityProvider.getAccount(java.lang.String, java.lang.String[]).

The following example will update only the user_email attribute.

WordPressSecurityProvider wpsp = new WordPressSecurityProvider(props);
try {
    String[] attrs = new String[] { "user_login", "user_email" };
    WordPressAccount acct = (WordPressAccount)wpsp.getAccount(acctname, attrs);
    acct.setProperty("user_email", "alice.baker@example.local");
    acct.update(attrs);
} finally {
    wpsp.dispose();
}

Updating a WordPress account using the WordPressSecurityProvider and WordPressAccount classes.

This method iterates over the attributes to be updated, compares the current values with those of an internal copy created when the account was originally loaded from the database, and executes SQL statements as described in the following table:

SQL operations generated when updating a WordPressAccount

Condition	Resulting SQL Operation
If the attribute is not in the original copy but is present in this object.	INSERT
If the attribute is present in the original copy and in this object but it's value has changed.	UPDATE
If the attribute is in the original copy but has since been removed from this object.	DELETE
Otherwise, no action is taken (becuase the attribute is not in either the original copy or this object or it is present in both but the value has not changed).	No action

Note that if the original copy of the account does not accurately represent exiting database values for the attributes being updated, unexpected results may occur. Specifically, if the WordPressSecurityProvider.getAccount() method was not used or did not retrieve an attribute to be updated (because it was not included in the attrs parameter), the update will attempt to INSERT the value when it should have used UPDATE. This will likely result in an SQL error. Similarly, removing an attribute will not emit the desired DELETE operation if the original copy does not contain the corresponding database value.

If present, the ID attribute of the wp_users table and the umeta_id and user_id fields of the wp_usermeta table are not used by and cannot be modified by this implementation (all operations hinge on the user_login attribute).

Specified by:

update in interface Account

Parameters:

attrs - A list of attribute names indicating the attributes to be updated. If the attrs parameter is the special Account.ALL_ATTRS constant, all attributes of this account instance will be updated.

Throws:

SecurityProviderException - if the user_login attribute is not present or if an SQL error occurs.

update

public void update()
            throws SecurityProviderException

Insert, update or delete attributes on an existing account in the WordPress database with all attribute values of this object.

See the update(String[]) method description for additional information. This method is equivalent to update(Account.ALL_ATTRS).

Specified by:

update in interface Account

Throws:

SecurityProviderException - if the user_login attribute is not present or if an SQL error occurs.

delete

public void delete()
            throws SecurityProviderException

Delete an existing account in the WordPress database. The user_login attribute is used to SELECT and DELETE all wp_usermeta records and subsequently the wp_users table record for the target account.

Specified by:

delete in interface Account

Throws:

SecurityProviderException - if the account does not exist or if an SQL error occurs.

isMemberOf

public boolean isMemberOf(java.lang.String role)
                   throws SecurityProviderException

Returns true if this account has the specified role.

This method retrieves the wp_capabilities field of the wp_usermeta table, unserializes it to a Map and verifies that it contains a key with the supplied role name mapped to a value of "1" (which is the PHP representation of true).

Note: The capabilities Map may also be retrieved using the "capabilities" property. See getProperty(java.lang.String, java.lang.Object) for details.

Specified by:

isMemberOf in interface Account

Parameters:

role - the name of the group to check.

Returns:

true if the Account is in the named group and false otherwise

Throws:

SecurityProviderException - if the account identified by this object cannot be found or if an SQL error occurs.

setPassword

public void setPassword(char[] password)
                 throws SecurityProviderException

Set the password for this account to the supplied value in the WordPress database. Specifically, this method computes the $P$ phpass MD5 password hash (the default WordPress password hashing method) for the supplied password and updates the user_pass field in the wp_users table.

Specified by:

setPassword in interface Account

Throws:

SecurityProviderException - if the account is not found or if an SQL error occurs.

changePassword

public void changePassword(char[] oldpassword,
                           char[] newpassword)
                    throws SecurityProviderException

Changes the password for this account to the new password only if the old password is correct. This method simply calls setPassword with the supplied new password after performing a standard authentication with the supplied old password.

Specified by:

changePassword in interface Account

Parameters:

oldpassword - the current password for this account.

newpassword - the new password to be set on this account.

Throws:

SecurityProviderException - if the account is not found or if an SQLException occurs