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

Interface SimpleAuthOutput

All Superinterfaces:

AsyncOutput<SimpleAuthOutput>, SimpleAsyncOutput<SimpleAuthOutput>

@DoNotImplement
public interface SimpleAuthOutput
extends AsyncOutput<SimpleAuthOutput>

Output parameter provided to SimpleAuthenticator.onConnect(SimpleAuthInput, SimpleAuthOutput).

It can be used to

• Authenticate the client successfully OR
• Fail authentication OR
• Delegate the decision to the next extension

Exactly one of the decisive methods must be called:

• authenticateSuccessfully()
• failAuthentication()
• failAuthentication(ConnackReasonCode)
• failAuthentication(String)
• failAuthentication(ConnackReasonCode, String)
• nextExtensionOrDefault()

Subsequent calls will fail with an UnsupportedOperationException.

The default topic permissions only apply if the client is authenticated successfully.

In case of a failed authentication a CONNACK packet with the appropriate reason code is sent to the client.

Since:

4.0.0, CE 2019.1

Method Summary

Modifier and Type	Method	Description
@NotNull Async<SimpleAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
@NotNull Async<SimpleAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback, @NotNull ConnackReasonCode reasonCode)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
@NotNull Async<SimpleAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback, @NotNull ConnackReasonCode reasonCode, @Nullable String reasonString)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
@NotNull Async<SimpleAuthOutput>	async(@NotNull Duration timeout, @NotNull TimeoutFallback timeoutFallback, @Nullable String reasonString)	If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.
void	authenticateSuccessfully()	Successfully authenticates the client.
void	failAuthentication()	Fails the authentication of the client.
void	failAuthentication(@NotNull ConnackReasonCode reasonCode)	Fails the authentication of the client.
void	failAuthentication(@NotNull ConnackReasonCode reasonCode, @Nullable String reasonString)	Fails the authentication of the client.
void	failAuthentication(@Nullable String reasonString)	Fails the authentication of the client.
@NotNull ModifiableClientSettings	getClientSettings()	Provides ModifiableClientSettings to configure client specific parameters and restrictions.
@NotNull ModifiableDefaultPermissions	getDefaultPermissions()	Provides ModifiableDefaultPermissions to configure client specific default permissions.
@NotNull ModifiableUserProperties	getOutboundUserProperties()	Provides ModifiableUserProperties to add or remove user properties to or from the outgoing CONNACK packet.
void	nextExtensionOrDefault()	The outcome of the authentication is determined by an authenticator of the next extension (with lower priority).

Methods inherited from interface com.hivemq.extension.sdk.api.async.SimpleAsyncOutput

async

Method Detail

authenticateSuccessfully

void authenticateSuccessfully()

Successfully authenticates the client.

A CONNACK packet with reason code SUCCESS is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication or nextExtensionOrDefault has already been called.

Since:

4.0.0, CE 2019.1

failAuthentication

void failAuthentication()

Fails the authentication of the client.

A CONNACK packet with reason code NOT_AUTHORIZED and reason string Authentication failed is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication or nextExtensionOrDefault has already been called.

Since:

4.0.0, CE 2019.1

failAuthentication

void failAuthentication(@NotNull ConnackReasonCode reasonCode)

Fails the authentication of the client.

A CONNACK packet with the specified reason code and reason string Authentication failed is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

reasonCode - The reason code of the CONNACK packet.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication or nextExtensionOrDefault has already been called.

Since:

4.3.0, CE 2020.1

failAuthentication

void failAuthentication(@Nullable String reasonString)

Fails the authentication of the client.

A CONNACK packet with reason code NOT_AUTHORIZED and the specified reason string is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

reasonString - Used as the reason string in the CONNACK packet.

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication or nextExtensionOrDefault has already been called.

Since:

4.0.0, CE 2019.1

failAuthentication

void failAuthentication(@NotNull ConnackReasonCode reasonCode,
                        @Nullable String reasonString)

Fails the authentication of the client.

A CONNACK packet with the specified reason code and reason string is sent to the client.

This is a final decision, authenticators of the next extensions (with lower priority) are not called.

Parameters:

reasonCode - Used as the reason code in the CONNACK packet.

reasonString - Used as the reason string in the CONNACK packet.

Throws:

IllegalArgumentException - If the reasonCode is SUCCESS.

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication or nextExtensionOrDefault has already been called.

Since:

4.0.0, CE 2019.1

nextExtensionOrDefault

void nextExtensionOrDefault()

The outcome of the authentication is determined by an authenticator of the next extension (with lower priority).

If no extension with an authenticator is left the default behaviour is used. The default behaviour is the same as failAuthentication().

Throws:

UnsupportedOperationException - When authenticateSuccessfully, failAuthentication or nextExtensionOrDefault has already been called.

Since:

4.0.0, CE 2019.1

getOutboundUserProperties

@NotNull ModifiableUserProperties getOutboundUserProperties()

Provides ModifiableUserProperties to add or remove user properties to or from the outgoing CONNACK packet.

Returns:

The ModifiableUserProperties of the CONNACK packet.

Since:

4.0.0, CE 2019.1

getDefaultPermissions

@NotNull ModifiableDefaultPermissions getDefaultPermissions()

Provides ModifiableDefaultPermissions to configure client specific default permissions.

Default permissions are automatically applied by HiveMQ for every PUBLISH and SUBSCRIBE packet sent by the client.

Returns:

The ModifiableDefaultPermissions for the client.

Since:

4.0.0, CE 2019.1

getClientSettings

@NotNull ModifiableClientSettings getClientSettings()

Provides ModifiableClientSettings to configure client specific parameters and restrictions.

Returns:

The ModifiableClientSettings for the client.

Since:

4.2.0, CE 2020.1

async

@NotNull Async<SimpleAuthOutput> async(@NotNull Duration timeout,
                                       @NotNull TimeoutFallback timeoutFallback)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Specified by:

async in interface AsyncOutput<SimpleAuthOutput>

Parameters:

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(ConnackReasonCode, String) with reason code NOT_AUTHORIZED and reason string Authentication failed, authenticator timed out.

timeout - Timeout that HiveMQ waits for the result of the async operation.

Since:

4.0.0, CE 2019.1

async

@NotNull Async<SimpleAuthOutput> async(@NotNull Duration timeout,
                                       @NotNull TimeoutFallback timeoutFallback,
                                       @NotNull ConnackReasonCode reasonCode)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Parameters:

timeout - Timeout that HiveMQ waits for the result of the async operation.

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(ConnackReasonCode, String) with the specified reason code and reason string Authentication failed, authenticator timed out.

reasonCode - The reason code sent in CONNACK when timeout occurs.

Throws:

UnsupportedOperationException - If async is called more than once.

Since:

4.0.0, CE 2019.1

async

@NotNull Async<SimpleAuthOutput> async(@NotNull Duration timeout,
                                       @NotNull TimeoutFallback timeoutFallback,
                                       @Nullable String reasonString)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Parameters:

timeout - Timeout that HiveMQ waits for the result of the async operation.

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(ConnackReasonCode, String) with reason code NOT_AUTHORIZED and the specified reason string.

reasonString - The reason string sent in CONNACK when timeout occurs.

Throws:

UnsupportedOperationException - If async is called more than once.

Since:

4.0.0, CE 2019.1

async

@NotNull Async<SimpleAuthOutput> async(@NotNull Duration timeout,
                                       @NotNull TimeoutFallback timeoutFallback,
                                       @NotNull ConnackReasonCode reasonCode,
                                       @Nullable String reasonString)

If the timeout is expired before Async.resume() is called then the outcome is handled either as failed or successful, depending on the specified fallback.

Do not call this method more than once. If an async method is called multiple times an exception is thrown.

Parameters:

timeout - Timeout that HiveMQ waits for the result of the async operation.

timeoutFallback - Fallback behaviour if a timeout occurs.

SUCCESS has the same effect as nextExtensionOrDefault().

FAILURE has the same effect as failAuthentication(ConnackReasonCode, String) with the specified reason code and reason string.

reasonCode - The reason code sent in CONNACK when timeout occurs.

reasonString - The reason string sent in CONNACK when timeout occurs.

Throws:

UnsupportedOperationException - If async is called more than once.

Since:

4.0.0, CE 2019.1