bundles/addons/org.eclipse.apogy.addons.mqtt/model/apogy_addons_mqtt.xcore

// *****************************************************************************
// Copyright (c) 2020 Agence spatiale canadienne / Canadian Space Agency 
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v1.0
// which accompanies this distribution, and is available at
// http://www.eclipse.org/legal/epl-v10.html
// 
// Contributors:
//     Pierre Allard - initial API and implementation
//        
// SPDX-License-Identifier: EPL-1.0
// *****************************************************************************
@GenModel(prefix="ApogyAddonsMQTT",
		  modelName="ApogyAddonsMQTT",
		  operationReflection="true",
		  childCreationExtenders="true",
		  extensibleProviderFactory="true",
		  multipleEditorPages="false",
copyrightText="*******************************************************************************
Copyright (c) 2020 Agence spatiale canadienne / Canadian Space Agency 
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html

Contributors:
     Pierre Allard - initial API and implementation     
        
SPDX-License-Identifier: EPL-1.0    
*******************************************************************************",
		  suppressGenModelAnnotations="false")
@GenModel(dynamicTemplates="true", templateDirectory="platform:/plugin/org.eclipse.apogy.common.emf.codegen/templates")		  
@GenModel(modelDirectory="/org.eclipse.apogy.addons.mqtt/src-gen")
@GenModel(editDirectory="/org.eclipse.apogy.addons.mqtt.edit/src-gen")

package org.eclipse.apogy.addons.mqtt

import org.eclipse.apogy.common.Apogy
import org.eclipse.apogy.common.emf.Named
import org.eclipse.apogy.common.emf.NamedDescribedElement

// Types
type Exception wraps java.lang.Exception
type HashMap<Key,Value> wraps java.util.HashMap
type List<T> wraps java.util.List

type StringArray wraps java.lang.String[]
type IntegerArray wraps int[]

type MqttCallback wraps org.eclipse.paho.client.mqttv3.MqttCallback
type MqttConnectOptions wraps org.eclipse.paho.client.mqttv3.MqttConnectOptions
type SocketFactory wraps javax.net.SocketFactory

/**
 * Defines a MQTT Node which is used to interface to a MQTT Broker.
 */
@Apogy(hasCustomClass="true",hasCustomItemProvider="true")
class MQTTClient extends Named
{
	/**
	 * Whether or not to log info and warning messages.
	 */
	boolean verbose = "false"
	
	/**
	 * Name of the Broker's Host.
	 */
	String brokerHostName

	/**
	 * Port on which to connect to broker
     */
	int port = "1883"

	/**
	 * Enables auto-reconnection to a server that disconnects.
	 */
	boolean enableServerAutomaticReconnect = "true"

	/**
	 * Connection state of the client
     */
	@GenModel(property="Readonly")
	transient MQTTClientState state = "Not Connected"

	/**
	 * Client Id, automatically generated.
	 */
	transient readonly String clientId

	/**
	 * Connection options.
	 */
	contains MQTTClientConnectionOptions[0..1] connectionOptions

	/**
	 * Topics to which the client is subscribed.
	 */
	refers transient MQTTTopic[0..*] subscribedTopics

	/**
	 * Starts the MQTT node
	 */
	op void start()		

	/**
	 * Stops the MQTT node
	 */
	op void stop()			
	
	/**
	 * Subscribe to a specified topic
	 * @param topic The specified topic.
	 */
	op void subscribe(MQTTTopic topic)
	
	/**
	 * Un-subscribe from a specified topic
	 * @param topic The specified topic.
	 */
	op void unsubscribe(MQTTTopic topic)	
	
	/**
	 * Publish a string on a specified topic.
	 * @param topic The topic on which to publish.
	 * @param message The content of the message.
	 */
	op void publish(MQTTTopic topic, String message) throws Exception
}

/**
 * Holds the set of options that control how the client connects to a MQTT server.
 */
@Apogy(hasCustomClass="true",hasCustomItemProvider="true")
class MQTTClientConnectionOptions
{
	/**
	 * User name required to connect to broker.
	 */
	String userName
	
	/**
	 * Password required to connect to broker.
	 */
	String password
		
	/**
	 * Sets the "keep alive" interval. This value, measured in seconds, defines the maximum time interval between messages 
	 * sent or received. It enables the client to detect if the server is no longer available, without having to wait for 
	 * the TCP/IP timeout. The client will ensure that at least one message travels across the network within each keep 
	 * alive period. In the absence of a data-related message during the time period, the client sends a very small "ping" 
	 * message, which the server will acknowledge. A value of 0 disables keepalive processing in the client. 
	 */
	@Apogy(units="s")	
	int keepAliveInterval = "60"
	
	/**
	 * The max inflight limits to how many messages we can send without receiving acknowledgments. Please increase 
	 * this value in a high traffic environment. 
	 */	
	int maxInFlight = "10"
	
	/**
	 * Connection timeout. This value, measured in seconds, defines the maximum time interval the client will wait for 
	 * the network connection to the MQTT server to be established. The default timeout is 30 seconds. A value of 0 
	 * disables timeout processing meaning the client will wait until the network connection is made successfully or fails.
	 */
	@Apogy(units="s")
	int connectionTimeout = "30"
	
	/**
	 * Sets whether the client and server should remember state across restarts and reconnects.
	 * If set to false both the client and server will maintain state across restarts of the client, the server and the connection. As state is maintained:
	 *  Message delivery will be reliable meeting the specified QOS even if the client, server or connection are restarted.
	 *  The server will treat a subscription as durable.
	 * If set to true the client and server will not maintain state across restarts of the client, the server or the connection. This means
     *	Message delivery to the specified QOS cannot be maintained if the client, server or connection are restarted
     *	The server will treat a subscription as non-durable 
	 */
	boolean cleanSession = "true"  
		
	/**
	 * Sets whether the client will automatically attempt to reconnect to the server if the connection is lost.
	 *	If set to false, the client will not attempt to automatically reconnect to the server in the event that the connection is lost. 
	 * 	If set to true, in the event that the connection is lost, the client will attempt to reconnect to the server. It will initially 
	 * wait 1 second before it attempts to reconnect, for every failed reconnect attempt, the delay will double until it is at 2 minutes 
	 * at which point the delay will stay at 2 minutes.	 
	 */
	boolean automaticReconnect = "true"
				
	/**
	 * Converts the MQTTClientConnectionOptions to MQTT equivalent.
	 */
	op MqttConnectOptions asMqttConnectOptions()
}

/**
 * Connection options that also includes the broker connection information.
 */
@Apogy(hasCustomClass="true")
class MQTTBrokerConnectionInfo extends NamedDescribedElement
{
	/*
	 * Whether or not the connection have been validated.
	 */	
	@GenModel(property="readonly")
	boolean valid = "false"
	
	/*
	 * Whether or not the connection requires to be validated.
	 */	
	@GenModel(property="none")
	boolean requireValidation = "true"
	
	/**
	 * Broker Host Name.
	 */
	String brokerHostName
	
	/**
	 * Broker Port.
	 */
	int port
	
	/**
	 * User name required to connect to broker.
	 */
	String userName
	
	/**
	 * Password required to connect to broker. Not persisted for security reasons.
	 */
	transient String password		
	
	/**
	 * Returns the password. User is prompted to provide the password the first time the password is requested (i.e. when the password is null).
	 */
	op String getUserPassword()
	
	/**
	 * Whether or not to use the system user name as the effective user name. This allows, when enabled, the 
	 * MQTTBrokerConnectionInfo to be shared between users without requiring to change the userName when ever a
	 * different user uses it.  
	 */
	boolean useSystemUserName = "false"
	
	/**
	 * Return the user name currently effective. When useSystemUserName is enabled, 
	 * this is the system user name, when useSystemUserName is disabled, returns userName. 
	 */
	op String getEffectiveUserName()
	
	/**
	 * Attempts to connect with the broker using the user name + password.
	 * @return True if the connection was accepted, false otherwise.
	 */
	op boolean validate()
}

/**
 * Registry containing a list of MQTTBrokerConnectionInfo. It can be used to shared connection information between 
 * plugins without explicit dependencies between these plugins. 
 * It is persisted between session.
 */
@Apogy(isSingleton="true", hasCustomClass="true")
class MQTTBrokerConnectionInfoRegistry
{
	/**
	 * The list off all the MQTTClient currently managed.
	 */
	contains MQTTBrokerConnectionInfo[0..*] brokersConnnectionInfo
	
	/**
	 * Find MQTTBrokerConnectionInfo by name
	 */
	op MQTTBrokerConnectionInfo getMQTTBrokerConnectionInfoByName(String name)	
}

/**
 * MQTTClientConnectionOptions that support SSL connections options
 */
@Apogy(hasCustomClass="true")
class SimpleSSLMQTTClientConnectionOptions extends MQTTClientConnectionOptions
{
	/**
	 * URL to the keyStore file.
	 */	
	String keyStoreFilePathURL
	
	/**
	 * Key Store password
	 */
	String keyStorePassword
	
	/**
	 * Create a SocketFactory using the KeyStore.
	 */
	op SocketFactory createSocketFactory() throws Exception
}

@Apogy(hasCustomItemProvider="true")
class MQTTTopic
{
	/**
	 * Name of the topic.
	 */
	String topicName

	/**
	 * Quality of Service, default is "At least once" (1)
	 */
	QualityOfService qualityOfService = "At least once"

	/**
	 * Expected update period, in milliseconds. When no update to topic happens within that period, the topic state will be set to STALLED.
	 * Use -1 to disable this feature.
	 */
	@Apogy(units="ms")
	long expectedUpdatePeriod = "-1"

	/**
	 * Call back to register to the topic.
	 */
	@GenModel(property="None")
	MqttCallback callBack
		
	/**
	 * State of the topic.
	 */
	@GenModel(property="Readonly")
	MQTTTopicState state = "Not Initialized"
}

/**
 * MQTT Quality Of Service
 */
enum QualityOfService
{
	// The broker/client will deliver the message once, with no confirmation.
	QOS_0 as "At most once" = 0, 
	
	//  The broker/client will deliver the message at least once, with confirmation required.
	QOS_1 as "At least once" = 1,
	
	// The broker/client will deliver the message exactly once by using a four step handshake.
	QOS_2 as "Exactly once" = 2	
}

/**
 * Topic states
 */
enum MQTTClientState
{
	NOT_CONNECTED   as "Not Connected" 	= 0,
	CONNECTING 		as "Connecting"		= 1,
	CONNECTED 		as "Connected"		= 2,	
	FAILED			as "Failed"			= 3
}

/**
 * Topic states
 */
enum MQTTTopicState
{
	NOT_INITIALIZED as "Not Initialized" 	= 0,
	INITIALIZING 	as "Initializing"	= 1,
	READY 			as "Ready"	= 2,
	STOPPED 		as "Stopped"	= 3,
	FAILED			as "Failed"	= 4,
	STALLED			as "Stalled"	= 5
}

/**
 * Facade for MQTT.
 */
@Apogy(isSingleton="true", hasCustomClass="true")
class ApogyAddonsMQTTFacade
{	
	op MQTTClient createMQTTClient(String name, 
								   String brokerHostName,
								   int port,
								   List<MQTTTopic> topics)
	
	op MQTTClient createMQTTClient(String name, 
								   String brokerHostName,
								   int port,
								   List<MQTTTopic> topics,
								   String username,
								   String password)
	
	op MQTTClient createMQTTClient(String name, 
								   String brokerHostName,
								   int port,
								   List<MQTTTopic> topics,
								   MQTTClientConnectionOptions connectionOptions)
	
	op MQTTTopic createMQTTTopic(String topicName,
								 QualityOfService qualityOfService,
								 MqttCallback callBack)
	
	op MQTTTopic createMQTTTopic(String topicName,
								 QualityOfService qualityOfService,
								 MqttCallback callBack,
								 long expectedUpdatePeriod)

	
	op MQTTClientConnectionOptions createMQTTClientConnectionOptions(String username,
								   									 String password)
	
	
	op SimpleSSLMQTTClientConnectionOptions createSimpleSSLMQTTClientConnectionOptions(String username,
								   									 String password,
								   									 String keyStoreFilePathURL,
								   									 String keyStorePassword)
	
	op MQTTClientConnectionOptions createMQTTClientConnectionOptions(String username,
								   									 String password,								   									 
								   									 boolean cleanSession,
								   									 boolean automaticReconnect)
	
	op SimpleSSLMQTTClientConnectionOptions createSimpleSSLMQTTClientConnectionOptions(String username,
								   									 String password,								   									 
								   									 boolean cleanSession,
								   									 boolean automaticReconnect,
								   									 String keyStoreFilePathURL,
								   									 String keyStorePassword)
	
	op StringArray getTopicsNames(List<MQTTTopic> topics)
	op IntegerArray getTopicsQualityOfService(List<MQTTTopic> topics)
}

/**
 * Class representing the list of all MQTTClient currently managed by Apogy.
 */
@Apogy(isSingleton="true", hasCustomClass="true")
class ApogyMQTTRegistry
{
	/**
	 * The list off all the MQTTClient currently managed.
	 */
	refers transient MQTTClient[0..*] clientList		
}