Leaderboard.java

/*
 * Copyright 2014-2015 GameUp
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.gameup.android.entity;

import com.google.gson.annotations.SerializedName;

import java.util.Iterator;
import java.util.List;

import lombok.AllArgsConstructor;
import lombok.Data;

/**
 * Represents a GameUp leaderboard metadata and top ranked gamers.
 */
@Data
@AllArgsConstructor(suppressConstructorProperties = true)
public class Leaderboard implements Iterable<Leaderboard.Entry> {

    /** The leaderboard unique identifier. */
    private final String leaderboardId;

    /** Leaderboard display name. */
    private final String name;

    /** Leaderboard public identifier. */
    private final String publicId;

    /** Sort order indicator. */
    private final Sort sort;

    /** Type indicator. */
    private final Type type;

    /**
     * A hint string giving additional information about how entry scores should
     * be formatted.
     */
    private final String displayHint;

    /** Tags potentially indicating leaderboard category, grouping hints etc */
    private final List<String> tags;

    /** Score limit, if set in the leaderboard configuration. */
    private final long scoreLimit;

    /** When this leaderboard was published. */
    private final long createdAt;

    /** The reset schedule of this leaderboard, if one is set. */
    private final Reset leaderboardReset;

    /**
     * Indicates the offset of entries that was requested.
     *
     * Examples:
     * offset = 0: first page
     * offset = 0 + limit: second page
     * offset = 0 + (limit * n): page n + 1
     */
    private final int offset;

    /**
     * Indicates the number of entries that was requested.
     *
     * Hint: if the number of entries present is less than this limit, this is
     * the last page of entries in this leaderboard.
     */
    private final int limit;

    /**
     * The top ranked gamers on this board, up to 50. Already sorted according
     * to the leaderboard sort settings.
     */
    private final List<Entry> entries;

    @Override
    public Iterator<Leaderboard.Entry> iterator() {
        return entries.iterator();
    }

    /**
     * A leaderboard reset schedule.
     */
    @Data
    @AllArgsConstructor(suppressConstructorProperties = true)
    public static class Reset {

        /** The type of reset this instance represents. */
        private final Type type;

        /** The hour of the day when the reset is scheduled. */
        private final int utcHour;

        /** The day of the week the reset is scheduled, if applicable. */
        private final Integer dayOfWeek;

        /** The day of the month the reset is scheduled, if applicable. */
        private final Integer dayOfMonth;

        /**
         * Leaderboard reset type.
         */
        public enum Type {

            /** Resets once per day. */
            @SerializedName("daily")
            DAILY,

            /** Resets once per week. */
            @SerializedName("weekly")
            WEEKLY,

            /** Resets once per month. */
            @SerializedName("monthly")
            MONTHLY

        }

    }

    /**
     * A gamer's public leaderboard entry data.
     */
    @Data
    @AllArgsConstructor(suppressConstructorProperties = true)
    public static class Entry {

        /** The rank on the leaderboard occupied by this entry. */
        private final long rank;

        /** Nickname, suitable for public display. */
        private final String name;

        /**
         * Any scoretags associated with this entry, if requested and avaliable.
         */
        private final Object scoretags;

        /** Score. */
        private final long score;

        /** When the score was submitted to this leaderboard. */
        private final long scoreAt;

    }

    /**
     * Leaderboard sort order hint.
     */
    public enum Sort {

        /** Indicates the entries should be sorted ascending by score. */
        @SerializedName("asc")
        ASC,

        /** Indicates the entries should be sorted descending by score. */
        @SerializedName("desc")
        DESC

    }

    /**
     * Leaderboard type hint.
     */
    public enum Type {

        /** Standard best score, one entry per gamer leaderboard type. */
        @SerializedName("rank")
        RANK

    }

}