Review (Composable Commerce JVM SDK 2.17.0-SNAPSHOT API)

All Superinterfaces:: CreationTimestamped, Custom, Identifiable<Review>, Referenceable<Review>, Resource<Review>, ResourceIdentifiable<Review>, ResourceView<Review,Review>, Timestamped, Versioned<Review>, WithKey

public interface Review
extends Resource<Review>, Custom, WithKey

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 Project, we create the approved state. Then we create the initial to-approve state, which has a possible transition to the approved state:

import io.sphere.sdk.client.BlockingSphereClient;

import io.sphere.sdk.states.*;

import io.sphere.sdk.states.commands.StateCreateCommand;

import java.util.List;

import static java.util.Arrays.asList;

import static java.util.Collections.singleton;

public class CreateReviewStates {
    public static List<State> createStates(final BlockingSphereClient client) {
        final StateDraft approvedStateDraft =
                StateDraftDsl.of("approved", StateType.REVIEW_STATE).withRoles(StateRole.REVIEW_INCLUDED_IN_STATISTICS);
        final State approvedState = client.executeBlocking(StateCreateCommand.of(approvedStateDraft));

        final StateDraft initialStateDraft =
                StateDraftDsl.of("to-approve", StateType.REVIEW_STATE)
                        .withInitial(true)
                        .withTransitions(singleton(approvedState.toReference()));
        final State initialState = client.executeBlocking(StateCreateCommand.of(initialStateDraft));
        return asList(initialState, approvedState);
    }
}
See the test code.

Only states with 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:

import io.sphere.sdk.client.BlockingSphereClient;

import io.sphere.sdk.models.Reference;

import io.sphere.sdk.models.ResourceIdentifier;

import io.sphere.sdk.products.Product;

import io.sphere.sdk.reviews.Review;

import io.sphere.sdk.reviews.ReviewDraft;

import io.sphere.sdk.reviews.ReviewDraftBuilder;

import io.sphere.sdk.reviews.commands.ReviewCreateCommand;

import static org.assertj.core.api.Assertions.assertThat;

public class CreateReviewToApprove {
    public static Review createReview(final BlockingSphereClient client, final Reference<Product> productReference) {
        final ReviewDraft reviewDraft = ReviewDraftBuilder
                .ofRating(4)
                .title("review title")
                .target(productReference)
                .state(ResourceIdentifier.ofKey("to-approve"))//you know the initial state by key and don't need a ref
                .build();
        final Review review = client.executeBlocking(ReviewCreateCommand.of(reviewDraft));
        assertThat(review.getState()).isNotNull();
        assertThat(review.getRating()).isEqualTo(4);
        return review;
    }
}
See the test code.

Querying which reviews should be approved

import io.sphere.sdk.client.BlockingSphereClient;

import io.sphere.sdk.reviews.Review;

import io.sphere.sdk.reviews.queries.ReviewQuery;

import io.sphere.sdk.states.State;

import io.sphere.sdk.states.queries.StateQuery;

import java.util.List;

import static org.assertj.core.api.Assertions.assertThat;

public class QueryReviewsToApprove {
    public static List<Review> query(final BlockingSphereClient client, final State initialState) {
        //this ID can be cached
        final String initialStateId = client.executeBlocking(StateQuery.of().byKey("to-approve")).head().get().getId();

        final ReviewQuery reviewQuery = ReviewQuery.of()
                .withPredicates(m -> m.state().id().is(initialStateId))
                .withSort(m -> m.createdAt().sort().asc());//oldest first
        final List<Review> reviewsToApprove = client.executeBlocking(reviewQuery).getResults();
        assertThat(reviewsToApprove).extracting(review -> review.getTitle()).contains("review title");
        return reviewsToApprove;
    }
}
See the test code.

Approving a review

import io.sphere.sdk.client.BlockingSphereClient;

import io.sphere.sdk.models.ResourceIdentifier;

import io.sphere.sdk.reviews.Review;

import io.sphere.sdk.reviews.commands.ReviewUpdateCommand;

import io.sphere.sdk.reviews.commands.updateactions.TransitionState;

import io.sphere.sdk.states.State;

import static org.assertj.core.api.Assertions.assertThat;

public class ApprovingAReview {
    public static Review approveReview(final BlockingSphereClient client, final Review reviewToApprove) {
        final ResourceIdentifier<State> state = ResourceIdentifier.ofKey("approved");//we know the state by key
        final ReviewUpdateCommand cmd = ReviewUpdateCommand.of(reviewToApprove, TransitionState.of(state));
        final Review approvedReview = client.executeBlocking(cmd);
        assertThat(reviewToApprove.getState()).isNotEqualTo(approvedReview.getState());
        return approvedReview;
    }
}
See the test code.

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

final List<FacetRange<BigDecimal>> facetRanges = IntStream.range(LOWEST_RATING, HIGHEST_RATING)
        .mapToObj(i -> FacetRange.of(new BigDecimal(i), new BigDecimal(i + 1)))
        .collect(toList());
assertThat(facetRanges.toString()).isEqualTo("[[0 to 1), [1 to 2), [2 to 3), [3 to 4), [4 to 5)]");

final ProductProjectionSearch searchRequest = ProductProjectionSearch.ofStaged()//in prod it would be current
        .withResultFilters(m -> m.reviewRatingStatistics().averageRating().isGreaterThanOrEqualTo(new BigDecimal(2)))
        .withFacets(m -> m.reviewRatingStatistics().averageRating().onlyRange(facetRanges))
        .withSort(m -> m.reviewRatingStatistics().averageRating().desc());

assertEventually(Duration.ofSeconds(60), Duration.ofMillis(100), () -> {
    final PagedSearchResult<ProductProjection> result = client().executeBlocking(searchRequest);
    assertThat(result.getResults()).hasSize(2);
    final ProductProjection productProjection = result.getResults().get(0);
    assertThat(productProjection.getReviewRatingStatistics().getCount()).isEqualTo(REVIEWS_PER_PRODUCT);
    final RangeFacetResult facetResult = (RangeFacetResult) result.getFacetResult("reviewRatingStatistics.averageRating");
    assertThat(facetResult.getRanges().get(2)).isEqualTo(RangeStats.of("2.0", "3.0", 2L, null, "2.2", "2.7", "4.9", 2.45));

});
See the test code.

Getting reviews for one product (only approved)

final String productId = product.getId();
final ReviewQuery reviewQuery = ReviewQuery.of()
        .withPredicates(review -> review.includedInStatistics().is(true).and(review.target().id().is(productId)))
        .withSort(m -> m.createdAt().sort().desc())
        .withLimit(REVIEWS_PER_PRODUCT);
final List<Review> reviews = client().executeBlocking(reviewQuery).getResults();
assertThat(reviews).hasSize(REVIEWS_PER_PRODUCT);
assertThat(reviews).extracting(r -> r.getTarget().getId()).containsOnlyElementsOf(singletonList(productId));
assertThat(reviews).extracting(r -> r.isIncludedInStatistics()).containsOnlyElementsOf(singletonList(true));
See the test code.

Getting reviews for one product

final String productId = product.getId();
final ReviewQuery reviewQuery = ReviewQuery.of()
        .withPredicates(m -> m.target().id().is(productId))
        .withSort(m -> m.createdAt().sort().desc())
        .withLimit(REVIEWS_PER_PRODUCT);
final List<Review> reviews = client().executeBlocking(reviewQuery).getResults();
assertThat(reviews).hasSize(REVIEWS_PER_PRODUCT);
assertThat(reviews).extracting(r -> r.getTarget().getId()).containsOnlyElementsOf(singletonList(productId));
See the test code.

See Also:: ReviewCreateCommand, ReviewUpdateCommand, ReviewDeleteCommand, ReviewQuery, ReviewByIdGet, ReviewByKeyGet

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`String`	`getAuthorName()` The name of the author which created this review or null.
`CustomFields`	`getCustom()` Gets the custom fields of this review or null.
`Reference<Customer>`	`getCustomer()` Gets the customer which created this review or null.
`String`	`getKey()` Gets the key assigned to this review or null.
`Locale`	`getLocale()` Gets the locale (language) in which the text and title are or null.
`Integer`	`getRating()` Gets the rating or null.
`Reference<State>`	`getState()` Gets the state of this review or null.
`Reference<?>`	`getTarget()` Identifies the target of the review.
`String`	`getText()` Gets the text of this review or null.
`String`	`getTitle()` Gets the title of this review or null.
`String`	`getUniquenessValue()`
`Boolean`	`isIncludedInStatistics()` Indicates if this review is taken into account in the ratings statistics of the target.
`static Reference<Review>`	`referenceOfId(String id)` Creates a reference for one item of this class by a known ID.
`static String`	`referenceTypeId()` A type hint for references which resource type is linked in a reference.
`static String`	`resourceTypeId()` An identifier for this resource which supports `CustomFields`.
`default Reference<Review>`	`toReference()` Creates a reference to this resource, the reference may not be filled.
`static com.fasterxml.jackson.core.type.TypeReference<Review>`	`typeReference()` Creates a container which contains the full Java type information to deserialize this class from JSON.

Methods inherited from interface io.sphere.sdk.models.Resource
getCreatedAt, getId, getLastModifiedAt, getVersion

Methods inherited from interface io.sphere.sdk.models.Versioned
of, of

Methods inherited from interface io.sphere.sdk.models.Referenceable
hasSameIdAs, toResourceIdentifier

- Method Detail
  - getAuthorName
```
@Nullable
String getAuthorName()
```
    The name of the author which created this review or null.
    
    Returns:
    
    author name
    
    See Also:
    
    SetAuthorName
  - getCustom
```
@Nullable
CustomFields getCustom()
```
    Gets the custom fields of this review or null.
    
    Specified by:
    
    getCustom in interface Custom
    
    Returns:
    
    custom fields
    
    See Also:
    
    SetCustomField, SetCustomType
  - getCustomer
```
@Nullable
Reference<Customer> getCustomer()
```
    Gets the customer which created this review or null.
    
    Returns:
    
    customer
    
    See Also:
    
    SetCustomer
  - getKey
```
@Nullable
String getKey()
```
    Gets the key assigned to this review or null.
    
    Specified by:
    
    getKey in interface WithKey
    
    Returns:
    
    key
    
    See Also:
    
    SetKey
  - getLocale
```
@Nullable
Locale getLocale()
```
    Gets the locale (language) in which the text and title are or null.
    
    Returns:
    
    locale
  - getRating
```
@Nullable
Integer getRating()
```
    Gets the rating or null.
    
    Returns:
    
    the rating
    
    See Also:
    
    SetRating
  - getState
```
@Nullable
Reference<State> getState()
```
    Gets the state of this review or null.
    
    Returns:
    
    state
    
    See Also:
    
    TransitionState
  - getTarget
```
@Nullable
Reference<?> getTarget()
```
    Identifies the target of the review. Can be a Product or a Channel or nothing.
    
    Returns:
    
    the target of this review or null
    
    See Also:
    
    SetTarget
  - getText
```
@Nullable
String getText()
```
    Gets the text of this review or null.
    
    Returns:
    
    text
    
    See Also:
    
    SetText
  - getTitle
```
@Nullable
String getTitle()
```
    Gets the title of this review or null.
    
    Returns:
    
    title
    
    See Also:
    
    SetTitle
  - getUniquenessValue
```
@Nullable
String getUniquenessValue()
```
  - isIncludedInStatistics
```
Boolean isIncludedInStatistics()
```
    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.
    
    Returns:
    
    is included in review rating of target
  - referenceTypeId
```
static String referenceTypeId()
```
    A type hint for references which resource type is linked in a reference.
    
    Returns:
    
    type hint
    
    See Also:
    
    Reference.getTypeId()
  - resourceTypeId
```
static String resourceTypeId()
```
    An identifier for this resource which supports CustomFields.
    
    Returns:
    
    ID of this resource type
    
    See Also:
    
    TypeDraft.getResourceTypeIds(), Custom
  - typeReference
```
static com.fasterxml.jackson.core.type.TypeReference<Review> typeReference()
```
    Creates a container which contains the full Java type information to deserialize this class from JSON.
    
    Returns:
    
    type reference
    
    See Also:
    
    SphereJsonUtils.readObject(byte[], TypeReference), SphereJsonUtils.readObject(String, TypeReference), SphereJsonUtils.readObject(com.fasterxml.jackson.databind.JsonNode, TypeReference), SphereJsonUtils.readObjectFromResource(String, TypeReference)
  - referenceOfId
```
static Reference<Review> referenceOfId(String id)
```
    Creates a reference for one item of this class by a known ID.
    An example for categories but this applies for other resources, too:
    final String categoryIdFromFormOrSession = "84ac4271-0fec-49d0-9fee-55586c565c58"; final Reference<Category> categoryReference = Category.referenceOfId(categoryIdFromFormOrSession); assertThat(categoryReference.getId()).isEqualTo(categoryIdFromFormOrSession);
    See the test code.
    If you already have a resource object, then use toReference() instead:
    final Category category = getCategory1(); final Reference<Category> categoryReference = category.toReference(); assertThat(category.getId()).isEqualTo(categoryReference.getId());
    See the test code.
    Parameters:
    
    id - the ID of the resource which should be referenced.
    
    Returns:
    
    reference
  - toReference
```
default Reference<Review> toReference()
```
    Description copied from interface: Referenceable
    
    Creates a reference to this resource, the reference may not be filled.
    
    Specified by:
    
    toReference in interface Referenceable<Review>
    
    Specified by:
    
    toReference in interface Resource<Review>
    
    Returns:
    
    reference

Interface Review

Review Approval Process

Creating reviews

Querying which reviews should be approved

Approving a review

Displaying Products

Searching for Products with a Minimal Rating

Getting reviews for one product (only approved)

Getting reviews for one product

Method Summary

Methods inherited from interface io.sphere.sdk.models.Resource

Methods inherited from interface io.sphere.sdk.models.Versioned

Methods inherited from interface io.sphere.sdk.models.Referenceable

Method Detail

getAuthorName

getCustom

getCustomer

getKey

getLocale

getRating

getState

getTarget

getText

getTitle

getUniquenessValue

isIncludedInStatistics

referenceTypeId

resourceTypeId

typeReference

referenceOfId

toReference