Working with Global Arrays

Glossary of Native SDK Terms

See the previous section for an overview of the concepts listed here. Examples in this glossary will refer to the global array structure listed below. The Legs global array has ten nodes and three node levels. Seven of the ten nodes contain values:

  Legs                       // root node, valueless, 3 child nodes
    fish = 0                 // level 1 node, value=0
    mammal                   // level 1 node, valueless
      human = 2              // level 2 node, value=2
      dog = 4                // level 2 node, value=4
    bug                      // level 1 node, valueless, 3 child nodes
      insect = 6             // level 2 node, value=6
      spider = 8             // level 2 node, value=8
      millipede = Diplopoda  // level 2 node, value="Diplopoda", 1 child node
        centipede = 100      // level 3 node, value=100

Global Naming Rules

Global names and subscripts obey the following rules:

• The length of a node address (totaling the length of the global name and all subscripts) can be up to 511 characters. (Some typed characters may count as more than one encoded character for this limit. For more information, see “Maximum Length of a Global Reference”).

• A global name can include letters, numbers, and periods ('.'), and can have a length of up to 31 significant characters. It must begin with a letter, and must not end with a period.

• A subscript can be a string or a number. String subscripts are case-sensitive and can use all characters (including control and non-printing characters). Length is limited only by the 511 character maximum for the total node address.

Creating Nodes and Setting Node Values

The set() and increment() methods can be used to create a persistent node with a specified value, or to change the value of an existing node.

IRIS.set() takes a value argument of any supported datatype and stores the value at the specified address. If no node exists at the target address, a new one is created.

Setting and changing node values

In the following example, the first call to set() creates a new node at subnode address myGlobal("A") and sets the value of the node to string "first". The second call changes the value of the subnode, replacing it with integer 1.

  irisjv.set("first", "myGlobal", "A");    // create node myGlobal("A") = "first"
  irisjv.set(1, "myGlobal", "A");  // change value of myGlobal("A") to 1.

set() can create and change values of any supported datatype. To read an existing value, you must use a different getter method for each datatype, as described in the next section.

IRIS.increment() takes a number argument, increments the node value by that amount, and returns the incremented value. The number argument can be Double, Integer, Long, or Short.

If there is no node at the target address, the method creates one and assigns the number argument as the value. This method uses a thread-safe atomic operation to change the value of the node, so the node is never locked.

Incrementing node values

In the following example, the first call to increment() creates new subnode myGlobal("B") with value -2. The next two calls each increment by -2, resulting in a final value of -6:

  for (int loop = 0; loop < 3; loop++) {
    irisjv.increment(-2,"myGlobal", "B");
  }

Getting Node Values

The set() method can be used with all supported datatypes, but each datatype requires a separate getter. Node values can be any of the following datatypes: Boolean, byte[], Double, Float, Integer, Long, Short, String, Date, Time, Timestamp, plus Object, IRISList, subclasses of java.io.InputStream and java.io.Reader, and objects that implement java.io.Serializable.

The following methods are used to retrieve node values of these datatypes:

• Numeric datatypes: getBoolean(), getShort(), getInteger(), getLong(), getDouble(), getFloat()

• String and Binary datatypes: getBytes(), getString()

• Object and $list datatypes: getObject(), getIRISList()

• Temporal datatypes: getDate(), getTime(), getTimestamp()

• Other datatypes: getInputStream(), getReader()

For more information on datatypes, see “Class IRIS Supported Datatypes” later in this chapter.

Deleting Nodes

IRIS.kill() deletes the specified node and all of its subnodes. The entire global array will be deleted if the root node is deleted, or if all nodes with values are deleted.

In the following example, global array myGlobal initially contains the following nodes:

   myGlobal = <valueless node>
     myGlobal("A") = 0
       myGlobal("A",1) = 0
       myGlobal("A",2) = 0
     myGlobal("B") = <valueless node>
       myGlobal("B",1) = 0

The example will delete the entire global array by calling kill() on two of its subnodes, myGlobal("A") and myGlobal("B",1).

Deleting a node or group of nodes

The first call will delete node myGlobal("A") and both of its subnodes:

  irisjv.kill("myGlobal", "A");
  // also kills child nodes myGlobal("A",1) and myGlobal("A",2)

The second call deletes myGlobal("B",1), the last remaining subnode with a value:

  irisjv.kill("myGlobal","B",1);

Since neither of the remaining nodes has a value, the entire global array is deleted:

• The parent node, myGlobal("B"), is deleted because it is valueless and now has no subnodes.

• Now root node myGlobal is valueless and has no subnodes, so the entire global array is deleted from the database.

Iterating Over a Set of Child Nodes

Child nodes are sets of subnodes immediately under the same parent node. Any child of the current target node can be addressed by adding only one subscript to the target address. All child nodes under the same parent are sibling nodes of each other. For example, the following global array has six sibling nodes under parent node ^myNames("people"):

  ^myNames                               (valueless root node)
     ^myNames("people")                  (valueless level 1 node)
        ^myNames("people","Anna") = 2    (first level 2 child node)
        ^myNames("people","Julia") = 4
        ^myNames("people","Misha") = 5
        ^myNames("people","Ruri") = 3
        ^myNames("people","Vlad") = 1
        ^myNames("people","Zorro") = -1  (this node will be deleted in example)

This section demonstrates the following methods:

• Methods used to create an iterator and traverse a set of child nodes

  • jdbc.IRIS.getIRISIterator() returns an instance of IRISIterator for the global starting at the specified node.

  • IRISIterator.next() returns the subscript for the next sibling node in collation order.

  • IRISIterator.hasNext() returns true if there is another sibling node in collation order.

• Methods that act on the current node

  • IRISIterator.getValue() returns the current node value.

  • IRISIterator.getSubscriptValue() returns the current subscript (same value as the last successful call to next()).

  • IRISIterator.remove() deletes the current node and all of its subnodes.

The following example iterates over each child node under ^myNames("people"). It prints the subscript and node value if the value is 0 or more, or deletes the node if the value is negative:

Finding all sibling nodes under ^myNames("people")

// Read child nodes in collation order while iter.hasNext() is true
  System.out.print("Iterate from first node:");
  try {
    IRISIterator iter = irisjv.getIRISIterator("myNames","people");
    while (iter.hasNext()) {
      iter.next();
      if ((Long)iter.getValue()>=0) {
        System.out.print(" \"" + iter.getSubscriptValue() + "\"=" + iter.getValue()); }
      else {
        iter.remove();
      }
    };
  } catch  (Exception e) {
    System.out.println( e.getMessage());
  }

• The call to getIRISIterator() creates iterator instance iter for the immediate children of ^myNames("people").

• Each iteration of the while loop performs the following actions:

  • next() determines the subscript of the next valid node in collation order and positions the iterator at that node. (In the first iteration, the subscript is "Anna" and the node value is 2).

  • If the node value returned by getValue() is negative, remove() is called to delete the node (including any subnodes. This is equivalent to calling kill() on the current node).

    Otherwise, getSubscriptValue() and getValue() are used to print the subscript and value of the current node.

• The while loop is terminated when hasNext() returns false, indicating that there are no more child nodes in this sequence.

This code prints the following line (element "Zorro" was not printed because its value was negative):

  Iterate from first node: "Anna"=2 "Julia"=4 "Misha"=5 "Ruri"=3 "Vlad"=1

This example is extremely simple, and would fail in several situations. What if we don’t want to start with the first or last node? What if the code attempts to get a value from a valueless node? What if the global array has data on more than one level? The following sections describe how to deal with these situations.

Finding Subnodes on All Levels

The next example will search a slightly more complex set of subnodes. We’ll add new child node "dogs" to ^myNames and use it as the target node for this example:

  ^myNames                                         (valueless root node)
     ^myNames("dogs")                              (valueless level 1 node)
        ^myNames("dogs","Balto") = 6
        ^myNames("dogs","Hachiko") = 8
        ^myNames("dogs","Lassie")                  (valueless level 2 node)
           ^myNames("dogs","Lassie","Timmy") = 10  (level 3 node)
        ^myNames("dogs","Whitefang") = 7
     ^myNames("people")                            (valueless level 1 node)
        [five child nodes]                         (as listed in previous example)

Target node ^myNames("dogs") has five subnodes, but only four of them are child nodes. In addition to the four level 2 subnodes, there is also a level 3 subnode, ^myNames("dogs","Lassie","Timmy"). The search will not find "Timmy" because this subnode is the child of "Lassie" (not "dogs"), and therefore is not a sibling of the others.

Although node ^myNames("dogs","Lassie") has a child node, it does not have a value. A call to getValue() will return null in this case. The following example searches for children of ^myNames("dogs") in reverse collation order:

Get nodes in reverse order from last node under ^myNames("dogs")

// Read child nodes in descending order while iter.next() is true
  System.out.print("Descend from last node:");
  try {
    IRISIterator iter = irisjv.getIRISIterator("myNames","dogs");
    while (iter.hasPrevious()) {
      iter.previous();
      System.out.print(" \"" + iter.getSubscriptValue() + "\"");
      if (iter.getValue()!=null) System.out.print("=" + iter.getValue());
    };
  } catch  (Exception e) {
    System.out.println( e.getMessage());
  }

This code prints the following line:

Descend from last node: "Whitefang"=7 "Lassie" "Hachiko"=8 "Balto"=6

In the previous example, the search misses several of the nodes in global array ^myNames because the scope of the search is restricted in various ways:

• Node ^myNames("dogs","Lassie","Timmy") is not found because it is not a level 2 subnode of ^myNames("dogs").

• Level 2 nodes under ^myNames("people") are not found because they are not siblings of the level 2 nodes under ^myNames("dogs").

The problem in both cases is that previous() and next() only find nodes that are under the same parent and on the same level as the starting address. You must specify a different starting address for each group of sibling nodes.

In most cases, you will probably be processing a known structure, and will traverse the various levels with simple nested calls. In the less common case where a structure has an arbitrary number of levels, the following jdbc.IRIS method can be used to determine if a given node has subnodes:

• isDefined() — returns 0 if the specified node does not exist, 1 if the node exists and has a value. 10 if the node is valueless but has subnodes, or 11 if it has both a value and subnodes.

If isDefined() returns 10 or 11, subnodes exist and can be processed by creating an iterator as described in the previous examples. A recursive algorithm could use this test to process any number of levels.