se.vlovgr.examresults.parse.ParsedResults.java Source code

Introduction

Here is the source code for se.vlovgr.examresults.parse.ParsedResults.java

Source

/*
 * Filename: @(#)ParsedResults.java
 * Last Modified: 2014-01-17 22:21:11
 * License: Copyleft () 2014. All rights reversed.
 *
 * This program is free software. It comes without any warranty, to
 * the extent permitted by applicable law. You can redistribute it
 * and/or modify it under the terms of the Do What The Fuck You Want
 * To Public License, Version 2, as published by Sam Hocevar. See
 * http://sam.zoy.org/wtfpl/COPYING for more details.
 */

package se.vlovgr.examresults.parse;

import com.google.common.base.Objects;
import com.google.common.base.Optional;
import com.google.common.collect.ImmutableList;
import se.vlovgr.examresults.result.CourseExam;

import java.util.List;

import static com.google.common.base.Preconditions.checkNotNull;

/**
 * An immutable class holding information returned from having parsed
 * course exam instances from a response to a query. Except for the
 * parsed instances, one can optionally include the total number
 * of parts available in the response.
 */
public final class ParsedResults {

    /** The parsed course exam instances; as an immutable list. */
    private final List<CourseExam> courseExams;

    /** The total amount of parts in the response; wrapped as an optional. */
    private final Optional<Integer> totalParts;

    /**
     * Creates a new {@code ParsedResults} instance using the specified immutable
     * list of immutable course exam instances. The parsed results should have been
     * parsed from the response to a query. The specified integer value is the total
     * amount of parts available in the response to the query. If a negative value
     * is specified, the information will be marked as absent. Also, consider using
     * the {@link #ParsedResults(ImmutableList)} constructor in such case.
     *
     * @param courseExams the course exam instances which have been parsed
     * @param totalParts the total number of parts available; negative if omitted
     * @throws NullPointerException if the list or any element is {@code null}
     */
    public ParsedResults(final ImmutableList<CourseExam> courseExams, final int totalParts) {
        checkNotNull(courseExams, "courseExams null");
        for (int i = 0, c = courseExams.size(); i < c; i++)
            checkNotNull(courseExams.get(i), "courseExams[%s] null", i);

        this.courseExams = courseExams;
        this.totalParts = totalParts < 0 ? Optional.<Integer>absent() : Optional.of(totalParts);
    }

    /**
     * Creates a new {@code ParsedResults} instance using the specified immutable
     * list of immutable course exam instances. The parsed results should have been
     * parsed from the response to a query. Note that it is also possible to specify
     * the total number of parts using the {@link #ParsedResults(ImmutableList, int)}
     * constructor. When using this constructor, the number of parts will be marked
     * as absent.
     *
     * @param courseExams the course exam instances which have been parsed
     * @throws NullPointerException if the list or any element is {@code null}
     */
    public ParsedResults(final ImmutableList<CourseExam> courseExams) {
        this(courseExams, -1);
    }

    /**
     * Gets the course exam instances which have been parsed from the response
     * to the query for which the response was obtained. The returned list will
     * contain only immutable instances and the list itself is also immutable.
     *
     * @return the parsed course exam instances from the response
     */
    public List<CourseExam> getCourseExams() {
        return courseExams;
    }

    /**
     * Gets the total amount of parts, or search results, available in the
     * response to the query for which the results where obtained. In case
     * the number of parts where not parsed when the results were
     * retrieved, the returned instance will be absent.
     *
     * @return the total number of parts available in the response;
     * or an absent optional instance if this value is unknown
     */
    public Optional<Integer> getTotalParts() {
        return totalParts;
    }

    /** {@inheritDoc} */
    @Override
    public boolean equals(final Object o) {
        if (this == o)
            return true;
        if (!(o instanceof ParsedResults))
            return false;

        final ParsedResults p = (ParsedResults) o;
        return courseExams.equals(p.courseExams) && totalParts.equals(p.totalParts);
    }

    /** {@inheritDoc} */
    @Override
    public int hashCode() {
        return Objects.hashCode(courseExams, totalParts);
    }

    /** {@inheritDoc} */
    @Override
    public String toString() {
        final Objects.ToStringHelper helper = Objects.toStringHelper(this).add("courseExams", courseExams);

        if (totalParts.isPresent())
            helper.add("totalParts", totalParts.get());
        return helper.toString();
    }
}