Package org.jivesoftware.openfire.user.property

Interface UserPropertyProvider

All Known Implementing Classes:

DefaultUserPropertyProvider, HybridUserPropertyProvider, JDBCUserPropertyProvider, MappedUserPropertyProvider

public interface UserPropertyProvider

A provider for user properties. User properties are defined Map of String key and values that does not support null. value. Some, but not all, implementations are expected to store user properties in a relation to an existing user object. This interface definition does not require implementations to verify that a user object indeed exists, when processing data. As a result, methods defined here may, but are not required to throw UserNotFoundException when processing property data for non-existing users. Implementations should clearly document their behavior in this respect. Warning: in virtually all cases a user property provider should not be used directly. Instead, use the Map returned by User.getProperties() to create, read, update or delete user properties. Failure to do so is likely to result in inconsistent data behavior and race conditions. Direct access to the user property provider is only provided for special-case logic.

Author:

Guus der Kinderen, guus@goodbytes.nl

See Also:

User.getProperties()

Method Summary

Modifier and Type	Method	Description
void	deleteProperty(String username, String propName)	Removes one particular property for a particular user.
void	insertProperty(String username, String propName, String propValue)	Adds a property for an user.
boolean	isReadOnly()	Returns true if this UserPropertyProvider is read-only.
Map<String,String>	loadProperties(String username)	Retrieves all properties for a particular user.
String	loadProperty(String username, String propName)	Retrieves a property value for a user.
void	updateProperty(String username, String propName, String propValue)	Changes a property value for an user.

Method Detail

isReadOnly

boolean isReadOnly()

Returns true if this UserPropertyProvider is read-only. When read-only, properties can not be created, deleted or modified. Invocation of the corresponding methods should result in an UnsupportedOperationException.

Returns:

true if the user provider is read-only.

loadProperties

Map<String,String> loadProperties(String username)
                                 throws UserNotFoundException

Retrieves all properties for a particular user.

Parameters:

username - The identifier of the user (cannot be null or empty).

Returns:

A collection, possibly empty, but never null.

Throws:

UserNotFoundException - if the user cannot be found

loadProperty

String loadProperty(String username,
                    String propName)
             throws UserNotFoundException

Retrieves a property value for a user. This method will return null when the desired property was not defined for the user (null values are not supported).

Parameters:

username - The identifier of the user (cannot be null or empty).

propName - The property name (cannot be null or empty).

Returns:

The property value (possibly null).

Throws:

UserNotFoundException - if the user cannot be found

insertProperty

void insertProperty(String username,
                    String propName,
                    String propValue)
             throws UserNotFoundException,
                    UnsupportedOperationException

Adds a property for an user. The behavior of inserting a duplicate property name is not defined by this interface.

Parameters:

username - The identifier of the user (cannot be null or empty).

propName - The property name (cannot be null or empty).

propValue - The property value (cannot be null).

Throws:

UserNotFoundException - if the user cannot be found

UnsupportedOperationException - if the property cannot be added

updateProperty

void updateProperty(String username,
                    String propName,
                    String propValue)
             throws UserNotFoundException,
                    UnsupportedOperationException

Changes a property value for an user. The behavior of updating a non-existing property is not defined by this interface.

Parameters:

username - The identifier of the user (cannot be null or empty).

propName - The property name (cannot be null or empty).

propValue - The property value (cannot be null).

Throws:

UserNotFoundException - if the user cannot be found

UnsupportedOperationException - if the property cannot be updated

deleteProperty

void deleteProperty(String username,
                    String propName)
             throws UserNotFoundException,
                    UnsupportedOperationException

Removes one particular property for a particular user. The behavior of deleting a non-existing property is not defined by this interface.

Parameters:

username - The identifier of the user (cannot be null or empty).

propName - The property name (cannot be null or empty).

Throws:

UserNotFoundException - if the user cannot be found

UnsupportedOperationException - if the property cannot be deleted