Ila

org.topoweb.ila
Class NodeSet

java.lang.Object
  |
  +--org.topoweb.ila.NodeSet
All Implemented Interfaces:
NodeConstants

public class NodeSet
extends java.lang.Object
implements NodeConstants

Immutable encapsulation of a list of monotonically ascending Node instances within a given lexical range. The nodes are guaranteed to be sorted in ascending order with no duplicates, if the reference to the node array passed in at instantiation is discarded by the caller. See note below.

A NodeSet represents not just a list of nodes, but also the lexical range of the Ori of the nodes in the list. A NodeSet may be complete, or truncated. When an instance is complete, it means the instance represents all the nodes in its range; when it is truncated, the instance represents a contiguous subset of the nodes of its range. If a node is not complete (is truncated), then the nodes in its list start from either end of it range. This is indicated by the getPageOrder method.

Implementation Note on Immutability

The constructors of this class each take an array of Node instances as one of their arguments. This array itself is not copied. The caller, therefore, must take care not to change the elements of the array after instantiation. This requirement is best achieved if the caller discards the reference to the node array after construction.

Note: Will probably adapt this class so that it implements java.util.SortedSet.

Author:
Babak Farhang

Field Summary
static NodeSet EMPTY
          An empty set with infinite range.
protected static java.util.Comparator searchComparator
          The comparator used to implement index-of-cursor searches.
static NodeSet UNKNOWN
          An empty set with no range.
 
Fields inherited from interface org.topoweb.ila.NodeConstants
BACK, FIRST_PAGE, FORE, LAST_PAGE, LINK_MASK, PAGE_MASK
 
Constructor Summary
NodeSet(Node[] nodes, org.topoweb.util.StringRange range)
          Convenience constructor.
NodeSet(Node[] nodes, org.topoweb.util.StringRange range, int page, int size)
          Creates a new instance with the given nodes array and range, and optional page flag and size..
 
Method Summary
protected  boolean checkForm(Node node)
          Checks the form of the node.
 int count()
          Returns the number of nodes stored in this instance.
 Node getNode(int index)
          Returns the node at the specified index.
 int getPageOrder()
          Returns the page order of this instance.
 org.topoweb.util.StringRange getRange()
          Returns the lexical range of the Oris of nodes that this set covers.
 int indexOfCursor(java.lang.String cursor)
          Returns the index of the Node whose Ori is lexically equal to the given string cursor.
 boolean isComplete()
          Returns whether this instance contains all the nodes in its range.
 boolean isFirstPage()
          Tests whether this instance represents the first page.
 boolean isLastPage()
          Tests whether this instance represents the last page.
 boolean isTruncated()
          Returns whether this instance contains only a subset of the nodes in its range.
 int size()
          Returns the number of elements in the range of this instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

searchComparator

protected static final java.util.Comparator searchComparator
The comparator used to implement index-of-cursor searches. This is just an instance of StringComparator.

See Also:
indexOfCursor(String)

EMPTY

public static final NodeSet EMPTY
An empty set with infinite range.

See Also:
StringRange.ALL

UNKNOWN

public static final NodeSet UNKNOWN
An empty set with no range.

See Also:
StringRange.Z
Constructor Detail

NodeSet

public NodeSet(Node[] nodes,
               org.topoweb.util.StringRange range)
        throws java.lang.IllegalArgumentException
Convenience constructor. Equivalent of invoking NodeSet(nodes, range, FIRST_PAGE, 0).

See Also:
NodeSet(Node[],StringRange,int,int), Implementation Note on Immutability

NodeSet

public NodeSet(Node[] nodes,
               org.topoweb.util.StringRange range,
               int page,
               int size)
        throws java.lang.IllegalArgumentException
Creates a new instance with the given nodes array and range, and optional page flag and size.. Subclasses may impose furthur restrictions on the form of the nodes by overriding checkForm(Node).

Parameters:
nodes - an array of Nodes sorted in ascending order
range - lexical range of the Oris of the nodes
page - page order flag (FIRST_PAGE or LAST_PAGE.
size - the number of nodes in the lexical range (defaults to nodes.length )
Throws:
java.lang.IllegalArgumentException - if nodes is null; if nodes contains null elements; if the elements of nodes are not monotonically ascending; if the checkForm method returns false for any of the elements in the nodes array; if range does not contain all the elements in nodes;
See Also:
Implementation Note on Immutability, checkForm(Node)
Method Detail

checkForm

protected boolean checkForm(Node node)
Checks the form of the node. Subclasses may override in order to enforce other constraints on the elements of the set. The default implementation always returns true.

Parameters:
node - the Node whose form is checked; never null
Returns:
true, if node is well formed; false, o.w.

indexOfCursor

public final int indexOfCursor(java.lang.String cursor)
Returns the index of the Node whose Ori is lexically equal to the given string cursor. If no match is found, then the value returned is -1 - insertionPoint , where insertionPoint is defined as documented in java.util.Arrays.binarySearch().

Parameters:
cursor - the string cursor
Returns:
the index of the match

getNode

public final Node getNode(int index)
Returns the node at the specified index. No exception is raised if the index is out of bounds.

Parameters:
index - the index of the node to be returned
Returns:
the node at the specified index, or null, if the index is out of bounds

count

public final int count()
Returns the number of nodes stored in this instance. This number can be used to discern the upperbound index for which the getNode method will return non-null values.


getRange

public final org.topoweb.util.StringRange getRange()
Returns the lexical range of the Oris of nodes that this set covers. The returned range can have application-specific semantics, such as an indication of knowledge about nodes in some lexical region.

Returns:
the lexical range of the nodes in this set

size

public final int size()
Returns the number of elements in the range of this instance. This number can be larger than this instances actual node count.

Returns:
the number of elements in the range of this instance

isComplete

public final boolean isComplete()
Returns whether this instance contains all the nodes in its range. This property is set at construction time. The return value is true iff count() == size().

Returns:
true, if all the nodes in this instance's range may be returned through the getNode method; false, o.w.
See Also:
isTruncated()

isTruncated

public final boolean isTruncated()
Returns whether this instance contains only a subset of the nodes in its range. This property is set at construction time.

Returns:
!isComplete()
See Also:
isComplete()

getPageOrder

public final int getPageOrder()
Returns the page order of this instance. The value returned is either FIRST_PAGE or LAST_PAGE. The page order is significant only if the instance is truncated; if the instance is complete, then FIRST_PAGE and LAST_PAGE represent the same thing.

Returns:
the page order

isFirstPage

public final boolean isFirstPage()
Tests whether this instance represents the first page.

Returns:
true, if getPageOrder() == FIRST_PAGE; false, o.w.

isLastPage

public final boolean isLastPage()
Tests whether this instance represents the last page.

Returns:
true, if getPageOrder() == LAST_PAGE; false, o.w.

Ila

Copyright (C) 2002 Babak Farhang

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.