Package org.eclipse.hono.adapter.mqtt

Class ErrorSubscription

java.lang.Object

org.eclipse.hono.adapter.mqtt.AbstractSubscription

org.eclipse.hono.adapter.mqtt.ErrorSubscription

All Implemented Interfaces:

Subscription

public final class ErrorSubscription
extends AbstractSubscription

A device's MQTT subscription for error messages.

Supported topic filters: error|e/[TENANT]/[DEVICE_ID]/#
(empty tenant/device segments can also be omitted)

Examples:

1. error/DEFAULT_TENANT/4711/# unauthenticated device
2. error///# - authenticated device
3. e///# - authenticated device using short name

Nested Class Summary

Nested classes/interfaces inherited from interface org.eclipse.hono.adapter.mqtt.Subscription

Subscription.Key

Field Summary

Fields

Modifier and Type	Field	Description
static String	COMMAND_RESPONSE_ENDPOINT	Endpoint used in the topic of the published error message identifying the message that lead to the error as a command response message.
static String	COMMAND_RESPONSE_ENDPOINT_SHORT	Short variant of the endpoint used in the topic of the published error message identifying the message that lead to the error as a command response message.
static String	ERROR_ENDPOINT	The name of the error endpoint.
static String	ERROR_ENDPOINT_SHORT	The short name of the error endpoint.
static String	UNKNOWN_ENDPOINT	Endpoint used in the topic of the published error message identifying the topic endpoint in the message that lead to the error as unknown.

Method Summary

Modifier and Type	Method	Description
static ErrorSubscription	fromTopic(io.vertx.mqtt.MqttTopicSubscription mqttTopicSub, org.eclipse.hono.auth.Device authenticatedDevice)	Creates a error subscription object for the given topic.
static ErrorSubscription	fromTopic(String topic, io.netty.handler.codec.mqtt.MqttQoS qos, org.eclipse.hono.auth.Device authenticatedDevice)	Creates a error subscription object for the given topic.
String	getErrorPublishTopic(String messageEndpoint, String deviceId, String correlationId, int errorCode)	Gets the name of the topic that an error should be published to.
String	getErrorPublishTopic(MqttContext context, int errorCode)	Gets the name of the topic that an error should be published to.
Subscription.Key	getKey()	Gets the key to identify a subscription in the list of (same-type) subscriptions of an MQTT Endpoint.
static Subscription.Key	getKey(String tenantId, String deviceId)	Gets the key to identify a subscription in the list of subscriptions of an MQTT Endpoint.
static Subscription.Key	getKey(String topic, org.eclipse.hono.auth.Device authenticatedDevice)	Gets the key to identify an error subscription in the list of error subscriptions of an MQTT Endpoint.
static boolean	hasErrorEndpointPrefix(String topic)	Checks whether the given topic name starts with the error endpoint identifier.

Methods inherited from class org.eclipse.hono.adapter.mqtt.AbstractSubscription

containsDeviceId, containsTenantId, getAuthenticatedDeviceId, getDeviceId, getEndpoint, getQos, getTenant, getTopic, isAuthenticated, isGatewaySubscriptionForSpecificDevice, logSubscribeFailure, logSubscribeSuccess, logUnsubscribe

Methods inherited from class java.lang.Object

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

Field Detail

ERROR_ENDPOINT

public static final String ERROR_ENDPOINT

The name of the error endpoint.

See Also:

Constant Field Values

ERROR_ENDPOINT_SHORT

public static final String ERROR_ENDPOINT_SHORT

The short name of the error endpoint.

See Also:

Constant Field Values

UNKNOWN_ENDPOINT

public static final String UNKNOWN_ENDPOINT

Endpoint used in the topic of the published error message identifying the topic endpoint in the message that lead to the error as unknown.

See Also:

Constant Field Values

COMMAND_RESPONSE_ENDPOINT

public static final String COMMAND_RESPONSE_ENDPOINT

Endpoint used in the topic of the published error message identifying the message that lead to the error as a command response message.

See Also:

Constant Field Values

COMMAND_RESPONSE_ENDPOINT_SHORT

public static final String COMMAND_RESPONSE_ENDPOINT_SHORT

Short variant of the endpoint used in the topic of the published error message identifying the message that lead to the error as a command response message.

See Also:

Constant Field Values

Method Detail

fromTopic

public static ErrorSubscription fromTopic(io.vertx.mqtt.MqttTopicSubscription mqttTopicSub,
                                          org.eclipse.hono.auth.Device authenticatedDevice)

Creates a error subscription object for the given topic.

If the authenticated device is given, it is used to either validate the tenant and device-id given via the topic or, if the topic doesn't contain these values, the authenticated device is used to provide tenant and device-id for the created error subscription object.

Parameters:

mqttTopicSub - The MqttTopicSubscription request from device for error subscription.

authenticatedDevice - The authenticated device or null.

Returns:

The ErrorSubscription object or null if the topic does not match the rules.

Throws:

NullPointerException - if mqttTopicSub is null.

fromTopic

public static ErrorSubscription fromTopic(String topic,
                                          io.netty.handler.codec.mqtt.MqttQoS qos,
                                          org.eclipse.hono.auth.Device authenticatedDevice)

Creates a error subscription object for the given topic.

If the authenticated device is given, it is used to either validate the tenant and device-id given via the topic or, if the topic doesn't contain these values, the authenticated device is used to provide tenant and device-id for the created error subscription object.

Parameters:

topic - The topic to subscribe for errors.

qos - The quality-of-service level for the subscription.

authenticatedDevice - The authenticated device or null.

Returns:

The ErrorSubscription object or null if the topic does not match the rules.

Throws:

NullPointerException - if topic or qos is null.

hasErrorEndpointPrefix

public static boolean hasErrorEndpointPrefix(String topic)

Checks whether the given topic name starts with the error endpoint identifier.

Parameters:

topic - The topic to check.

Returns:

true if the topic has the error endpoint prefix.

getKey

public static Subscription.Key getKey(String topic,
                                      org.eclipse.hono.auth.Device authenticatedDevice)

Gets the key to identify an error subscription in the list of error subscriptions of an MQTT Endpoint.

Only returns a non-null key if the topic is valid.

Parameters:

topic - The topic to subscribe for errors.

authenticatedDevice - The authenticated device or null.

Returns:

The key or null if the topic does not match the rules.

Throws:

NullPointerException - if topic is null.

getKey

public static Subscription.Key getKey(String tenantId,
                                      String deviceId)

Gets the key to identify a subscription in the list of subscriptions of an MQTT Endpoint.

Parameters:

tenantId - The tenant identifier.

deviceId - The device identifier.

Returns:

The key.

Throws:

NullPointerException - If tenantId or deviceId is null.

getKey

public Subscription.Key getKey()

Description copied from interface: Subscription

Gets the key to identify a subscription in the list of (same-type) subscriptions of an MQTT Endpoint.

Returns:

The key.

getErrorPublishTopic

public String getErrorPublishTopic(MqttContext context,
                                   int errorCode)

Gets the name of the topic that an error should be published to.

Parameters:

context - The context in which the error occurred.

errorCode - The error code.

Returns:

The topic name.

Throws:

NullPointerException - if context is null.

getErrorPublishTopic

public String getErrorPublishTopic(String messageEndpoint,
                                   String deviceId,
                                   String correlationId,
                                   int errorCode)

Gets the name of the topic that an error should be published to.

Parameters:

messageEndpoint - The endpoint of the message for which to send the error (e.g. "telemetry").

deviceId - The identifier of the device for which to send the error (may be null). The value will be used if it is not empty and differs from the (not empty) device identifier of this error subscription.

correlationId - The identifier of the message for which to send the error (may be null).

errorCode - The error code.

Returns:

The topic name.