io.sphere.sdk.models.Reference Maven / Gradle / Ivy

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

import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;

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

/**
 * A {@link io.sphere.sdk.models.Reference} is a loose reference to another resource on the SPHERE.IO platform.
 *
 * The reference may have a copy of the referenced object available via the method {@link io.sphere.sdk.models.Reference#getObj()} on {@link io.sphere.sdk.models.Reference#getObj() certain conditions}.
 *
 * For equals, only the {@link Reference#getTypeId()} and {@link io.sphere.sdk.models.Reference#getId()} are compared used and {@link Reference#getObj()} will be ignored.
 *
 * @param  the type of the referenced object
 */
@JsonDeserialize(as = ReferenceImpl.class)
public interface Reference extends Referenceable, Identifiable, ResourceIdentifier {

    /**
     * Id of the object this reference represents.
     * @return the id
     */
    @Override
    String getId();

    /**
     * Type id of the object this reference represents, e.g. "customer".
     * @return the type id
     */
    @Override
    String getTypeId();

    /**
     * The optional value of the referenced object.
     *
     * This value is by default null on requests:
     *
     * {@include.example io.sphere.sdk.models.ReferenceIntegrationTest#referencesAreNotByDefaultExpanded()}
     *
     * But it can be expanded with using {@link io.sphere.sdk.expansion.ReferenceExpansionDsl#withExpansionPaths(List)} on requests:
     *
     * {@include.example io.sphere.sdk.models.ReferenceIntegrationTest#howToExpandReferences()}
     *
     * Refer to {@link io.sphere.sdk.expansion.ReferenceExpansionDsl} which endpoints support reference expansion.
     *
     * @return The value of the referenced object or null.
     */
    @JsonIgnore
    @Nullable
    T getObj();

    default Reference filled(@Nullable final T obj) {
        return new ReferenceImpl<>(getTypeId(), getId(), obj);
    }

    static  Reference of(final String typeId, final String id) {
        return new ReferenceImpl<>(typeId, id, null);
    }

    static  Reference of(final String typeId, final String id, T obj) {
        return Reference.of(typeId, id).filled(obj);
    }

    static > Reference of(final String typeId, final T obj) {
        return Reference.of(typeId, obj.getId(), obj);
    }

    default boolean referencesSameResource(final Referenceable counterpart) {
        final Reference reference = counterpart.toReference();
        return reference.getId().equals(getId()) && reference.getTypeId().equals(getTypeId());
    }

    @Override
    default Reference toReference() {
        return this;
    }

    @Override
    default ResourceIdentifier toResourceIdentifier() {
        return this;
    }

    /**
     * In references the key should always be null
     * @return null
     */
    @Nullable
    @Override
    default String getKey() {
        return null;
    }
}