[plc4x] branch develop updated: - Added some documentation on the PooledPlcDriverManager

[cd...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cdutz pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git


The following commit(s) were added to refs/heads/develop by this push:
     new 9f06bb0  - Added some documentation on the PooledPlcDriverManager
9f06bb0 is described below

commit 9f06bb0f6a35fa90dde17807f75565f52c38666d
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Wed Jul 1 09:49:58 2020 +0200

    - Added some documentation on the PooledPlcDriverManager
---
 src/site/asciidoc/users/tools/connection-pool.adoc | 55 ++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/src/site/asciidoc/users/tools/connection-pool.adoc b/src/site/asciidoc/users/tools/connection-pool.adoc
index b0a6af8..aa657cf 100644
--- a/src/site/asciidoc/users/tools/connection-pool.adoc
+++ b/src/site/asciidoc/users/tools/connection-pool.adoc
@@ -18,3 +18,58 @@
 :icons: font
 
 == Connection Pool
+
+There are situations where you don't want to carry around connections in your code.
+
+For example if you have a microservice application, you might have multiple services accessing PLC data.
+
+Keeping an open connection for each of these is rather problematic as in contrast to modern computers, PLCs usually are only able to manage a small number of concurrent conntections.
+
+I think a Siemens S7-1200 is limited to 7 concurrent connections and a Siemens LOGO can't do more than 3.
+
+One alternative would be to open and close the connections all the time.
+This however puts an unnecessary stress on the PLCs as for protocols like the S7 or the ADS protocol a handshake of multiple requests and responses has to be executed before being able to communicate.
+
+As usually these services only require ad-hoc access to a PLC, it would be ideal to share connections between services.
+
+Another problem occurs when you open a connection and keep it open for a prolonged timeperiod.
+Here it can happen quite often that a connection is terminated because the PLC has been turned off.
+
+Per default the PLC connection has no means of automatically re-connecting.
+
+The `PooledPlcDriverManager` can help you with both of these scenarios.
+
+=== The PooledPlcDriverManager
+
+The `PooledPlcDriverManager` is a wrapper around the normal `PlcDriverManager`.
+
+The main difference is that as soon as a connection is requested, it will look if one already exists and return that.
+
+If no connection exists it will create a new one and keep it in the pool.
+
+There are no API differences from using the normal `PlcDriverManager` so you call `createConnection` and `close` just like with the normal PLC4X API.
+
+The structure of the code is now more or less like if you would create a new connection for every request and close it afterwards.
+
+Another benefit of the `PooledPlcDriverManager` is that it will check a connection for any problems before retutning it to the client.
+
+So if a connection was terminated, it will detect this and create a new connection.
+
+=== Example
+
+Here comes a little example program utilizing the `PooledPlcDriverManager`:
+
+----
+    PlcDriverManager driverManager = new PooledPlcDriverManager();
+
+    // This just simulates a scenario where a lot of connections would be created and immediately destroyed again.
+    for(int i = 0; i < 100; i++) {
+        try(PlcConnection connection = driverManager.getConnection("...")) {
+
+            ... do something ... (please refer to the PLC4J getting started for details)
+
+        }
+    }
+----
+
+NOTE: When sharing connections between multiple services, be sure to share the instance of the `PooledPldDriverManager` as otherwise you will result in having multiple pools.
\ No newline at end of file