io.sphere.sdk.meta

Class ConstructionDocumentation

java.lang.Object

io.sphere.sdk.meta.ConstructionDocumentation

public final class ConstructionDocumentation
extends Object

This documentation is about creating objects. The commercetools Composable Commerce APIs save e-commerce data in the cloud. The JVM SDK is one way to read and write the data. There can be other tools like the Merchant Center or product sync tools which can also change data. As a result the data loaded with the JVM SDK is a record of the present or the past since another tool might have changed the data just after loading the data . Therefore, data containers are immutable and contain no setters.

Static 'of' method

To achieve flexibility in the implementation the SDK mostly doesn't support object instantiation by the new operator. Simple objects with few optional parameters typically have a static method called of to create an object.

For example use LocalizedString.of(java.util.Locale, String, java.util.Locale, String) to create a translation for different locales:

final LocalizedString dogFood = LocalizedString.
        of(Locale.ENGLISH, "dog food", Locale.GERMAN, "Hundefutter");
See the test code.

The of method is inspired by Optional.of(Object) and the Java date and time classes such as DateTimeFormatter.ofPattern(String).

Builders

For objects with a lot of optional parameters the SDK provides builders. The builder is initialized with a static of method and the mandatory parameters for creating the target object. The builder provides methods to fill each target object's optional field. To create the target object a method called Builder.build() has to be executed.

The Address object with the AddressBuilder is a good example since it contains only the country as mandatory parameter and a lot of optional fields:

final Address commercetoolsMunich = AddressBuilder.of(CountryCode.DE)
        .company("commercetools GmbH")
        .streetName("Adams-Lehmann-Str.").streetNumber("44")
        .postalCode("80797").city("München").build();
See the test code.

The invariants of builders in the SDK:

final AddressBuilder builder = AddressBuilder.of(CountryCode.GB)
        .firstName("John").lastName("Smith");
final Address john1 = builder.build();
final Address john2 = builder.build();
assertThat(john1 == john2)
        .overridingErrorMessage("different build() calls create different instances")
        .isFalse();
final AddressBuilder builder1 = builder.firstName("Stefanie");
final AddressBuilder builder2 = builder.firstName("Matt");
assertThat(builder1 == builder && builder2 == builder1)
        .overridingErrorMessage("builders are mutable and return themselves")
        .isTrue();
assertThat(builder1.build().getFirstName())
        .overridingErrorMessage("the last setting wins")
        .contains("Matt");
See the test code.

Some builders support a model as prototype:

//we need an address in advance
final Address template = AddressBuilder.of(CountryCode.GB)
        .firstName("John").lastName("Smith").build();

//create an address builder and use an address as template
final AddressBuilder builder = AddressBuilder.of(template);
final Address address = builder.firstName("Matt").build();
assertThat(address.getLastName())
        .overridingErrorMessage("not overwritten values are used from the template")
        .contains("Smith");
assertThat(address.getFirstName())
        .overridingErrorMessage("fields can be overwritten in the builder")
        .contains("Matt");
See the test code.

Copy methods

Sometimes you need to clone objects and to update one field since most objects are immutable; you can create updated copies with a method starting with "with":

final MonetaryAmount eur100 = MoneyImpl.of(100, EUR);
final PriceDraft price0 = PriceDraft.of(eur100);//price without country
//builder style
final PriceDraft price1 = PriceDraftBuilder.of(eur100).country(DE).build();
//of method + copy method
final PriceDraft price2 = PriceDraft.of(eur100).withCountry(DE);
//withCountry semantically the same to
final PriceDraft price3 = PriceDraftBuilder.of(PriceDraft.of(eur100)).country(DE).build();
assertThat(price1).isEqualTo(price2).isEqualTo(price3)
        .isNotEqualTo(price0);
See the test code.

The 'with copy'-methods are inspired by Scala and the Java date and time API: OffsetDateTime.withMinute(int).

Persisting Changes

For persistent changes you need to use a commercetools Composable Commerce client and to execute a Command. Available commands for the Composable Commerce API resources are listed in SphereResources

Typically there are three kinds of commands:

• CreateCommand: command to create a resource
• UpdateCommand: command to update an existing resource
• DeleteCommand: command to delete resources

Method Summary

Methods inherited from class java.lang.Object

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