Package com.hivemq.extension.sdk.api.auth.parameter

Interface SubscriptionAuthorizerOutput

All Superinterfaces:
AsyncOutput<SubscriptionAuthorizerOutput>, SimpleAsyncOutput<SubscriptionAuthorizerOutput>
@DoNotImplement
public interface SubscriptionAuthorizerOutput
extends AsyncOutput<SubscriptionAuthorizerOutput>
This is the output parameter of any SubscriptionAuthorizer providing methods to define the outcome of the subscription authorization.

It can be used to

  • Authorize a subscription successfully
  • Let the authorization of the subscription fail
  • Disconnect the sender of the subscription
  • Delegate the decision to the next extension

Exactly one of the decisive methods must be called:

Subsequent calls will fail with an UnsupportedOperationException.
Since:
4.0.0, CE 2019.1

  • Method Details

    • authorizeSuccessfully

      void authorizeSuccessfully()
      Successfully authorizes the subscription.

      This is a final decision, other extensions or default permissions are ignored.

      Throws:
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1

    • failAuthorization

      void failAuthorization()
      Fails the authorization of the subscription. The outcome depends on the MQTT version specified by the subscribing client.
      • For an MQTT 3.1 client the connection is closed.
      • For an MQTT 3.1.1 client the return code for the subscription in the SUBACK packet is 'Failure'.
      • For an MQTT 5 client the reason code for the subscription in the SUBACK packet is NOT_AUTHORIZED.

      This is a final decision, other extensions or default permissions are ignored.

      Throws:
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1

    • failAuthorization

      void failAuthorization​(@NotNull SubackReasonCode reasonCode)
      Fails the authorization of the subscription. The outcome depends on the MQTT version specified by the subscribing client.
      • For an MQTT 3.1 client the connection is closed.
      • For an MQTT 3.1.1 client the return code for the subscription in the SUBACK packet is 'Failure'.
      • For an MQTT 5 client the specified reason code is used for the subscription in the SUBACK packet.

      This is a final decision, other extensions or default permissions are ignored.

      Parameters:
      reasonCode - Used as the reason code for the subscription in the SUBACK packet.
      Throws:
      IllegalArgumentException - If the specified reason code is not an error code.
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1

    • failAuthorization

      void failAuthorization​(@NotNull SubackReasonCode reasonCode, @NotNull String reasonString)
      Fails the authorization of the subscription. The outcome depends on the MQTT version specified by the subscribing client.
      • For an MQTT 3.1 client the connection is closed.
      • For an MQTT 3.1.1 client the return code for the subscription in the SUBACK packet is 'Failure'.
      • For an MQTT 5 client the specified reason code is used for the subscription in the SUBACK packet and the SUBACK packet will contain the specified reason string. If this method is called for more than one subscription, the reason strings are combined.

      This is a final decision, other extensions or default permissions are ignored.

      Parameters:
      reasonCode - Used as the reason code for the subscription in the SUBACK packet.
      reasonString - Used as the reason string for the SUBACK packet.
      Throws:
      IllegalArgumentException - If the specified reason code is not an error code.
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1

    • disconnectClient

      void disconnectClient()
      Disconnects the client that sent the subscription. The outcome depends on the MQTT version specified by the subscribing client.
      • For an MQTT 3 client the connection is closed.
      • An MQTT 5 client receives a DISCONNECT packet with reason code NOT_AUTHORIZED, then the connection is closed.

      All subscriptions from the same SUBSCRIBE packet are ignored, independent of the outcome for the other subscriptions in this packet.

      This is a final decision, other extensions or default permissions are ignored.

      Throws:
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1

    • disconnectClient

      void disconnectClient​(@NotNull DisconnectReasonCode reasonCode)
      Disconnects the client that sent the subscription. The outcome depends on the MQTT version specified by the subscribing client.
      • For an MQTT 3 client the connection is closed.
      • An MQTT 5 client receives a DISCONNECT packet with the specified reason code, then the connection is closed.

      All subscriptions from the same SUBSCRIBE packet are ignored, independent of the outcome for the other subscriptions in this packet.

      This is a final decision, other extensions or default permissions are ignored.

      Parameters:
      reasonCode - Used as the reason code for the DISCONNECT packet.
      Throws:
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1

    • disconnectClient

      void disconnectClient​(@NotNull DisconnectReasonCode reasonCode, @NotNull String reasonString)
      Disconnects the client that sent the subscription. The outcome depends on the MQTT version specified by the subscribing client.
      • For an MQTT 3 client the connection is closed.
      • An MQTT 5 client receives a DISCONNECT packet with the specified reason code and reason string, then the connection is closed.

      All subscriptions from the same SUBSCRIBE packet are ignored, independent of the outcome for the other subscriptions in this packet.

      This is a final decision, other extensions or default permissions are ignored.

      Parameters:
      reasonCode - Used as the reason code for the DISCONNECT packet.
      reasonString - Used as the reason string for the DISCONNECT packet.
      Throws:
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1

    • nextExtensionOrDefault

      void nextExtensionOrDefault()
      The outcome of the authorization is determined by the next extension with a SubscriptionAuthorizer.

      If no extension with a SubscriptionAuthorizer is left the default permissions (see ModifiableDefaultPermissions) are used. If no default permissions are set, then the authorization is denied.

      Throws:
      UnsupportedOperationException - When authorizeSuccessfully, failAuthorization, disconnectClient or nextExtensionOrDefault has already been called.
      Since:
      4.0.0, CE 2019.1