io.sphere.sdk.meta

Class ReferenceExpansionDocumentation

java.lang.Object

io.sphere.sdk.meta.ReferenceExpansionDocumentation

public final class ReferenceExpansionDocumentation
extends Object

Introduction

Reference expansion is a feature of certain endpoints implementing ReferenceExpansionSupport that enables clients to request server-side expansion of Reference resources, thereby reducing the number of required client-server roundtrips to obtain the data that a client needs for a specific use-case. A query endpoint that supports reference expansion does so by providing an expand query parameter which can be used to specifiy one or more expansion paths.

For example, Customer contains a member Customer.getCustomerGroup(), which may has a reference to a CustomerGroup.

By default, the field Reference.getObj() will return null and also the reference itself can be null if the customer does not have a customer group.

withCustomerInGroup(client(), (customer, customerGroup) -> {
    final CustomerByIdGet customerByIdGet = CustomerByIdGet.of(customer);
    final Customer loadedCustomer = client().executeBlocking(customerByIdGet);
    final Reference<CustomerGroup> customerGroupReference = loadedCustomer.getCustomerGroup();
    assertThat(customerGroupReference.getId()).isEqualTo(customerGroup.getId());
    assertThat(customerGroupReference.getObj())
            .as("reference is not expanded")
            .isNull();
});
See the test code.

If you specify an expansion path with ReferenceExpansionDsl.withExpansionPaths(java.util.List) it is possible that the product type will be filled so that you can work with it:

withCustomerInGroup(client(), (customer, customerGroup) -> {
    final CustomerByIdGet customerByIdGet = CustomerByIdGet.of(customer)
            .withExpansionPaths(m -> m.customerGroup());//the important part
    final Customer loadedCustomer = client().executeBlocking(customerByIdGet);
    final Reference<CustomerGroup> customerGroupReference = loadedCustomer.getCustomerGroup();
    final CustomerGroup loadedCustomerGroup = customerGroupReference.getObj();
    assertThat(loadedCustomerGroup)
            .as("reference is expanded")
            .isEqualTo(customerGroup);
});
See the test code.

Guarantees

Reference expansion is a feature without any guarantees. So, if you provide a mal-formatted reference expansion path, the system will not inform you about the problem; but just fulfills the query. Even if the expansion path is correct, it is possible that it will not be expanded. This can happen, for example, if too many resources are expanded at the same time.

Use Expansion Models

To prevent you from constructing invalid paths, endpoints implementing MetaModelReferenceExpansionDsl provide methods to generate valid paths.

If you want to expand the product type of a product you can query like this:

final ProductQuery query = ProductQuery.of()
        .withExpansionPaths(m -> m.productType());
See the test code.

Expansion paths are not limited to the next element; for example, you can expand the categories for a product projection plus you can expand the parent category of the category you have expanded before:

final ProductProjectionQuery query = ProductProjectionQuery.ofStaged()
        .withExpansionPaths(m -> m.categories().parent());
See the test code.

Expansion Path by String

If the SDK does not provide a type-safe way to construct a reference path, you can create it by string:

final ExpansionPath<ProductProjection> safePath =
        ProductProjectionExpansionModel.of().categories().parent().expansionPaths().get(0);
final ExpansionPath<ProductProjection> unsafePath = ExpansionPath.of("categories[*].parent");
assertThat(safePath).isEqualTo(unsafePath);
See the test code.

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait