Merge pull request #30 from Stwissel/develop

First 0.1.0 Release

docs/configure.md

@@ -1,7 +1,57 @@
 # Configuration
 
-The SFDCMainVerticle reads the system configuration from a JSON file with the name `sfdcoptions.json` in the root of your project. Additionally credentials are pulled from the environment since this is the prevalent method used on Heroku or other PaaS environments.
+The ApplicationStarter Verticle reads the system configuration from a JSON file with the name `SFDCOoptions.json` in the root of your project. Additionally credentials are pulled from the environment since this is the prevalent method used on Heroku or other PaaS environments.
 
-## sfdcoptions.json
+## SFDCOptions.json
+Copy the `sampleconfig.json` file as a start. The JSON file has the following main elements:
 
-## Environment parameters
+- authConfigurations: Array with Auth providers. Important: the `authName` is used as reference by listners and consumer verticles
+- listenerConfigurations: Array with listners. You can listen to multiple different Salesforce instances and topics, you need one entry for each topic. A listener can forward incoming data to multiple addresses on the eventbus
+- consumerConfigurations: a consumer listens to one internal vert.x Eventbus address and consumes what a listener produces 
+- verticlesToLoad: other verticles you want to load
+- parameters: parameters for the ApplicationStarter verticle config object
+- Port: the localhost port the API listens to, mainly for shutdown or web sockets 
+
+### Common Parameters
+- verticleName: the class or identifier to load a verticle - polyglot, any supported language
+- verticleInstanceCount: (optional) how many instances should be deployed
+- deployAsWorker: (optional) true/false should it run in a worker thread
+- autoStart: (optional) true/false Should the verticle automatically start listening (or wait for some eventbus to wake it)
+- enabled: (optional) true/false - to temp disable a verticle
+- proxy: Proxy IP or address (if any)
+- proxyPort: numeric proxy port (if any)
+- parameters: (optional) JSON object that gets passed to verticle.config()
+- authName: What authprovider is used, needs to exist
+
+### authConfig Parameters
+- serverURL: "login.salesforce.com", "test.salesforce.com", your known SF instance or a local mock server
+- sfdcUser: UserName - optional here if provided in environment
+- sfdcPassword: Password (don't put it here, put it into the environment)
+
+### listenerConfigurations
+- listenSubject: what to listen to in SFDC e.g. "/event/DataChange__e",
+- eventBusAddresses: Array of internal addresses to send to. E.g. `["SFDC.SampleEvents2", "SFDC.SampleEvents"]` an implementation could treat this as prefix only
+
+
+### consumerConfigurations
+- providesRouterExtension: the verticle must be Java, to add routes e.g. Websockets
+- url: the URL of the consumer destination (REST, SOAP, Websockets)
+- in parameters for the websockets: `websocketname`
+
+## Environment parameters
+Mostly for compatibility for the PaaS environments and your security:
+- port: Overwrites the listener port for the HTTP admin task
+- For each authConfig sdfcUser and sfdcPassword prefixed by the authName
+
+Sample:<br />
+When your 2 authConfigs, one has `"authName" : "default"` and the other `"authName" : "system36"` then the following
+ variables are pulled from the environment, overwriting values that might be in the JSON file:
+
+- port
+- default_sfdcUser
+- default_sfdcPassword
+- system36_sfdcUser
+- system36_sfdcPassword
+
+As far as I tested: all is case sensitive
+

docs/index.md

@@ -6,9 +6,24 @@ Collection of verticles that enable interaction with the Salesforce API
 
 - Authentication
 - Subscription to platform events
-- Process platform events
+- Send result to console
+- Send result to websocket
 - Main/Setup Verticle
 
+## Flow
+One or more listner Verticles connect to a Salesforce instance. This can be development, sandbox or production.
+The listeners will register for the configured events and publish incoming data to the vert.x eventbus.
+
+Zero or more consumers listen to the eventbus and do with the incoming data what they have to do. 
+As sample a Consumer that forwards the payload to a websocket and one that just prints to the console is provided. 
+
+The flow is suppored by one or more Authentication verticles.
+The main one of type SoapApi retrieves the session information from Salesforce.
+
+A second one "Basic" is provided to allow Verticles to retrieve basic Auth. e.g. for use in a JSON POST in a listener
+
+Finally the ApplicationStarter Verticle loads the configuration file "SFDCOptions.json" and all verticles described in it
+
 ## Setup
 
 Add this dependencies to your `pom.xml`:
@@ -17,7 +32,13 @@ Add this dependencies to your `pom.xml`:
 <dependency>
 	<groupId>net.wissel.salesforce</groupId>
 	<artifactId>net.wissel.salesforce.vertx</artifactId>
-	<version>${sfdc.version}</version>
+	<version>0.1.0</version>
 </dependency>
 ```
-Then [configure the `sfdcoptions.json`](configure.md) file
+Then [configure the `sfdcoptions.json`](configure.md) file
+
+## Start
+Start the verticle `net.wissel.salesforce.vertx.ApplicationStarter` to launch the configured listener and consumers
+
+## Feedback
+Open an issue

pom.xml

@@ -3,7 +3,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>net.wissel.salesforce</groupId>
 	<artifactId>net.wissel.salesforce.vertx</artifactId>
-	<version>0.1.0-SNAPSHOT</version>
+	<version>0.1.0</version>
 	<name>Vert.x modules for Salesforce</name>
 	<description>Verticles that connect to Salesforce Platform events and API</description>
 

sampleconfig.json

@@ -1,41 +1,55 @@
 {
     "authConfigurations": [
-        {
-            "authName": "default",
-            "verticleName": "net.wissel.salesforce.vertx.auth.SoapApi",
-            "serverURL": "login.salesforce.com",
-            "sfdcUser": "User",
-            "sfdcPassword": "pwd",
-            "parameters": { "key": "value" }
-        }
+    {
+    "authName": "default",
+    "verticleName": "net.wissel.salesforce.vertx.auth.SoapApi",
+    "serverURL": "login.salesforce.com",
+    "sfdcUser": "User",
+    "sfdcPassword": "pwd"
+    }
     ],
     "listenerConfigurations": [
-        {
-            "authName": "default",
-            "verticleName": "net.wissel.salesforce.vertx.listener.CometD",
-            "listenSubject": "/event/DataChange__e",
-            "eventBusAddresses": ["SFDC.SampleEvents2", "SFDC.SampleEvents"],
-            "forwardAs": "PUBLISH",
-            "parameters": {"key":"value"}
-        },
-        {
-            "authName": "default",
-            "verticleName": "net.wissel.salesforce.vertx.listener.CometD",
-            "listenSubject": "/event/DataChange2__e",
-            "eventBusAddresses": ["SFDC.SampleEvents2"],
-            "parameters": {"key":"value"}
-        }
-    ],
+    {
+        "verticleName": "net.wissel.salesforce.vertx.listener.CometD",
+        "verticleInstanceCount": 1,
+        "deployAsWorker": false,
+        "autoStart": true,
+        "enabled": true,
+        "providesRouterExtension": false,
+        "proxy": null,
+        "proxyPort": 0,
+        "parameters":
+        {},
+        "authName": "default",
+        "listenSubject": "/event/DataChange__e",
+        "eventBusAddresses": ["SFDC.SampleEvents2", "SFDC.SampleEvents"]
+    }],
     "consumerConfigurations": [
-        {
+    {
             "verticleName": "net.wissel.salesforce.vertx.consumer.WebSocketConsumer",
-            "eventBusAddress": "SFDC.SampleEvents",
+            "eventBusAddress": "SFDC:SampleEvents",
+            "deployAsWorker": false,
+            "autoStart": true,
             "providesRouterExtension": true,
+            "parameters":
+             {
+                "websocketname" : "ui.data.changes"
+             },
+            "url": "/datachange/*"
+        },
+        {
+            "verticleName": "net.wissel.salesforce.vertx.consumer.ConsoleConsumer",
+            "eventBusAddress": "SFDC:SampleEvents",
             "deployAsWorker": false,
-            "autoStart": false
-        }
-    ],
-    "verticlesToLoad": {},
-    "parameters": { "key2": "value",
-                    "key": "value" }
-}
+            "autoStart": true,
+            "providesRouterExtension": false
+        }],
+    "verticlesToLoad":
+    {},
+    "parameters":
+    {
+        "key2": "value",
+        "key": "value"
+    },
+    "port": 8044
+}

src/main/java/net/wissel/salesforce/vertx/config/ConsumerConfig.java

@@ -42,6 +42,12 @@ public class ConsumerConfig extends BaseConfig {
 	 */
 	private String authName = null;
 
+	/**
+	 * Endpoint the consumer serves
+	 * can be REST, SOAP, SOCKET
+	 */
+	private String url;
+
 
 	/**
 	 * @return the authName
@@ -75,4 +81,16 @@ public final void setEventBusAddress(final String eventBusAddress) {
 		this.eventBusAddress = eventBusAddress;
 	}
 
+	/**
+	 * 
+	 * @return The URL the consumer serves, e.g. REST, WebSocket etc
+	 */
+	public final String getUrl() {
+		return this.url;
+	}
+
+	public final void setUrl(final String newURL) {
+		this.url = newURL;
+	}
+
 }

src/main/java/net/wissel/salesforce/vertx/consumer/AbstractSDFCConsumer.java

@@ -0,0 +1,97 @@
+/** ========================================================================= *
+ * Copyright (C)  2017, 2018 Salesforce Inc ( http://www.salesforce.com/      *
+ *                            All rights reserved.                            *
+ *                                                                            *
+ *  @author     Stephan H. Wissel (stw) <swissel@salesforce.com>              *
+ *                                       @notessensei                         *
+ * @version     1.0                                                           *
+ * ========================================================================== *
+ *                                                                            *
+ * Licensed under the  Apache License, Version 2.0  (the "License").  You may *
+ * not use this file except in compliance with the License.  You may obtain a *
+ * copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>.       *
+ *                                                                            *
+ * Unless  required  by applicable  law or  agreed  to  in writing,  software *
+ * distributed under the License is distributed on an  "AS IS" BASIS, WITHOUT *
+ * WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied.  See the *
+ * License for the  specific language  governing permissions  and limitations *
+ * under the License.                                                         *
+ *                                                                            *
+ * ========================================================================== *
+ */
+package net.wissel.salesforce.vertx.consumer;
+
+import io.vertx.core.Future;
+import io.vertx.core.eventbus.EventBus;
+import io.vertx.core.eventbus.Message;
+import io.vertx.core.eventbus.MessageConsumer;
+import io.vertx.core.json.JsonObject;
+import io.vertx.ext.web.Router;
+import net.wissel.salesforce.vertx.AbstractSFDCVerticle;
+import net.wissel.salesforce.vertx.config.ConsumerConfig;
+
+/**
+ * @author swissel
+ *
+ */
+public abstract class AbstractSDFCConsumer extends AbstractSFDCVerticle implements SFDCConsumer {
+
+	private Router router = null;
+	protected MessageConsumer<JsonObject> consumer = null;
+	private ConsumerConfig consumerConfig = null;
+
+	@Override
+	public void setRouter(final Router router) {
+		this.router = router;
+	}
+
+	/**
+	 * Add local routes if any
+	 * 
+	 * @param router
+	 */
+	protected abstract void addRoutes(Router router);
+
+	protected ConsumerConfig getConsumerConfig() {
+		if (this.consumerConfig == null) {
+			this.consumerConfig = this.config().mapTo(ConsumerConfig.class);
+		}
+		return this.consumerConfig;
+	}
+
+	/**
+	 * What to do with actual arriving data
+	 * 
+	 * @param incomingData
+	 *            the payload in an envelope
+	 */
+	protected abstract void processIncoming(final Message<JsonObject> incomingData);
+
+	@Override
+	protected void startListening() {
+		this.logger.info("Start listening:" + this.getClass().getName());
+		// Listen on the event bus
+		final EventBus eb = this.vertx.eventBus();
+		this.consumer = eb.consumer(this.getConsumerConfig().getEventBusAddress());
+		System.out.println(this.getClass().getName()+" listening on " + this.consumer.address());
+		this.consumer.handler(this::processIncoming);
+		// Setup local routes if needed
+		this.addRoutes(this.router);
+		// Done
+		this.listening = true;
+	}
+
+	@Override
+	protected void stopListening(final Future<Void> stopListenFuture) {
+		this.logger.info("Stop listening:" + this.getClass().getName());
+		this.listening = false;
+		if (this.consumer == null) {
+			stopListenFuture.complete();
+		} else {
+			this.consumer.unregister(res -> {
+				stopListenFuture.complete();
+			});
+		}
+	}
+
+}

src/main/java/net/wissel/salesforce/vertx/consumer/ConsoleConsumer.java

@@ -0,0 +1,46 @@
+/** ========================================================================= *
+ * Copyright (C)  2017, 2018 Salesforce Inc ( http://www.salesforce.com/      *
+ *                            All rights reserved.                            *
+ *                                                                            *
+ *  @author     Stephan H. Wissel (stw) <swissel@salesforce.com>              *
+ *                                       @notessensei                         *
+ * @version     1.0                                                           *
+ * ========================================================================== *
+ *                                                                            *
+ * Licensed under the  Apache License, Version 2.0  (the "License").  You may *
+ * not use this file except in compliance with the License.  You may obtain a *
+ * copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>.       *
+ *                                                                            *
+ * Unless  required  by applicable  law or  agreed  to  in writing,  software *
+ * distributed under the License is distributed on an  "AS IS" BASIS, WITHOUT *
+ * WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied.  See the *
+ * License for the  specific language  governing permissions  and limitations *
+ * under the License.                                                         *
+ *                                                                            *
+ * ========================================================================== *
+ */
+package net.wissel.salesforce.vertx.consumer;
+
+import io.vertx.core.eventbus.Message;
+import io.vertx.core.json.JsonObject;
+import io.vertx.ext.web.Router;
+
+/**
+ * @author swissel
+ *
+ */
+public class ConsoleConsumer extends AbstractSDFCConsumer implements SFDCConsumer {
+
+	@Override
+	protected void addRoutes(final Router router) {
+		// We don't use routes here
+	}
+
+	@Override
+	// Just write out to the console
+	protected void processIncoming(final Message<JsonObject> incomingData) {
+		final JsonObject body = incomingData.body();
+		System.out.println(body.encodePrettily());
+	}
+
+}