Presence.java 6.2 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
 * Copyright (C) 2002 CoolServlets, Inc. All rights reserved.
 *
 * This software is the proprietary information of CoolServlets, Inc.
 * Use is subject to license terms.
 */
package org.jivesoftware.messenger;

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

/**
 * <p>Allows the simple creation, reading, and updating of presence packets.<p>
 * <p>The methods used are mainly convenience interfaces to the various parts
 * of a typical presence packet.</p>
 * <p>A Presence encapsulates information relating to the owning user such as login time, status and
 * last update time.</p>
 *
 * @author Iain Shigeoka
 */
public interface Presence extends XMPPPacket {


    /**
     * <p>Sender is available for messaging.</p>
     */
    Type AVAILABLE = new Type("");
    /**
     * <p>Sender is unavailable for messaging.</p>
     */
    Type UNAVAILABLE = new Type("unavailable");
    /**
     * <p>Sender is available for message reciept but presence should not be broadcast to roster members.</p>
     */
    Type INVISIBLE = new Type("invisible");
    /**
     * <p>Sender wishes to subscribe to recipient's roster.</p>
     */
    Type SUBSCRIBE = new Type("subscribe");
    /**
     * <p>Indicates the sender should be unsubscribed from the recipient's roster.</p>
     */
    Type UNSUBSCRIBE = new Type("unsubscribe");
    /**
     * <p>Sent to indicate a pending subcription request has been filled.</p>
     */
    Type SUBSCRIBED = new Type("subscribed");
    /**
     * <p>Sent to indicate a pending subscription removal request has been filled.</p>
     */
    Type UNSUBSCRIBED = new Type("unsubscribed");
    /**
     * <p>Used when the sender wants to know the recipient's presence.</p>
     */
    Type PROBE = new Type("probe");

    int NO_PRIORITY = -10;

    public static final int STATUS_ONLINE = 0;

    public static final int STATUS_IDLE = 1;

    public static final int STATUS_INVISIBLE = 2;

    public static final int STATUS_OFFLINE = 4;

    public static final int STATUS_PROBE = -1;

    /**
     * Available to chat show state
     */
    public static final int SHOW_CHAT = 100;
    /**
     * No show state
     */
    public static final int SHOW_NONE = 101;
    /**
     * Away show state
     */
    public static final int SHOW_AWAY = 102;
    /**
     * "Extended away" show state
     */
    public static final int SHOW_XA = 103;
    /**
     * Do not disturb show state
     */
    public static final int SHOW_DND = 104;
    /**
     * Invisible show state (user not shown)
     */
    public static final int SHOW_INVISIBLE = 110;

    /**
     * The online/offline status of the user. Being available indicates that the node can be
     * sent packets and does not imply how the presence is propogated or presented to users.
     *
     * @return True if the node is available for messaging
     */
    public boolean isAvailable();

    /**
     * Sets the online/offline status of the user.
     *
     * @param online True if the node is available for messaging
     */
    public void setAvailable(boolean online) throws UnauthorizedException;

    /**
     * Gets the visibility of the user. Invisible nodes can be sent packets, but don't
     * automatically propagate presence to subscribers.
     *
     * @return True if the user is visible
     *         (presence should be automatically propagated to subscribers)
     */
    public boolean isVisible();

    /**
     * Sets the visibility of the user. Invisible nodes can be sent packets, but don't
     * automatically propagate presence to subscribers.
     *
     * @param visible True if the node is visible (presence is broadcast)
     * @throws UnauthorizedException If the caller doesn't have permission
     */
    public void setVisible(boolean visible) throws UnauthorizedException;

    /**
     * Returns the unique ID for this status. The ID in the default implmentation is the user's
     * session ID, which is unique within a single JVM.
     *
     * @return the unique ID for the presence.
     */
    public String getID();

    /**
     * Return the user owning the presence.
     *
     * @return the presence owner.
     */
    public long getUserID();

    /**
     * Return the time when the presence was created.
     *
     * @return the time when the presence was created.
     */
    public Date getLoginTime();

    /**
     * Return the time when the presence was last updated (when the user last visited).
     *
     * @return the time when the presence was last updated (when the user last visited).
     */
    public Date getLastUpdateTime();

    /**
     * Set the time when the presence was last updated (when the user last visited).
     *
     * @param time the time of the last update.
     * @throws UnauthorizedException If the caller doesn't have permissions to make this modification
     */
    public void setLastUpdateTime(Date time) throws UnauthorizedException;

    /**
     * Returns the status of the presence.
     *
     * @return the status of the presence.
     */
    public int getShow();

    /**
     * Sets the status of the user.
     *
     * @param status the status of the user.
     * @throws UnauthorizedException If the caller doesn't have permissions to make this modification
     */
    public void setShow(int status) throws UnauthorizedException;

    /**
     * Gets the free text status of the user. (e.g. "out to lunch").
     *
     * @return The status text for the user or null if none has been set
     */
    public String getStatus();

    /**
     * Sets the free text status of the user. (e.g. "out to lunch").
     *
     * @param status The new status or null if none is set
     * @throws UnauthorizedException
     */
    public void setStatus(String status) throws UnauthorizedException;

    /**
     * Obtain the priority associated with this presence if any
     *
     * @return The priority of this presence or -1 to indicate none set
     */
    public int getPriority();

    /**
     * Sets the new priority for this presence
     *
     * @param priority The new priority value
     * @throws UnauthorizedException If the caller doesn't have the appropriate authorization
     */
    public void setPriority(int priority) throws UnauthorizedException;
}