cool.mqtt.hooks.MqttBrokerConfig Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mqtt.cool-hook-java-api Show documentation
The Java API for developing MQTT.Cool Hooks
The newest version!
package cool.mqtt.hooks;

/**
 * An encapsulation of the MQTT broker configuration corresponding to the connection alias provided
 * by a client on connection establishment with MQTT.Cool.
 *
 * The Hook is expected to supply an instance of {@code MqttBrokerConfig} (through an invocation
 * of {@link MQTTCoolHook#resolveAlias(String)}) if no static entries have been provided in the
 * {@code mqtt_master_connector_conf.xml} file for a given connection alias.
 *
 * 
The configuration is made up of:
 * 

 * Mandatory address of the MQTT broker.
 * Optional connection timeout and keep alive interval values.
 * Optional ClientId prefix.
 * Optional {@code username} and {@code password}, if the MQTT broker requires an authenticated
 * access.
 * Optional {@code Will Message}.
 * Optional set of parameters for encrypted connections.
 * 
 * 
 * @see MQTTCoolHook#resolveAlias(String)
 */
public interface MqttBrokerConfig {
  /**
   * Gets the address of the MQTT broker to connect to.
   *
   * The address must be specified in one of the following URI forms:
   * 

   * {@code tcp://:}
   * {@code mqtt://:}
   * {@code mqtts://:}
   * {@code ssl://:}
   * 
   * otherwise MQTT.Cool will invalidate it and the client will be notified with an error.
   *
   * Note that use of {@code mqtts} and {@code ssl} triggers encrypted communication with the
   * MQTT broker, therefore further parameters (provided through an instance of
   * {@link SecurityParams}) might be required in order to properly support the setting up of secure
   * channels.
   *
   * @return the address of the MQTT broker
   *
   * @see #getSecurityParams()
   */
  String getAddress();

  /**
   * Gets the ClientId prefix to be used for shared connections.
   *
   * 
If the clients want to share a single connection, MQTT.Cool concatenates the ClientId
   * prefix with a randomly generated suffix in order to make a unique ClientId for opening the
   * physical connection to the MQTT broker. Uniqueness of the ClientId is mandatory as multiple
   * shared connections may exist for the same MQTT broker.
   *
   * 
In case of blank return value (that is, an empty, whitespace or {@code null} string), the
   * default ClientId prefix {@code "MQTT_Cool"} will be used.
   *
   * @return the ClientId prefix, or a blank value (as defined above) if the default ClientId prefix
   *         is accepted
   */
  String getClientIdPrefix();

  /**
   * Gets the connection timeout expressed in seconds.
   *
   * 
In case of a {@code null} return value, a default value of {@code 5} seconds will be used.
   *
   * @return the connection timeout expressed in seconds, or {@code null} if the default value is
   *         accepted
   */
  Integer getConnectionTimeout();

  /**
   * Gets the keep alive interval expressed in seconds.
   *
   * 
In case of a {@code null} return value, a default value of {@code 30} seconds will be used.
   *
   * @return the keep alive interval expressed in seconds, or {@code null} if the default value is
   *         accepted
   */
  Integer getKeepAlive();

  /**
   * Gets the {@code username} for authenticating with the MQTT broker.
   *
   * 
If the MQTT broker does not require authentication, this method should return a {@code null}
   * value. Empty or blank values will be provided as is in the {@code CONNECT} Control
   * Packet built to connect to the broker.
   *
   * 
Note that the {@code username} which may be provided by the client will take precedence over
   * the one returned by this method.
   *
   * @return the {@code username}, or {@code null} if no credential is provided
   * @see MqttConnectOptions#getUsername()
   */
  String getUsername();

  /**
   * Gets the {@code password} for authenticating with the MQTT broker.
   * 
   * 
As for {@link #getUsername()}, this method should returns {@code null} value in the case of
   * unauthenticated access. Empty or blank values will be provided as is in the
   * {@code CONNECT} Control Packet built to connect to the broker.
   * 
   * 
Note that the {@code password} which may be provided by the client will take precedence over
   * the one returned by this method.
   *
   * @return the {@code password}, or {@code null} if no credential is provided
   * @see MqttConnectOptions#getPassword()
   */
  String getPassword();

  /**
   * Gets the {@code Will Message} to be stored by the MQTT broker.
   *
   * 
Note that the {@code Will Message} which may be provided by the client will take precedence
   * over the one returned by this method.
   *
   * @return the {@code Will Message} to be stored by the MQTT broker if any, or {@code null}
   * @see MqttConnectOptions#getWillMessage()
   */
  MqttMessage getWillMessage();

  /**
   * Gets the {@code SecureParams} instance to be used for supporting the setting up of encrypted
   * connections to the MQTT broker.
   * 
   * 
Note that this method will be invoked only in the case the address returned by
   * {@link #getAddress()} specifies a secure schema.
   *
   * 
Furthermore, if {@code null} is returned, the MQTT.Cool server will try to establish a
   * secure channel using the following default settings:
   *
   * 

   * TLSv1.2 as security protocol.
   * Default truststore and keystore, determined according to the JSSE
   * Reference Guide.
   * 
   *
   * @return a {@code SecureParams} instance, or {@code null}
   */
  SecurityParams getSecurityParams();

}