svn commit: r1857118 - /mina/site/trunk/content/mina-project/userguide/ch5-filters/ch5.3-compression-filter.mdtext

[el...@apache.org]

Author: elecharny
Date: Mon Apr  8 15:52:58 2019
New Revision: 1857118

URL: http://svn.apache.org/viewvc?rev=1857118&view=rev
Log:
Update the compression filter documentation

Modified:
    mina/site/trunk/content/mina-project/userguide/ch5-filters/ch5.3-compression-filter.mdtext

Modified: mina/site/trunk/content/mina-project/userguide/ch5-filters/ch5.3-compression-filter.mdtext
URL: http://svn.apache.org/viewvc/mina/site/trunk/content/mina-project/userguide/ch5-filters/ch5.3-compression-filter.mdtext?rev=1857118&r1=1857117&r2=1857118&view=diff
==============================================================================
--- mina/site/trunk/content/mina-project/userguide/ch5-filters/ch5.3-compression-filter.mdtext (original)
+++ mina/site/trunk/content/mina-project/userguide/ch5-filters/ch5.3-compression-filter.mdtext Mon Apr  8 15:52:58 2019
@@ -24,4 +24,30 @@ Notice:    Licensed to the Apache Softwa
 
 # 5.3 - Compression Filter
 
-TBD...
\ No newline at end of file
+The _CompressionFilter_ class is used to compress data before it gets sent and decompress it when it's received. It uses the [JZLIB library](http://www.jcraft.com/jzlib/).
+
+It only handles two events :
+
+* _messageReceived_: The received message will be decompressed, if it's contained in a _IoBuffer_.
+* _filterWrite_: The message to write will be compressed, assuming it's storeed in a _IoBuffer_ (otherwise an exception will be generated).
+
+## Configuration
+
+It's possible to configure the _CompressionFilter_, with the listed parameters :
+
+* _compressInbound_: if set to _true_, the incoming data will be decompressed, otherwise they will be left intact.
+* _compressOutbound_: if set to _true_, the outgoing data will be compressed, otherwise they will be ignored.
+* _compressionLevel_: one of _COMPRESSION_DEFAULT_ (-1), _COMPRESSION_MAX_ (9), _COMPRESSION_MIN_ (1), _COMPRESSION_NONE_ (0). Sets the level, of desired compression.
+
+There is one more parameter that can be used, injected into the session's attributes, the _DISABLE_COMPRESSION_ONCE_ flag. If present in the session's attributes, the first compression will be ignored (this is probably useful for application that needs to send a message that the floowing messages are going to be compressed).
+
+## Initialization
+
+When the filter is added to the chain, instances of the deflater and inflater are created and injected into the session's attributes. This could change, as each session has its own instance of the filter in its chain, so there is no reason not to store those instances in the filter itself.
+
+
+## Side notes
+
+The way this filter works does not lmake it very efficient. It requires that the received data to be decompressed are fully read - and there are no control that it's the case of not -, and it also requires that the data to be compressed be fully compressed in one pass, which is quite inneficient from the memory perspective, as we may compress data by blocks, and send them immediately, waiting for the block to be really sent to compress the next one.
+
+All in all, it's a brittle filter, you'd better not use it !
\ No newline at end of file