UserPropertiesProvider.java 4.95 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
Matt Tucker's avatar
Matt Tucker committed
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
package org.jivesoftware.messenger.user;

import org.jivesoftware.messenger.auth.UnauthorizedException;
import java.util.Map;

/**
 * <p>Implement this provider to store user and vcard properties somewhere
 * other than the Jive tables, or to capture jive property events.</p>
 * <p/>
 * <p>Implementors: Most integrators will not need to create their own
 * user property providers. In almost all cases, it's best to let Messenger
 * store these values in the Jive tables.</p>
 *
 * @author Iain Shigeoka
 */
public interface UserPropertiesProvider {

    /**
     * <p>Delete a user's vcard property (optional operation).</p>
     *
32
     * @param username the username of the user
Matt Tucker's avatar
Matt Tucker committed
33 34 35 36
     * @param name The name of the property to delete
     * @throws UnauthorizedException         If the caller does not have permission to carry out the operation
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
37
    public void deleteVcardProperty(String username, String name) throws UnauthorizedException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
38 39 40 41

    /**
     * <p>Delete a user's user property (optional operation).</p>
     *
42
     * @param username the username of the user
Matt Tucker's avatar
Matt Tucker committed
43 44 45 46
     * @param name The name of the property to delete
     * @throws UnauthorizedException         If the caller does not have permission to carry out the operation
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
47
    public void deleteUserProperty(String username, String name) throws UnauthorizedException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
48 49 50 51

    /**
     * <p>Insert a new vcard property (optional operation).</p>
     *
52
     * @param username the username of the user
Matt Tucker's avatar
Matt Tucker committed
53 54 55 56 57
     * @param name  The name of the property
     * @param value The value of the property
     * @throws UnauthorizedException         If the caller does not have permission to carry out the operation
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
58
    public void insertVcardProperty(String username, String name, String value) throws UnauthorizedException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
59 60 61 62

    /**
     * <p>Insert a new user property (optional operation).</p>
     *
63
     * @param username the username of the user
Matt Tucker's avatar
Matt Tucker committed
64 65 66 67 68
     * @param name  The name of the property
     * @param value The value of the property
     * @throws UnauthorizedException         If the caller does not have permission to carry out the operation
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
69
    public void insertUserProperty(String username, String name, String value) throws UnauthorizedException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
70 71 72 73

    /**
     * <p>Update a vcard property (optional operation).</p>
     *
74 75 76 77 78
     * @param username the username of the user.
     * @param name  The name of the property.
     * @param value The value of the property.
     * @throws UnauthorizedException  if the caller does not have permission to carry out the operation
     * @throws UnsupportedOperationException if the provider does not support the operation (this is an optional operation).
Matt Tucker's avatar
Matt Tucker committed
79
     */
80 81
    public void updateVcardProperty(String username, String name, String value)
            throws UnauthorizedException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
82 83 84 85

    /**
     * <p>Update an Existing user property (optional operation).</p>
     *
86
     * @param username the username of the user
Matt Tucker's avatar
Matt Tucker committed
87 88 89 90 91
     * @param name  The name of the property
     * @param value The value of the property
     * @throws UnauthorizedException         If the caller does not have permission to carry out the operation
     * @throws UnsupportedOperationException If the provider does not support the operation (this is an optional operation)
     */
92
    public void updateUserProperty(String username, String name, String value) throws UnauthorizedException, UnsupportedOperationException;
Matt Tucker's avatar
Matt Tucker committed
93 94 95 96 97 98

    /**
     * <p>Obtain a map containing all vcard properties for a user.</p>
     * <p/>
     * <p>If the provider doesn't support vcard properties, return an empty map.</p>
     *
99
     * @param username the username of the user to retrieve the vcard properties
Matt Tucker's avatar
Matt Tucker committed
100 101
     * @return A map of property name-value pairs
     */
102
    public Map getVcardProperties(String username);
Matt Tucker's avatar
Matt Tucker committed
103 104 105 106 107 108

    /**
     * <p>Obtain a map containing all user properties for a user.</p>
     * <p/>
     * <p>If the provider doesn't support user properties, return an empty map.</p>
     *
109
     * @param username the username of the user to retrieve the user properties
Matt Tucker's avatar
Matt Tucker committed
110 111
     * @return A map of property name-value pairs
     */
112
    public Map getUserProperties(String username);
Matt Tucker's avatar
Matt Tucker committed
113
}