001    package org.bukkit;
002    
003    import java.util.Date;
004    
005    /**
006     * A single entry from a ban list. This may represent either a player ban or
007     * an IP ban.
008     * <p>
009     * Ban entries include the following properties:
010     * <table border=1>
011     * <tr>
012     *     <th>Property</th>
013     *     <th>Description</th>
014     * </tr><tr>
015     *     <td>Target Name / IP Address</td>
016     *     <td>The target name or IP address</td>
017     * </tr><tr>
018     *     <td>Creation Date</td>
019     *     <td>The creation date of the ban</td>
020     * </tr><tr>
021     *     <td>Source</td>
022     *     <td>The source of the ban, such as a player, console, plugin, etc</td>
023     * </tr><tr>
024     *     <td>Expiration Date</td>
025     *     <td>The expiration date of the ban</td>
026     * </tr><tr>
027     *     <td>Reason</td>
028     *     <td>The reason for the ban</td>
029     * </tr>
030     * </table>
031     * <p>
032     * Unsaved information is not automatically written to the implementation's
033     * ban list, instead, the {@link #save()} method must be called to write the
034     * changes to the ban list. If this ban entry has expired (such as from an
035     * unban) and is no longer found in the list, the {@link #save()} call will
036     * re-add it to the list, therefore banning the victim specified.
037     * <p>
038     * Likewise, changes to the associated {@link BanList} or other entries may or
039     * may not be reflected in this entry.
040     */
041    public interface BanEntry {
042    
043        /**
044         * Gets the target involved. This may be in the form of an IP or a player
045         * name.
046         *
047         * @return the target name or IP address
048         */
049        public String getTarget();
050    
051        /**
052         * Gets the date this ban entry was created.
053         *
054         * @return the creation date
055         */
056        public Date getCreated();
057    
058        /**
059         * Sets the date this ban entry was created.
060         *
061         * @param created the new created date, cannot be null
062         * @see #save() saving changes
063         */
064        public void setCreated(Date created);
065    
066        /**
067         * Gets the source of this ban.
068         * <p>
069         * Note: A source is considered any String, although this is generally a
070         * player name.
071         *
072         * @return the source of the ban
073         */
074        public String getSource();
075    
076        /**
077         * Sets the source of this ban.
078         * <p>
079         * Note: A source is considered any String, although this is generally a
080         * player name.
081         *
082         * @param source the new source where null values become empty strings
083         * @see #save() saving changes
084         */
085        public void setSource(String source);
086    
087        /**
088         * Gets the date this ban expires on, or null for no defined end date.
089         *
090         * @return the expiration date
091         */
092        public Date getExpiration();
093    
094        /**
095         * Sets the date this ban expires on. Null values are considered
096         * "infinite" bans.
097         *
098         * @param expiration the new expiration date, or null to indicate an
099         *     eternity
100         * @see #save() saving changes
101         */
102        public void setExpiration(Date expiration);
103    
104        /**
105         * Gets the reason for this ban.
106         *
107         * @return the ban reason, or null if not set
108         */
109        public String getReason();
110    
111        /**
112         * Sets the reason for this ban. Reasons must not be null.
113         *
114         * @param reason the new reason, null values assume the implementation
115         *     default
116         * @see #save() saving changes
117         */
118        public void setReason(String reason);
119    
120        /**
121         * Saves the ban entry, overwriting any previous data in the ban list.
122         * <p>
123         * Saving the ban entry of an unbanned player will cause the player to be
124         * banned once again.
125         */
126        public void save();
127    }