001    package org.bukkit.scoreboard;
002    
003    import org.bukkit.OfflinePlayer;
004    
005    /**
006     * An objective on a scoreboard that can show scores specific to entries. This
007     * objective is only relevant to the display of the associated {@link
008     * #getScoreboard() scoreboard}.
009     */
010    public interface Objective {
011    
012        /**
013         * Gets the name of this Objective
014         *
015         * @return this objective'ss name
016         * @throws IllegalStateException if this objective has been unregistered
017         */
018        String getName() throws IllegalStateException;
019    
020        /**
021         * Gets the name displayed to players for this objective
022         *
023         * @return this objective's display name
024         * @throws IllegalStateException if this objective has been unregistered
025         */
026        String getDisplayName() throws IllegalStateException;
027    
028        /**
029         * Sets the name displayed to players for this objective.
030         *
031         * @param displayName Display name to set
032         * @throws IllegalStateException if this objective has been unregistered
033         * @throws IllegalArgumentException if displayName is null
034         * @throws IllegalArgumentException if displayName is longer than 32
035         *     characters.
036         */
037        void setDisplayName(String displayName) throws IllegalStateException, IllegalArgumentException;
038    
039        /**
040         * Gets the criteria this objective tracks.
041         *
042         * @return this objective's criteria
043         * @throws IllegalStateException if this objective has been unregistered
044         */
045        String getCriteria() throws IllegalStateException;
046    
047        /**
048         * Gets if the objective's scores can be modified directly by a plugin.
049         *
050         * @return true if scores are modifiable
051         * @throws IllegalStateException if this objective has been unregistered
052         * @see Criterias#HEALTH
053         */
054        boolean isModifiable() throws IllegalStateException;
055    
056        /**
057         * Gets the scoreboard to which this objective is attached.
058         *
059         * @return Owning scoreboard, or null if it has been {@link #unregister()
060         *     unregistered}
061         */
062        Scoreboard getScoreboard();
063    
064        /**
065         * Unregisters this objective from the {@link Scoreboard scoreboard.}
066         *
067         * @throws IllegalStateException if this objective has been unregistered
068         */
069        void unregister() throws IllegalStateException;
070    
071        /**
072         * Sets this objective to display on the specified slot for the
073         * scoreboard, removing it from any other display slot.
074         *
075         * @param slot display slot to change, or null to not display
076         * @throws IllegalStateException if this objective has been unregistered
077         */
078        void setDisplaySlot(DisplaySlot slot) throws IllegalStateException;
079    
080        /**
081         * Gets the display slot this objective is displayed at.
082         *
083         * @return the display slot for this objective, or null if not displayed
084         * @throws IllegalStateException if this objective has been unregistered
085         */
086        DisplaySlot getDisplaySlot() throws IllegalStateException;
087    
088        /**
089         * Gets a player's Score for an Objective on this Scoreboard
090         *
091         * @param player Player for the Score
092         * @return Score tracking the Objective and player specified
093         * @throws IllegalArgumentException if player is null
094         * @throws IllegalStateException if this objective has been unregistered
095         * @deprecated Scoreboards can contain entries that aren't players
096         * @see #getScore(String)
097         */
098        @Deprecated
099        Score getScore(OfflinePlayer player) throws IllegalArgumentException, IllegalStateException;
100    
101        /**
102         * Gets an entry's Score for an Objective on this Scoreboard.
103         *
104         * @param entry Entry for the Score
105         * @return Score tracking the Objective and entry specified
106         * @throws IllegalArgumentException if entry is null
107         * @throws IllegalStateException if this objective has been unregistered
108         */
109        Score getScore(String entry) throws IllegalArgumentException, IllegalStateException;
110    }