com.nexaweb.server.pushconnection
Interface FlushPolicy

All Known Subinterfaces:

ConfigurableFlushPolicy

public interface FlushPolicy

A FlushPolicy may introspect the content flowing over a PushConnection and may flush the stream to ensure delivery of the content. Different policies may be applied to different sessions' connections based on the configuration specified in the application's nexaweb-client.xml file, or it may be set through the API. Some implementations of FlushPolicy are provided, or you may write your own.

Use of FlushPolicy is not required.

Feature Motivation

Many users of Nexaweb Applications will be in a corporate environment behind a firewall and browsing the web through an HTTP proxy server. When a Nexaweb Application's users are not internal to the corporate entity that deployed it, it is often the case that the deploying entity has no control over the proxy servers their customers use. HTTP proxy servers are generally designed to serve request / response cycles. Therefore some proxy servers do not handle responses on a persistent HTTP connection properly, buffering content until either the buffer is full, or the response stream is closed. This can cause messages sent over Nexaweb server push connections to be hung up in the proxy server, either delaying delivery to the client or stopping delivery altogether. Since this is a bug in the way proxy servers buffer content and not a bug in Nexaweb software, the most appropriate and recommended way to deal with this bug is to change proxy servers altogether or if the buffering of content is configurable to configure your proxy server so that it does not buffer response content. However, since our customers often don't have control over the proxy servers of their customers, FlushPolicies are provided as a configurable workaround for this problem.

How Flushing Works

In order to push content through the network buffer, a large whitespace message is sent down the connection after the real content. This whitespace content displaces the real content in the buffer, causing it to be delivered to the client. When the client receives flush messages, they are ignored. The size of this whitespace message is determined by the getFlushSizeInBytes() method. When the connection is flushed is determined by the policy. The policy will be notified when something is sent over the connection, it may call the Flushable.flush() whenever it likes.

Determining which policy to use and configuring it will require knowing something about your application's use of the PushConnection and the size of the network buffer you're trying to flush content through. A profile of PushConnection use can be obtained from the ConnectionStatistics object available from the PushConnection.getConnectionStatistics() method. Unfortunately, it is not possible for Nexaweb server to detect the size of any possible network buffers between the server and its clients. You must obtain that information on your own.

Configuring Provided Policies

Here is the sequence of steps to select a flush policy:

1. Nexaweb Server matches the client profile against available session configurations defined in the webapp's nexaweb-client.xml or the server-wide nexaweb-client.xml files under <session-configurations> sections.
2. Once the matching session configuration is found (default configuration specified within the <default-session-configuration> section is used when there are no matching session configurations) Nexaweb Server extracts the <push-connection-flush-policies> element defined within that configuration. If none defined, the element is taken from the first <default-session-configuration> that contains it. The order of lookup is: webapp's nexaweb-client.xml, server-wide nexaweb-client.xml.
3. Each policy defined in the retrieved <push-connection-flush-policies> element is matched against the client profile in order in which the policies appear within the extracted flush policies element.
4. The first policy that matches is used for the client's push connection, the rest is ignored.

Nexaweb provides several flush policies as part of the default session configuration of your nexaweb-client.xml file. If the client does not match any session configurations or the matching configuration does not specify any policies, these policies will be available.

Important! If you define a <push-connection-flush-policies> block within your custom lt;session-configuration> section only the flush policies defined there will be available for the client that matches your session configuration, i.e. it will not inherit flush policies defined in the default session configuration. The default policies are only available if you completely omit <push-connection-flush-policies> element from your session configuration.

The syntax for the match rules used to match clients against defined session configurations and flush policies is the same. In order for a session configuration or a flush policy to match, each <match> expression specified within the <rules> element must evaluate to a boolean true. The <match> element supports ONE of two attributes:

• xpath - Evaluated as boolean against sessions' ClientInfo XML document.
• address - An IPv4 address that the open push connection must come from in order to have this policy applied. Wildcards are supported in each part, as the whole part only. The wildcard character is '*'. All four parts of the IPv4 address must be present.

Only one element with the 'address' attribute is supported per policy. If more than one element with the 'address' attribute is present, only the first one will be used.

Example ClientInfo XML

 
    <client-info>                                                                
       <client-version>Nexaweb Platform v4.1</client-version> 
       <java-version>1.4.2</java-version>                                        
       <java-vendor>Sun Microsystems Inc.</java-vendor>                          
       <os>Windows XP</os>                                                       
       <os-version>5.1</os-version>                                              
       <browser>sun.plugin</browser>                                             
       <architecture>x86</architecture>                                          
       <user-agent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT )</user-agent>  
       <screen-size>1600,1200</screen-size>                                      
       <locale>en,US,</locale>                                                   
       <is-connection-secure>false</is-connection-secure>                                                   
    </client-info>                                                               
 

Example Configuration

   <session-configurations>
      <session-configuration>
          <rules>
              <match xpath="starts-with(/client-info/java-version, '1.4')" />
          </rules>       
          
          <push-connection-flush-policies>
              <policy>
                  <rules>
                      <match xpath="starts-with(/client-info/java-version, '1.4')" />
                      <match xpath="starts-with(/client-info/java-vendor, 'Sun')" />
                      <match xpath="contains(/client-info/user-agent, 'MSIE 6')" />
                      <match address="127.0.0.*" />
                  </rules>		 
                  <configuration class="com.nexaweb.server.pushconnection.flushpolicies.IdlePeriodFlushPolicy">
                      <flush-size>8 K</flush-size>
                      <period>10 sec.</period>
                  </configuration>
              </policy>
          </push-connection-flush-policies>
      </session-configuration>
   </session-configurations>
 

In the above example we defined one custom session configuration for clients who are running jvm version 1.4. All clients with that jvm will match this session configuration. Since the session configuration defines the flush policies block only these policies are available for clients with jvm 1.4. Here we defined only one policy which narrows down further the client profile that should use this flush policy. You could omit the rules for the flush policy in which case it simply inherits the rules of the enclosing session configuration.

Nexaweb provides the following policies.

• IdlePeriodFlushPolicy
• IdlePeriodWithSizeThresholdFlushPolicy
• ThroughputFlushPolicy

Since:

4.0

See Also:

ClientInfo, PushConnection

Method Summary

int	getFlushSizeInBytes() Returns the number of bytes that should be used to flush data on the connection.
boolean	isStreamClosedOnFlush() Returns true if the content should be flushed by closing the stream instead of writing bytes down the stream.
void	onMessageSend(Flushable flushableConnection, byte[] content) This method will be called by the Nexaweb Server as notification that a message was sent down the push connection.

Method Detail

getFlushSizeInBytes

public int getFlushSizeInBytes()

Returns the number of bytes that should be used to flush data on the connection. This method is only called if the isStreamClosedOnFlush() method returns false. If this method is called, it is called only once, when the policy is set on a PushConnection. The number of bytes returned should be equal to the number of bytes in the buffer between the server and client.

Returns:

The number of bytes to use when flushing the push connection.

Since:

4.0

isStreamClosedOnFlush

public boolean isStreamClosedOnFlush()

Returns true if the content should be flushed by closing the stream instead of writing bytes down the stream.

Returns:

A boolean value of true indicates that calling Flushable.flush() will flush by closing the stream. False indicates that whitespace bytes should be written behind the content to flush the content.

Since:

4.1

onMessageSend

public void onMessageSend(Flushable flushableConnection,
                          byte[] content)
                   throws java.io.IOException

This method will be called by the Nexaweb Server as notification that a message was sent down the push connection. Implementors should take care to return from this method as quickly as possible. Note that a many logical messages (calls to com.nexaweb.server.messaging.MessagingService.publish() or com.nexaweb.server.messaging.MessagingService.send() as well as many DOM changes) may be encapsulated in one physical message.

Parameters:

flushableConnection - The Flushable PushConnection to which the message was sent.

content - The content that was sent a String in UTF-8 encoding.

Throws:

java.io.IOException

Since:

4.0