XmlBlaster Logo

REQUIREMENT

interface.erase

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic Messages are deleted with the erase() method
Des
cription

The erase() method allows to erase messages in xmlBlaster.

Method detail (CORBA IDL notation): 

   typedef string XmlType;
   typedef sequence<string> StringArr;

   StringArr erase(in XmlType xmlKey, in XmlType qos) raises(XmlBlasterException);
ParameterTypeDescription
xmlKeystringThe XML encoded key containing the oid or XPATH query to select messages to erase
xmlQosstringThe XML encoded Quality of Service (QoS)
returnarray of stringAn array of XML encoded strings containing status and the deleted messages (see EraseReturnQos link below)
XmlBlasterExceptionexceptionThrown on error

Here is an overview of all available erase QoS: 

<qos>
   <!-- Kill a topic even if there are pending updates or subscriptions (default: false) -->
   <erase forceDestroy='true'/>
</qos>
Example
XML

Here is an example key and QoS with its default settings:

Key<key oid='MyTopic'/>
QoS<qos> <erase forceDestroy='false'/> </qos>

and a example where the topic with its subscribers remain and only all message instances inside the topic are destroyed:

Key<key oid='MyTopic'/>
QoS<qos> <erase forceDestroy='false'> <history numEntries='-1'/> </erase> </qos>

And a return value: 

<qos>
   <state id='OK'/>
   <key oid='MyTopic'/>
</qos>

Note that erasing a topic sends to all subscribers an update with the update QoS state id set to ERASED, see HelloWorld4.java as an example.
Constants.java defines the ERASED state and other states. This setting defaults to true. Here is a typical QoS markup received in the update() method: 

<qos>
  <state id='ERASED'/>
  <sender>/node/heron/client/subby/3</sender>
  <subscribe id='__subId:heron-7'/>
</qos>

A subscriber can decide to suppress those erase events with a specific SubscribeQoS setting.

The forceDestroy setting influences the life cycle of messages in this topic, please have a look into the message state chart in the engine.message.lifecycle requirement. This setting defaults to false.

Example
XML

Here is an example erasing multiple topics identified by an XPath query:

Key<key queryType='XPATH'>//key</key>
QoS<qos> <erase forceDestroy='true'/> </qos>

And a returned QoS array: 

<qos>
   <state id='OK'/>
   <key oid='__sys__UserList'/>
   <isErase/>
</qos>'
<qos>
   <state id='OK'/>
   <key oid='__sys__Logout'/>
   <isErase/>
</qos>'
<qos>
   <state id='OK'/>
   <key oid='__sys__Login'/>
   <isErase/>
</qos>'
<qos>
   <state id='OK'/>
   <key oid='HelloWorld'/>
   <isErase/>
</qos>'
Example
XmlRpc

This is the XmlRpc server interface variant: 

   public Vector erase(String sessionId, String xmlKey_literal, String qos_literal)
                                                         throws XmlBlasterException
Example
Java

A typical Java client code in Erase/Subscribe mode: 

   import org.xmlBlaster.client.key.SubscribeKey;
   import org.xmlBlaster.client.qos.*;
   ...

   EraseQos eq = new EraseQos(glob);

   EraseKey ek = new EraseKey(glob, "HelloWorld4");

   try {
      EraseReturnQos[] er = con.erase(ek.toXml(), eq.toXml());
   } catch(XmlBlasterException e) {
      e.printStackTrace();
   }

See xmlBlaster/demo/HelloWorld*.java for more examples.

Configure

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

See REQ interface
See REQ engine.message.lifecycle
See API org.xmlBlaster.engine.xml2java.XmlKey
See API org.xmlBlaster.client.qos.EraseQos
See API org.xmlBlaster.client.qos.EraseReturnQos
See API org.xmlBlaster.client.I_XmlBlasterAccess
See API org.xmlBlaster.protocol.xmlrpc.XmlBlasterImpl
See API org.xmlBlaster.util.def.Constants
See TEST org.xmlBlaster.test.qos.TestSubXPathMany
See TEST org.xmlBlaster.test.qos.TestErase
See TEST org.xmlBlaster.test.cluster.EraseTest
See TEST org.xmlBlaster.test.classtest.EraseReturnQosTest

This page is generated from the requirement XML file xmlBlaster/doc/requirements/interface.erase.xml

Back to overview