Package org.eclipse.ditto.model.base.headers

Interface DittoHeadersBuilder<B extends DittoHeadersBuilder<B,​R>,​R extends DittoHeaders>

  • Type Parameters:
    B - the type of the class which implements this interface; this type is used as return value for Method Chaining.
    R - the type of the built DittoHeaders object.
    All Known Implementing Classes:
    AbstractDittoHeadersBuilder
    @NotThreadSafe
public interface DittoHeadersBuilder<B extends DittoHeadersBuilder<B,​R>,​R extends DittoHeaders>
    This interface represents a mutable builder with a fluent API for a DittoHeaders object or an object of a descendant type.

    • Method Detail

      • correlationId

        B correlationId​(@Nullable
                CharSequence correlationId)
        Sets the specified correlation ID.
        Parameters:
        correlationId - the correlation ID to be set.
        Returns:
        this builder for Method Chaining.
        Throws:
        IllegalArgumentException - if correlationId is empty.

      • randomCorrelationId

        default B randomCorrelationId()
        Sets a generated random correlation ID.
        Returns:
        this builder for Method Chaining.

      • schemaVersion

        B schemaVersion​(@Nullable
                JsonSchemaVersion schemaVersion)
        Sets the json schema version value.
        Parameters:
        schemaVersion - the "schema version" value to be set.
        Returns:
        this builder for Method Chaining.

      • authorizationContext

        B authorizationContext​(@Nullable
                       AuthorizationContext authorizationContext)
        Sets the authorization context value.
        Parameters:
        authorizationContext - the "authorizationContext" value to be set.
        Returns:
        this builder for Method Chaining.

      • authorizationSubjects

        @Deprecated
B authorizationSubjects​(CharSequence authorizationSubject,
                        CharSequence... furtherAuthorizationSubjects)
        Deprecated.
        as of 1.1.0, please use authorizationContext(AuthorizationContext) instead for adding the authorizationSubjects
        Sets the authorizationSubjects value.
        Parameters:
        authorizationSubject - the authorizationSubject value to be set.
        furtherAuthorizationSubjects - further of "authorized subjects" to be set.
        Returns:
        this builder for Method Chaining.
        Throws:
        NullPointerException - if any argument is null.

      • readGrantedSubjects

        B readGrantedSubjects​(Collection<AuthorizationSubject> readGrantedSubjects)
        Sets the subjects with granted READ access.
        Parameters:
        readGrantedSubjects - the value to be set.
        Returns:
        this builder for Method Chaining.
        Throws:
        NullPointerException - if readGrantedSubjects is null.
        Since:
        1.1.0

      • readRevokedSubjects

        B readRevokedSubjects​(Collection<AuthorizationSubject> readRevokedSubjects)
        Sets the subjects with explicitly revoked READ access.
        Parameters:
        readRevokedSubjects - the value to be set.
        Returns:
        this builder for Method Chaining.
        Throws:
        NullPointerException - if readRevokedSubjects is null.
        Since:
        1.1.0

      • channel

        B channel​(@Nullable
          CharSequence channel)
        Sets the specified String as channel of the Signal/Exception.
        Parameters:
        channel - the channel of the Signal/Exception to be set.
        Returns:
        this builder for Method Chaining.
        Throws:
        IllegalArgumentException - if channel is empty.

      • responseRequired

        B responseRequired​(boolean responseRequired)
        Sets the responseRequired value. Call this method for explicitly waiving a response. Please note: If ACK requests are set (see acknowledgementRequests(Collection) calling this method has no effect. ACK requests always imply that a response is required.
        Parameters:
        responseRequired - the responseRequired value to be set.
        Returns:
        this builder for Method Chaining.

      • dryRun

        B dryRun​(boolean dryRun)
        Sets the dryRun value.
        Parameters:
        dryRun - the dryRun value to be set.
        Returns:
        this builder for Method Chaining.

      • origin

        B origin​(CharSequence origin)
        Sets the origin value.
        Parameters:
        origin - the origin value to be set.
        Returns:
        this builder for Method Chaining.

      • contentType

        B contentType​(@Nullable
              CharSequence contentType)
        Sets the contentType value.
        Parameters:
        contentType - the contentType value to be set.
        Returns:
        this builder for Method Chaining.

      • contentType

        B contentType​(@Nullable
              ContentType contentType)
        Sets the Ditto typed contentType value.
        Parameters:
        contentType - the Ditto typed contentType value to be set.
        Returns:
        this builder for Method Chaining.
        Since:
        1.3.0

      • eTag

        B eTag​(EntityTag eTag)
        Sets the ETag value.
        Parameters:
        eTag - The ETag value to be set.
        Returns:
        this builder for Method Chaining

      • ifMatch

        B ifMatch​(EntityTagMatchers entityTags)
        Sets the If-Match value.
        Parameters:
        entityTags - The entity tags where one should match.
        Returns:
        this builder for Method Chaining

      • ifNoneMatch

        B ifNoneMatch​(EntityTagMatchers entityTags)
        Sets the If-None-Match value.
        Parameters:
        entityTags - The entity tags that must not match.
        Returns:
        this builder for Method Chaining

      • inboundPayloadMapper

        B inboundPayloadMapper​(@Nullable
                       String inboundPayloadMapperId)
        Sets the inbound MessageMapper ID value.
        Parameters:
        inboundPayloadMapperId - the inbound MessageMapper ID which mapped incoming arbitrary payload from external sources. If null, the header will be removed.
        Returns:
        this builder for Method Chaining

      • replyTarget

        B replyTarget​(@Nullable
              Integer replyTarget)
        Set the reply-target.
        Parameters:
        replyTarget - the reply-target identifier.
        Returns:
        this builder.

      • expectedResponseTypes

        B expectedResponseTypes​(ResponseType... responseTypes)
        Set the expected response types. In combination with replyTarget(Integer) this decides which type of responses are delivered to a reply target of a connection source.
        Parameters:
        responseTypes - the response types that should be delivered to a reply target.
        Returns:
        this builder.
        Since:
        1.2.0

      • expectedResponseTypes

        B expectedResponseTypes​(Collection<ResponseType> responseTypes)
        Set the expected response types. In combination with replyTarget(Integer) this decides which type of responses are delivered to a reply target of a connection source.
        Parameters:
        responseTypes - the response types that should be delivered to a reply target.
        Returns:
        this builder.
        Since:
        1.2.0

      • acknowledgementRequests

        B acknowledgementRequests​(Collection<AcknowledgementRequest> acknowledgementRequests)
        Sets the acknowledgements ("ACK") which are requested together with an issued Ditto Command. Such ACKs are sent back to the issuer of the command so that it can be verified which steps were successful.

        In addition to built-in ACK labels like DittoAcknowledgementLabel.TWIN_PERSISTED also custom labels may be used which can be sent back even by external systems.

        Parameters:
        acknowledgementRequests - the requests for acknowledgements.
        Returns:
        this builder.
        Throws:
        NullPointerException - if acknowledgementRequests is null.
        Since:
        1.1.0

      • acknowledgementRequest

        B acknowledgementRequest​(AcknowledgementRequest acknowledgementRequest,
                         AcknowledgementRequest... furtherAcknowledgementRequests)
        Sets the acknowledgements ("ACK") which are requested together with an issued Ditto Command. Such ACKs are sent back to the issuer of the command so that it can be verified which steps were successful.

        In addition to built-in ACK labels like DittoAcknowledgementLabel.TWIN_PERSISTED also custom labels may be used which can be sent back even by external systems.

        As long as ACKs are requested, calls of responseRequired(boolean) are neglected as requested ACKs always imply that a response is required.

        Parameters:
        acknowledgementRequest - the request for an acknowledgement.
        furtherAcknowledgementRequests - further requests for acknowledgements.
        Returns:
        this builder.
        Throws:
        NullPointerException - if any argument is null.
        Since:
        1.1.0

      • timeout

        B timeout​(@Nullable
          CharSequence timeoutStr)
        Sets the positive timeout string of the DittoHeaders to build.
        Parameters:
        timeoutStr - the duration of the command containing the DittoHeaders to time out.
        Returns:
        this builder.
        Throws:
        DittoHeaderInvalidException - if the given timeout char sequence does not contain a parsable duration or if the duration is negative.
        Since:
        1.1.0

      • timeout

        B timeout​(@Nullable
          Duration timeout)
        Sets the positive timeout duration of the DittoHeaders to build.
        Parameters:
        timeout - the duration of the command containing the DittoHeaders to time out.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if timeout is negative.
        Since:
        1.1.0

      • putMetadata

        B putMetadata​(MetadataHeaderKey key,
              org.eclipse.ditto.json.JsonValue value)
        Puts the given metadata association to this builder. An existing entry with the same key will be replaced.
        Parameters:
        key - the metadata key.
        value - the metadata value.
        Returns:
        this builder.
        Since:
        1.2.0

      • allowPolicyLockout

        B allowPolicyLockout​(boolean allowPolicyLockout)
        Sets the allowPolicyLockout value.
        Parameters:
        allowPolicyLockout - the allowPolicyLockout value to be set.
        Returns:
        this builder for method chaining.
        Since:
        1.3.0

      • putHeaders

        B putHeaders​(Map<String,​String> headers)
        Puts the specified headers to this builder. Existing headers with the same key will be replaced.
        Parameters:
        headers - the headers to be put.
        Returns:
        this builder for Method Chaining.
        Throws:
        NullPointerException - if headers is null.
        DittoHeaderInvalidException - if headers contains a value that did not represent its appropriate Java type.

      • removeHeader

        B removeHeader​(CharSequence key)
        Removes from this builder the value which is associated with the specified key.
        Parameters:
        key - the key to remove the associated value for.
        Returns:
        this builder for Method Chaining.
        Throws:
        NullPointerException - if key is null.
        IllegalArgumentException - if key is empty.

      • removePreconditionHeaders

        B removePreconditionHeaders()
        Removes all precondition headers from this builder.
        Returns:
        The builder without preconditionHeaders

      • build

        R build()
        Creates a DittoHeaders object containing the key-value-pairs which were put to this builder.
        Returns:
        the headers.