org.mbari.siam.core
Class InstrumentService

java.lang.Object
  extended by java.rmi.server.RemoteObject
      extended by java.rmi.server.RemoteServer
          extended by java.rmi.server.UnicastRemoteObject
              extended by org.mbari.siam.core.DeviceService
                  extended by org.mbari.siam.core.InstrumentService
All Implemented Interfaces:
java.io.Serializable, java.rmi.Remote, ScheduleOwner, Device, DeviceServiceIF, Instrument
Direct Known Subclasses:
CompassKVHC100, Environmental, GashoundSubsystem, mdTest, Metsys, NobskaMAVS, Pump, PumpUser, SatlanticISUS, Shmoo, ShmooInstrumentService, SmartStar, TerminalInstrumentService

Deprecated. Replaced by BaseInstrumentService, PolledInstrumentService, and StreamingInstrumentService. InstrumentService is the base class of an "application framework" for instruments which communicate through a serial port

The application framework is a semi-complete application, providing data and behavior which are common to all instrument services. To complete the implementation of a specific instrument service, the programmer extends the InstrumentService class, and implements or overrides several InstrumentService methods.

InstrumentService provides the following as built-in features:

Access to instrument serial port: InstrumentService contains a java.io.OutputStream for output to the instrument's CommPort, and a java.io.InputStream for input from the instrument's CommPort. Subclasses can use these stream objects to communicate with the instrument. Note that these objects should NOT be accessed from your subclass constructor, as they haven't been created yet at construction time.

Power management: Your subclass must implement methods initCommunicationPowerPolicy(), and initInstrumentPowerPolicy(), which should return one of the following values defined in interface org.mbari.isi.interfaces.Instrument: PowerPolicy.NEVER (for self-powered instruments), PowerPolicy.ALWAYS, or PowerPolicy.WHEN_SAMPLING. The subclass needn't do any further power management, as the base automatically manages instrument power through its DPA port based on the "power policy" specified by your subclass.

The base class provides default values for a number of attributes (member variables); see comments on the DEFAULT_ fields (below). These default values can be overridden using the "set" methods provided for each attribute (e.g. setMaxSampleTries()). For some attributes, no reasonable default value is known, and must be provided by your subclass. These values are specified by implementing the abstract "init" member functions defined by the base class (e.g. initCommunicationPowerPolicy()).

To implement a specific instrument service, complete the following steps:

1. Extend InstrumentService to create your service's subclass

2. Implement any abstract InstrumentService methods (see documentation below for specific methods)

3. If necessary, override base class initializeInstrument() method, where service- and instrument-specific initialization should be done. If necessary, change values of base class attributes here, using "set" methods provided.

4. If necessary, override other base class methods

5. If necessary, add any additional attributes/methods needed to implement your instrument's service.

public abstract class InstrumentService
extends DeviceService
implements Instrument, DeviceServiceIF, ScheduleOwner

Author:
Tom O'Reilly, Kent Headley, Bill Baugh
See Also:
Serialized Form

Field Summary
protected  java.lang.String _defaultSampleScheduleName
          Deprecated. Name of default sample schedule
protected  InstrumentServiceAttributes _instrumentAttributes
          Deprecated. Basic instrument service attributes.
protected  DevicePacket _lastPacket
          Deprecated. Most recent DataPacket sent (of any kind)
protected  SensorDataPacket _lastSensorDataPacket
          Deprecated. Most recent SensorDataPacket sent
protected static org.apache.log4j.Logger _log4j
          Deprecated. Log4j logger
protected  DeviceMessagePacket _messagePacket
          Deprecated. DeviceMessagePacket.
protected  FilteredDeviceLog _packetLog
          Deprecated. Sensor log for persistent packet storage.
protected  long _recordType
          Deprecated.  
protected  java.util.Vector _schedules
          Deprecated. ScheduleTask container (schedules)
protected  SensorDataPacket _sensorDataPacket
          Deprecated. SensorDataPacket to be returned to clients.
protected static long RECORDTYPE_DEFAULT
          Deprecated.  
protected static long RECORDTYPE_METADATA
          Deprecated.  
protected static long RECORDTYPE_UNDEFINED
          Deprecated. Default record type
 
Fields inherited from class org.mbari.siam.core.DeviceService
_fromDevice, _instrumentPort, _nodeProperties, _parentNode, _regEntry, _sandBox, _serviceCachePath, _serviceName, _servicePropertiesPath, _serviceXMLPath, _toDevice, CACHED_PROPERTIES_FILENAME, PROPERTIES_FILENAME, XML_FILENAME
 
Fields inherited from class java.rmi.server.RemoteObject
ref
 
Fields inherited from interface org.mbari.siam.distributed.Device
ERROR, INITIAL, INSTRUMENT_STATE, MDATA_ALL, OK, SAFE, SAMPLING, SERVICE_ATTRIBUTES, SERVICE_CACHE, SERVICE_PROPERTIES, SERVICE_XML, SHUTDOWN, SLEEPING, SUSPEND, UNKNOWN
 
Constructor Summary
InstrumentService()
          Deprecated. Constructor.
 
Method Summary
 SensorDataPacket acquire(boolean logSample)
          Deprecated. Acquire data sample from instrument, process it, and put data into output queue.
 SensorDataPacket acquireSample(boolean logPacket)
          Deprecated. Acquire data sample from instrument, process it, log it, and return it to caller.
 void addDefaultPacketFilters(PacketFilter[] filters)
          Deprecated. Add default packet filters for data retrieval.
protected  int addSchedule(ScheduleTask schedule, boolean overwrite)
          Deprecated. Add the specified schedule task.
 int addSchedule(java.lang.String name, java.lang.String schedule, boolean overwrite)
          Deprecated. Add/replace instrument schedule
 void annotate(byte[] annotation)
          Deprecated. Put annotation into device data stream.
 void cacheProperties(byte[] note)
          Deprecated. Cache service properties on the node, such that current property values will be restored next time service is created on this node.
protected  void checkInputProperties(java.util.Properties properties)
          Deprecated. Check that all specified properties are allowed to be set on-the-fly.
 void cleanupServiceState()
          Deprecated. Do overhead tasks needed to clean up after sample cycle.
 void clearDefaultPacketFilters()
          Deprecated. Clear default packet filters for data retrieval.
 void clearPropertiesCache(byte[] note)
          Deprecated. Clear properties cache.
protected abstract  ScheduleSpecifier createDefaultSampleSchedule()
          Deprecated. Return specifier for default sampling schedule.
 ScheduleTask createTask(java.lang.String name, ScheduleSpecifier schedule, ScheduleOwner owner)
          Deprecated. createTask is a factory method to make new schedule tasks by name.
 void disableSamplingDiagnostics()
          Deprecated. Disable sampling diagnostics.
 void disableSummary()
          Deprecated. Disable data summary generation.
 void doScheduledTask(ScheduleTask task)
          Deprecated. Execute the scheduled task, as part of ScheduleOwner implementation.
 void enableSamplingDiagnostics()
          Deprecated. Enable sampling diagnostics.
 void enableSummary()
          Deprecated. Enable data summary generation.
 java.util.Collection getAllSchedules()
          Deprecated. Return a vector of ScheduleTask objects Part of ScheduleOwner interface.
 Device[] getChildren()
          Deprecated. Return child Devices.
protected  PowerPolicy getCommunicationPowerPolicy()
          Deprecated. Get instrument communication power policy.
protected  int getCurrentLimit()
          Deprecated. Get power channel's current limit.
 PacketFilter[] getDefaultPacketFilters()
          Deprecated. Get default packet filters for data retrieval.
 ScheduleTask getDefaultSampleSchedule()
          Deprecated. Get the default schedule
 java.lang.String getDefaultSampleScheduleName()
          Deprecated. Get default sample schedule name
 DevicePacketParser getDevicePacketParser()
          Deprecated. NOTE: THis method should be overridden by classes who need a DevicePacketParser
 byte[] getFileBytes(java.lang.String file)
          Deprecated. Get the contents of a file and return them as a byte array
 InstrumentBlock getInstrumentBlock()
          Deprecated.  
protected  PowerPolicy getInstrumentPowerPolicy()
          Deprecated. Get instrument power policy.
protected  int getInstrumentStartDelay()
          Deprecated. Get instrument startup time
protected  byte[] getInstrumentStateMetadata()
          Deprecated. Get instrument- and service-specific metadata.
 SensorDataPacket getLastSample()
          Deprecated. Get last sample packet.
 Location getLocation()
          Deprecated. Return Location of device.
protected  int getMaxSampleBytes()
          Deprecated. Get maximum number of bytes in a data sample read from instrument.
protected  int getMaxSampleTries()
          Deprecated. Get maximum number of tries when retrieving sample from instrument.
 MetadataPacket getMetadata(byte[] cause, int components, boolean logPacket)
          Deprecated. Create, return and optionally log a metadata packet
protected  MetadataPacket getMetadata(byte[] cause, int components, java.lang.String[] attributeNames, boolean logPacket)
          Deprecated. Create, return, and optionally log metadata packet; if service attributes are requested, then include only specified attributes.
 byte[] getMetadataPayload(int components, java.lang.String[] attributeList)
          Deprecated. Get requested metadata state components in a byte array containing serialized State and StateAttribute objects.
 DevicePacketSet getPackets(long startTime, long stopTime)
          Deprecated. Return all logged data packets having creation time within specified time window.
 DevicePacketSet getPackets(long startTime, long stopTime, PacketFilter[] filters, boolean excludeStale)
          Deprecated. Return all logged data packets having creation time within specified time window, that pass specified packet filters.
 Device getParent()
          Deprecated. Return parent Device.
 PacketParser getParser()
          Deprecated. Get instrument's parser.
 byte[] getPortDiagnostics(boolean logPacket)
          Deprecated. Get diagnostics message from device's port and optionally log it.
 byte[] getPortDiagnosticsSummary(boolean logPacket)
          Deprecated. Get diagnostics summary message from device's port and optionally log it.
protected  byte[] getPromptString()
          Deprecated. Get instrument's "prompt" character(s).
 java.util.Vector getProperties()
          Deprecated. Get Vector of instrument properties; each Vector element consists of byte array with form "key=value".
 byte[] getProperty(byte[] key)
          Deprecated. Get value of specified service property.
protected  byte[] getSampleBuf()
          Deprecated. Get raw sample buffer.
 byte[] getSampleSchedule()
          Deprecated. Return byte-string representation of instrument sampling schedule.
protected  byte[] getSampleTerminator()
          Deprecated. Get sample terminator
protected  long getSampleTimeout()
          Deprecated. Get sampling timeout (millisec)
 ScheduleTask getSchedule(java.lang.String name)
          Deprecated. Get a schedule by name
 Scheduler.ScheduleKey getScheduleKey()
          Deprecated. Return the schedule key, as part of ScheduleOwner implementation.
 java.util.Vector getSchedules()
          Deprecated. Return a vector of ScheduleTask objects Part of Instrument interface.
 byte[] getServiceCacheBytes()
          Deprecated. Get Service Cache file, returned as a byte array
 byte[] getServicePropertiesBytes()
          Deprecated. Get Service Properties file, returned as a byte array
 byte[] getServiceXMLBytes()
          Deprecated. Get Service XML file, returned as a byte array
protected abstract  PowerPolicy initCommunicationPowerPolicy()
          Deprecated. Return initial value of instrument communication power policy.
protected abstract  int initCurrentLimit()
          Deprecated. Return initial value of DPA current limit (milliamp).
 void initialize(NodeProperties nodeProperties, Parent parent, InstrumentPort port, ServiceSandBox sandBox, java.lang.String serviceXMLPath, java.lang.String servicePropertiesPath, java.lang.String cachedServicePath)
          Deprecated. Initialize service parameters.
 void initializeDriverDefaults()
          Deprecated. Load defaults for member variables using abstract methods.
protected  void initializeInstrument()
          Deprecated. Do instrument- and service-specific initialization.
protected abstract  PowerPolicy initInstrumentPowerPolicy()
          Deprecated. Return initial value of instrument power policy.
protected abstract  int initInstrumentStartDelay()
          Deprecated. Return initial value of instrument startup time in millisec.
protected abstract  int initMaxSampleBytes()
          Deprecated. Return initial value for maximum number of bytes in a instrument data sample.
protected abstract  byte[] initPromptString()
          Deprecated. Return initial value for instrument's "prompt" character.
protected abstract  byte[] initSampleTerminator()
          Deprecated. Return initial value for instrument's sample terminator
 void initServiceState()
          Deprecated. Do overhead tasks needed to prepare for sample cycle.
protected  void interruptSampling()
          Deprecated. Interrupt any sampling threads.
 void logPacket(DevicePacket devicePacket)
          Deprecated. Centralized packet logging logic
protected  void managePowerSleep()
          Deprecated. Return instrument to lowest possible power state between samples
protected  void managePowerWake()
          Deprecated. Prepare instrument for sampling; connect comms and turn on power.
 java.lang.Object parseDataPacket(SensorDataPacket packet)
          Deprecated. Parse the SensorDataPacket, returning an Object of a type that can (presumably) be interpreted by the invoker.
protected  void postSample()
          Deprecated. Called after sample has been acquired, processed and logged.
 int powerOff()
          Deprecated. Turn off instrument power.
protected  void powerOffCallback()
          Deprecated. Called after power is removed from instrument.
 int powerOn()
          Deprecated. Turn on instrument power
protected  void powerOnCallback()
          Deprecated. Called after power is applied to instrument; return when instrument is ready for use.
 void prepareToRun()
          Deprecated. Initialize service and instrument.
protected  void prepareToSample()
          Deprecated. Prepare the device for sampling; called before requestSample().
protected  void printData(byte[] buf)
          Deprecated. Print instrument data contained in input buffer.
protected  SensorDataPacket processSample(byte[] sample, int nBytes)
          Deprecated. Process raw sample bytes, return TimeStampedData object.
protected  int readSample(byte[] sample)
          Deprecated. Read raw sample bytes from serial port into buffer, return number of bytes read.
 int removeAllSchedules()
          Deprecated. Remove all schedules.
 int removeSchedule(java.lang.String taskName)
          Deprecated. Remove the specified schedule.
protected abstract  void requestSample()
          Deprecated. Request a data sample from instrument.
 void resetPortDiagnostics()
          Deprecated. Reset port diagnostics.
 int resumeSchedule(java.lang.String schedule)
          Deprecated. Resume specified schedule.
 boolean running()
          Deprecated. Indicates if run() has been successful.
 void setAttributes(ServiceAttributes attributes)
          Deprecated. Set the ServiceAttributes object for this service.
 void setClock()
          Deprecated. Set device's clock to current time; can throw NotSupportedException.
abstract  void setClock(long epochMsecs)
          Deprecated. Set device's clock; can throw NotSupportedException.
protected  void setCommunicationPowerPolicy(PowerPolicy policy)
          Deprecated. Set instrument communication power policy.
protected  void setCurrentLimit(int milliamps)
          Deprecated. Set power channel's current limit.
 void setDefaultSampleScheduleName(java.lang.String name)
          Deprecated. Set default sample schedule name
 void setInstrumentBlock(InstrumentBlock instrumentBlock)
          Deprecated.  
protected  void setInstrumentPowerPolicy(PowerPolicy policy)
          Deprecated. Set instrument power policy.
protected  void setInstrumentStartDelay(int millisec)
          Deprecated. Set instrument startup time
protected  void setMaxSampleBytes(int maxBytes)
          Deprecated. Set maximum number of bytes in a raw data sample read from instrument.
protected  void setMaxSampleTries(int maxTries)
          Deprecated. Set maximum number of tries when retrieving sample from instrument.
protected  void setPromptString(byte[] promptString)
          Deprecated. Set instrument's "prompt" character(s).
 void setProperty(byte[] propertyStrings, byte[] unused)
          Deprecated. Set value of specified instrument service properties.
protected  void setRecordType(long type)
          Deprecated. Set _recordType field
protected  void setSampleTerminator(byte[] sampleTerminator)
          Deprecated. Set sample terminator.
protected  void setSampleTimeout(long timeout)
          Deprecated. Set sampling timeout (millisec).
 byte[] shutdown()
          Deprecated. Stop the service.
protected  java.lang.String shutdownInstrument()
          Deprecated. Perform any instrument-specific shutdown actions; subclasses can override; by default does nothing.
 long sleepingUntil(ScheduleTask task)
          Deprecated. If execution thread of specified task is sleeping, return time at which it will resume; otherwise return 0.
 boolean summaryEnabled()
          Deprecated. Return true if summary generation is enabled.
 void suspend()
          Deprecated. Put service in SUSPEND state.
 int suspendSchedule(java.lang.String schedule)
          Deprecated. Suspend the specified schedule.
protected  int sync(long delayMillis)
          Deprecated. Sync default sample schedule
 int syncSchedule(java.lang.String schedule, long delayMillis)
          Deprecated. "Synchronize" specified schedule.
protected  void validateSample(byte[] _sampleBuf, int nBytes)
          Deprecated. This method can optionally be overriden so the sub-class can determines the validity of the sampled bytes.
 
Methods inherited from class org.mbari.siam.core.DeviceService
addDataListener, advertiseService, createRegistryEntry, getAttributes, getCommPortName, getFrameworkVersion, getId, getInstrumentPort, getName, getRemoteSerialPort, getRemoteSerialPort, getSamplingCount, getSamplingErrorCount, getSamplingRetryCount, getSerialPortParameters, getStatus, host, incRetryCount, initializePropertyDefaults, registryEntry, registryName, removeDataListener, resume, setInstrumentPort, setNodeProperties, setParent, setSerialPort, setStatusError, setStatusInitial, setStatusOk, setStatusSafe, setStatusSampling, setStatusShutdown, setStatusSuspend
 
Methods inherited from class java.rmi.server.UnicastRemoteObject
clone, exportObject, exportObject, exportObject, unexportObject
 
Methods inherited from class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
 
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.mbari.siam.distributed.Device
getCommPortName, getFrameworkVersion, getId, getName, getSamplingCount, getSamplingErrorCount, getSamplingRetryCount, getStatus, host, resume, test
 
Methods inherited from interface org.mbari.siam.distributed.DeviceServiceIF
getName
 

Field Detail

_log4j

protected static org.apache.log4j.Logger _log4j
Deprecated. 
Log4j logger


_messagePacket

protected DeviceMessagePacket _messagePacket
Deprecated. 
DeviceMessagePacket.


_sensorDataPacket

protected SensorDataPacket _sensorDataPacket
Deprecated. 
SensorDataPacket to be returned to clients.


_lastSensorDataPacket

protected SensorDataPacket _lastSensorDataPacket
Deprecated. 
Most recent SensorDataPacket sent


_lastPacket

protected DevicePacket _lastPacket
Deprecated. 
Most recent DataPacket sent (of any kind)


_packetLog

protected FilteredDeviceLog _packetLog
Deprecated. 
Sensor log for persistent packet storage.


RECORDTYPE_UNDEFINED

protected static final long RECORDTYPE_UNDEFINED
Deprecated. 
Default record type

See Also:
Constant Field Values

RECORDTYPE_METADATA

protected static final long RECORDTYPE_METADATA
Deprecated. 
See Also:
Constant Field Values

RECORDTYPE_DEFAULT

protected static final long RECORDTYPE_DEFAULT
Deprecated. 
See Also:
Constant Field Values

_recordType

protected long _recordType
Deprecated. 

_schedules

protected java.util.Vector _schedules
Deprecated. 
ScheduleTask container (schedules)


_defaultSampleScheduleName

protected java.lang.String _defaultSampleScheduleName
Deprecated. 
Name of default sample schedule


_instrumentAttributes

protected InstrumentServiceAttributes _instrumentAttributes
Deprecated. 
Basic instrument service attributes.

Constructor Detail

InstrumentService

public InstrumentService()
                  throws java.rmi.RemoteException
Deprecated. 
Constructor.

Throws:
java.rmi.RemoteException
Method Detail

running

public boolean running()
Deprecated. 
Indicates if run() has been successful.


enableSamplingDiagnostics

public void enableSamplingDiagnostics()
Deprecated. 
Enable sampling diagnostics.


disableSamplingDiagnostics

public void disableSamplingDiagnostics()
Deprecated. 
Disable sampling diagnostics.


initInstrumentPowerPolicy

protected abstract PowerPolicy initInstrumentPowerPolicy()
Deprecated. 
Return initial value of instrument power policy.


initCommunicationPowerPolicy

protected abstract PowerPolicy initCommunicationPowerPolicy()
Deprecated. 
Return initial value of instrument communication power policy.


initInstrumentStartDelay

protected abstract int initInstrumentStartDelay()
Deprecated. 
Return initial value of instrument startup time in millisec.


initCurrentLimit

protected abstract int initCurrentLimit()
Deprecated. 
Return initial value of DPA current limit (milliamp).


initSampleTerminator

protected abstract byte[] initSampleTerminator()
Deprecated. 
Return initial value for instrument's sample terminator


initPromptString

protected abstract byte[] initPromptString()
Deprecated. 
Return initial value for instrument's "prompt" character.


initMaxSampleBytes

protected abstract int initMaxSampleBytes()
Deprecated. 
Return initial value for maximum number of bytes in a instrument data sample.


getPromptString

protected final byte[] getPromptString()
Deprecated. 
Get instrument's "prompt" character(s).


setPromptString

protected final void setPromptString(byte[] promptString)
Deprecated. 
Set instrument's "prompt" character(s).

Parameters:
promptString - instrument's prompt string

getSampleTerminator

protected final byte[] getSampleTerminator()
Deprecated. 
Get sample terminator


setSampleTerminator

protected final void setSampleTerminator(byte[] sampleTerminator)
Deprecated. 
Set sample terminator.

Parameters:
sampleTerminator - instrument sample termination string

getSampleTimeout

protected final long getSampleTimeout()
Deprecated. 
Get sampling timeout (millisec)


setSampleTimeout

protected final void setSampleTimeout(long timeout)
                               throws RangeException
Deprecated. 
Set sampling timeout (millisec).

Parameters:
timeout - sampling timeout in millisec
Throws:
RangeException

getMaxSampleTries

protected final int getMaxSampleTries()
Deprecated. 
Get maximum number of tries when retrieving sample from instrument.


setMaxSampleTries

protected final void setMaxSampleTries(int maxTries)
                                throws RangeException
Deprecated. 
Set maximum number of tries when retrieving sample from instrument.

Parameters:
maxTries - maximum number of times to attempt sample retrieval; must be greater than 0
Throws:
RangeException

getMaxSampleBytes

protected final int getMaxSampleBytes()
Deprecated. 
Get maximum number of bytes in a data sample read from instrument.


setMaxSampleBytes

protected final void setMaxSampleBytes(int maxBytes)
                                throws RangeException
Deprecated. 
Set maximum number of bytes in a raw data sample read from instrument. Allocates sample buffer (retrieved by getSampleBuf()).

Parameters:
maxBytes - maximum number of bytes in a raw sample
Throws:
RangeException

getSampleBuf

protected final byte[] getSampleBuf()
Deprecated. 
Get raw sample buffer.


getLastSample

public final SensorDataPacket getLastSample()
                                     throws NoDataException
Deprecated. 
Get last sample packet.

Specified by:
getLastSample in interface Instrument
Throws:
NoDataException

getCurrentLimit

protected final int getCurrentLimit()
Deprecated. 
Get power channel's current limit.


setCurrentLimit

protected final void setCurrentLimit(int milliamps)
                              throws RangeException
Deprecated. 
Set power channel's current limit. Breaker will trip if limit is exceeded.

Parameters:
milliamps - current limit in milliamps
Throws:
RangeException

getInstrumentPowerPolicy

protected final PowerPolicy getInstrumentPowerPolicy()
Deprecated. 
Get instrument power policy.


getInstrumentBlock

public InstrumentBlock getInstrumentBlock()
Deprecated. 

setInstrumentBlock

public void setInstrumentBlock(InstrumentBlock instrumentBlock)
Deprecated. 

setInstrumentPowerPolicy

protected final void setInstrumentPowerPolicy(PowerPolicy policy)
Deprecated. 
Set instrument power policy.


getCommunicationPowerPolicy

protected final PowerPolicy getCommunicationPowerPolicy()
Deprecated. 
Get instrument communication power policy.


setCommunicationPowerPolicy

protected final void setCommunicationPowerPolicy(PowerPolicy policy)
Deprecated. 
Set instrument communication power policy.


getInstrumentStartDelay

protected final int getInstrumentStartDelay()
Deprecated. 
Get instrument startup time


setInstrumentStartDelay

protected final void setInstrumentStartDelay(int millisec)
                                      throws RangeException
Deprecated. 
Set instrument startup time

Parameters:
millisec - instrument startup delay in milliseconds
Throws:
RangeException

initializeDriverDefaults

public void initializeDriverDefaults()
                              throws InitializeException
Deprecated. 
Load defaults for member variables using abstract methods. Values specified in service.properties may override some of these.

Throws:
InitializeException

prepareToRun

public final void prepareToRun()
                        throws InitializeException,
                               java.lang.InterruptedException
Deprecated. 
Initialize service and instrument. This method must be invoked by outside entity before data acquisition starts. This method is declared 'final' to guarantee basic initialization

Specified by:
prepareToRun in interface Device
Overrides:
prepareToRun in class DeviceService
Throws:
InitializeException
java.lang.InterruptedException

prepareToSample

protected void prepareToSample()
                        throws java.lang.Exception
Deprecated. 
Prepare the device for sampling; called before requestSample(). By default this method does nothing, and may be overridden in the subclass.

Throws:
java.lang.Exception

postSample

protected void postSample()
Deprecated. 
Called after sample has been acquired, processed and logged. By default this method does nothing, an may be overridden in the subclass.


acquireSample

public SensorDataPacket acquireSample(boolean logPacket)
                               throws NoDataException
Deprecated. 
Acquire data sample from instrument, process it, log it, and return it to caller.

Specified by:
acquireSample in interface Instrument
Throws:
NoDataException

initServiceState

public void initServiceState()
                      throws NoDataException
Deprecated. 
Do overhead tasks needed to prepare for sample cycle. It is broken out into a separate method to allow other methods (e.g., when a service wants to override acquire()) to use the same code without cutting and pasting.

Throws:
NoDataException

cleanupServiceState

public void cleanupServiceState()
Deprecated. 
Do overhead tasks needed to clean up after sample cycle. It is broken out into a separate method to allow other methods (e.g., when a service wants to override acquire()) to use the same code without cutting and pasting.


acquire

public SensorDataPacket acquire(boolean logSample)
                         throws NoDataException
Deprecated. 
Acquire data sample from instrument, process it, and put data into output queue. Call sequence is requestSample(), readSample(), and processSample(). If these are successful, output is put into outbound message queue.

Parameters:
logSample - log data if true
Throws:
NoDataException

managePowerWake

protected void managePowerWake()
Deprecated. 
Prepare instrument for sampling; connect comms and turn on power. Uses _powerPolicy to determine appropriate action. Instrument and comms power are lumped together (no immediate need to have separate power policy for comms); may need to change.

Overrides:
managePowerWake in class DeviceService

powerOn

public int powerOn()
Deprecated. 
Turn on instrument power

Specified by:
powerOn in interface Device

managePowerSleep

protected void managePowerSleep()
Deprecated. 
Return instrument to lowest possible power state between samples

Overrides:
managePowerSleep in class DeviceService

powerOff

public int powerOff()
Deprecated. 
Turn off instrument power.

Specified by:
powerOff in interface Device

requestSample

protected abstract void requestSample()
                               throws TimeoutException,
                                      java.lang.Exception
Deprecated. 
Request a data sample from instrument.

Throws:
TimeoutException
java.lang.Exception

readSample

protected int readSample(byte[] sample)
                  throws TimeoutException,
                         java.io.IOException,
                         java.lang.Exception
Deprecated. 
Read raw sample bytes from serial port into buffer, return number of bytes read. Reads characters from serial port until sample terminator string is encountered.

Parameters:
sample - output buffer
Throws:
TimeoutException
java.io.IOException
java.lang.Exception

validateSample

protected void validateSample(byte[] _sampleBuf,
                              int nBytes)
                       throws InvalidDataException
Deprecated. 
This method can optionally be overriden so the sub-class can determines the validity of the sampled bytes. If an error is detected an InvalidDataException is thrown.

Parameters:
_sampleBuf - sample buffer containing data to validate
nBytes - Number of bytes of data to validate
Throws:
InvalidDataException - thrown if data is found to be invalid

processSample

protected SensorDataPacket processSample(byte[] sample,
                                         int nBytes)
                                  throws java.lang.Exception
Deprecated. 
Process raw sample bytes, return TimeStampedData object. By default, raw sample is encapsulated in TimeStampedData object, and no additional processing is done.

Parameters:
sample - raw sample
nBytes - number of bytes in raw sample
Throws:
java.lang.Exception

parseDataPacket

public java.lang.Object parseDataPacket(SensorDataPacket packet)
                                 throws InvalidDataException,
                                        java.rmi.RemoteException
Deprecated. 
Parse the SensorDataPacket, returning an Object of a type that can (presumably) be interpreted by the invoker. This is intended to be used with the InstrumentRegistry. The consumer of information initially invokes InstrumentRegistry.registerDataCallback(). It then receives a SensorDataPacket every time this service generates one. It can then use pass this SensorDataPacket to the parseDataPacket() method, receiving back an Object that it knows how to use. This default implementation just returns a null Object.

Throws:
InvalidDataException
java.rmi.RemoteException

getMetadataPayload

public byte[] getMetadataPayload(int components,
                                 java.lang.String[] attributeList)
                          throws java.rmi.RemoteException,
                                 InvalidPropertyException
Deprecated. 
Get requested metadata state components in a byte array containing serialized State and StateAttribute objects.

Throws:
java.rmi.RemoteException
InvalidPropertyException

getMetadata

public MetadataPacket getMetadata(byte[] cause,
                                  int components,
                                  boolean logPacket)
                           throws java.rmi.RemoteException
Deprecated. 
Create, return and optionally log a metadata packet

Specified by:
getMetadata in interface Device
Specified by:
getMetadata in class DeviceService
Throws:
java.rmi.RemoteException

getMetadata

protected MetadataPacket getMetadata(byte[] cause,
                                     int components,
                                     java.lang.String[] attributeNames,
                                     boolean logPacket)
                              throws java.rmi.RemoteException,
                                     InvalidPropertyException
Deprecated. 
Create, return, and optionally log metadata packet; if service attributes are requested, then include only specified attributes.

Parameters:
cause -
components -
attributeNames -
logPacket -
Returns:
one or more types of metadata (MetadataPacket)
Throws:
java.rmi.RemoteException
InvalidPropertyException

getFileBytes

public byte[] getFileBytes(java.lang.String file)
                    throws java.io.FileNotFoundException,
                           java.io.IOException,
                           java.lang.NullPointerException
Deprecated. 
Get the contents of a file and return them as a byte array

Throws:
java.io.FileNotFoundException
java.io.IOException
java.lang.NullPointerException

getServiceXMLBytes

public byte[] getServiceXMLBytes()
Deprecated. 
Get Service XML file, returned as a byte array


getServicePropertiesBytes

public byte[] getServicePropertiesBytes()
Deprecated. 
Get Service Properties file, returned as a byte array


getServiceCacheBytes

public byte[] getServiceCacheBytes()
Deprecated. 
Get Service Cache file, returned as a byte array


getInstrumentStateMetadata

protected byte[] getInstrumentStateMetadata()
Deprecated. 
Get instrument- and service-specific metadata. By default, this method does nothing, and can be overridden. This method should return any available configuration information that is available from the instrument device. Note that this method should NOT power-manage the device, as that is the responsibility of the caller.


initializeInstrument

protected void initializeInstrument()
                             throws InitializeException,
                                    java.lang.Exception
Deprecated. 
Do instrument- and service-specific initialization. By default, this method does nothing, and may be overridden.

Throws:
InitializeException
java.lang.Exception

getLocation

public Location getLocation()
                     throws UnknownLocationException
Deprecated. 
Return Location of device. NOT YET IMPLEMENTED.

Specified by:
getLocation in interface Device
Overrides:
getLocation in class DeviceService
Throws:
UnknownLocationException

annotate

public void annotate(byte[] annotation)
Deprecated. 
Put annotation into device data stream. Annotation will be automatically time-tagged by host.

Specified by:
annotate in interface Instrument

getSampleSchedule

public final byte[] getSampleSchedule()
Deprecated. 
Return byte-string representation of instrument sampling schedule.

Specified by:
getSampleSchedule in interface Instrument

getParent

public Device getParent()
                 throws NoParentException
Deprecated. 
Return parent Device.

Specified by:
getParent in interface Device
Throws:
NoParentException

getChildren

public Device[] getChildren()
                     throws NoChildrenException
Deprecated. 
Return child Devices.

Specified by:
getChildren in interface Device
Throws:
NoChildrenException

initialize

public void initialize(NodeProperties nodeProperties,
                       Parent parent,
                       InstrumentPort port,
                       ServiceSandBox sandBox,
                       java.lang.String serviceXMLPath,
                       java.lang.String servicePropertiesPath,
                       java.lang.String cachedServicePath)
                throws MissingPropertyException,
                       InvalidPropertyException,
                       PropertyException,
                       InitializeException,
                       java.io.IOException,
                       gnu.io.UnsupportedCommOperationException
Deprecated. 
Initialize service parameters. Called immediately after service is instantiated.

Overrides:
initialize in class DeviceService
Throws:
MissingPropertyException
InvalidPropertyException
PropertyException
InitializeException
java.io.IOException
gnu.io.UnsupportedCommOperationException

powerOnCallback

protected void powerOnCallback()
Deprecated. 
Called after power is applied to instrument; return when instrument is ready for use. By default, sleeps for 'instrumentStartDelay' milliseconds.


powerOffCallback

protected void powerOffCallback()
Deprecated. 
Called after power is removed from instrument. By default this method does nothing, and may be overridden.


suspend

public void suspend()
Deprecated. 
Put service in SUSPEND state. Release resources (e.g. serial port) for use by other applications.

Specified by:
suspend in interface Device
Overrides:
suspend in class DeviceService

getPackets

public DevicePacketSet getPackets(long startTime,
                                  long stopTime)
                           throws NoDataException
Deprecated. 
Return all logged data packets having creation time within specified time window.

Specified by:
getPackets in interface Instrument
Throws:
NoDataException

getPackets

public DevicePacketSet getPackets(long startTime,
                                  long stopTime,
                                  PacketFilter[] filters,
                                  boolean excludeStale)
                           throws NoDataException
Deprecated. 
Return all logged data packets having creation time within specified time window, that pass specified packet filters.

Specified by:
getPackets in interface Instrument
Throws:
NoDataException

clearDefaultPacketFilters

public void clearDefaultPacketFilters()
Deprecated. 
Clear default packet filters for data retrieval.

Specified by:
clearDefaultPacketFilters in interface Instrument

addDefaultPacketFilters

public void addDefaultPacketFilters(PacketFilter[] filters)
Deprecated. 
Add default packet filters for data retrieval.

Specified by:
addDefaultPacketFilters in interface Instrument

getDefaultPacketFilters

public PacketFilter[] getDefaultPacketFilters()
Deprecated. 
Get default packet filters for data retrieval.

Specified by:
getDefaultPacketFilters in interface Instrument

getProperty

public byte[] getProperty(byte[] key)
                   throws MissingPropertyException
Deprecated. 
Get value of specified service property.

Specified by:
getProperty in interface Instrument
Throws:
MissingPropertyException

setProperty

public final void setProperty(byte[] propertyStrings,
                              byte[] unused)
                       throws java.rmi.RemoteException,
                              InvalidPropertyException
Deprecated. 
Set value of specified instrument service properties. Input consists of one or more 'key=value' pairs. Each key=value pair is separated from the next pair by newline ('\n').

Specified by:
setProperty in interface Instrument
Throws:
java.rmi.RemoteException
InvalidPropertyException

cacheProperties

public void cacheProperties(byte[] note)
                     throws java.lang.Exception
Deprecated. 
Cache service properties on the node, such that current property values will be restored next time service is created on this node.

Specified by:
cacheProperties in interface Instrument
Throws:
java.lang.Exception

clearPropertiesCache

public void clearPropertiesCache(byte[] note)
                          throws java.rmi.RemoteException,
                                 java.lang.Exception
Deprecated. 
Clear properties cache.

Specified by:
clearPropertiesCache in interface Instrument
Throws:
java.rmi.RemoteException
java.lang.Exception

checkInputProperties

protected void checkInputProperties(java.util.Properties properties)
                             throws InvalidPropertyException
Deprecated. 
Check that all specified properties are allowed to be set on-the-fly. Throw PropertyException if any disallowed properties have been specified.

Throws:
InvalidPropertyException

getProperties

public java.util.Vector getProperties()
Deprecated. 
Get Vector of instrument properties; each Vector element consists of byte array with form "key=value".

Specified by:
getProperties in interface Instrument

createDefaultSampleSchedule

protected abstract ScheduleSpecifier createDefaultSampleSchedule()
                                                          throws ScheduleParseException
Deprecated. 
Return specifier for default sampling schedule.

Throws:
ScheduleParseException

sync

protected int sync(long delayMillis)
Deprecated. 
Sync default sample schedule


printData

protected void printData(byte[] buf)
Deprecated. 
Print instrument data contained in input buffer. By default does nothing, and may be overridden.


getPortDiagnostics

public byte[] getPortDiagnostics(boolean logPacket)
                          throws java.rmi.RemoteException
Deprecated. 
Get diagnostics message from device's port and optionally log it.

Specified by:
getPortDiagnostics in interface Instrument
Throws:
java.rmi.RemoteException

setRecordType

protected void setRecordType(long type)
Deprecated. 
Set _recordType field


logPacket

public void logPacket(DevicePacket devicePacket)
Deprecated. 
Centralized packet logging logic


getDevicePacketParser

public DevicePacketParser getDevicePacketParser()
Deprecated. 
NOTE: THis method should be overridden by classes who need a DevicePacketParser

Returns:
The DevicePacketParser for this instrument. Will return null if none has been defined

getPortDiagnosticsSummary

public byte[] getPortDiagnosticsSummary(boolean logPacket)
                                 throws java.rmi.RemoteException
Deprecated. 
Get diagnostics summary message from device's port and optionally log it.

Specified by:
getPortDiagnosticsSummary in interface Instrument
Throws:
java.rmi.RemoteException

resetPortDiagnostics

public void resetPortDiagnostics()
Deprecated. 
Reset port diagnostics.

Specified by:
resetPortDiagnostics in interface Instrument

getParser

public PacketParser getParser()
                       throws NotSupportedException
Deprecated. 
Get instrument's parser. Not supported, by default.

Specified by:
getParser in interface Instrument
Throws:
NotSupportedException

setClock

public void setClock()
              throws NotSupportedException
Deprecated. 
Set device's clock to current time; can throw NotSupportedException.

Specified by:
setClock in interface Instrument
Throws:
NotSupportedException

setClock

public abstract void setClock(long epochMsecs)
                       throws NotSupportedException
Deprecated. 
Set device's clock; can throw NotSupportedException.

Specified by:
setClock in interface Instrument
Throws:
NotSupportedException

getScheduleKey

public final Scheduler.ScheduleKey getScheduleKey()
Deprecated. 
Return the schedule key, as part of ScheduleOwner implementation.

Specified by:
getScheduleKey in interface ScheduleOwner

doScheduledTask

public final void doScheduledTask(ScheduleTask task)
Deprecated. 
Execute the scheduled task, as part of ScheduleOwner implementation.

Specified by:
doScheduledTask in interface ScheduleOwner

getSchedules

public final java.util.Vector getSchedules()
                                    throws java.rmi.RemoteException
Deprecated. 
Return a vector of ScheduleTask objects Part of Instrument interface.

Specified by:
getSchedules in interface Instrument
Throws:
java.rmi.RemoteException

getAllSchedules

public final java.util.Collection getAllSchedules()
Deprecated. 
Return a vector of ScheduleTask objects Part of ScheduleOwner interface.

Specified by:
getAllSchedules in interface ScheduleOwner

getDefaultSampleSchedule

public ScheduleTask getDefaultSampleSchedule()
Deprecated. 
Get the default schedule


getSchedule

public ScheduleTask getSchedule(java.lang.String name)
Deprecated. 
Get a schedule by name


getDefaultSampleScheduleName

public java.lang.String getDefaultSampleScheduleName()
Deprecated. 
Get default sample schedule name


addSchedule

public int addSchedule(java.lang.String name,
                       java.lang.String schedule,
                       boolean overwrite)
Deprecated. 
Add/replace instrument schedule

Specified by:
addSchedule in interface ScheduleOwner
Parameters:
name - Schedule name
schedule - Representation of schedule
overwrite - If true, replace existing schedule
Returns:
Scheduler.UNDEFINED,Scheduler.NOT_FOUND

addSchedule

protected int addSchedule(ScheduleTask schedule,
                          boolean overwrite)
Deprecated. 
Add the specified schedule task.


removeAllSchedules

public int removeAllSchedules()
Deprecated. 
Remove all schedules. Return integer code defined by Scheduler.

Specified by:
removeAllSchedules in interface ScheduleOwner

removeSchedule

public int removeSchedule(java.lang.String taskName)
Deprecated. 
Remove the specified schedule.

Specified by:
removeSchedule in interface ScheduleOwner

suspendSchedule

public int suspendSchedule(java.lang.String schedule)
Deprecated. 
Suspend the specified schedule.

Specified by:
suspendSchedule in interface ScheduleOwner

resumeSchedule

public int resumeSchedule(java.lang.String schedule)
Deprecated. 
Description copied from interface: ScheduleOwner
Resume specified schedule. Return integer code defined by Scheduler.

Specified by:
resumeSchedule in interface ScheduleOwner

syncSchedule

public int syncSchedule(java.lang.String schedule,
                        long delayMillis)
Deprecated. 
Description copied from interface: ScheduleOwner
"Synchronize" specified schedule. Return integer code defined by Scheduler.

Specified by:
syncSchedule in interface ScheduleOwner

setDefaultSampleScheduleName

public void setDefaultSampleScheduleName(java.lang.String name)
Deprecated. 
Set default sample schedule name


createTask

public ScheduleTask createTask(java.lang.String name,
                               ScheduleSpecifier schedule,
                               ScheduleOwner owner)
Deprecated. 
createTask is a factory method to make new schedule tasks by name. Subclasses may add new types of schedules by overriding createTask, calling super, and checking the return for null (return value if not null) before checking the name argument for one of the new added types.


setAttributes

public final void setAttributes(ServiceAttributes attributes)
Deprecated. 
Set the ServiceAttributes object for this service.

Specified by:
setAttributes in interface DeviceServiceIF
Overrides:
setAttributes in class DeviceService

shutdown

public byte[] shutdown()
Deprecated. 
Stop the service. Note that this method should NOT be synchronized, since must be able to shut down a service that is currently being sampled.

Specified by:
shutdown in interface Device
Overrides:
shutdown in class DeviceService

interruptSampling

protected void interruptSampling()
Deprecated. 
Interrupt any sampling threads.


sleepingUntil

public long sleepingUntil(ScheduleTask task)
Deprecated. 
If execution thread of specified task is sleeping, return time at which it will resume; otherwise return 0.

Specified by:
sleepingUntil in interface ScheduleOwner

shutdownInstrument

protected java.lang.String shutdownInstrument()
                                       throws java.lang.Exception
Deprecated. 
Perform any instrument-specific shutdown actions; subclasses can override; by default does nothing.

Throws:
java.lang.Exception

enableSummary

public void enableSummary()
Deprecated. 
Enable data summary generation.

Specified by:
enableSummary in interface Instrument

disableSummary

public void disableSummary()
Deprecated. 
Disable data summary generation.

Specified by:
disableSummary in interface Instrument

summaryEnabled

public boolean summaryEnabled()
Deprecated. 
Return true if summary generation is enabled.

Specified by:
summaryEnabled in interface Instrument


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.