/XmpConnectionHook\"\n}\n```\nThis hook file is __required__ with the start of the broker.\n
\nIn this case the command to start the broker is:\n
\n__gp.broker --config=<full-config-file-name>
__\n\nAn example for a user defined hook is the [XmpConnectionHook.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/XmpConnectionHook.js) file:\n\n```js\nvar util = require ( \"util\" ) ;\nvar ConnectionHook = require ( \"gepard\" ).ConnectionHook ;\nvar XmpConnectionHook = function()\n{\n\tXmpConnectionHook.super_.call ( this ) ;\n};\nutil.inherits ( XmpConnectionHook, ConnectionHook ) ;\nXmpConnectionHook.prototype.connect = function ( connection )\n{\n\tconsole.log ( \"connection.getRemoteAddress()=\" + connection.getRemoteAddress() ) ;\n\treturn true ;\n};\nmodule.exports = XmpConnectionHook ;\n```\nIf you prefer to start the broker from within your own JavaScript-program the configuration object can be set like:\n```js\n\tvar b = new Broker() ;\n\tb.setConfig ( ) ;\n\tb.listen() ;\n```\nThe parameter __connection__ in the above method-signatures is an internal used object with mainly the public useful methods:\n\n1. connection.isLocalHost()\n1. connection.getRemoteAddress()\n1. connection.getHostName()\n1. connection.getLanguage()\n1. connection.getApplicationName()\n1. connection.getApplication()\n1. connection.getId()\n\n## Perfect load balanced message handling.\n\nThe use-case for request/respond is enhanced to a perfect load balancing.\n
\nSuppose there are __n__ message-listeners offering the same service-name ( event-name )\n
\n__m__ messages come in to the broker with __m__ = __n + 1__\n
\nThe following is done:\n\n1. the first __n__ messages are sent to the __n__ free listener for processing the request.\n1. the __m-th__ message is stored inside the broker waiting for any of the listeners sending back the response.\n1. after receiving the first message-response from any listener the waiting __m-th + 1__ message is sent to the now free listener.\n\nAs long as a sent message is not returned the Broker stores it in relation to the worker connection.\nIf this connection dies the stored message is sent back to the originator marked with the fail state and appropriate text.\nThe status can be tested with event.isBad() which returns true or false.\n\n## Java bindings for all features:\n\n* emit event\n* listen to events\n* request / result ( messages )\n* semaphores\n* locks\n\nWith this it is very easy to communicate or synchronize between JavaScript programs or webapps in a browser with a Java server or Java program.\n\nThe conversion from JSON to Java and vice versa is done with the Gson Google library for Java.\n\nIf you need special serialization / deserialization you may set the appropriate Gson instance in the Event-class statically with the method Event.setGson() ;\n\nThe Event-class may convert the json to map Java's byte[]-array to NodeJS's Buffer and vice versa.\nThis can be set statically by Event.mapByteArrayToJavaScriptBuffer ( boolean state ).\nThe default is true.\n\n\n# Use Cases\n\n## Configuration Changes (Events)\n\nSuppose you have 1 program that changes configuration-entries in a database-table.\nAfter the new entries are committed the program sends an event with:\n\n```js\nclient.emit ( \"CONFIG-CHANGE\" ) ;\n```\n\nSeveral clients do their work based on these data.
\n\nAll clients including web-clients setup a listener for example with\n\n```js\nclient.on ( \"CONFIG-CHANGE\", function callback(e) {} ) ;\n```\n\n## Concurrent editing of a Dataset (Semaphores)\nTwo users with their web browser want to edit the same user-data in a database.\nIn this case a Semaphore is very useful.\n\n
\nBoth do\n\n```js\ngepard.port = 17502 ;\nvar sem = new gepard.Semaphore ( \"user:4711\" ) ;\nthis.sem.acquire ( function sem_callback ( err )\n{\n\t// we are owner\n\tfetch data, edit and save\n\n\tthen:\n\n\tthis.release() ; // with this statement the second user's browser app is callbacked\n}) ;\n```\n\n## Synchronization of file processing (Locks)\n\nSuppose there are many files in a directory waiting to be processed.\n
\nLet's name the directory: foo/bar/input\n
\nIn order to speed up the overall processing several identical programs should work together.\n
\nIn this case Locks are very useful.\nThe following should be done:\n\n```js\nvar fs = require ( \"fs\" ) ;\nvar gepard = require ( \"gepard\" ) ;\nvar lock ;\n\nvar array = fs.readdirSync ( \"foo/bar/input\" ) ;\nfor ( var i = 0 ; i < array.length ; i++ )\n{\n\tlock = new gepard.Lock ( array[i], function()\n\t{\n\t\ttry\n\t\t{\n\t\t\tif ( ! this.isOwner() ) return ;\n\t\t\t.............. process file ................\n\t\t}\n\t\tfinally\n\t\t{\n\t\t\tthis.release() ;\n\t\t}\n\t} ) ;\n}\n```\n## A Nice Exotic Mixture of Programming Languages\n\nSuppose the following: There are a couple of JavaScript and Python programs to interact with a database. The database changes.\nAnd it would be nice to not change modules for database access.\n
\nEspecially if the new database is an Oracle database. Perhaps on Linux.\n
\nEverybody who had ever tried to install the appropriate NodeJS or Python module ended up in a mess of build, configuration and installation problems.\n
\nOne of the nicest Java features is the total abstraction of the database handling via the JDBC api.\n
\nIt is clear what to do: Use a Java Gepard client connected to a database and execute all simple REST kind of actions\nvia request/respond on the basis of Gepard.\n
\nIn this combination changing a database vendor is only a 10 second job changing the connection url and restart the Java client. Ok: another 5 seconds. But that's it.\n
\nNo compilation, no installation no problems.\n\n# The Event Body\nThis member of an event is the holder for all payload-data. In all languages this is a hashtable with the restriction that the key must be\nof type string.\n
\n* Java: __Map<String,Object>__\n* JavaScript: __{}__ or in long form: __Object__\n* Python: __{}__ which is in fact an object of type __dict__\n* PHP: __[]__ which is in fact an object of type __Array__\n\nSetter and getter are the appropriate methods __Event.putValue(name,value)__ and __Event.getValue(name)__.\n
\n__value__ is either a scalar type, a hashtable with strings as keys and valid object types, a list containing valid object types or a a combination of all valid types.\nThus a set of data like a tree can be used.\n
\n__Note: Gepard's data exchange mechanism is NOT intended to transport serialized objects between clients.__\n
\nThe valid types are:\n* scalar type objects: string, int, double, number\n* array type objects:\n\t- Array ( [] )\n\t- List ( [] )\n* hashtable type objects:\n\t- Java: Map<String,Object>\n\t- Python: dict ( {} )\n\t- JavaScript: Object ( {} )\n\nThere are 2 type of objects which are treated by gepard in a special way:\n* dates\n\t- JavaScript: Date\n\t- Java: Date\n\t- Python: datetime.datetime\n\t- PHP: Date\n* bytes\n\t- JavaScript: Buffer\n\t- Java: byte[]\n\t- Python: bytearray, bytes ( bytes should not be used to send because in python < 3 bytes is a subclass of str, typeof byte == 'str'\n\t\tand thus cannot be detected by this mechanism)\n\nIn these cases an object is transferred from a generic class of a sender to the generic class of the receiver which means it is reconstructed in the target programming language.\n
\n__Note on Python:__\n
\nThe built-in date class in python is not able to parse or format ISO date strings. In order to enable full interoperability related to dates\nthe gapard module tries to import the well known __dateutils__ module. This in turn imports the __six__ module. If these modules are in\npython's module path the generic python date class can be used.\n
\nDetails in:\n\n* JavaScript: [gepard/xmp/EmitterWithBody.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/EmitterWithBody.js)\n* Java: [gepard/java/org.gessinger/gepard/xmp/EmitterWithBody.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/EmitterWithBody.java)\n* Python: [EmitterWithBody.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/EmitterWithBody.py)\n\n# Examples\n\nReady to use examples for JavaScript are located in __.../gepard/xmp__\n
\nReady to use examples for Java are located in __.../gepard/gepard/java/org.gessinger/gepard/xmp__ and compiled in\n__.../gepard/java/lib/Gepard.jar__\n
\nReady to use examples for Python are located in __.../gepard/python/xmp__\n\n## Examples Short\n\n### Event listener\n\nAdding a event-listener with the __on()__ method may be done with a single event-name or a list of event-names.\n\n__JavaScript__: client.on ( \"ALARM\", callback )\n\t
or client.on ( [ \"ALARM\", \"BLARM\" ], callback )\n\n__Java__: client.on ( \"ALARM\", callback )\n
or client.on ( new String[] { \"ALARM\", \"BLARM\" }, callback )\n\n__Python__: client.on ( \"ALARM\", callback )\n
or client.on ( [ \"ALARM\", \"BLARM\" ], callback )\n\n__PHP__: client->on ( \"ALARM\", callback )\n
or client->on ( [ \"ALARM\", \"BLARM\" ], callback )\n\nThe callback will be called with an Event object of the appropriate name ( e.getName() or $e->getName() )\n\n\nApplication\n\n```js\n\tvar gepard = require ( \"gepard\" ) ;\n\tvar client = gepard.getClient() ;\n```\nBrowser\n\n```js\n\tvar client = gepard.getWebClient ( 17502[, host] ) ;\n```\n\nCode\n\n```js\nclient.on ( \"ALARM\", function event_listener_callback(e)\n{\n\tconsole.log ( e.toString() ) ;\n});\n```\n\nJava\n\n```java\nimport org.gessinger.gepard.Client ;\nimport org.gessinger.gepard.EventListener ;\nimport org.gessinger.gepard.Event ;\nClient client = Client.getInstance() ;\n\nclient.on ( \"ALARM\", new EventListener()\n{\n\tpublic void event ( Event e )\n\t{\n\t\tSystem.out.println ( e ) ;\n\t}\n} ) ;\n```\n\nPython\n\n```python\nimport gepard\nclient = gepard.Client.getInstance()\n\ndef on_ABLARM ( event ):\n\tprint ( \"on_ALARM\" )\n\tprint ( event )\n\nclient.on ( \"ALARM\", on_ABLARM )\n```\n\nPHP\n\n```php\nnamespace Gepard;\nrequire ( 'vendor/autoload.php' );\nuse Gepard;\n$client = Client::getInstance();\n$client->on ( 'ALARM', function($event) {\n\techo ( $event ) ;\n}) ;\n\n``\n\nDetails in:\n\n* JavaScript: [gepard/xmp/Listener.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/Listener.js)\n* Java: [gepard/java/org.gessinger/gepard/xmp/Listener.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/Listener.java)\n* Python: [Listener.py](https://github.com/gessinger-hj/gepard-python/blob/master/python/xmp/Listener.py)\n* PHP: [Listener.php](https://github.com/gessinger-hj/gepard-php/blob/master/xmp/Listener.php)\n\n### Event Emitter\n\nApplication\n\n```js\nvar gepard = require ( \"gepard\" ) ;\nvar client = gepard.getClient() ;\nclient.emit ( \"ALARM\",\n{\n\tvar thiz = this ;\n\twrite: function()\n\t{\n\t\tthiz.end() ; // close connection after written\n\t}\n});\n```\n\nBrowser\n\n```js\nvar client = gepard.getWebClient ( 17502[, host] ) ;\nclient.emit ( \"CONFIG-CHANGED\" ) ;\n```\n\nJava\n\n```java\nimport org.gessinger.gepard.Client ;\nClient client = Client.getInstance() ;\nclient.emit ( \"ALARM\" ) ;\n```\n\nPython\n\n```python\nimport gepard\nclient = gepard.Client.getInstance()\nclient.emit ( \"ALARM\" )\n```\n\nPHP\n```php\nnamespace Gepard;\nrequire ( 'vendor/autoload.php' );\nuse Gepard;\n$client = Client::getInstance();\n$client->emit ( 'ALARM' );\n```\nDetails in:\n\n* JavaScript: [gepard/xmp/Emitter.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/Emitter.js)\n* JavaScript: [gepard/xmp/EmitterWithStatusInfo.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/EmitterWithStatusInfo.js)\n* JavaScript: [gepard/xmp/EmitterWithBody.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/EmitterWithBody.js)\n* Java: [gepard/java/org.gessinger/gepard/xmp/Emitter.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/Emitter.java)\n* Java: [gepard/java/org.gessinger/gepard/xmp/EmitterWithStatusInfo.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/EmitterWithStatusInfo.java)\n* Java: [gepard/java/org.gessinger/gepard/xmp/EmitterWithBody.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/EmitterWithBody.java)\n* Python: [Emitter.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/Emitter.py)\n* Python: [EmitterWithStatusInfo.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/EmitterWithStatusInfo.py)\n* Python: [EmitterWithBody.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/EmitterWithBody.py)\n* PHP: [Emitter.php](https://github.com/gessinger-hj/gepard-php/blob/master/xmp/Emitter.php)\n\n### Locks\n\nApplication\n\n```js\n\tvar gepard = require ( \"gepard\" ) ;\n\tvar lock = new gepard.Lock ( \"resid:main\" ) ;\n```\nBrowser\n\n```js\ngepard.port = 17502 ;\nvar lock = new gepard.Lock ( \"resid:main\" ) ;\n```\nCode\n\n```js\nlock.acquire ( function ( err )\n{\n\tconsole.log ( this.toString() ) ;\n\tif ( this.isOwner() )\n\t{\n\t\t.........\n\t\tthis.release() ;\n\t}\n} ) ;\n```\n\nJava\n\n```java\nimport org.gessinger.gepard.Lock ;\nLock lock = new Lock ( \"resid:main\" ) ;\nlock.acquire() ;\nif ( lock.isOwner() )\n{\n\t.........\n\tlock.release() ;\n}\n```\n\nPython\n\n```python\nimport gepard\n\nlock = gepard.Lock ( \"resid:main\" )\nlock.acquire()\n\nif lock.isOwner():\n\t......................\n\tlock.release()\n\n```\n\nDetails in:\n\n* JavaScript: [gepard/xmp/Locker.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/Locker.js)\n* Java: [gepard/java/org.gessinger/gepard/xmp/Locker.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/Locker.java)\n* Python: [Locker.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/Locker.py)\n\n\n### Semaphores\n\nApplication\n\n```js\n\tvar gepard = require ( \"gepard\" ) ;\n\tvar sem = new gepard.Semaphore ( \"user:4711\" ) ;\n```\nBrowser\n\n```js\ngepard.port = 17502 ;\nvar sem = new gepard.Semaphore ( \"user:4711\" ) ;\n```\n\nCode\n\n```js\nsem.acquire ( function ( err )\n{\n\tconsole.log ( this.toString() ) ;\n\n\t\t.....................\n\n\tthis.release() ;\n} ) ;\n```\n\nJava\n\nAsynchronously\n\n```java\nimport org.gessinger.gepard.Semaphore ;\nimport org.gessinger.gepard.SemaphoreCallback ;\nfinal Semaphore sem = new Semaphore ( \"user:4711\" ) ;\nsem.acquire ( new SemaphoreCallback()\n{\n\tpublic void acquired ( Event e )\n\t{\n\t\tSystem.out.println ( sem ) ;\n\t\t.....................\n\t\tsem.release() ;\n\t}\n}) ;\n```\n\nSynchronously\n\n```java\nimport org.gessinger.gepard.Semaphore ;\nfinal Semaphore sem = new Semaphore ( \"user:4711\" ) ;\n// with or without a timeout\nsem.acquire(5000) ;\n\nif ( sem.isOwner() ) // if not timeout occured\n{\n\t\t.....................\n\tsem.release() ;\n}\n```\n\nPython\n\nAsynchronously\n\n```python\nimport gepard\n\ndef on_owner(sem):\n\t................\n\tsem.release()\n\nsem = gepard.Semaphore ( \"user:4711\" )\nsem.acquire ( on_owner )\n```\n\nSynchronously\n\n```python\n\nimport gepard\n\nsem = gepard.Semaphore ( name )\n\nsem.acquire ( 5 ) # with or without a timeout\n\nif sem.isOwner():\n\t...........\n\tsem.release()\n```\n\nDetails in:\n\n* JavaScript: [gepard/xmp/AsyncSemaphore.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/AsyncSemaphore.js)\n* Java: [gepard/java/org.gessinger/gepard/xmp/AsyncSemaphore.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/AsyncSemaphore.java)\n* Java: [gepard/java/org.gessinger/gepard/xmp/AsyncSemaphore.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/BlockingSemaphore.java)\n* Python: [AsyncSemaphore.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/AsyncSemaphore.py)\n* Python: [BlockingSemaphore.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/BlockingSemaphore.py)\n\n### Request / Result\n\n#### Send request\n\nApplication:\n\n```js\n\tvar gepard = require ( \"gepard\" ) ;\n\tvar client = gepard.getClient() ;\n```\nBrowser:\n\n```js\n\tvar client = gepard.getWebClient ( 17502[, host] ) ;\n```\nCode:\n\n```js\nclient().request ( \"getFileList\"\n, function result(e)\n\t{\n\t\tconsole.log ( e.getBody().list ) ;\n\t\tthis.end() ;\n\t});\n```\n\nJava\n\n```java\nimport org.gessinger.gepard.Client ;\nimport org.gessinger.gepard.ResultCallback ;\nimport org.gessinger.gepard.Util ;\nimport java.util.List ;\nfinal Client client = Client.getInstance() ;\nclient.request ( \"getFileList\", new ResultCallback()\n{\n\tpublic void result ( Event e )\n\t{\n\t\tif ( e.isBad() )\n\t\t{\n\t\t\tSystem.out.println ( \"e.getStatusReason()=\" + e.getStatusReason() ) ;\n\t\t}\n\t\telse\n\t\t{\n\t\t\tList list = (List) e.getBodyValue ( \"file_list\" ) ;\n\t\t\tSystem.out.println ( Util.toString ( list ) ) ;\n\t\t}\n\t\tclient.close() ;\n\t}\n}) ;\n\n```\n\nPython\n\n```python\nimport gepard\n\nclient = gepard.Client.getInstance()\n\ndef getFileList ( e ):\n\tif e.isBad():\n\t\tprint ( e.getStatusReason() )\n\telse:\n\t\tprint ( e.getValue ( \"file_list\" ) )\n\te.getClient().close()\n\nclient.request ( \"getFileList\", getFileList )\n\n```\n\nDetails in:\n\n* JavaScript: [gepard/xmp/Requester.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/Requester.js)\n* Java: [gepard/java/org.gessinger/gepard/xmp/Requester.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/Requester.java)\n* Python: [Requester.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/Requester.py)\n* PHP: [Requester.php](https://github.com/gessinger-hj/gepard-php/blob/master/xmp/Requester.php)\n\n#### Send result\n\nApplication:\n\n```js\n\tvar gepard = require ( \"gepard\" ) ;\n\tvar client = gepard.getClient() ;\n```\nBrowser:\n\n```js\n\tvar client = gepard.getWebClient ( 17502[, host] ) ;\n```\nCode:\n\n```js\nvar list = [ \"one.js\", \"two.js\", \"three.js\" ] ;\nclient.on ( \"getFileList\", function ( e )\n{\n\te.getBody().list = list ;\n\te.sendBack() ;\n});\n```\n\nJava\n\n```java\nimport org.gessinger.gepard.Client ;\nimport org.gessinger.gepard.EventListener ;\nimport org.gessinger.gepard.Event ;\nfinal Client client = Client.getInstance() ;\nclient.on ( name, new EventListener()\n{\n\tpublic void event ( Event e )\n\t{\n\t\tString[] fileList = new String[] { \"a.java\", \"b.java\", \"c.java\" } ;\n\t\te.putBodyValue ( \"file_list\", fileList ) ;\n\t\te.sendBack() ;\n\t}\n} ) ;\n```\n\nPython\n\n```python\nimport gepard\nclient = gepard.Client.getInstance()\n\nfileList = [ \"a.py\", \"b.py\", \"c.py\" ] ;\ndef on_getFileList ( event ):\n\tprint ( \"Request in\" ) ;\n\tprint ( \"File list out:\" ) ;\n\tprint ( fileList ) ;\n\tevent.body[\"file_list\"] = fileList ;\n\tevent.sendBack() ;\n\nclient.on ( \"getFileList\", on_getFileList )\n```\n\nDetails in:\n\n* JavaScript: [gepard/xmp/Responder.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/Responder.js)\n* Java: [gepard/java/org.gessinger/gepard/xmp/Responder.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/Responder.java)\n* Python: [Responder.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/Responder.py)\n* PHP: [Responder.php](https://github.com/gessinger-hj/gepard-php/blob/master/xmp/Responder.php)\n\n## Examples Long\n\n### Event listener\n\n#### In Application\n\n```js\nvar gepard = require ( \"gepard\" ) ;\nvar c = gepard.getClient() ;\n\nvar eventName = \"ALARM\" ;\nconsole.log ( \"Listen for events with name=\" + eventName ) ;\nc.on ( eventName, function(e)\n{\n\tconsole.log ( e ) ;\n});\nc.on('end', function()\n{\n\tconsole.log('socket disconnected');\n});\nc.on('error', function ( event)\n{\n\tconsole.log( event );\n});\nc.on('shutdown', function()\n{\n\tconsole.log('broker shut down');\n});\n```\n\n#### In Browser\n\n```html\n\n\n\n```\n\n```js\n\t\tvar wc = gepard.getWebClient ( 17502 ) ;\n\t\tthis.wc.on ( \"open\", function onopen()\n\t\t{\n\t\t}) ;\n\t\tthis.wc.on ( \"error\", function onerror()\n\t\t{\n\t\t}) ;\n\t\tthis.wc.on ( \"close\", function onclose()\n\t\t{\n\t\t}) ;\n\t\twc.on ( \"ALARM\", function event_listener_callback ( e )\n\t\t{\n\t\t\tconsole.log ( e.toString() ) ;\n\t\t}) ;\n```\n\n### Event Emitter\n\n#### In Application\n\n```js\nvar gepard = require ( \"gepard\" ) ;\nvar c = gepard.getClient() ;\n\nvar event = new gepard.Event ( \"CONFIG-CHANGED\" ) ;\nevent.setBody ( { \"config-name\" : \"app.conf\" } ) ;\nc.emit ( event,\n{\n\twrite: function() // close connection after write\n\t{\n\t\tc.end() ;\n\t}\n});\n```\n#### In Browser\n\n```html\n\n\n\n```\n\n```js\nvar wc = gepard.getWebClient ( 17502 ) ;\nvar event = new gepard.Event ( \"CONFIG-CHANGED\" ) ;\nevent.setBody ( { \"config-name\" : \"app.conf\" } ) ;\nwc.emit ( event ) ;\n```\n\n# File Transfer with the FileContainer Class\n\nThe basic usage of this class is as follows:\n\n## FileSender\n\nJavaScript:\n
See also: [gepard/xmp/FileSender.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/FileSender.js)\n\n\n```js\nvar gepard = require ( \"gepard\" ) ;\nvar client = gepard.getClient() ;\nvar event = new gepard.Event ( \"__FILE__\" ) ;\nvar file = \"\" ;\nevent.putValue ( \"DATA\", new gepard.FileContainer ( file ) ) ;\nclient.request ( event, function ( e )\n{\n\tif ( e.isBad() )\n\t{\n\t\tconsole.log ( e.getStatus() ) ;\n\t}\n\telse\n\t{\n\t\tconsole.log ( \"File \" + file + \" sent successfully.\" )\n\t}\n\tthis.end() ;\n}) ;\n```\n\nPython:\n
See also: [gepard/python/xmp/FileSender.py](https://github.com/gessinger-hj/gepard/blob/master/python/xmp/FileSender.py)\n\n```python\nclient = gepard.Client.getInstance()\n\nevent = gepard.Event ( \"__FILE__\" )\n\nfile = \"\" ;\nevent.putValue ( \"DATA\", gepard.FileContainer ( file ) )\n\ndef result ( e ):\n\tif e.isBad():\n\t\tprint ( e.getStatusReason() )\n\telse:\n\t\tprint ( \"File \" + file + \" sent successfully.\" )\n\te.getClient().close()\n\nprint ( \"Sending \" + file )\nclient.request ( event, result )\n```\nJava:\n
See also: [gepard/java/org.gessinger/gepard/xmp/FileSender.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/FileSender.java)\n\n```java\n\t\tfinal Client client = Client.getInstance() ;\n\n\t\tEvent event = new Event ( \"__FILE__\" ) ;\n\t\tfinal String file = \"\"\n\t\tevent.putValue ( \"DATA\", new FileContainer ( file ) ) ;\n\t\tclient.request ( event, new ResultCallback()\n\t\t{\n\t\t\tpublic void result ( Event e )\n\t\t\t{\n\t\t\t\tif ( e.isBad() )\n\t\t\t\t{\n\t\t\t\t\tSystem.out.println ( e ) ;\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t{\n\t\t\t\t\tSystem.out.println ( \"File \" + file + \" sent successfully.\" ) ;\n\t\t\t\t\tSystem.out.println ( \"code: \" + e.getStatusCode() );\n\t\t\t\t\tSystem.out.println ( \"name: \" + e.getStatusName() );\n\t\t\t\t\tSystem.out.println ( \"reason: \" + e.getStatusReason() );\n\t\t\t\t}\n\t\t\t\tclient.close() ;\n\t\t\t}\n\t\t}) ;\n```\n\n##FileReceiver\n\nJavaScript:\n
See also: [gepard/xmp/FileReceiver.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/FileReceiver.js)\n\n```js\n\tvar client = gepard.getClient() ;\n\tclient.on ( \"__FILE__\", function(e)\n\t{\n\t\tvar data = e.removeValue ( \"DATA\" ) ;\n\t\tconsole.log ( data.getName() + \" received.\" ) ;\n\t\tvar fname = data.getName() + \".in\" ;\n\t\ttry\n\t\t{\n\t\t\tdata.write ( fname ) ;\n\t\t\tconsole.log ( fname + \" written.\" ) ;\n\t\t}\n\t\tcatch ( exc )\n\t\t{\n\t\t\te.control.status = { code:1, name:\"error\", reason:\"could not write: \" + fname } ;\n\t\t\tconsole.log ( exc ) ;\n\t\t}\n\t\te.sendBack() ;\n\t});\n```\n\nPython:\n
See also: [FileReceiver.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/FileReceiver.py)\n\n```py\nclient = gepard.Client.getInstance()\n\ndef on___FILE__ ( e ):\n\tdata = e.removeValue ( \"DATA\" )\n\tprint ( data.getName() + \" received.\" ) ;\n\tfname = data.getName() + \".in\"\n\ttry:\n\t\tdata.write ( fname ) ;\n\t\tprint ( fname + \" written.\")\n\texcept Exception as exc:\n\t\tprint ( exc )\n\te.sendBack() ;\n\nclient.on ( \"__FILE__\", on___FILE__ )\n```\nJava:\n
See also: [gepard/java/org.gessinger/gepard/xmp/FileReceiver.java](https://github.com/gessinger-hj/gepard/blob/master/java/src/org/gessinger/gepard/xmp/FileReceiver.java)\n\n```java\nfinal Client client = Client.getInstance() ;\nclient.on ( \"__FILE__\", new EventListener()\n{\n\tpublic void event ( Event e )\n\t{\n\t\ttry\n\t\t{\n\t\t\tFileContainer fileContainer = (FileContainer) e.removeValue ( \"DATA\" ) ;\n\t\t\tString fname = fileContainer.getName() + \".in\" ;\n\t\t\tfileContainer.write ( fname ) ;\n\t\t\tSystem.out.println ( fname + \" written.\" );\n\t\t\te.setStatus ( 0, \"success\", \"File accepted.\" ) ;\n\t\t}\n\t\tcatch ( Exception exc )\n\t\t{\n\t\t\te.setStatus ( 1, \"error\", \"File not saved.\" ) ;\n\t\t\tSystem.out.println ( Util.toString ( exc ) ) ;\n\t\t}\n\t\ttry\n\t\t{\n\t\t\te.sendBack() ;\n\t\t}\n\t\tcatch ( Exception exc )\n\t\t{\n\t\t\tSystem.out.println ( Util.toString ( exc ) ) ;\n\t\t}\n\t}\n} ) ;\n\n```\n\n# Heartbeat and Reconnection Capability Parameterization\n\n## Broker Side\n\nThe default ping interval for the broker is 180000 milli-sec or 3 minutes. This value can be changed in different ways:\n\n1. Startup parameter: --gepard.heartbeat.millis=<nnn>\n1. Evironment variable: GEPARD_HEARTBEAT_MILLIS=<nnn>\n1. Variable in configuration-file: { \"heartbeatMillis\":<nnn> }\n1. In program: broker.setHeartbeatMillis ( <nnn> )\n\n## Client Side\n\nThe default is reconnect=false\n\n This value can be changed in different ways:\n \n1. Startup parameter: --gepard.reconnect=true\n1. environment variable: export GEPARD_RECONNECT=true\n1. client.setReconnect ( true ) before any socket connection is active\n1. gepard.setProperty ( 'gepard.reconnect', 'true' )\n\nIf the boker is shut down all clients receive a __shutdown event__.\nIf __reconnect==true__ the appropriate callback in the client is called and the client api tries to reconnect.\n
\nAt this place a call to __client.setReconnect(false|False)__ initiates a Client-shutdown without reconnection.\n
\nThere are two new callbacks available signaling the state-change to the owner-application:\n\n* Java\n\t1. client.onReconnect ( InfoCallback icb )\n\t1. client.onDisconnect ( InfoCallback icb )\n\n* Python\n\t1. client.onReconnect ( <callback> )\n\t1. client.onDisconnect ( <callback> )\n\n* JavaScript\n\t1. client.on ( \"reconnect\", <callback> )\n\t1. client.on ( \"disconnect\", <callback> )\n\n### Example to test\n\n1. open a terminal, execute: node_modules/.bin/gp.broker or node node_modules/gepard/src/Broker.js\n1. open a terminal, execute: node node_modules/gepard/xmp/Listener.js\n1. open a terminal, execute: python node_modules/gepard/python/xmp/Listener.py\n1. open a terminal, goto node_modules/gepard/java\n\t\t
execute: java -cp lib/Gepard.jar:lib/gson-2.3.1.jar org.gessinger.gepard.xmp.Listener\n\nThen goto terminal one and kill the Broker either with ^C ( ctrl+C ) or with kill -9 <pid> or with the taskmanger on windows. \n
\nAppropriate output is visible.\n
\nThen start the Broker again and all clients reconnect again. Check with gp.info that all event-listener are registered again.\n\n# The TracePoint Concept\n\nTracePoints or short __TP__ are used to monitor a data flow at specific places in an application. The combination of all traced-data\nhelps to analyze and control the behaviour especially within a distributed system..\n
\nIt is very important to use these TracePoints immediately in a running system without changing static configuration\nand system-restart.\n
\nAll defined TracePoints in a Gepard-based distributed application can be switched on/off and reconfigured at runtime on behalf of the Admin programm.\nTracePoint commands are sent to the running Broker and forwarded to all or selected clients.\n\n## TracePoints in the Broker\n\nThere are 2 predefined __TPs__ in the Broker. Each TP in the context of a program has a unique name to address commands to.\n
\n\n1. __EVENT_IN__\n\tIf this TP is switched on all incoming events are logged to the Broker's log-file.\n1. __EVENT_OUT__\n\tIf this TP is switched on all outgoing events are logged to the Broker's log-file.\n\nThe status of these __TPs__ can be viewed with the command: __gp.tplist__\n
\nThe output reads as:\n```js\n{ tracePointStatus:\n\t { name: 'broker',\n\t\t list:\n\t\t\t[ { name: 'EVENT_IN', active: false },\n\t\t\t\t{ name: 'EVENT_OUT', active: false } ],\n\t\t output: 'local' } }\n```\nSwitching the __TPs__ is done with the commands:\n\n- __gp.tpon__ [ <tp-name> { , <tp-name> }] \n\tswitch on all or given __TPs__\n- __gp.tpoff__ [ <tp-name> { , <tp-name> }] \n\tswitch off all or given __TPs__\n- __gp.tp__\n\ttoggle all __TPs__\n\nIn all cases the current status of the __TPs__ is shown.\n\n## TracePoints in the Client\n\nThere are 2 predefined __TPs__ in each client. Each TP in the context of a program has a unique name to address commands to.\n
\n\n1. __EVENT_IN__\n\tIf this TP is switched on all incoming events are logged.\n1. __EVENT_OUT__\n\tIf this TP is switched on all outgoing events are logged.\n\nThe status of these __TPs__ can be viewed with the command: __gp.client.tplist__\n
\nThe output reads as:\n\n```js\n{ tracePointStatus:\n\t { name: 'broker',\n\t\t list:\n\t\t\t[ { name: 'EVENT_IN', active: false },\n\t\t\t\t{ name: 'EVENT_OUT', active: false } ],\n\t\t output: 'local' } }\n```\n\nSwitching the __TPs__ is done with the commands:\n\n- __gp.client.tpon__ [ <tp-name> { , <tp-name> }] [ --output=remote|local ] [ --sid=<sid-of-specific-client> ]\n\t
\n\tswitch on all or given TPs\n\t
\n\toptional: direct output to local or remote to the Broker.\n- __gp.client.tpoff__ [ <tp-name> { , <tp-name> }] [ --output=remote|local ] [ --sid=<sid-of-specific-client> ]\n\t
\n\tswitch off all or given TPs\n\t
\n\toptional: direct output to local or remote to the Broker.\n- __gp.client.tp__ [ --output=remote|local ] [ --sid=<sid-of-specific-client> ]\n\t
\n\ttoggle all TPs\n\t
\n\toptional: direct output to local or remote to the Broker.\n\nIn all cases the current status of the __TPs__ is shown.\n\nExamples with 2 clients:\n- __gp.client.tplist__\n\n```js\n{ tracePointStatus:\n\t { name: 'client',\n\t\t list:\n\t\t\t[ { name: 'EVENT_IN', active: false },\n\t\t\t\t{ name: 'EVENT_OUT', active: false },\n\t\t output: 'local' },\n\tsid: '::ffff:127.0.0.1_44109_1452621748330',\n\tapplicationName: 'Listener' }\n{ tracePointStatus:\n\t { name: 'client',\n\t\t list:\n\t\t\t[ { name: 'EVENT_IN', state: false },\n\t\t\t\t{ name: 'EVENT_OUT', state: false } ],\n\t\t output: 'local' },\n\tsid: '::ffff:127.0.0.1_44246_1452621873697',\n\tapplicationName: 'org.gessinger.gepard.xmp.Listener' }\n```\n- __gp.client.tplist --sid=::ffff:127.0.0.1_44246_1452621873697__\n\n```js\n{ tracePointStatus:\n\t { name: 'client',\n\t\t list:\n\t\t\t[ { name: 'EVENT_IN', state: false },\n\t\t\t\t{ name: 'EVENT_OUT', state: false } ],\n\t\t output: 'local' },\n\tsid: '::ffff:127.0.0.1_44246_1452621873697',\n\tapplicationName: 'org.gessinger.gepard.xmp.Listener' }\n```\n\n- __gp.client.tp --sid=::ffff:127.0.0.1_44246_1452621873697 --output=remote__\n\n```js\n{ tracePointStatus:\n\t { name: 'client',\n\t\t list:\n\t\t\t[ { name: 'EVENT_IN', state: true },\n\t\t\t\t{ name: 'EVENT_OUT', state: true } ],\n\t\t output: 'remote' },\n\tsid: '::ffff:127.0.0.1_44246_1452621873697',\n\tapplicationName: 'org.gessinger.gepard.xmp.Listener' }\n```\n\n# Zeroconf Usage in Detail\n\n## Zeronconf on the Broker's Side\n\nIf configured the gepard Broker publishes a service in the local subnet and can be discovered by any interested client.\n
\nThe fully qualified domain name (FQDN) for the service consists out of 3 parts:\n\n1.\tname, e.g. __Broker__\n\n1.\ttype, e.g. __gepard__\n\n1.\tprotocol, **tcp.local**\n\nThe FQDN is derived from this parameters as: __Broker._gepard._tcp.local__\n
\nThis name and type can be defined by\n\n1.\tan entry in the broker's json config\n
\n\tThe form is either a comma separated list like\n\n\t```js\n\t{\n\t\t\"zeroconf\": [,] [ ,|0]\n\t}\n\t```\n\tor\n\t```js\n\t{\n\t\t\"zeroconf\": { \"name\": , \"type\": [ , \"port\": |0] }\n\t}\n\t```\n1.\ta startup parameter of the form: --gepard.zeroconv=[<name>,]<type>[,<port>]\n\n1.\tan environment variable of the form:\n\t\texport GEPARD_ZEROCONF=[<name>,]<type>[,<port>]\n\n1.\tcalling the method\n\t\tbroker.setZeroconfParameter ( [<name>,]<type> [ ,<port>] )\n\nIf only the <type> is given the <name> is choosen to be:\n```js\nGepard-[H:]-[P:]\n```\n\nThis postfix __-[H:<hostname>]-[P:<port>]__ is always appended to make the name unique.\n
\nIf the <port> is not given the standard definitions are used.\nIf the port is __exactly 0__ a random free port is choosen. Thus no special arrangement is needed for running several brokers on one machine.\nThe __TXT__ segment contains a comma-list of all registered event-names as TOPIC entry and a comma-list of all channels as CHANNELS entry.\nWith this an interested client can choose a a Broker depending on this information e.g. with the methods\n\n*\tservice.topicExists(<topic-name>) and\n\n* service.channelExists(<channel-name>)\n\nThis convention is expanded because of the lack of proper parsing the __TXT__ segment of the advertised service in the python zeroconf-module.\nIn addition to the __TXT__ segment the advertised service-name contains the comma-lists of topics and channels if given.\nThe format is:\n\n[T:topic1,topic2,...] and [C:channel1,channel2,...]\n\nWith this information a client can make a profound decision whether to connect to a found broker or ignore it and search another instance.\n\n## Zeroconf on the Client's Side\n\nUp to now only the JavaScript and Python flavors works out of the box. There is no reliable pure Java implementation available.\n\nSuppose the broker is started with __test-gepard,0__. (service-type is test-gepard and port is arbitrary)\n\n```js\ngp.broker --gepard.zeroconf=test-gepard,0\n```\n\n
\nAn interested listener would do the following:\n\n__JavaScript__\n\n```js\nvar gepard = require ( \"gepard\" ) ;\nvar client = gepard.getClient ( { type: 'test-gepard' }, function acceptService ( service )\n{\n\t// optional e.g.: ignore service which is not on localhost with:\n\t// if ( ! service.isLocalhost() ) return false ;\n\treturn true ;\n} ) ;\nclient.setReconnect ( true ) ; // This is for re-connect if broker dies.\n // in this case the above function acceptService is re-used.\nclient.on ( \"ALARM\", (e) => console.log ( e ) ) ; // The \"ALARM\" listener is registered.\n```\n\nor simpler:\n\n```js\nvar client = gepard.getClient ( 'test-gepard' ) ;\nclient.setReconnect ( true ) ;\nclient.on ( \"ALARM\", (e) => console.log ( e ) ) ;\n```\n\nExample: [ZeroconfListener.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/ZeroconfListener.js)\n\n__Python__\n```py\nimport gepard\n\ndef acceptService ( client, service ):\n\t# optional e.g.: ignore service which is not on localhost with:\n\t# if not service.isLocalhost() return False\n\treturn True\n\ndef on_ALARM ( event ):\n\tprint ( event )\n\nclient = gepard.Client.getInstance('test-gepard',acceptService)\nclient.setReconnect ( True )\nclient.on ( \"ALARM\", on_ALARM )\n```\n\nor simpler:\n\n```py\ndef on_ALARM ( event ):\n\tprint ( event )\ngepard.Client.getInstance('test-gepard').setReconnect ( True ).on ( \"ALARM\", on_ALARM )\n```\n\nExample: [ZeroconfListener.py](https://github.com/gessinger-hj/gepard-python/blob/master/xmp/ZeroconfListener.py)\n\nIf a client uses no connection parameter it can be parametrised by\n\n*\tstart-parameter: --gepard.zeroconf.type=[__localhost__:]<type> or\n\n*\tenvironment-parameter: export GEPARD_ZEROCONF_TYPE=[__localhost__:]<type>\n\n__localhost:__ is optional and indicates to include only Broker running on the same host.\n\nIn this case the code to write is minimal:\n\n__JavaScript__\n\n```js\nvar client = gepard.getClient() ;\nclient.setReconnect ( true ) ;\nclient.on ( \"ALARM\", (e) => console.log ( e ) ) ;\n```\n__Python__\n\n```py\ndef on_ALARM ( event ):\n\tprint ( event )\n\nclient = gepard.Client.getInstance()\nclient.setReconnect ( True )\nclient.on ( \"ALARM\", on_ALARM )\n```\n\nThus the behaviour of a client can be easily changed with only external parameters without\nany code-change.\n
\n\nAn interested emitter would do the following:\n\n__JavaScript__\n\n```js\nvar gepard = require ( \"gepard\" ) ;\nvar client = gepard.getClient ( 'test-gepard', function acceptService ( service )\n{\n\tif ( service.getTopics().indexOf ( \"ALARM\" ) < 0 ) // ignore if listener does not exist\n\t{\n\t\treturn ;\n\t}\n\tclient.emit ( \"ALARM\",\n\t{\n\t write: function() // The event is sent -> end connection and exit\n\t {\n\t client.end() ;\n\t }\n\t});\n\treturn true ;\n} ) ;\n```\n__Python__\n```py\ndef acceptService ( client, service ):\n\tprint ( service )\n\tif service.isLocalHost():\n\t\tclient.emit ( \"ALARM\" )\n\t\tclient.close()\n\t\treturn True\n\treturn False\n\nclient = gepard.Client.getInstance ( 'test-gepard', acceptService )\n```\n\nor with external parametrisation use simply the simple Emitter.py in python/xmp and start it as:\n```py\npython Emitter.py --gepard.zeroconf.type=test-gepard\n```\n\nExample: [ZeroconfEmitter.js](https://github.com/gessinger-hj/gepard/blob/master/xmp/ZeroconfEmitter.js),[ZeroconfEmitter.py](https://github.com/gessinger-hj/gepard-py","maintainers":[{"name":"gessinger-hj","email":"gessinger.hj@gmail.com"}],"time":{"modified":"2022-06-18T07:42:09.089Z","created":"2015-01-29T21:47:09.141Z","1.0.0":"2015-01-29T21:47:09.141Z","1.0.2":"2015-02-17T09:20:18.369Z","1.2.0":"2015-03-10T19:35:25.036Z","1.2.1":"2015-04-08T20:46:58.827Z","1.2.2":"2015-04-22T22:16:56.496Z","1.2.3":"2015-06-25T22:12:30.898Z","1.3.0":"2015-08-17T08:33:24.561Z","1.3.1":"2015-08-18T21:47:01.036Z","1.3.2":"2015-08-18T21:49:19.909Z","1.3.3":"2015-10-28T18:10:38.714Z","1.4.0":"2015-11-18T17:44:53.289Z","1.4.1":"2015-11-18T18:11:09.122Z","1.4.2":"2015-11-21T11:42:51.401Z","1.4.3":"2015-12-18T12:05:34.728Z","1.4.4":"2016-01-14T13:13:34.133Z","1.4.5":"2016-01-19T14:01:59.566Z","1.5.0":"2016-02-04T17:02:16.073Z","1.5.1":"2016-02-14T22:27:54.640Z","1.6.0":"2016-04-11T16:32:14.762Z","1.7.0":"2016-05-24T13:21:49.913Z","1.7.1":"2016-05-24T15:00:08.402Z","1.7.2":"2016-07-13T12:11:35.017Z","1.7.3":"2016-07-13T13:33:52.916Z","1.7.4":"2016-07-13T14:58:13.602Z","1.7.5":"2016-07-29T20:26:06.314Z","1.7.6":"2016-08-02T14:19:29.549Z","1.7.7":"2016-08-02T14:28:25.445Z","1.7.8":"2016-08-11T14:16:35.154Z","1.7.9":"2016-08-16T11:22:55.683Z","1.8.0":"2016-08-26T18:09:41.162Z","1.8.1":"2016-09-12T16:58:08.314Z","1.8.2":"2016-10-07T14:16:45.403Z","1.8.3":"2017-01-18T15:45:23.045Z","1.8.4":"2017-02-02T13:04:18.509Z","1.8.5":"2017-02-02T14:50:18.979Z","1.9.0":"2017-07-19T16:40:05.286Z","1.9.1":"2017-08-01T21:52:50.279Z","1.9.2":"2017-08-19T18:36:24.693Z","1.9.3":"2017-10-28T17:58:01.369Z","1.9.4":"2017-10-29T14:09:08.914Z"},"homepage":"https://github.com/gessinger-hj","keywords":["distributed-applications","events","semaphores","locks","messages","JavaScript","Java","Python","PHP","message"],"repository":{"type":"git","url":"git+https://github.com/gessinger-hj/gepard.git"},"author":{"name":"Hans-Jürgen Gessinger","email":"gessinger.hj@gmail.com"},"bugs":{"url":"https://github.com/gessinger-hj/gepard/issues"},"readmeFilename":"README.md","license":"MIT"}