org.xmlBlaster.contrib.mime
Class DropIfNotDeliverableUniqueOnly

java.lang.Object
  org.xmlBlaster.contrib.mime.DropIfNotDeliverableUniqueOnly

All Implemented Interfaces:

org.xmlBlaster.engine.mime.I_AccessFilter, org.xmlBlaster.util.dispatch.I_ConnectionStatusListener, org.xmlBlaster.util.plugin.I_Plugin

public class DropIfNotDeliverableUniqueOnly
extends java.lang.Object
implements org.xmlBlaster.util.plugin.I_Plugin, org.xmlBlaster.engine.mime.I_AccessFilter, org.xmlBlaster.util.dispatch.I_ConnectionStatusListener

Sometimes we need to support this subscribe pattern: A client only wants the newest message with this details:

 - Initial connect and subscribe: send current newest (or given history depth)
 - If it is online it is a normal subscription
 - If it is offline don't add messages to callback queue
 - If it comes online again check if current message was delivered,
   if not send it initially (if redeliverNewestOnReconnect==false which is default; else on reconnect the newest is always send. Note: You can't use both variants simultaneously as it operates on the session Map)
 

If a client callback goes to polling, this plugin removes all existing subscriptions. The client needs to add a filter Qos to its SubscribeQos to activate the plugin.
and needs to re-subscribe on relogin if desired.

The message uniqueness is checked per topic, but if you pass a client property "_uniqueGroupId" this is used to check uniqueness: Messages with the same "_uniqueGroupId" value are compared to decide if delivered already. This is like a sub-group of the topic and is for your convenience only as it could be solved by having a separate topic for each "_uniqueGroupId".

This makes only sense if the client is operating in fail save mode (-dispatch/callback/retries -1) and reconnects with the same publicSessionId > 0 (-session.name jack/session/1) so that its session is found again.

Configuration example (put to xmlBlaster.properties):

 MimeAccessPlugin[DropIfNotDeliverableUniqueOnly][1.0]=\
   org.xmlBlaster.contrib.mime.DropIfNotDeliverableUniqueOnly,dropper.types=*,uniqueGroupIdKeyName=_myuniqueGroupId
 

dropper.types=* is default and activates the plugin for any published message where a subscriber has set this filter,
dropper.types=text/xml;application/xml would for example limit the plugin to such messages having his mime type declared on publish

A typical subscribeQos is for example:

<qos>
   <multiSubscribe>false</multiSubscribe>
   <local>false</local>
   <initialUpdate>false</initialUpdate>
   <updateOneway>false</updateOneway>
   <notify>false</notify>
   <persistent>false</persistent>
   <filter type='DropIfNotDeliverableUniqueOnly'>
    <![CDATA[_]]>
   </filter>
</qos>
  

The query statement '_' is ignored by this plugin.

This plugin is a singleton and loaded once only for multiple subscribers configuring it

Example to try on command line

  export CLASSPATH=$XMLBLASTER_HOME/lib/xmlBlaster.jar
  
  Start the server:
    java org.xmlBlaster.Main
 
  Start a sniffer GUI to see what happens:
    cd ~/xmlBlaster
    build SimpleReader
    
  Start the subscriber which wants the newest and unique message only:
    java javaclients.HelloWorldSubscribe -session.name subscriber/session/1 -disconnect false -multiSubscribe false -initialUpdate true -unSubscribe false -dispatch/callback/retries -1 -filter.type DropIfNotDeliverableUniqueOnly -filter.query _
    (Avoid disconnect as it cleans up the session)
    (example to get first ten of history: -historyNumUpdates 10 -historyNewestFirst false)
  
  Start the publisher for two groupIds:
    java javaclients.HelloWorldPublish -clientProperty[_uniqueGroupId] weather.south




Author:
  
Marcel Ruff
See Also:
The mime.plugin.accessfilter requirement






Field Summary




static java.lang.String
MIME_TYPES



           


 



Constructor Summary
DropIfNotDeliverableUniqueOnly()



           
 



Method Summary




 java.lang.String[]
getMimeExtended()



          Get the content MIME version number for which this plugin applies



 java.lang.String[]
getMimeTypes()



          Get the content MIME type for which this plugin applies,
 currently { "*" }.



 java.lang.String
getName()



          Get a human readable name of this filter implementation



 java.lang.String
getType()



          Return plugin type for Plugin loader



 java.lang.String
getVersion()



          Return plugin version for Plugin loader



 void
init(org.xmlBlaster.util.Global glob,
     org.xmlBlaster.util.plugin.PluginInfo pluginInfo)



          This method is called by the PluginManager (enforced by I_Plugin).



 void
initialize(org.xmlBlaster.engine.ServerScope serverScope)



          This is called after instantiation of the plugin



 boolean
match(org.xmlBlaster.authentication.SessionInfo receiver,
      org.xmlBlaster.util.MsgUnit msgUnit,
      org.xmlBlaster.engine.mime.Query query)



          Check if the filter rule matches for this message.



 void
shutdown()



          Cleans up the resource.



 void
toAlive(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
        org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState)



           



 void
toAliveSync(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
            org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState)



           



 void
toDead(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
       org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState,
       org.xmlBlaster.util.XmlBlasterException xmlBlasterException)



           



 void
toPolling(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
          org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState)



           


 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 





Field Detail



MIME_TYPES
public static final java.lang.String MIME_TYPES


See Also:
Constant Field Values





Constructor Detail



DropIfNotDeliverableUniqueOnly
public DropIfNotDeliverableUniqueOnly()






Method Detail



initialize
public void initialize(org.xmlBlaster.engine.ServerScope serverScope)

This is called after instantiation of the plugin


Specified by:
initialize in interface org.xmlBlaster.engine.mime.I_AccessFilter


Parameters:
glob - The Global handle of this xmlBlaster server instance.





init
public void init(org.xmlBlaster.util.Global glob,
                 org.xmlBlaster.util.plugin.PluginInfo pluginInfo)
          throws org.xmlBlaster.util.XmlBlasterException

This method is called by the PluginManager (enforced by I_Plugin).


Specified by:
init in interface org.xmlBlaster.util.plugin.I_Plugin



Throws:
org.xmlBlaster.util.XmlBlasterException
See Also:
I_Plugin.init(org.xmlBlaster.util.Global,org.xmlBlaster.util.plugin.PluginInfo)





getType
public java.lang.String getType()

Return plugin type for Plugin loader


Specified by:
getType in interface org.xmlBlaster.util.plugin.I_Plugin



Returns:
"DropIfNotDeliverableUniqueOnly"





getVersion
public java.lang.String getVersion()

Return plugin version for Plugin loader


Specified by:
getVersion in interface org.xmlBlaster.util.plugin.I_Plugin



Returns:
"1.0"





getName
public java.lang.String getName()

Get a human readable name of this filter implementation


Specified by:
getName in interface org.xmlBlaster.engine.mime.I_AccessFilter



Returns:
"DropIfNotDeliverableUniqueOnly"





getMimeTypes
public java.lang.String[] getMimeTypes()

Get the content MIME type for which this plugin applies,
 currently { "*" }.
 Is configurable with
 dropper.types=text/xml;image/svg+xml;application/xml


Specified by:
getMimeTypes in interface org.xmlBlaster.engine.mime.I_AccessFilter



Returns:
{ "*" } This plugin handles all mime types





getMimeExtended
public java.lang.String[] getMimeExtended()

Get the content MIME version number for which this plugin applies


Specified by:
getMimeExtended in interface org.xmlBlaster.engine.mime.I_AccessFilter



Returns:
"1.0" (this is the default version number)





match
public boolean match(org.xmlBlaster.authentication.SessionInfo receiver,
                     org.xmlBlaster.util.MsgUnit msgUnit,
                     org.xmlBlaster.engine.mime.Query query)
              throws org.xmlBlaster.util.XmlBlasterException

Description copied from interface: org.xmlBlaster.engine.mime.I_AccessFilter
Check if the filter rule matches for this message. 
 

 Note that you are not allowed to manipulate the content or XmlKey or QoS of a message with your plugin
 as this would affect all other subscribers (you are working on a reference to the
 original message).
 You can find out the publisher name like msgUnit.getQosData().getSender()
 


Specified by:
match in interface org.xmlBlaster.engine.mime.I_AccessFilter


Parameters:
receiver - The session object describing the receiver, is never null.
msgUnit - The message to check, is never null.
query - The query containing the filter rule on subscribe/get usually
                the client defines his own rule which is passed here.

                null: If for a subscribe() or get() no rule is given, your plugin
                      needs to have its own general rule or react how it likes.

                Access the raw query string with query.getQuery(), you can parse it
                and store the prepared query with query.setPreparedQuery() - query.getPreparedQuery()
                to increase performance.
Returns:
true If the filter matches this message, else false
Throws:
org.xmlBlaster.util.XmlBlasterException - Is thrown on problems, for example if the MIME type
            does not fit to message content.

            Take care throwing an exception, the message is not updated and an error is logged
            and the message is sent as dead letter.
            (see TopicHandler.java:1032).
            It is best to return 'false' instead and handle the situation yourself.





shutdown
public void shutdown()

Description copied from interface: org.xmlBlaster.util.plugin.I_Plugin
Cleans up the resource.


Specified by:
shutdown in interface org.xmlBlaster.engine.mime.I_AccessFilter
Specified by:
shutdown in interface org.xmlBlaster.util.plugin.I_Plugin








toAlive
public void toAlive(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
                    org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState)


Specified by:
toAlive in interface org.xmlBlaster.util.dispatch.I_ConnectionStatusListener








toAliveSync
public void toAliveSync(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
                        org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState)


Specified by:
toAliveSync in interface org.xmlBlaster.util.dispatch.I_ConnectionStatusListener








toDead
public void toDead(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
                   org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState,
                   org.xmlBlaster.util.XmlBlasterException xmlBlasterException)


Specified by:
toDead in interface org.xmlBlaster.util.dispatch.I_ConnectionStatusListener


xmlBlasterException - Can be null





toPolling
public void toPolling(org.xmlBlaster.util.dispatch.I_DispatchManager dispatchManager,
                      org.xmlBlaster.util.dispatch.ConnectionStateEnum oldState)


Specified by:
toPolling in interface org.xmlBlaster.util.dispatch.I_ConnectionStatusListener