io.sphere.sdk.reviews.Review Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commercetools-models Show documentation
There is a newer version: 2.16.0
package io.sphere.sdk.reviews;

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import io.sphere.sdk.annotations.*;
import io.sphere.sdk.customers.Customer;
import io.sphere.sdk.models.Reference;
import io.sphere.sdk.models.Resource;
import io.sphere.sdk.models.WithKey;
import io.sphere.sdk.states.State;
import io.sphere.sdk.types.Custom;
import io.sphere.sdk.types.CustomFields;
import io.sphere.sdk.types.TypeDraft;

import javax.annotation.Nullable;
import java.util.Locale;

/**
  Reviews are used to evaluate products and channels.

  Review Approval Process

  If you do not need any approval process, skip this part.

 If we have an approval process for a review to be used for a product or a channel, we model the approval process with a state machine.

 First of all, once per commercetools project, we create the approved state. Then we create the initial to-approve state, which has a possible transition to the approved state:

 {@include.example io.sphere.sdk.reviews.approvaldemo.CreateReviewStates}

 Only states with {@link io.sphere.sdk.states.StateRole#REVIEW_INCLUDED_IN_STATISTICS} makes review ratings count in statistics.

 Creating reviews
 Now we can create a review in the initial state to-approve:

 {@include.example io.sphere.sdk.reviews.approvaldemo.CreateReviewToApprove}

 Querying which reviews should be approved

 {@include.example io.sphere.sdk.reviews.approvaldemo.QueryReviewsToApprove}

 Approving a review


 {@include.example io.sphere.sdk.reviews.approvaldemo.ApprovingAReview}

Displaying Products
Searching for Products with a Minimal Rating
 We can display all products that:

 have at least 2 stars (average rating superior to 2)
 with facets about the number of products rated with an average in the different ranges 0 to 1 star, 1 to 2 stars, 2 to 3 stars, 3 to 4 stars and 4 to 5 stars.
 sorted by average ratings
 

 {@include.example io.sphere.sdk.reviews.ReviewProductProjectionSearchIntegrationTest#searchForReviewsWithAverageRatingGreaterThan2()}

 Getting reviews for one product (only approved)
 {@include.example io.sphere.sdk.reviews.ReviewProductProjectionSearchIntegrationTest#getApprovedReviewsForOneProduct()}

 Getting reviews for one product
 {@include.example io.sphere.sdk.reviews.ReviewProductProjectionSearchIntegrationTest#getReviewsForOneProduct()}

 @see io.sphere.sdk.reviews.commands.ReviewCreateCommand
 @see io.sphere.sdk.reviews.commands.ReviewUpdateCommand
 @see io.sphere.sdk.reviews.commands.ReviewDeleteCommand
 @see io.sphere.sdk.reviews.queries.ReviewQuery
 @see io.sphere.sdk.reviews.queries.ReviewByIdGet
 @see io.sphere.sdk.reviews.queries.ReviewByKeyGet
 */
@JsonDeserialize(as = ReviewImpl.class)
@ResourceValue
@HasQueryEndpoint()
@ResourceInfo(pluralName = "reviews", pathElement = "reviews")
@HasByIdGetEndpoint(includeExamples = "io.sphere.sdk.reviews.queries.ReviewByIdGetIntegrationTest#execution()", javadocSummary = "Retrieves a review by a known ID.")
@HasByKeyGetEndpoint
@HasCreateCommand(includeExamples = "io.sphere.sdk.reviews.commands.ReviewCreateCommandIntegrationTest#createByCode()")
@HasUpdateCommand(javadocSummary = "Updates a review.", updateWith = "key")
@HasDeleteCommand(deleteWith = {"key","id"}, canEraseUsersData = true)
@HasQueryModel()
public interface Review extends Resource, Custom, WithKey {
    /**
     * The name of the author which created this review or null.
     *
     * @see io.sphere.sdk.reviews.commands.updateactions.SetAuthorName
     * @return author name
     */
    @Nullable
    String getAuthorName();

    /**
     * Gets the custom fields of this review or null.
     * @see io.sphere.sdk.reviews.commands.updateactions.SetCustomField
     * @see io.sphere.sdk.reviews.commands.updateactions.SetCustomType
     * @return custom fields
     */
    @Nullable
    CustomFields getCustom();

    /**
     * Gets the customer which created this review or null.
     * @see io.sphere.sdk.reviews.commands.updateactions.SetCustomer
     * @return customer
     */
    @Nullable
    Reference getCustomer();

    /**
     * Gets the key assigned to this review or null.
     *
     * @see io.sphere.sdk.reviews.commands.updateactions.SetKey
     * @return key
     */
    @Nullable
    String getKey();

    /**
     * Gets the locale (language) in which the text and title are or null.
     * @return locale
     */
    @Nullable
    @QueryModelHint(type = "io.sphere.sdk.queries.LocaleQuerySortingModel", impl = "return localeQuerySortingModel(fieldName);")
    Locale getLocale();

    /**
     * Gets the rating or null.
     * @see io.sphere.sdk.reviews.commands.updateactions.SetRating
     * @return the rating
     */
    @Nullable
    Integer getRating();

    /**
     * Gets the state of this review or null.
     * @see io.sphere.sdk.reviews.commands.updateactions.TransitionState
     * @return state
     */
    @Nullable
    Reference getState();

    /**
     * Identifies the target of the review. Can be a Product or a Channel or nothing.
     * @see io.sphere.sdk.reviews.commands.updateactions.SetTarget
     * @return the target of this review or null
     */
    @Nullable
    Reference getTarget();

    /**
     * Gets the text of this review or null.
     * @see io.sphere.sdk.reviews.commands.updateactions.SetText
     * @return text
     */
    @Nullable
    String getText();

    /**
     * Gets the title of this review or null.
     * @see io.sphere.sdk.reviews.commands.updateactions.SetTitle
     * @return title
     */
    @Nullable
    String getTitle();

    @Nullable
    String getUniquenessValue();

    /**
     * Indicates if this review is taken into account in the ratings statistics of the target.
     A review is per default used in the statistics, unless the review is in a state that does not have the role ReviewIncludedInStatistics.
     If the role of a State is modified after the calculation of this field, the calculation is not updated.
     * @return is included in review rating of target
     */
    @JsonProperty("includedInStatistics")
    Boolean isIncludedInStatistics();

    /**
     * A type hint for references which resource type is linked in a reference.
     * @see Reference#getTypeId()
     * @return type hint
     */
    static String referenceTypeId() {
        return "review";
    }

    /**
     * An identifier for this resource which supports {@link CustomFields}.
     * @see TypeDraft#getResourceTypeIds()
     * @see io.sphere.sdk.types.Custom
     * @return ID of this resource type
     */
    static String resourceTypeId() {
        return "review";
    }

    /**
     * Creates a container which contains the full Java type information to deserialize this class from JSON.
     *
     * @see io.sphere.sdk.json.SphereJsonUtils#readObject(byte[], TypeReference)
     * @see io.sphere.sdk.json.SphereJsonUtils#readObject(String, TypeReference)
     * @see io.sphere.sdk.json.SphereJsonUtils#readObject(com.fasterxml.jackson.databind.JsonNode, TypeReference)
     * @see io.sphere.sdk.json.SphereJsonUtils#readObjectFromResource(String, TypeReference)
     *
     * @return type reference
     */
    static TypeReference typeReference() {
        return new TypeReference() {
            @Override
            public String toString() {
                return "TypeReference";
            }
        };
    }

    /**
     * Creates a reference for one item of this class by a known ID.
     *
     * An example for categories but this applies for other resources, too:
     * {@include.example io.sphere.sdk.categories.CategoryTest#referenceOfId()}
     *
     * If you already have a resource object, then use {@link #toReference()} instead:
     *
     * {@include.example io.sphere.sdk.categories.CategoryTest#toReference()}
     *
     * @param id the ID of the resource which should be referenced.
     * @return reference
     */
    static Reference referenceOfId(final String id) {
        return Reference.of(referenceTypeId(), id);
    }

    default Reference toReference() {
        return Reference.of(referenceTypeId(), getId(), this);
    }
}