loliball/media3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revise javadoc for Rating classes

Browse Source 
PiperOrigin-RevId: 371625281
This commit is contained in:
gyumin 2021-05-03 04:19:38 +01:00 committed by bachinger
parent 54440261b0
commit 3be50b26a0
6 changed files with 107 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
library/common/src/main/java/com/google/android/exoplayer2/HeartRating.java
View File

@ -26,42 +26,40 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* A class for rating with a single degree of rating, "heart" vs "no heart". This can be used to
* indicate the content referred to is a favorite (or not).
* A rating expressed as "heart" or "no heart". It can be used to indicate whether the content is a
* favorite.
*/
public final class HeartRating extends Rating {
@RatingType private static final int TYPE = RATING_TYPE_HEART;
private final boolean rated;
private final boolean isRated;
/** Whether the rating is "heart". */
public final boolean isHeart;
/** Whether the rating has a heart rating or not. */
public final boolean hasHeart;
/** Creates a unrated HeartRating instance. */
/** Creates a unrated instance. */
public HeartRating() {
isRated = false;
hasHeart = false;
rated = false;
isHeart = false;
}
/**
* Creates a HeartRating instance.
* Creates a rated instance.
*
* @param hasHeart true for a "heart selected" rating, false for "heart unselected".
* @param isHeart {@code true} for "heart", {@code false} for "no heart".
*/
public HeartRating(boolean hasHeart) {
isRated = true;
this.hasHeart = hasHeart;
public HeartRating(boolean isHeart) {
rated = true;
this.isHeart = isHeart;
}
@Override
public boolean isRated() {
return isRated;
return rated;
}
@Override
public int hashCode() {
return Objects.hashCode(isRated, hasHeart);
return Objects.hashCode(rated, isHeart);
}
@Override
@ -70,42 +68,40 @@ public final class HeartRating extends Rating {
return false;
}
HeartRating other = (HeartRating) obj;
return hasHeart == other.hasHeart && isRated == other.isRated;
}
@Override
public String toString() {
return "HeartRating: " + (isRated ? "hasHeart=" + hasHeart : "unrated");
return isHeart == other.isHeart && rated == other.rated;
}
// Bundleable implementation.
@RatingType private static final int TYPE = RATING_TYPE_HEART;
@Documented
@Retention(RetentionPolicy.SOURCE)
@IntDef({FIELD_RATING_TYPE, FIELD_IS_RATED, FIELD_HAS_HEART})
@IntDef({FIELD_RATING_TYPE, FIELD_RATED, FIELD_IS_HEART})
private @interface FieldNumber {}
private static final int FIELD_IS_RATED = 1;
private static final int FIELD_HAS_HEART = 2;
private static final int FIELD_RATED = 1;
private static final int FIELD_IS_HEART = 2;
@Override
public Bundle toBundle() {
Bundle bundle = new Bundle();
bundle.putInt(keyForField(FIELD_RATING_TYPE), TYPE);
bundle.putBoolean(keyForField(FIELD_IS_RATED), isRated);
bundle.putBoolean(keyForField(FIELD_HAS_HEART), hasHeart);
bundle.putBoolean(keyForField(FIELD_RATED), rated);
bundle.putBoolean(keyForField(FIELD_IS_HEART), isHeart);
return bundle;
}
/** Object that can restore a {@link HeartRating} from a {@link Bundle}. */
public static final Creator<HeartRating> CREATOR = HeartRating::fromBundle;
private static HeartRating fromBundle(Bundle bundle) {
checkArgument(
bundle.getInt(keyForField(FIELD_RATING_TYPE), /* defaultValue= */ RATING_TYPE_DEFAULT)
== TYPE);
boolean isRated = bundle.getBoolean(keyForField(FIELD_IS_RATED), /* defaultValue= */ false);
boolean isRated = bundle.getBoolean(keyForField(FIELD_RATED), /* defaultValue= */ false);
return isRated
? new HeartRating(
bundle.getBoolean(keyForField(FIELD_HAS_HEART), /* defaultValue= */ false))
? new HeartRating(bundle.getBoolean(keyForField(FIELD_IS_HEART), /* defaultValue= */ false))
: new HeartRating();
}

26
library/common/src/main/java/com/google/android/exoplayer2/PercentageRating.java
View File

@ -26,30 +26,27 @@ import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/** A class for rating expressed as a percentage. */
/** A rating expressed as a percentage. */
public final class PercentageRating extends Rating {
@RatingType private static final int TYPE = RATING_TYPE_PERCENTAGE;
/**
* The percent value of this rating. Will be greater or equal to 0.0f, or {@link #RATING_UNSET} if
* it is unrated.
* The percent value of this rating. Will be within the range {@code [0f, 100f]}, or {@link
* #RATING_UNSET} if unrated.
*/
public final float percent;
/** Creates a unrated PercentageRating instance. */
/** Creates a unrated instance. */
public PercentageRating() {
percent = RATING_UNSET;
}
/**
* Creates a PercentageRating instance with the given percentage. If {@code percent} is less than
* 0f or greater than 100f, it will throw IllegalArgumentException.
* Creates a rated instance with the given percentage.
*
* @param percent the value of the rating
* @param percent The percentage value of the rating.
*/
public PercentageRating(@FloatRange(from = 0, to = 100) float percent) {
checkArgument(percent >= 0.0f && percent <= 100.0f, "percent must be in the rage of [0, 100]");
checkArgument(percent >= 0.0f && percent <= 100.0f, "percent must be in the range of [0, 100]");
this.percent = percent;
}
@ -71,12 +68,10 @@ public final class PercentageRating extends Rating {
return percent == ((PercentageRating) obj).percent;
}
@Override
public String toString() {
return "PercentageRating: " + (isRated() ? "percentage=" + percent : "unrated");
}
// Bundleable implementation.
@RatingType private static final int TYPE = RATING_TYPE_PERCENTAGE;
@Documented
@Retention(RetentionPolicy.SOURCE)
@IntDef({FIELD_RATING_TYPE, FIELD_PERCENT})
@ -92,6 +87,7 @@ public final class PercentageRating extends Rating {
return bundle;
}
/** Object that can restore a {@link PercentageRating} from a {@link Bundle}. */
public static final Creator<PercentageRating> CREATOR = PercentageRating::fromBundle;
private static PercentageRating fromBundle(Bundle bundle) {

36
library/common/src/main/java/com/google/android/exoplayer2/Rating.java
View File

@ -21,11 +21,23 @@ import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/** An abstract class to encapsulate rating information used as content metadata. */
/**
* A rating for media content. The style of a rating can be one of {@link HeartRating}, {@link
* PercentageRating}, {@link StarRating}, or {@link ThumbRating}.
*/
public abstract class Rating implements Bundleable {
/** A float value that denotes the rating is unset. */
public static final float RATING_UNSET = -1.0f;
// Default package-private constructor to prevent extending Rating class outside this package.
/* package */ Rating() {}
/** Whether the rating exists or not. */
public abstract boolean isRated();
// Bundleable implementation.
@Documented
@Retention(RetentionPolicy.SOURCE)
@IntDef({
@ -35,28 +47,22 @@ public abstract class Rating implements Bundleable {
RATING_TYPE_STAR,
RATING_TYPE_THUMB
})
protected @interface RatingType {}
/* package */ @interface RatingType {}
protected static final int RATING_TYPE_DEFAULT = -1;
protected static final int RATING_TYPE_HEART = 0;
protected static final int RATING_TYPE_PERCENTAGE = 1;
protected static final int RATING_TYPE_STAR = 2;
protected static final int RATING_TYPE_THUMB = 3;
/* package */ static final int RATING_TYPE_DEFAULT = -1;
/* package */ static final int RATING_TYPE_HEART = 0;
/* package */ static final int RATING_TYPE_PERCENTAGE = 1;
/* package */ static final int RATING_TYPE_STAR = 2;
/* package */ static final int RATING_TYPE_THUMB = 3;
// Default package-private constructor to prevent extending Rating class outside this package.
/* package */ Rating() {}
/** Whether rating exists or not. */
public abstract boolean isRated();
// Bundleable implementation.
@Documented
@Retention(RetentionPolicy.SOURCE)
@IntDef({FIELD_RATING_TYPE})
private @interface FieldNumber {}
protected static final int FIELD_RATING_TYPE = 0;
/* package */ static final int FIELD_RATING_TYPE = 0;
/** Object that can restore a {@link Rating} from a {@link Bundle}. */
public static final Creator<Rating> CREATOR = Rating::fromBundle;
private static Rating fromBundle(Bundle bundle) {

43
library/common/src/main/java/com/google/android/exoplayer2/StarRating.java
View File

@ -27,28 +27,24 @@ import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/** A class for rating expressed as the number of stars. */
/** A rating expressed as a fractional number of stars. */
public final class StarRating extends Rating {
@RatingType private static final int TYPE = RATING_TYPE_STAR;
private static final int MAX_STARS_DEFAULT = 5;
/** The maximum number of stars for this rating. Must be a positive number. */
/** The maximum number of stars. Must be a positive number. */
@IntRange(from = 1)
public final int maxStars;
/**
* The value of stars for this rating. Will range from 0.0f to {@link #maxStars}, or {@link
* #RATING_UNSET} if it is unrated.
* The fractional number of stars of this rating. Will range from {@code 0f} to {@link #maxStars},
* or {@link #RATING_UNSET} if unrated.
*/
public final float starRating;
/**
* Creates a unrated StarRating instance with {@code maxStars}. If {@code maxStars} is not a
* positive integer, it will throw IllegalArgumentException.
* Creates a unrated instance with {@code maxStars}. If {@code maxStars} is not a positive
* integer, it will throw an {@link IllegalArgumentException}.
*
* @param maxStars a range of this star rating from 0.0f to {@code maxStars}
* @param maxStars The maximum number of stars this rating can have.
*/
public StarRating(@IntRange(from = 1) int maxStars) {
checkArgument(maxStars > 0, "maxStars must be a positive integer");
@ -57,13 +53,14 @@ public final class StarRating extends Rating {
}
/**
* Creates a StarRating instance with {@code maxStars} and the given integer or fractional number
* of stars. Non-integer values can for instance be used to represent an average rating value,
* which might not be an integer number of stars. If {@code maxStars} is not a positive integer or
* {@code starRating} has invalid value, it will throw IllegalArgumentException.
* Creates a rated instance with {@code maxStars} and the given fractional number of stars.
* Non-integer values may be used to represent an average rating value. If {@code maxStars} is not
* a positive integer or {@code starRating} is out of range, it will throw an {@link
* IllegalArgumentException}.
*
* @param maxStars the maximum number of stars which this rating can have.
* @param starRating a number ranging from 0.0f to {@code maxStars}
* @param maxStars The maximum number of stars this rating can have.
* @param starRating A fractional number of stars of this rating from {@code 0f} to {@code
* maxStars}.
*/
public StarRating(@IntRange(from = 1) int maxStars, @FloatRange(from = 0.0) float starRating) {
checkArgument(maxStars > 0, "maxStars must be a positive integer");
@ -92,14 +89,11 @@ public final class StarRating extends Rating {
return maxStars == other.maxStars && starRating == other.starRating;
}
@Override
public String toString() {
return "StarRating: maxStars="
+ maxStars
+ (isRated() ? ", starRating=" + starRating : ", unrated");
}
// Bundleable implementation.
@RatingType private static final int TYPE = RATING_TYPE_STAR;
private static final int MAX_STARS_DEFAULT = 5;
@Documented
@Retention(RetentionPolicy.SOURCE)
@IntDef({FIELD_RATING_TYPE, FIELD_MAX_STARS, FIELD_STAR_RATING})
@ -117,6 +111,7 @@ public final class StarRating extends Rating {
return bundle;
}
/** Object that can restore a {@link StarRating} from a {@link Bundle}. */
public static final Creator<StarRating> CREATOR = StarRating::fromBundle;
private static StarRating fromBundle(Bundle bundle) {

57
library/common/src/main/java/com/google/android/exoplayer2/ThumbRating.java
View File

@ -25,40 +25,38 @@ import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/** A class for rating with a single degree of rating, "thumb up" vs "thumb down". */
/** A rating expressed as "thumbs up" or "thumbs down". */
public final class ThumbRating extends Rating {
@RatingType private static final int TYPE = RATING_TYPE_THUMB;
private final boolean rated;
private final boolean isRated;
/** Whether the rating is "thumbs up". */
public final boolean isThumbsUp;
/** Whether the rating has a thumb up or thumb down rating. */
public final boolean thumbUp;
/** Creates a unrated ThumbRating instance. */
/** Creates a unrated instance. */
public ThumbRating() {
isRated = false;
thumbUp = false;
rated = false;
isThumbsUp = false;
}
/**
* Creates a ThumbRating instance.
* Creates a rated instance.
*
* @param thumbIsUp true for a "thumb up" rating, false for "thumb down".
* @param isThumbsUp {@code true} for "thumbs up", {@code false} for "thumbs down".
*/
public ThumbRating(boolean thumbIsUp) {
isRated = true;
thumbUp = thumbIsUp;
public ThumbRating(boolean isThumbsUp) {
rated = true;
this.isThumbsUp = isThumbsUp;
}
@Override
public boolean isRated() {
return isRated;
return rated;
}
@Override
public int hashCode() {
return Objects.hashCode(isRated, thumbUp);
return Objects.hashCode(rated, isThumbsUp);
}
@Override
@ -67,42 +65,41 @@ public final class ThumbRating extends Rating {
return false;
}
ThumbRating other = (ThumbRating) obj;
return thumbUp == other.thumbUp && isRated == other.isRated;
}
@Override
public String toString() {
return "ThumbRating: " + (isRated ? "isThumbUp=" + thumbUp : "unrated");
return isThumbsUp == other.isThumbsUp && rated == other.rated;
}
// Bundleable implementation.
@RatingType private static final int TYPE = RATING_TYPE_THUMB;
@Documented
@Retention(RetentionPolicy.SOURCE)
@IntDef({FIELD_RATING_TYPE, FIELD_IS_RATED, FIELD_IS_THUMB_UP})
@IntDef({FIELD_RATING_TYPE, FIELD_RATED, FIELD_IS_THUMBS_UP})
private @interface FieldNumber {}
private static final int FIELD_IS_RATED = 1;
private static final int FIELD_IS_THUMB_UP = 2;
private static final int FIELD_RATED = 1;
private static final int FIELD_IS_THUMBS_UP = 2;
@Override
public Bundle toBundle() {
Bundle bundle = new Bundle();
bundle.putInt(keyForField(FIELD_RATING_TYPE), TYPE);
bundle.putBoolean(keyForField(FIELD_IS_RATED), isRated);
bundle.putBoolean(keyForField(FIELD_IS_THUMB_UP), thumbUp);
bundle.putBoolean(keyForField(FIELD_RATED), rated);
bundle.putBoolean(keyForField(FIELD_IS_THUMBS_UP), isThumbsUp);
return bundle;
}
/** Object that can restore a {@link ThumbRating} from a {@link Bundle}. */
public static final Creator<ThumbRating> CREATOR = ThumbRating::fromBundle;
private static ThumbRating fromBundle(Bundle bundle) {
checkArgument(
bundle.getInt(keyForField(FIELD_RATING_TYPE), /* defaultValue= */ RATING_TYPE_DEFAULT)
== TYPE);
boolean isRated = bundle.getBoolean(keyForField(FIELD_IS_RATED), /* defaultValue= */ false);
return isRated
boolean rated = bundle.getBoolean(keyForField(FIELD_RATED), /* defaultValue= */ false);
return rated
? new ThumbRating(
bundle.getBoolean(keyForField(FIELD_IS_THUMB_UP), /* defaultValue= */ false))
bundle.getBoolean(keyForField(FIELD_IS_THUMBS_UP), /* defaultValue= */ false))
: new ThumbRating();
}

4
library/common/src/test/java/com/google/android/exoplayer2/RatingTest.java
View File

@ -39,7 +39,7 @@ public class RatingTest {
boolean hasHeart = true;
HeartRating rating = new HeartRating(hasHeart);
assertThat(rating.isRated()).isTrue();
assertThat(rating.hasHeart).isEqualTo(hasHeart);
assertThat(rating.isHeart).isEqualTo(hasHeart);
assertThat(roundTripViaBundle(rating)).isEqualTo(rating);
}
@ -71,7 +71,7 @@ public class RatingTest {
boolean isThumbUp = true;
ThumbRating rating = new ThumbRating(isThumbUp);
assertThat(rating.isRated()).isTrue();
assertThat(rating.thumbUp).isEqualTo(isThumbUp);
assertThat(rating.isThumbsUp).isEqualTo(isThumbUp);
assertThat(roundTripViaBundle(rating)).isEqualTo(rating);
}