com.tailf.maapi

Class MaapiCursor

Object

com.tailf.maapi.MaapiCursor

public class MaapiCursor
extends Object

Whenever we wish to iterate over a set of objects in the XML tree, we must first initialize a cursor. The cursor is subsequently used in a while loop.

For example if we have:

 module mtest {
   namespace "http://tail-f.com/test/mtest/1.0";
   prefix mtest;

   import ietf-inet-types {
     prefix inet;
   }
   import tailf-common {
     prefix tailf;
   }

   container mtest {
     container servers {
       list server {
         key name;
         max-elements 64;
         leaf name {
           type string;
         }
         leaf ip {
           type inet:host;
           mandatory true;
         }
         leaf port {
           type inet:port-number;
           default 80;
         }
         list interface {
           key name;
           max-elements 8;
           leaf name {
             type string;
           }
           leaf mtu {
             type int64;
             default 1500;
           }
         }
       }
     }
   }
 }
 

We can have the following Java code which iterates over all 'server' instances.

 MaapiCursor c;
 ConfKey x;

 c = maapi.newCursor(th, "/mtest:mtest/servers/server");

 x = maapi.getNext(c);
 while (x != null) {
     // do something
     x = maapi.getNext(c);
 }
 

A cursor can also be created with an XPath filter:

 MaapiCursor c =
     maapi.newCursorWithFilter(th,
                               "starts-with(ip, \"10.\") and port > 8000",
                               "/mtest:mtest/servers/server");

See Also:

Maapi.getNext(MaapiCursor)

Method Summary

Modifier and Type	Method and Description
void	destroy() Destroy the cursor on the server side.
String	getFilter() Return the XPath filter for this cursor, or null if there is none.
int	getId()
ConfPath	getPath()
ConfEObject	getPrev()
String	getSecondaryIndex() Return the name of the specified secondary index (if any).
int	getTid()
void	setPrev(ConfEObject prev)
void	setSecondaryIndex(String idx) Makes it possible to use a secondary index for the getNext calls.
String	toString()

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getPrev

public ConfEObject getPrev()

getPath

public ConfPath getPath()

getTid

public int getTid()

getId

public int getId()

setPrev

public void setPrev(ConfEObject prev)

setSecondaryIndex

public void setSecondaryIndex(String idx)

Makes it possible to use a secondary index for the getNext calls.

Parameters:

idx - Secondary index name

getSecondaryIndex

public String getSecondaryIndex()

Return the name of the specified secondary index (if any).

toString

public String toString()

Overrides:

toString in class Object

getFilter

public String getFilter()

Return the XPath filter for this cursor, or null if there is none.

Returns:

XPath filter for this cursor

destroy

public void destroy()

Destroy the cursor on the server side.

There is normally no need to call this method. Only call it if the use pattern below feels familiar.

If iteration is ended before all results have been fetched the cursor will still be held on to on the server side since it cannot know that we are done using the cursor.

The cursor will be cleaned up on the server side when the transaction is finished or the MaapiCursor is garbage collected.

But, if the transaction is kept open and we create new cursors over and over again or perhaps keep them in a list, preventing them from being garbage collected, they will still be present on the server side if not iterated to the end, effectively creating a resource leak.

Calling this function explicitly cleans up resources on the server.