Ila

org.topoweb.ila
Class StateBuffer

java.lang.Object
  |
  +--org.topoweb.ila.StateBuffer
All Implemented Interfaces:
NodeConstants, StateConstants
Direct Known Subclasses:
HttpStateBuffer, IncommunicadoStateBuffer

public class StateBuffer
extends java.lang.Object
implements StateConstants, NodeConstants

Creates and transmutes immutable State instances. This class makes the model for State transitions more concrete. Each node in an Ila system undergoes a series of state transitions -- from the time it is first added to the system, to the time when it is finally removed from the system. A StateBuffer instance is used to transition from one state to another. To do so, you first load a node's state, then apply one of the mutator methods (e.g. initLink), followed by the toState method. The diagram below illustrates the allowed status changes.

Each arrow represents a valid state transition: bidirectional arrows mean that status transitions are possible both directions. For example, nodes that are not in the system have NK (not known) status, and an arrow from NK to NV or OK represents the addition (creation) of a node with NV or OK state status, respectively; conversely, an arrow to NK represents the removal (deletion) of a node from Ila. The allowed transitions are listed below:

At any point in time, a StateBuffer's toState method can be invoked successfully (no exceptions will be raised). This means the internal state of this class is always consistent with that of a State instance.

Although not a State subclass, this class exposes the same accessor methods. The semantics of these accessors are intended to be the same. The mutator methods of this class return the instance itself so that as per the informal contract for buffer types, mutator methods can be chained.

Implementation Notes

This class is not safe under concurrent access. Exceptions thrown by methods of this class are thrown in a fail-fast manner: if an exception is thrown (typically a java.lang.IllegalArgumentException instance), the state of the buffer remains unchanged.

Author:
Babak Farhang
See Also:
State, State.State(int,int,long,int,long,int,int,long,long), Node.getState()

Field Summary
 
Fields inherited from interface org.topoweb.ila.StateConstants
NF, NK, NV, OK
 
Fields inherited from interface org.topoweb.ila.NodeConstants
BACK, FIRST_PAGE, FORE, LAST_PAGE, LINK_MASK, PAGE_MASK
 
Constructor Summary
StateBuffer()
           
 
Method Summary
 StateBuffer addBacklink()
          Adds one to the backlink count and bumps the version.
 StateBuffer addCoBacklink()
          Adds one to the co-backlink count and bumps the version.
 StateBuffer bumpSyncVersion()
          Bumps the current version and sets the sync version to the current version.
 StateBuffer bumpVersion()
          Bumps the current version.
 StateBuffer clear()
          Clears the buffer.
 long getCoLinkCount(int type)
          Returns the co-link count for the specified link type.
 long getLinkCount(int type)
          Returns the link count for the specified link type.
 int getStatus()
          Returns the status code.
 int getSyncVersionId()
          Returns the sync version ID for this instance.
 long getSyncVersionTimestamp()
          Returns the version timestamp for this instance.
 int getVersionId()
          Returns the version ID.
 long getVersionTimestamp()
          Returns the version timestamp.
 StateBuffer initCoLinked()
          Initializes the instance to NV status with exactly one backlink and one co-backlink.
 StateBuffer initLinked()
          Initializes the instance to NV status with exactly one backlink and zero co-backlinks.
 StateBuffer load(State state)
          Loads the given state object.
 StateBuffer removeBacklink()
          Removes one from the backlink count and bumps the version.
 StateBuffer removeCoBacklink()
          Removes one from the backlink count and bumps the version.
 StateBuffer setNotFound()
          Sets the result of an unsuccessful visit.
 StateBuffer setOkay(int linkCount, int coLinkCount)
          Sets the result of a successful visit of a node with the specified [fore-] link and co-link counts.
 State toState()
          Returns the state of this buffer as an immutable State instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StateBuffer

public StateBuffer()
Method Detail

load

public StateBuffer load(State state)
Loads the given state object. After invocation, the fields of this buffer instance assume the corresponding values of the passed in state. This is typically the first step of a state transition.

Parameters:
state - the object used to set the fields of this buffer
Returns:
this instance

toState

public State toState()
Returns the state of this buffer as an immutable State instance. The state of the buffer, itself, remains unchanged.

Returns:
an immutable State instance.
See Also:
load(State)

getStatus

public int getStatus()
Returns the status code. The return value is either of the 4 values OK, or NF, or NV, or NK.

Returns:
the status of the instance
See Also:
StateConstants

setOkay

public StateBuffer setOkay(int linkCount,
                           int coLinkCount)
Sets the result of a successful visit of a node with the specified [fore-] link and co-link counts. The status is bumped to OK if either the forelink or backlink count is non-zero; otherwise (a rare event), the node represented by this instance is subject to removal from Ila and its status is adjusted to NK. The version is bumped. If the previous status was not OK, then the sync version is set to new current version.

Parameters:
linkCount - the total forelink count
coLinkCount - the co-forelink count
Returns:
this instance
Throws:
java.lang.IllegalArgumentException - if either argument is < 0; if linkCount < coLinkCount

initLinked

public StateBuffer initLinked()
Initializes the instance to NV status with exactly one backlink and zero co-backlinks. Invocation clears any previous data in the buffer. The version is bumped and the sync version is adjusted to the new bumped version.

Returns:
this instance
See Also:
addBacklink(), removeBacklink(), initCoLinked()

addBacklink

public StateBuffer addBacklink()
Adds one to the backlink count and bumps the version. The status of the instance changes only if the previous status was NK (in which case the sync version is set to the new current version).

Returns:
this instance
See Also:
initLinked(), removeBacklink(), addCoBacklink()

removeBacklink

public StateBuffer removeBacklink()
Removes one from the backlink count and bumps the version. The status of the instance changes only if the both the forelink and backlink counts are zero upon invocation (in which case the sync version is set to the new current version).

Returns:
this instance
See Also:
initLinked(), addBacklink(), removeCoBacklink()

initCoLinked

public StateBuffer initCoLinked()
Initializes the instance to NV status with exactly one backlink and one co-backlink. Invocation clears any previous data in the buffer.

Returns:
this instance
See Also:
addCoBacklink(), removeCoBacklink(), initLinked()

addCoBacklink

public StateBuffer addCoBacklink()
Adds one to the co-backlink count and bumps the version. The status of the instance changes only if the previous status was NK (in which case the sync version is set to the new current version).

Returns:
this instance
See Also:
initCoLinked(), removeCoBacklink(), addBacklink()

removeCoBacklink

public StateBuffer removeCoBacklink()
Removes one from the backlink count and bumps the version. The status of the instance changes only if the both the forelink and backlink counts are zero upon invocation (in which case the sync version is set to the new current version).

Returns:
this instance
See Also:
initCoLinked(), addCoBacklink(), removeBacklink()

setNotFound

public StateBuffer setNotFound()
Sets the result of an unsuccessful visit. The forelink counts are set to zero and the version is bumped. If the backlink count is also zero, the node is subject to removal and the status is adjusted to NK; otherwise (the more common case), the status will be NF. If invocation causes a change in status, then the sync version is set to the current new version.

Returns:
this instance

clear

public StateBuffer clear()
Clears the buffer. The status is set to NK, and all the link counts and version data are set to zero.

Returns:
this instance

bumpVersion

public StateBuffer bumpVersion()
Bumps the current version. The version ID is incremented by one (subject to signed int overflow), and the version timestamp is set to the current UTF milliseconds. Every time the state represented by an instance changes, this method is implicitly invoked.

Returns:
this instance

bumpSyncVersion

public StateBuffer bumpSyncVersion()
Bumps the current version and sets the sync version to the current version. Every time the state represented by an instance changes and the status of the instance also changes, this method is implicitly invoked.

Returns:
this instance
See Also:
bumpVersion()

getVersionId

public int getVersionId()
Returns the version ID.

Returns:
the version ID

getVersionTimestamp

public long getVersionTimestamp()
Returns the version timestamp. The value returned indicates the time (in UTC millis) when the version was first created.

Returns:
the version timestamp

getSyncVersionId

public int getSyncVersionId()
Returns the sync version ID for this instance. Sync version ID indicates the version ID of the node when its information was last synchronized with the nodes it is linked to.

Returns:
the sync version ID

getSyncVersionTimestamp

public long getSyncVersionTimestamp()
Returns the version timestamp for this instance. The value returned indicates the time (in UTC millis) when the sync version was first created.

Returns:
the sync version timestamp

getLinkCount

public long getLinkCount(int type)
Returns the link count for the specified link type.

Parameters:
type - the link type
Returns:
the forelink count, if (type & LINK_MASK) == FORE; the backlink count, o.w.

getCoLinkCount

public long getCoLinkCount(int type)
Returns the co-link count for the specified link type.

Parameters:
type - the link type
Returns:
the co-forelink count, if (type & LINK_MASK) == FORE; the co-backlink count, 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.