org.mbari.siam.core
Class DeviceLog

java.lang.Object
  extended by org.mbari.siam.core.DeviceLog
Direct Known Subclasses:
FilteredDeviceLog

public class DeviceLog
extends java.lang.Object

DeviceLog is the top level class implementation of an indexed record retrieval class. It utilizes two subordinate classes, DeviceLogData and DeviceLogIndex to implement indexed random access record storage.

Author:
Tim Meese
See Also:
DeviceLogData, DeviceLogIndex, SensorDataPacket, DevicePacket

Field Summary
protected  DeviceLogData _data
           
protected  DeviceLogIndex _index
           
protected  StopWatch _writeTimer
           
static long EOF
           
static long SYNC_NOT_FOUND
           
static byte[] SYNC_PATTERN
           
 
Constructor Summary
protected DeviceLog(long deviceId, int segmentNum, java.lang.String directory)
          Create DeviceLog for specified device, sequence number, in specified directory.
  DeviceLog(long deviceId, java.lang.String directory)
          Create DeviceLog for specified device, with storage in specified directory.
 
Method Summary
 void appendPacket(DevicePacket packet)
          This method appends the specified DevicePacket object to the log that is being maintained.
 void appendPacket(DevicePacket packet, boolean setSequenceNos, boolean checkTime)
          This method appends the specified DevicePacket object to the log that is being maintained.
static void check(DeviceLog log, boolean repair)
          When applications like logView and logPublish encounter corrupt data packets or index entries, they fail and can not proceed beyond the bad packets.
 void close()
          Close the DeviceLog and associated files.
 long getDeviceId()
          returns the ISI deviceId associated with this DeviceLog
 long getLastMetadataRef()
          Return last metadata reference number.
 DevicePacket getLastPacket()
          Return the last sequential packet in the log.
 long getMaxTimestamp()
          returns the maximum key that has been registered by all DevicePacket storage operations
 long getMinTimestamp()
          returns the minimum key that has been registered by all DevicePacket storage operations
 DevicePacket getNextPacket()
          returns the next unread DevicePacket in sequential order.
static long getNextSync(DeviceLog log, long offset)
          Returns the offset (in bytes) of the beginning of the next sync pattern, starting the search at offset bytes into the file.
 int getNumUnreadPackets()
          returns the number of unread packets remaining if packets are retrieved using the getNextPacket() method
protected  DevicePacket getPacket(DeviceLogIndex.Entry indexEntry)
           
 DevicePacketSet getPacketKeyRange(long startKey, long endKey, int maxEntries)
          Call getPacketKeyRange() - calls getPackets().
 DevicePacketSet getPackets(long startKey, long endKey, int maxEntries)
          returns a DevicePacketSet object populated with DeviceLog objects (i.e.
 int nPackets()
          Return total number of packets in log.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SYNC_PATTERN

public static final byte[] SYNC_PATTERN

EOF

public static final long EOF
See Also:
Constant Field Values

SYNC_NOT_FOUND

public static final long SYNC_NOT_FOUND
See Also:
Constant Field Values

_index

protected DeviceLogIndex _index

_data

protected DeviceLogData _data

_writeTimer

protected StopWatch _writeTimer
Constructor Detail

DeviceLog

protected DeviceLog(long deviceId,
                    int segmentNum,
                    java.lang.String directory)
             throws java.io.IOException,
                    java.io.FileNotFoundException
Create DeviceLog for specified device, sequence number, in specified directory.

Throws:
java.io.IOException
java.io.FileNotFoundException

DeviceLog

public DeviceLog(long deviceId,
                 java.lang.String directory)
          throws java.io.FileNotFoundException,
                 java.io.IOException
Create DeviceLog for specified device, with storage in specified directory.

Throws:
java.io.FileNotFoundException
java.io.IOException
Method Detail

getLastMetadataRef

public long getLastMetadataRef()
Return last metadata reference number.


getDeviceId

public long getDeviceId()
returns the ISI deviceId associated with this DeviceLog


appendPacket

public void appendPacket(DevicePacket packet,
                         boolean setSequenceNos,
                         boolean checkTime)
This method appends the specified DevicePacket object to the log that is being maintained. The object is serialized and subsequently written to a data file while indexing information is maintained. If argument setSequenceNos is set to 'true', then appendPacket() will automatically set the packet's sequence number and metadata reference.

Parameters:
packet - DevicePacket object to append to active log

appendPacket

public void appendPacket(DevicePacket packet)
This method appends the specified DevicePacket object to the log that is being maintained. The object is serialized and subsequently written to a data file while indexing information is maintained. This version of appendPacket() will automatically set the packet's sequence number and metadata reference.

Parameters:
packet - DevicePacket object to append to active log

getPackets

public DevicePacketSet getPackets(long startKey,
                                  long endKey,
                                  int maxEntries)
                           throws NoDataException
returns a DevicePacketSet object populated with DeviceLog objects (i.e. a result set) that matches the key comparison criterion specified by the parameters, up to the maximum number of packets specified.

Parameters:
startKey - beginning key value (inclusive) of the result set
endKey - ending key value (inclusive) of the result set
maxEntries - maximum number of packets to include in the set
Throws:
NoDataException
See Also:
Vector, DevicePacket

getPacketKeyRange

public DevicePacketSet getPacketKeyRange(long startKey,
                                         long endKey,
                                         int maxEntries)
                                  throws NoDataException
Call getPacketKeyRange() - calls getPackets(). getPacketKeyRange() is an obsolete method name, but we keep it for patch compatibility.

Throws:
NoDataException

getLastPacket

public DevicePacket getLastPacket()
                           throws NoDataException
Return the last sequential packet in the log.

Returns:
last sequential packet (DevicePacket)
Throws:
NoDataException

getNextPacket

public DevicePacket getNextPacket()
                           throws NoDataException
returns the next unread DevicePacket in sequential order.

Throws:
NoDataException
See Also:
DevicePacket

getPacket

protected DevicePacket getPacket(DeviceLogIndex.Entry indexEntry)
                          throws NoDataException
Throws:
NoDataException

nPackets

public int nPackets()
Return total number of packets in log.


getNumUnreadPackets

public int getNumUnreadPackets()
returns the number of unread packets remaining if packets are retrieved using the getNextPacket() method

See Also:
getNextPacket()

getMinTimestamp

public long getMinTimestamp()
returns the minimum key that has been registered by all DevicePacket storage operations

See Also:
getPacketKeyRange(long, long, int)

getMaxTimestamp

public long getMaxTimestamp()
returns the maximum key that has been registered by all DevicePacket storage operations

See Also:
getPacketKeyRange(long, long, int)

close

public void close()
           throws java.io.IOException
Close the DeviceLog and associated files. This DeviceLog instance is no longer usable after close() has been called.

Throws:
java.io.IOException

getNextSync

public static long getNextSync(DeviceLog log,
                               long offset)
Returns the offset (in bytes) of the beginning of the next sync pattern, starting the search at offset bytes into the file. Originally, this used a FileInputStream wrapper around the RandomAccessFile, but this resulted in an IOException with a "handle not valid" message. Alternatively, a read implementation has been implented (DeviceLogData.readBytes()) that uses RandomAcessFile.read() directly.

Returns:
offset of next sync pattern on success

check

public static void check(DeviceLog log,
                         boolean repair)
When applications like logView and logPublish encounter corrupt data packets or index entries, they fail and can not proceed beyond the bad packets. This method is used to read each packet in the specified log, report errors, and optionally construct a new index (.idx) file if repair is set to true. It does not change the original data file or index. When the -repair option is given, it produces a new index file in the current working directory: _.rebuilt.idx To invoke this method, use logView -check [-repair] Other logView options (e.g. filters) are ignored inside check. The check() method works by traversing the binary sync patterns in the data (.dat) file. When it finds a sync pattern, it finds the next sync pattern and attempts to read everything between as a DevicePacket. If the read succeeds, a new IndexEntry is added to the new index (.idx) file. Otherwise, an error is counted, and the process repeats. Note that because the index and its journal contain no information about what types of packets are in the log, it is not possible to directly detect when a metadata packet is missing or corrupt. check() tracks metadata packets and looks at each packet's metadata reference value on the fly. It keeps track of metadata packets and references, and reports the number of references without corresoponding metadata packets. This may report a missing packet for the first packet, and would fail to detect when a reference value comes before its metadata packet (which should not happen in general). Originally, this used a FileInputStream wrapper around the RandomAccessFile, but this resulted in an IOException with a "handle not valid" message. Alternatively, a read implementation has been implented (DeviceLogData.readBytes()) that uses RandomAcessFile.read() directly.



Copyright © 2003 MBARI.

The Monterey Bay Aquarium Research Institute (MBARI) provides this documentation and code "as is", with no warranty, express or implied, of its quality or consistency. It is provided without support and without obligation on the part of MBARI to assist in its use, correction, modification, or enhancement.