Like ASP.NET and J2EE application containers, PHP makes it quite easy to plug-in your own HTTP session handler and lots of different flavours exist already, from in-memory stores using tools like memcached to file and database persistent session mechanisms using products like MySQL.  Coherence is an ideal persistence store for HTTP sessions because it is:

• Very fast, enabling dynamic web pages to be quickly displayed
• Resilient and fault-tolerant, ensuring that process or server failures do not impact users – logging them off etc.
• Scalable, to support and ever increasing number of online users/customers
• Simple to integrate and manage, so the overhead of introducing Coherence does not burden either web development of operational staff

So can Coherence be used with PHP?. Well using the native Coherence C++ client to create a PHP extension that can then be wrapped using a PHP session_set_save_handler to setup some user defined session storage functions. A diagram to illustrate the relationship between the PHP runtime, Coherence C++ extension and the Coherence cache is shown below:

To include the PHP custom session handlers in your PHP page add the following to the top of your PHP page:

<?php
require 'coherence_session.php';
$s = new CoherencePHPSessionHandler();
.
.
?>

This basically enables a new session to be started using the custom session save handler. The custom session save handler looks like this:

<?php
class CoherencePHPSessionHandler
{
    private static $debug = False;

    /**
     * A reference to a Coherence named cache
     * @var resource
     */
    private $cache;

    /**
     * Session lifetime
     * @var resource
     */
    private $lifeTime;

    private static function Log($msg)
    {
      if(CoherencePHPSessionHandler::$debug)
      {
        echo "<br>DEBUG PHP: " . $msg . "\n";
      }
    }

    function __construct()
    {
        // get session-lifetime
        $this->lifeTime = get_cfg_var("session.gc_maxlifetime");

        CoherencePHPSessionHandler::Log("Lifetime: " . $this->lifeTime);
        $this->cache = new Cache("dist-php-sessions");

        if ($this->cache == null)
        {
            return false;
        }

        CoherencePHPSessionHandler::Log("Got cache handle");

        session_set_save_handler(array(&$this, 'open'),
                                array(&$this, 'close'),
                                array(&$this, 'read'),
                                array(&$this, 'write'),
                                array(&$this, 'destroy'),
                                array(&$this, 'gc'));
        register_shutdown_function('session_write_close');
        session_start();

        CoherencePHPSessionHandler::Log("Started session");
        return true;
    }

    /**
     * Open the session
     * @return bool
     */
    function open($savePath, $sessName)
    {
        // get session-lifetime
        $this->lifeTime = get_cfg_var("session.gc_maxlifetime");
        CoherencePHPSessionHandler::Log("Opening session");
        return true;
    }

    /**
     * Close the session
     * @return bool
     */
    public function close()
    {
        // ToDo: need to release Coherence resources
        return true;
    }

    /**
     * Read the session
     * @param int session id
     * @return string string of the session
     */
    public function read($id)
    {
        $result = $this->cache->get($id);

        if($result != null)
        {
          CoherencePHPSessionHandler::Log("Read session, id: " . $id . ", value: " . $result);
          return $result;
        }
        return '';
    }

    /**
     * Write the session
     * @param int session id
     * @param string data of the session
     */
    public function write($id, $data)
    {
        CoherencePHPSessionHandler::Log("Session value: " . serialize($data));

        $this->cache->put($id, $data, $this->lifeTime);
        CoherencePHPSessionHandler::Log("Written session, id: " . $id . ", value: " . $data);
        return true;
    }

    /**
     * Destoroy the session
     * @param int session id
     * @return bool
     */
    public function destroy($id)
    {
        $this->cache->remove($id);
        return true;
    }

    /**
     * Garbage Collector
     * @param int life time (sec.)
     * @return bool
     * @see session.gc_divisor      100
     * @see session.gc_maxlifetime 1440
     * @see session.gc_probability    1
     * @usage execution rate 1/100
     *        (session.gc_probability/session.gc_divisor)
     */
    public function gc($max)
    {
        return true;
    }
}
?>

As for the Coherence PHP extension there is too much to show here, though in total it does not amount to a lot of code. The C++ client class that wraps the Coherence client API is also very simple and the class functions are shown below:

#include "cache.h"

extern "C" {
#include <stdio.h>
#include <stdlib.h>
#include "php.h"
}

static char * copyString(const char *str)
{
    char *s;

    if(str != NULL && (s = (char *)emalloc(sizeof(char) * (strlen(str)  + 1))) == NULL)
    {
        return NULL;
    }
    else
    {
        if(strncpy(s, str, strlen(str) + 1) == NULL)
        {
            efree(s);
            return NULL;
        }
        return s;
    }
}

Cache::Cache(const char *name)
{
    // Get handle to a Named Cache
    String::View vsCacheName = String::create(name);
    hCache = CacheFactory::getCache(vsCacheName);
}

const char *Cache::getCacheName()
{
    String::View name = cast<String::View>(hCache->getCacheName());

    return copyString(name->getCString());
}

char* Cache::put(const char *key, const char *value, long ttl)
{
    if(key == NULL || value == NULL)
    {
        throw std::invalid_argument("Key or value for put() NULL");
    }
    String::View vKey = String::create(key);
    String::View vValue = String::create(value);
    String::View vOldValue = cast<String::View>(hCache->put(vKey, vValue, ttl));

    return (vOldValue == NULL ? NULL : copyString(vOldValue->getCString()));
}

char* Cache::remove(const char *key)
{
    String::View vKey = String::create(key);
    String::View vOldValue = cast<String::View>(hCache->remove(vKey));

    return (vOldValue == NULL ? NULL : copyString(vOldValue->getCString()));
}

char* Cache::get(const char *key)
{
    String::View vKey = String::create(key);
    String::View vOldValue = cast<String::View>(hCache->get(vKey));

    return (vOldValue == NULL ? NULL : copyString(vOldValue->getCString()));
}

int Cache::size()
{
    return (int)hCache->size();
}

The Coherence PHP extension can also be used for simply caching PHP values, as well as PHP session information. The above example was tested on Oracle Enterprise Linux 4, but can easily be compiled on Windows. You can download the whole example from here to try it out for yourself. Instructions are included which should hopefully be easy to follow. A couple of outstanding issues still remain with the Coherence PHP extension which I have not been able to resolve. Although simple PHP types as well as objects and arrays can be cached – both as keys and values – I could not get objects with private or protected variables to serialize. If anyone more experienced in the internals of PHP can help here it would be much appreciated, as I drew a blank.

This is achieved with the introduction of POF extractors and POF updaters, that fetch and update native POF objects without de-serializing the value to Java. As well as allowing .NET and C++ developers to just work in the language they are most comfortable and productive in, this new feature also has a number of other benefits:

• It dramatically improves performance, as no de-serialization needs to take place, so no new objects need to be created – or garbage collected.
• Less memory is required as a result.
• The development and deployment process is simpler, as no corresponding Java classes need to be created, managed and deployed.

However, there are some occasions where you do still need to create complementary Java objects to match your .NET or C++ objects. These are:

• When you want to use Key Association, as Coherence will always de-serializes keys to determine whether they implement KeyAssociation.
• If you use a Cache Stores - Coherence passes the de-serialized version of the key and value to the cache store to write to the back end so that ORM (Object Relational Mapping) tools, like Hibernate and EclipseLink (JPA) have access to the Java objects.

To update a value in a cache from C# you would use code similar to that shown below:

    // Parameters: key, (extractor, new value)
    cache.Invoke(0, new UpdaterProcessor(new PofUpdater(BetSerializer.ODDS), 1)); 

Here a cache value identified by the key ‘0’ is being updated using an UpdateProcessor. The ValueUpdator being used is a C# PofUpdater which will access the attribute at offset BetSerializer.ODD in the serialized POF value. Values held in a cache are held in a serialized format. When the POF serialization mechanism is used the values of an object are written and read from the POF stream in the same order. So here a constant  (BetSerializer.ODDS) is being used to provide a more readable representation for an offset like 3, i.e. the 3rd object value to be written and read from the POF stream.

For reading values from a cache in C# a similar approach is used, as shown below:

    // Query cache for all entries whose event name is 'FA Cup'
    EqualsFilter equalsFilter =
        new EqualsFilter(new PofExtractor(BetSerializer.EVENT_NAME), "FA Cup");

    Object[] results = cache.GetValues(equalsFilter);
    Console.WriteLine("Filter results:");

    for (int i = 0; i < results.Length; i++)
    {
        Console.WriteLine("Value = " + results[i]);
    }

Here all cache values that have an event name or “FA Cup” will be returned by the EqualsFilter. The C# PofExtractor is being used to extract the attribute at the offset BetSerializer.EVENT_NAME, which will be a number , like 4 indicating it was the 4th value to be written and read from the POF stream when the object it was part of was serialized.

This is a great new feature of Coherence and very easy to use. If you would like to see the full example the above extracts were taken from the you can download it from here. Happy coding - in C# and C++ ;).

To push database changes to Coherence in real-time when they are being made outside of Coherence, a queue needs to be used. Fortunately most databases support the queuing of transactional change information, either implicitly or explicitly. In this example architecture the explicit queuing of changes to an Oracle database, using Triggers and Oracle’s Advanced Queuing (AQ) technology, will be used to propagate them to a Coherence cache holding objects representing the same information.

Overview

Below is a diagram showing how the changes flow from the Oracle database to the Coherence cache.

In the example the read/receive operation from the queue is performed as a transaction, so the message is only removed from the queue once the corresponding cache object has been updated. This ensures that if the Coherence JVM/node that the client runs on fails the update message will not be lost. Although the example code focuses on cache updates it could easily be modified to accommodate inserts and deletes as well.

To enable Advanced Queuing (AQ) to be used for propagating table changes a number of database permissions first need to be granted. The PL/SQL to do this is shown below:

-- Execute as sys/welcome1

GRANT SELECT_CATALOG_ROLE TO scott;
GRANT EXECUTE ON DBMS_APPLY_ADM TO scott;
GRANT EXECUTE ON DBMS_AQ TO scott;
GRANT EXECUTE ON DBMS_AQADM TO scott;
GRANT EXECUTE ON DBMS_CAPTURE_ADM TO scott;
GRANT EXECUTE ON DBMS_FLASHBACK TO scott;
GRANT EXECUTE ON DBMS_STREAMS_ADM TO scott;
EXECUTE dbms_aqadm.grant_system_privilege('ENQUEUE_ANY', 'scott', TRUE);
EXECUTE dbms_aqadm.grant_system_privilege('DEQUEUE_ANY', 'scott', TRUE);
GRANT aq_administrator_role TO scott;
GRANT EXECUTE ON dbms_lock TO scott;
GRANT EXECUTE ON sys.dbms_aqin TO scott;
GRANT EXECUTE ON sys.dbms_aqjms TO scott;
EXIT;

Note: These GRANT statements need to be executed as the database administrator (sys) or another database user who has privileges to grant them.

Then the AQ queue need to be setup and the PL/SQL procedure and trigger created to put the database table changes in the appropriate queue. Below is the PL/SQL used to do this:

-- Execute as scott/tiger

-- Create queue
EXECUTE dbms_aqadm.stop_queue(queue_name => 'trade_queue');
EXECUTE dbms_aqadm.drop_queue(queue_name => 'trade_queue');
EXECUTE DBMS_AQADM.DROP_QUEUE_TABLE(queue_table => 'trade_queue_table');
EXECUTE dbms_aqadm.create_queue_table(queue_table => 'trade_queue_table',queue_payload_type => 'sys.aq$_jms_text_message', multiple_consumers => false);
EXECUTE dbms_aqadm.create_queue(queue_name => 'trade_queue', queue_table =>'trade_queue_table', queue_type => DBMS_AQADM.NORMAL_QUEUE, retention_time => 0, max_retries => 5, retry_delay => 60);
EXECUTE dbms_aqadm.start_queue(queue_name => 'trade_queue');

-- Create table

DROP TABLE Trade CASCADE CONSTRAINTS;
CREATE TABLE Trade
(
    Id     NUMBER PRIMARY KEY,
    Symbol VARCHAR2(5)       ,
    Created DATE             ,
    Quantity NUMBER          ,
    Amount   NUMBER(8,2)
);

-- Enable SERVEROUTPUT in SQL Command Line (SQL*Plus) to display output with
-- DBMS_OUTPUT.PUT_LINE, this enables SERVEROUTPUT for this SQL*Plus session only
SET SERVEROUTPUT ON
CREATE OR REPLACE
PROCEDURE testmessage(text_message VARCHAR2)
AS
  msg SYS.AQ$_JMS_TEXT_MESSAGE;
  msg_hdr SYS.AQ$_JMS_HEADER;
  msg_agent SYS.AQ$_AGENT;
  msg_proparray SYS.AQ$_JMS_USERPROPARRAY;
  msg_property SYS.AQ$_JMS_USERPROPERTY;
  queue_options DBMS_AQ.ENQUEUE_OPTIONS_T;
  msg_props DBMS_AQ.MESSAGE_PROPERTIES_T;
  msg_id RAW(16);
  dummy VARCHAR2(4000);
BEGIN
  msg_agent := SYS.AQ$_AGENT(' ', NULL, 0);
  msg_proparray := SYS.AQ$_JMS_USERPROPARRAY()  ;
  msg_proparray.EXTEND(1);
  msg_property := SYS.AQ$_JMS_USERPROPERTY('JMS_OracleDeliveryMode', 100, '2', NULL, 27);
  msg_proparray(1) := msg_property;
  msg_hdr := SYS.AQ$_JMS_HEADER(msg_agent,NULL,'<USERNAME>',NULL,NULL,NULL,msg_proparray);
  msg := SYS.AQ$_JMS_TEXT_MESSAGE(msg_hdr,NULL,NULL,NULL);
  msg.text_vc  := text_message;
  msg.text_len := LENGTH(msg.text_vc);
  DBMS_AQ.ENQUEUE(queue_name => 'trade_queue' , enqueue_options => queue_options , message_properties => msg_props , payload => msg , msgid => msg_id);
END;
/
CREATE OR REPLACE TRIGGER TradeAQTrigger AFTER INSERT OR UPDATE ON Trade
FOR EACH row DECLARE xml_complete VARCHAR2(1000);
BEGIN
    xml_complete := '<?xml version="1.0" encoding="UTF-8" ?>' ||
      '<TradeElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ' ||
      'xsi:schemaLocation="http://www.oracle.com/coherenceaq src/aq-object.xsd" ' ||
      'xmlns="http://www.oracle.com/coherenceaq">' ||
    '<Id>' || :new.ID || '</Id>' ||
    '<Symbol>' || :new.SYMBOL || '</Symbol>' ||
    '<Quantity>' || :new.QUANTITY || '</Quantity>' ||
    '<Amount>' || :new.AMOUNT || '</Amount>' ||
    '<Created>' || :new.CREATED || '</Created>' ||
    '</TradeElement>';   
    testmessage(xml_complete);
END;
/
SHOW ERRORS;

The Java code that runs in the background Coherence thread – started by the BackingMapListener – that reads messages from the queue looks like this:

.
.
.

/**
* <p>AQ client interface</p>
*/
public class AQClient
{
  .
  .
  .

  /**
   * Send an acknowledgement message for a received message. This enables the
   * message to be kept by the sender if client dies. An acknowledgement should only
   * be sent when the received message has been saved, e.g. in a cache
   *
   * @throws JMSException If an exception occurs sending an acknowledgement
   */
  public void aknowledgeMessage()
    throws JMSException
  {
    textMsg.acknowledge();
  }

  /**
   * Reads XML text message from the queue and transforms it into a Trade
   * object using JAXB classes.
   *
   * @return a Trade object
   * @throws JMSException If an exception occurs sending an acknowledgement
   * @throws JAXBException If an exception occurs during JAXB processing
   */
  public Trade receiveMessage()
    throws JMSException, JAXBException
  {
    // Wait for a message to show up in the queue
    textMsg = (TextMessage) queueReciever.receive();
    System.out.println("Message is: " + textMsg.getText());

    // Use JAXB to create object
    JAXBContext jc = JAXBContext.newInstance("com.oracle.demo.model");
    Unmarshaller u = jc.createUnmarshaller();
    JAXBElement<Trade> trade =
      (JAXBElement<Trade>) u.unmarshal(new StreamSource(new StringReader(textMsg.getText())));
    Trade t = trade.getValue();
    System.out.println("Trade created on: " + t.toString());
    return t;
  }
}

A full code example can be found here, including all the necessary PL/SQL scripts. All you need to try it out is Coherence, Oracle XE and Coherence .NET – if you want to see the changes propagated to a .NET Coherence client.

If changes in the Coherence cache data also need to be written back to the database then something like a status field or flag would need to be added to the the cached objects and table, to ensure that a circular loop isn’t created. For instance the following logic could enable bi-directional synchronization:

1. Propagate flag added to cached object (Trade) and database table (Trade) to signify if changes should be propagated by the after update trigger from the database to Coherence
2. Data changes propagated from Coherence to Database have propagate flag set to FALSE.
3. Introduce a new before insert/update trigger to reset the propagate flag to TRUE when it is FALSE.
4. When the after insert/update trigger fires only place the new value on the queue if the old value is not FALSE.

A modified example of the PL/SQL to add this functionality is in the setup-queue2.sql file, though you will need to add the additional column to the Trade table and attribute to the Trade object.

Summary

This approach is not the only mechanism for propagating changes from an Oracle Database to Coherence. Using a BackingMapListener to start the background queue client thread has an added benefit. If the node it is running on fails, Coherence will re-start the queue client on another node as part of its recovery process, i.e. when the queue configuration entry is failed-over and the new primary created it will cause a new background queue client thread to be started.

Alternative approaches to the one above might be to use Oracle Streams or the Data Change Notification mechanism in Oracle 11g

Stock price updates are pushed down to the Excel spreadsheet using the standard RTD (Read Time Data) server mechanism. As for the cache updates from Excel, they are send through a Coherence COM interface. VBA User Defined Functions (UDF’s) provide the interface in Excel for specifying where event data goes or which cell updates get mapped onto cache objects. These are added to Excel via the Add-in option from the Tools menu.

The UDF’s also hide some of the complexity of the interfaces from users. Here are he 3 UDF’s that provide the interface to Coherence:

• For updating properties of Stock objects in the cache
• UpdateDoubleProperty("dist-stocks",E4,"ORCL","StockPrice")
• UpdateStringProperty("dist-stocks",E4,"ORCL","StockPrice")
• For receiving update events for Stock objects in the cache
• RealTimeData("dist-stocks","ORCL","StockPrice")

In the UDF’s above “dist-stocks” is the name of the Coherence cache, “ORCL” is the key for the object you wish to update or receive change events from (this must be a string in the example) and “StockPrice” is the name of the property you want to update or get the latest value of. “E4” in the UpdateDoubleProperty() is the cell to take the new property value from – when it changes.

If properties of objects in the cache that you wish to receive updates about or change are in nested objects you can specify the target property via a “.” or if the target is in an object nested in a List or array you can use the “[ ]” operator. So for instance if the cache contained a Portfolio object with nested Stock objects in an array, you could specify the target Stock price for one of the nested Stocks as “Stocks[2].StockPrice”. This would get the 3rd Stock in a property of the Portfolio object called “Stocks” and from that Stock the “StockPrice” property. At the moment the UDF functions only support String and Double properties – but they could easily be enhanced to support other properties. This property specification method can also be nested as much as you like and provide as convenient way of specifying a target property as a string in Excel.

The easiest way to see how this all works in practice is to download the example and try it out – there is a readme.txt file in the example that explains how to set it up and try it out. Some of the things you will need to run the example are:

• Coherence for Java and .NET 3.4.2. It should work with more recent versions, though this is the release I have tested the example against.
• Java JDK 1.4.2 (or above)
• Microsoft Visual Studio 2008 and .NET 3.5. I tried to build the example using Visual Studio Express and via the command line but was unable to specify that the Coherence configuration files be embedded resources. Also someone has successfully back-ported the example to Visual Studio 2005 (though I don’t have the code)
• Excel 2003. It should work with later versions, though I am not sure when Excel started supporting the RTD mechanism.
• Office XP Primary Interop Assemblies (for Office 2003). This is need for the Excel integration assemblies.

Have fun trying this out and if anyone has any additional thoughts, recommendations or feedback I’d be keen to hear them.

The Web application outlined below is a Coherence*Extend Client, that means that it connects over a TCP/IP connection to the Coherence cluster (which uses UDP for inter-node communications) holding the cache data. A Proxy service run either on one or more of the cache nodes (or in a separate JVM) is used to pass requests and response between the client and the Coherence cluster – in a similar fashion to the way an Oracle Database listener works.

Note, the client could also be a Coherence Data Client, which means that the Web client would actually be part of the Coherence cluster. In this case the client would need to be ‘storage disabled’ through a system property or through the tangosol-coherence-override.xml configuration file. This means that although it will be part of the cluster it will not actually hold any data, so when the client is deployed or un-deployed there will be no cluster overhead re-organising cache data.

Accessing the configuration files

You really have a choice here. put them in the packaged Web application or reference them externally through the CLASSPATH or via a system property. Here I am going to package them with the Web application to make is completely self-contained. The code to do this is shown below:

 56    /**
 57     * <p>Reference to ConfigurableCacheFactory that can be used to
 58     * create a cache.</p>
 59     */
 60    private ConfigurableCacheFactory factory = null;
 61  
 62    /**
 63     * @inheritDoc
 64     */
 65    public void init(ServletConfig config)
 66      throws ServletException
 67    {
 68      super.init(config);
 69      // Create DefaultConfigurableCacheFactory using cache configuration file
 70      // in classes dir
 71      factory =
 72          new DefaultConfigurableCacheFactory("/config/cache-config.xml",
 73                                              getClass().getClassLoader());
 74    }

Here a DefaultConfigurableCacheFactory is used to read the configuration file used to setup the Coherence client parameters. All the configuration files that the Coherence client needs will be stored in the /WEB-INF/classes/config directory of the Web application. These are:

• cache-config.xml indicating where the Coherence cluster can be contacted
• pof-config.xml indicating the mapping between client and server objects. As both the client and server are Java only one object needs to be defined.
• tangosol-coherence-override.xml encapsulated many of the Coherence settings the are often specified as system properties.

The cache is accessed in the doGet(..) method of Servlet  as shown below:

 76    /**
 77     * @inheritDoc
 78     */
 79    public void doGet(HttpServletRequest request,
 80                      HttpServletResponse response)
 81      throws ServletException, IOException
 82    {
 83      // Create response
 84      response.setContentType(CONTENT_TYPE);
 85      PrintWriter out = response.getWriter();
 86      out.println("<html>");
 87      out.println("<head><title>CoherenceServlet</title></head>");
 88      out.println("<body>");
 89      // Get Coherence cache date
 90      NamedCache cache =
 91        factory.ensureCache("stock-cache", getClass().getClassLoader());
 92      // Get Stock object from cache
 93      Stock s = (Stock) cache.get("ORCL");
 94      double price = 0;
 95      if (s != null)
 96      {
 97        price = s.getPrice();
 98      }
 99      // Output stock price in response
100      out.println("<p>The latest Oracle Stock Price is: <b>" + price +
101                  "</b></p>");
102      out.println("</body></html>");
103      out.close();
104    }

The other source file that needs to be deployed with the Servlet is the Stock object that is being cached – a separate Java application is used in this scenario to add a Stock object to the “stock-cache” and then continually update it. This means that if the content displayed by the Servlet is refreshed in a browser a new stock price will appear.

Packaging it all up

To package it all up you naturally wrap the Servlet and Stock classes – along with the Coherence configuration files and supporting web configuration files – in a WAR file. This WAR file then needs to be wrapped in an EAR file with the coherence.jar file and a reference to this JAR in the MANIFEST.MF file as follows:

Class-Path: lib/coherence.jar

Note in the Eclipse project the coherence.jar file is in the base dir of the EAR file. The complete structure of the EAR file is shown below:

When the application is deployed and run you should see something like this which if you keep refreshing should change.

Summary

That’s it. You should now be able to create a cache, put some data into it and then access it from the above Servlet. The full source code for this example can be found here. There is a JDeveloper 11g project and an Eclipse Eurpoa project. There are some batch files to run-up a cache server and a separate client to insert and update Stock data, but unfortunately they are only in JDeveloper project – at the moment. See the readme.txt file for details of how to set things up.

The screen shot of the demonstration shows how a constantly updating graph (shown below) of stock price information can be displayed in Excel. The data which is constantly changing, in this case stock prices, is held in a Coherence cache. A separate client application is changing the stock prices and these changes in the data cache are then being pushed to the .NET Coherence client (RTD Server) and on to the Excel spreadsheet.

The RTD Server is a C# .NET client packaged as an .NET Assembly/DLL and then registered as a COM object. The example in the demonstration is pretty flexible but the next version will be enhanced to provide a great range of filtering.

Now the example being shown in the demonstration is a first cut (developed with help from Aleksandar Seovic). An improved version will be published very soon with a fuller explanation about it works along with the code itself.