Advanced Techniques - Polling

General

This workshop demonstrates how you can deliberately replace the content of a page in just a few minutes using the Intrexx polling mechanism - and only when this is actually required. It is aimed at readers with some programming experience. It is a common requirement that parts of a page (e.g. one or more tables) should be updated when changes are made to the underlying data records. This is especially the case when these are pages that are shown on shop floors, for example: and many other cases of application. The function is required when the portal is not directly operated by employees but when a highly-visible screen needs to be refreshed automatically. Developers usually take the approach of reloading the entire displayed page with all of its elements in these cases. However, this increases the server workload unnecessarily because some content doesn't always need to be reloaded. This approach can lead to long and increased loading times for many procedures.

Example files

The example files "70-test-polling.xml" (Spring configuration) and "Polling-Sample.zip" (application and process) can be downloaded here.

Functionality

Intrexx provides a functionality that enables a number to be queried on the server. This number is connected to a key.

Example: "testKey": 15

When a data record is changed and you want to force a refresh, you can increase this number using an Intrexx process. The browser page requests this value at a predefined interval. As soon as the value changes, the polling mechanism calls up a function defined by you. Here is the sequence:

"testKey": 15 -> Change to data record triggers the event -> Process responds and changes the value: "testKey": 16 -> Polling is triggered: Content is reloaded

The advantage of this method is that the request of the polling endpoint only takes about 4-5 milliseconds. However, reloading the entire page would take much longer - up to 100 times longer with a lot of content.

Implementation

Definition of the polling endpoint

The polling endpoint is a Java class with the name "JsonUsnPollingEndpoint". It has the property of returning the value to the client in a JSON structure. So that this can be available under its key, it must be made known with a specific Spring Bean. Proceed as follows:
  1. Create a file with a name (as unique as possible) in the portal directory internal/cfg/spring (e.g. 77-mytestpolling.xml). "77" defines the sorting order that the configurations are loaded in. This is insignificant in the case of polling.
  2. Copy the following content into this file:
    <?xml version="1.0" encoding="UTF-8"?> 
    <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
    
    <!-- Polling endpoint configuration --> 
    	<bean class="de.uplanet.lucy.server.polling.PollingEndpointConfigurator">
    		<property name="endpointName" value="testKey" />
    		<property name="endpoint">
    			<bean class="de.uplanet.lucy.server.polling.JsonUsnPollingEndpoint" /> 
    		</property> 
    	</bean>
    </beans>
  3. Save the file.
  4. Restart the portal service so that the new polling endpoint is active.

Increase the value in the polling endpoint via a process

Proceed as follows:

Polling JavaScript in the application

Now the following JavaScript needs to be added to your application for the polling. The page that should be refreshed needs to call the function "startPolling()" in the onLoad event. The function stopPolling() needs to be called in the onUnload event. The developer's task is to bring the checkReload() function to life. Currently, only a notification will be shown in the browser when a change has been made.
/** 
* Called in the onLoad of the page
* Initializes the polling mechanism
* key: This value ("testKey" in the example) is initially set and needs to 
* be defined in the Bean properties. The implemented polling endpoint will then
* be checked accordingly. 
* success (optional): If the value is different, the method checkReload()
* is called.
* error(optional): If errors occur while reading the value from the endpoint,
* the method errorOnPolling() is called in this example.
* id: The polling works internally with this subscriber ID. In this way,
* multiple polling queries with different subscriber IDs can be started
* for an identical key.
* Furthermore, it is also possible to adjust the polling interval dynamically
*(e.g. small changes: slower)
* millisec: Polling interval in millseconds, 5000 in this example
* @method startPolling
*/ 

function startPolling()
{ 
	registerAjaxPolling({ 
		key: "testKey", 
		success: function(){ 
			checkReload(); 
		}, 
		error: function(){
			errorOnPolling(); 
		},
		id: "testId",
		millisec: 5000 
	}); 
}

/** 
* Stops the polling and should always be called in the onUnload of a page
* @method stopPolling 
*/ 

function stopPolling()
{ 
	unregisterAjaxPolling("testKey", "testId"); 
} 

// In the example application, the table on the "All Entries" page will be reloaded

function checkReload()

{ 
	alert("Page should be reloaded."); 
	return true; 
} 

// A notification window is shown when an error occurs.

function errorOnPolling()
{ 
	Notifier.status.notify("Text: Error on retrieving reload information", "Title: Polling", "ID: MyId"); 
}
Polling should always be used sparingly because it adds to the server workload. Choose your intervals carefully.