Package com.tailf.maapi

Class MaapiCursor

Object
com.tailf.maapi.MaapiCursor
All Implemented Interfaces:
AutoCloseable
public class MaapiCursor extends Object implements AutoCloseable
A cursor for iterating over configuration data elements.

MaapiCursor provides an efficient mechanism for traversing objects in the XML tree. The cursor maintains server-side state and supports filtered iteration using XPath expressions.

Basic Usage

Cursors are created via Maapi.newCursor(int, String, Object...) and used with Maapi.getNext(MaapiCursor) for iteration.

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 code which iterates over all 'server' instances. 

 try (MaapiCursor cursor = maapi.newCursor(th,
         "/mtest:mtest/servers/server")) {
     ConfKey key = maapi.getNext(cursor);
     while (key != null) {
         // Process the key
         key = maapi.getNext(cursor);
     }
 }

Filtered Iteration

Cursors support XPath filtering for efficient data selection: 


 try (MaapiCursor cursor = maapi.newCursorWithFilter(th,
         "starts-with(ip, \"10.\") and port > 8000",
         "/servers/server")) {
     // Only servers matching the filter will be returned
     ConfKey key = maapi.getNext(cursor);
     // ...
 }

Performance Optimization

For large datasets, secondary indexes can be configured using setSecondaryIndex(String) to improve iteration performance.

Resource Management

Cursors maintain server-side resources that are automatically cleaned up when:

  • The cursor is explicitly closed via close()
  • The transaction completes
  • There is no reference to the cursor

Important: For optimal resource utilization, especially in long-running transactions or when creating many cursors, use try-with-resources or explicitly call close() when done.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Destroy the cursor on the server side.
    void
    destroy()
    Deprecated.
    Use close() instead.
    String
    getFilter()
    Returns the XPath filter expression used to constrain cursor iteration.
    int
    getId()
    Returns the unique cursor identifier assigned by the server.
    ConfPath
    getPath()
    Returns the configuration path associated with this cursor.
    ConfEObject
    getPrev()
    Returns the previous element retrieved during cursor iteration.
    String
    getSecondaryIndex()
    Returns the name of the currently configured secondary index.
    int
    getTid()
    Returns the transaction identifier associated with this cursor.
    void
    setPrev(ConfEObject prev)
    Sets the previous element for cursor iteration tracking.
    void
    setSecondaryIndex(String idx)
    Configures a secondary index for optimized cursor iteration.
    String
    toString()
    Returns a string representation of this cursor for debugging purposes.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • getPrev

      public ConfEObject getPrev()
      Returns the previous element retrieved during cursor iteration.
      Returns:
      the previous ConfEObject, or "first" if no iteration has occurred

    • getPath

      public ConfPath getPath()
      Returns the configuration path associated with this cursor.
      Returns:
      the ConfPath representing the cursor's location in the configuration tree

    • getTid

      public int getTid()
      Returns the transaction identifier associated with this cursor.
      Returns:
      the transaction handle used for this cursor

    • getId

      public int getId()
      Returns the unique cursor identifier assigned by the server.
      Returns:
      the cursor identifier

    • setPrev

      public void setPrev(ConfEObject prev)
      Sets the previous element for cursor iteration tracking.
      Parameters:
      prev - the ConfEObject to set as the previous element

    • setSecondaryIndex

      public void setSecondaryIndex(String idx)
      Configures a secondary index for optimized cursor iteration. Secondary indexes can improve performance when iterating over large datasets.
      Parameters:
      idx - the name of the secondary index to use for getNext() calls

    • getSecondaryIndex

      public String getSecondaryIndex()
      Returns the name of the currently configured secondary index.
      Returns:
      the secondary index name, or null if none is configured

    • toString

      public String toString()
      Returns a string representation of this cursor for debugging purposes.
      Overrides:
      toString in class Object
      Returns:
      a formatted string containing cursor details including transaction ID, cursor ID, path, and previous element

    • getFilter

      public String getFilter()
      Returns the XPath filter expression used to constrain cursor iteration.
      Returns:
      the XPath filter string, or null if no filter is applied

    • destroy

      @Deprecated public void destroy()
      Deprecated.
      Use close() instead.
      Destroys the cursor and releases server-side resources.

    • close

      public void close()

      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.

      Specified by:
      close in interface AutoCloseable