com.timeindexing.index
Class TimeIndex

java.lang.Object
  extended bycom.timeindexing.index.TimeIndex
All Implemented Interfaces:
java.lang.Cloneable, Index, IndexHeader, IndexView, java.io.Serializable

public class TimeIndex
extends java.lang.Object
implements Index, IndexView, java.lang.Cloneable, java.io.Serializable

This is the generic object that applications interact with. It is a view onto an index.

See Also:
Serialized Form

Field Summary
 boolean isTerminated
           
 
Constructor Summary
protected TimeIndex(Index impl)
          Construct a Time Index using the nominated Index object.
 
Method Summary
 Index activate()
          Make the Index activated.
 boolean addDataType(ID typeID, java.lang.String typeName)
          Add a new data type
 long addItem(DataItem item)
          Add a Data Item to the Index.
 long addItem(DataItem item, Timestamp datatime)
          Add a Data Item to the Index with a specific Data Timestamp
 long addReference(IndexItem otherItem, Index otherIndex)
          Add a Referemnce to an IndexItem in a Index.
 long addReference(IndexItem otherItem, Index otherIndex, Timestamp dataTS)
          Add a Referemnce to an IndexItem in a Index.
 IndexView asView()
          Get a view onto the Index.
 IndexView backward()
          Sets the current navigation position into the IndexView to be one backward.
 java.lang.Object clone()
          Clone me
 boolean close()
          Close the index.
 boolean commit()
          Commit all changes to the index.
 boolean contains(Timestamp t, IndexTimestampSelector sel)
          Does a timestamp fall within the bounds of the Index.
 IndexView exchange()
          Exchanges the mark into the IndexView, with the current navigation position.
protected  void finalize()
          The finalize behviour is to call close().
 IndexView forward()
          Sets the current navigation position into the IndexView to be one forward.
 int getAnnotationStyle()
          Get the annotation style.
 java.lang.String getDataPathName()
          Get the path of the data if the index data style is external or shadow.
 long getDataSize()
          Get the size of the data items, if there is fixed size data.
 java.lang.String getDataType(ID typeID)
          Get the type name of the things in the data stream.
 Description getDescription()
          Get the description for an index.
 Position getEndPosition()
          Get the end position, in the index, of this IndexView.
 Timestamp getEndTime()
          Get the end time of the index.
 Timestamp getFirstDataTime()
          Get the data time for the first IndexItem in the Index.
 Timestamp getFirstTime()
          Get the time the first IndexItem was put into the Index.
 ID getID()
          Get an ID of an index.
 DataType getIndexDataType()
          Get the index data type.
 java.lang.String getIndexPathName()
          Get the path of the index file.
 IndexType getIndexType()
          Get the type of an index.
 IndexItem getItem()
          Get the Index Item from the Index at position position().
 IndexItem getItem(long n)
          Get an Index Item from the Index.
 IndexItem getItem(Position p)
          Get an Index Item from the Index.
 IndexItem getItem(Timestamp t, IndexTimestampSelector sel, Lifetime lifetime)
          Get an Index Item from the Index.
 IndexItem getItemAtMark()
          Get the Index Item from the Index at position mark().
 int getItemSize()
          Get the size of the index items.
 Timestamp getLastAccessTime()
          Get the last time an IndexItem was accessed from the index.
 Timestamp getLastDataTime()
          Get the data time for the last IndexItem in the Index.
 Timestamp getLastTime()
          Get the time the last IndexItem was put into the Index.
 long getLength()
          Get the no of items in the index.
 java.lang.String getName()
          The name of the index.
 IndexView getSelectionIndexView()
          Return the IndexView used to get a selection.
 Interval getSelectionInterval()
          Return the Interval used to get a selection.
 Position getStartPosition()
          Get the start position, in the index, of this IndexView.
 Timestamp getStartTime()
          Get the start time of the index.
 java.net.URI getURI()
          Get the Index specification in the form of a URI.
 boolean hasAnnotations()
          Does this index have annotations.
 boolean hasDataType(java.lang.String typeName)
          Does this index have a typed name.
 boolean isActivated()
          Is the Index activated.
 boolean isChanged()
          Has the index changed in any way.
 boolean isClosed()
          Is the Index closed.
 boolean isFixedSizeData()
          Does the index have fixed size data.
 boolean isInTimeOrder()
          Is the index still in time order.
 boolean isReadOnly()
          Is the Index only available for read-only operations.
 boolean isSelection()
          Is this a selection.
 boolean isTerminated()
          Is the Index terminated.
 boolean isWriteLocked()
          Has the Index been write-locked.
 java.util.Iterator iterator()
          Get an iterator over the IndexItems in the Index.
 TimestampMapping locate(Position p, IndexTimestampSelector sel, Lifetime lifetime)
          Try and determine the Timestamp associated with the speicifed Position.
 TimestampMapping locate(Timestamp t, IndexTimestampSelector sel, Lifetime lifetime)
          Try and determine the position associated with the speicifed data Timestamp.
 IndexView mark()
          Sets the mark into the IndexView, using the current navigation position as the mark value.
 Position position()
          Gets the current navigation position into the IndexView.
 IndexView position(long n)
          Sets the current navigation position into the IndexView.
 IndexView position(Position p)
          Sets the current navigation position into the IndexView specified as a Position.
 IndexView position(Timestamp t, IndexTimestampSelector selector, Lifetime lifetime)
          Sets the current navigation position into the IndexView specified as a Timestamp.
 Interval region()
          What is the region covered by position and mark.
 IndexView select(Interval interval, IndexTimestampSelector selector, Overlap overlap, Lifetime lifetime)
          Select an Interval.
 boolean setAutoCommit(boolean commit)
          Set auto commit to be true or false.
 boolean setCachePolicy(CachePolicy policy)
          Set a CachePolicy in order to manage the cache.
 Index terminate()
          Make the Index finalized.
 Index updateDescription(Description description)
          Set the description.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

isTerminated

public boolean isTerminated
Constructor Detail

TimeIndex

protected TimeIndex(Index impl)
Construct a Time Index using the nominated Index object.

Method Detail

getName

public java.lang.String getName()
The name of the index.

Specified by:
getName in interface IndexHeader

getID

public ID getID()
Get an ID of an index.

Specified by:
getID in interface IndexHeader

getURI

public java.net.URI getURI()
Get the Index specification in the form of a URI.

Specified by:
getURI in interface IndexHeader

getIndexType

public IndexType getIndexType()
Get the type of an index.

Specified by:
getIndexType in interface IndexHeader

getIndexDataType

public DataType getIndexDataType()
Get the index data type. Some indexes have the same type throughout, other have mixed type data.

Specified by:
getIndexDataType in interface IndexHeader

getStartTime

public Timestamp getStartTime()
Get the start time of the index. This is when the index was created not necessarliy when the first item was added to the index.

Specified by:
getStartTime in interface IndexHeader

getEndTime

public Timestamp getEndTime()
Get the end time of the index. This is the time the last item was closed, not necessarliy when the last item was added to the index.

Specified by:
getEndTime in interface IndexHeader

getFirstTime

public Timestamp getFirstTime()
Get the time the first IndexItem was put into the Index.

Specified by:
getFirstTime in interface IndexHeader
Returns:
ZeroTimestamp if there is no first item, usually when there are no items in the index

getLastTime

public Timestamp getLastTime()
Get the time the last IndexItem was put into the Index.

Specified by:
getLastTime in interface IndexHeader
Returns:
ZeroTimestamp if there is no last item, usually when there are no items in the index

getFirstDataTime

public Timestamp getFirstDataTime()
Get the data time for the first IndexItem in the Index.

Specified by:
getFirstDataTime in interface IndexHeader
Returns:
ZeroTimestamp if there is no first item, usually when there are no items in the index

getLastDataTime

public Timestamp getLastDataTime()
Get the data time for the last IndexItem in the Index.

Specified by:
getLastDataTime in interface IndexHeader
Returns:
ZeroTimestamp if there is no last item, usually when there are no items in the index

getItemSize

public int getItemSize()
Get the size of the index items.

Specified by:
getItemSize in interface Index

isFixedSizeData

public boolean isFixedSizeData()
Does the index have fixed size data.

Specified by:
isFixedSizeData in interface IndexHeader

getDataSize

public long getDataSize()
Get the size of the data items, if there is fixed size data.

Specified by:
getDataSize in interface IndexHeader

getDataType

public java.lang.String getDataType(ID typeID)
Get the type name of the things in the data stream.

Specified by:
getDataType in interface Index

hasDataType

public boolean hasDataType(java.lang.String typeName)
Does this index have a typed name.

Specified by:
hasDataType in interface Index

addDataType

public boolean addDataType(ID typeID,
                           java.lang.String typeName)
Add a new data type

Specified by:
addDataType in interface Index
Returns:
true, if a new type was added; false, if the index had this ID/typeName pair already

hasAnnotations

public boolean hasAnnotations()
Does this index have annotations.

Specified by:
hasAnnotations in interface Index

getAnnotationStyle

public int getAnnotationStyle()
Get the annotation style. Either inline or external.

Specified by:
getAnnotationStyle in interface Index

addItem

public long addItem(DataItem item)
             throws IndexTerminatedException,
                    IndexClosedException,
                    IndexActivationException,
                    AddItemException
Add a Data Item to the Index.

Specified by:
addItem in interface Index
Throws:
IndexTerminatedException
IndexClosedException
IndexActivationException
AddItemException

addItem

public long addItem(DataItem item,
                    Timestamp datatime)
             throws IndexTerminatedException,
                    IndexClosedException,
                    IndexActivationException,
                    AddItemException
Add a Data Item to the Index with a specific Data Timestamp

Specified by:
addItem in interface Index
Throws:
IndexTerminatedException
IndexClosedException
IndexActivationException
AddItemException

addReference

public long addReference(IndexItem otherItem,
                         Index otherIndex)
                  throws IndexTerminatedException,
                         IndexClosedException,
                         IndexActivationException,
                         AddItemException
Add a Referemnce to an IndexItem in a Index.

Specified by:
addReference in interface Index
Throws:
IndexTerminatedException
IndexClosedException
IndexActivationException
AddItemException

addReference

public long addReference(IndexItem otherItem,
                         Index otherIndex,
                         Timestamp dataTS)
                  throws IndexTerminatedException,
                         IndexClosedException,
                         IndexActivationException,
                         AddItemException
Add a Referemnce to an IndexItem in a Index.

Specified by:
addReference in interface Index
Throws:
IndexTerminatedException
IndexClosedException
IndexActivationException
AddItemException

getLength

public long getLength()
Get the no of items in the index.

Specified by:
getLength in interface IndexHeader

getItem

public IndexItem getItem(long n)
                  throws GetItemException
Get an Index Item from the Index.

Specified by:
getItem in interface Index
Throws:
GetItemException

getItem

public IndexItem getItem(Position p)
                  throws GetItemException
Get an Index Item from the Index.

Specified by:
getItem in interface Index
Throws:
GetItemException

getItem

public IndexItem getItem(Timestamp t,
                         IndexTimestampSelector sel,
                         Lifetime lifetime)
                  throws GetItemException
Get an Index Item from the Index.

Specified by:
getItem in interface Index
Throws:
GetItemException

getLastAccessTime

public Timestamp getLastAccessTime()
Get the last time an IndexItem was accessed from the index.

Specified by:
getLastAccessTime in interface Index

getIndexPathName

public java.lang.String getIndexPathName()
Get the path of the index file.

Specified by:
getIndexPathName in interface IndexHeader
Returns:
null if there is no index path

getDataPathName

public java.lang.String getDataPathName()
Get the path of the data if the index data style is external or shadow.

Specified by:
getDataPathName in interface IndexHeader
Returns:
null if there is no data path

getDescription

public Description getDescription()
Get the description for an index.

Specified by:
getDescription in interface IndexHeader
Returns:
null if there is no description

updateDescription

public Index updateDescription(Description description)
Set the description. This is one of the few attributes of an index that can be set directly.

Specified by:
updateDescription in interface Index

contains

public boolean contains(Timestamp t,
                        IndexTimestampSelector sel)
Does a timestamp fall within the bounds of the Index. The bounds are the first time data is put in and the last time data is put in the Index.

Specified by:
contains in interface Index

locate

public TimestampMapping locate(Timestamp t,
                               IndexTimestampSelector sel,
                               Lifetime lifetime)
Try and determine the position associated with the speicifed data Timestamp.

Specified by:
locate in interface Index
Returns:
null if no position is found

locate

public TimestampMapping locate(Position p,
                               IndexTimestampSelector sel,
                               Lifetime lifetime)
Try and determine the Timestamp associated with the speicifed Position. Returns a TimestampMapping which contains the original Position and the found Timestamp. Lifetime has no effect in this situation.

Specified by:
locate in interface Index

select

public IndexView select(Interval interval,
                        IndexTimestampSelector selector,
                        Overlap overlap,
                        Lifetime lifetime)
Select an Interval. Returns null if it cant be done.

Specified by:
select in interface IndexView

getSelectionInterval

public Interval getSelectionInterval()
Return the Interval used to get a selection.

Specified by:
getSelectionInterval in interface IndexView
Returns:
null if the view is not a selection.

getSelectionIndexView

public IndexView getSelectionIndexView()
Return the IndexView used to get a selection.

Specified by:
getSelectionIndexView in interface IndexView
Returns:
null if the view is not a selection.

isSelection

public boolean isSelection()
Is this a selection.

Specified by:
isSelection in interface IndexView

isActivated

public boolean isActivated()
Is the Index activated.

Specified by:
isActivated in interface Index

activate

public Index activate()
               throws IndexReadOnlyException,
                      IndexWriteLockedException
Make the Index activated. It is not possible to add items to an Index that is not active.

Specified by:
activate in interface Index
Throws:
IndexReadOnlyException
IndexWriteLockedException

isTerminated

public boolean isTerminated()
Is the Index terminated.

Specified by:
isTerminated in interface IndexHeader

terminate

public Index terminate()
Make the Index finalized. It is not possible to add items ever again to an Index that has been terminated.

Specified by:
terminate in interface Index

isInTimeOrder

public boolean isInTimeOrder()
Is the index still in time order.

Specified by:
isInTimeOrder in interface IndexHeader

commit

public boolean commit()
               throws IndexCommitException
Commit all changes to the index.

Specified by:
commit in interface Index
Throws:
IndexCommitException

setAutoCommit

public boolean setAutoCommit(boolean commit)
Set auto commit to be true or false. When auto commit is true, then every addItem() is automatically committed.

Specified by:
setAutoCommit in interface Index
Returns:
the previous value of auto commit.

isClosed

public boolean isClosed()
Is the Index closed.

Specified by:
isClosed in interface Index

close

public boolean close()
              throws IndexCloseException
Close the index. Intened to close all associated streams and files, and this sets the end time too.

Specified by:
close in interface Index
Throws:
IndexCloseException

isChanged

public boolean isChanged()
Has the index changed in any way.

Specified by:
isChanged in interface Index

isReadOnly

public boolean isReadOnly()
Is the Index only available for read-only operations.

Specified by:
isReadOnly in interface IndexHeader

isWriteLocked

public boolean isWriteLocked()
Has the Index been write-locked.

Specified by:
isWriteLocked in interface Index

asView

public IndexView asView()
Get a view onto the Index.

Specified by:
asView in interface Index

iterator

public java.util.Iterator iterator()
Get an iterator over the IndexItems in the Index.

Specified by:
iterator in interface Index

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Clone me

Throws:
java.lang.CloneNotSupportedException

position

public Position position()
Gets the current navigation position into the IndexView.

Specified by:
position in interface IndexView

position

public IndexView position(Position p)
Sets the current navigation position into the IndexView specified as a Position.

Specified by:
position in interface IndexView

position

public IndexView position(long n)
Sets the current navigation position into the IndexView. specified as a long.

Specified by:
position in interface IndexView

position

public IndexView position(Timestamp t,
                          IndexTimestampSelector selector,
                          Lifetime lifetime)
Sets the current navigation position into the IndexView specified as a Timestamp.

Specified by:
position in interface IndexView

getStartPosition

public Position getStartPosition()
Get the start position, in the index, of this IndexView.

Specified by:
getStartPosition in interface IndexView

getEndPosition

public Position getEndPosition()
Get the end position, in the index, of this IndexView.

Specified by:
getEndPosition in interface IndexView

mark

public IndexView mark()
Sets the mark into the IndexView, using the current navigation position as the mark value.

Specified by:
mark in interface IndexView

forward

public IndexView forward()
Sets the current navigation position into the IndexView to be one forward.

Specified by:
forward in interface IndexView

backward

public IndexView backward()
Sets the current navigation position into the IndexView to be one backward.

Specified by:
backward in interface IndexView

getItem

public IndexItem getItem()
                  throws GetItemException
Get the Index Item from the Index at position position().

Specified by:
getItem in interface IndexView
Throws:
GetItemException

getItemAtMark

public IndexItem getItemAtMark()
                        throws GetItemException
Get the Index Item from the Index at position mark().

Specified by:
getItemAtMark in interface IndexView
Throws:
GetItemException

region

public Interval region()
What is the region covered by position and mark. Returned value is an Interval.

Specified by:
region in interface IndexView

exchange

public IndexView exchange()
Exchanges the mark into the IndexView, with the current navigation position.

Specified by:
exchange in interface IndexView

finalize

protected void finalize()
                 throws java.lang.Throwable
The finalize behviour is to call close().

Throws:
java.lang.Throwable

setCachePolicy

public boolean setCachePolicy(CachePolicy policy)
Set a CachePolicy in order to manage the cache. Setting a new CachePolicy in the middle of operation can lose some timing information held by the existing CachePolicy, so use with care.

Specified by:
setCachePolicy in interface Index
Returns:
true if the policy was set