org.mbari.siam.core
Class InstrumentService

java.lang.Object
  java.rmi.server.RemoteObject
      java.rmi.server.RemoteServer
          java.rmi.server.UnicastRemoteObject
              org.mbari.siam.core.DeviceService
                  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:

• Generic service and instrument initialization method
• Main control loop which invokes methods to a) request data sample from the instrument, b) read the sample from the instrument, c) process the sample, and d) log the sample. The subclass must implement the sample request method, but in many cases the sample retrieval and processing methods can be used "as is".
• Automatic power management of the instrument

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