org.mbari.siam.distributed
Class InstrumentServiceAttributes

java.lang.Object
  org.mbari.siam.distributed.ServiceAttributes
      org.mbari.siam.distributed.InstrumentServiceAttributes

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

ActiVideoServer.Attributes, AxisCamera.Attributes, CO2SubsystemMonitorAttributes, ControlLoopAttributes, DataLogger.Attributes, DummyInstrument.Attributes, ElmoService.Attributes, PhDigital.PhDigitalAttributes, PumpAttributes, SAMI.SAMIAttributes, SBE18.SBE18Attributes, ScaledAnalog.ScaledAnalogAttributes, Seabird.Attributes, StreamingInstrumentService.Attributes, WaveSensor.Attributes, WetLabsECO.Attributes, WhoiAsimet.Attributes, WorkhorseADCP.Attributes

public class InstrumentServiceAttributes
extends ServiceAttributes
implements java.io.Serializable

InstrumentServiceAttributes and its base class ServiceAttributes provide a framework for representation of instrument service state, which is an important component of service metadata. Each member variable of InstrumentServiceAttributes whose name does not being with "_" is treated as an "attribute", and each instrument service contains an instance of InstrumentServiceAttributes (or subclass). As the service runs, it sets the attribute values to reflect the service state. When generating a metadata packet, the InstrumentService framework automatically generates a representation of service state based on the ServiceAttribute values.

Moreover some attributes are "configurable", in the sense that the attribute's initial value can be specified at service runtime, in a "service properties" file. InstrumentServiceAttributes supports runtime configuration by providing methods that convert from attribute values to Java property strings, and vice versa. Each configurable attribute will have a property, the property name being the name of the attribute's member variable. E.g. an attribute declared as

 long isiID;
 

will be represented as a property named "isiID" and a property value string that can be converted to a "long" value. An attribute is configurable only if the requiredIsConfigurable() or isConfigurable() method returns 'true'.

When a service is started, the InstrumentService framework reads the service property file and invokes ServiceAttributes.fromProperties(). During this process, ServiceAttributes will verify that the property values are consistent with the attribute types, and will detect property names that do not correspond to any attribute name. Moreover, several override-able ServiceAttributes callback methods are invoked:

• isConfigurable(); returns true if value of specified attribute can be set through a property
• setAttributeCallback(); allows attribute value to be checked as its property is parsed
• missingAttributeCallback(); called when an input property is not found for an attribute
• checkValues(); called after all properties have been parsed

Extending the class

By default, the framework instantiates an InstrumentServiceAttributes object for every instrument service; this object is referenced by the InstrumentService._instrumentAttributes member. However, you can extend InstrumentServiceAttributes by adding additional attribute members, and overriding the various callback methods, adding addtional methods, etc. Any member variable that begins with underscore ("_") will NOT be treated as an attribute. Attribute members must be of one of the following:

• primitive
• String
• any object that implements org.mbari.siam.distributed.Mnemonic (e.g. PowerPolicy, ScheduleSpecifier). Note that this object *MUST* have a public no-argument constructor.

Your subclass can also include arrays of the above types. Your subclass must define a constructor that takes a DeviceServiceIF object as an argument, and invokes super() with the DeviceServiceIF argument. By default, an attribute is configurable. To define attributes that are NOT configurable, override isConfigurable(), and return 'false' if the input field name matches the name of any of your non-configurable attributes. To define mandatory configurable attributes, override missingAttributeCallback(), and throw MissingPropertyException if the input name matches that of any of your mandatory configurable attributes. To verify that all attributes have been assigned valid values, override checkValues(), and throw InvalidPropertyException if any attributes have invalid values. Note that when overriding methods with attribute name string arguments, you must take care to specify strings that correspond to member names.

Finally, instantiate your attributes subclass within your instrument service, specifying a reference to the instrument service as a constructor argument:

 MyAttributes _attributes = new MyAttributes(this);
 

This will replace the framework's InstrumentServiceAttributes object with your attributes subclass object. (Note that if you do not instantiate a new attributes object in this manner, the framework will continue to use the default InstrumentServiceAttributes object referenced by the InstrumentService._instrumentAttributes member.)

*

Author:

Tom O'Reilly

See Also:

ServiceAttributes, DeviceServiceIF, Mnemonic, Serialized Form

Field Summary

PowerPolicy	commPowerPolicy Instrument communication policy.
int	currentLimitMa Current limit (milliamp)
float	dataShelfLifeHours By default don't telemeter packets older than dataShelfLifeHours.
int	defaultSkipInterval SensorDataPackets skipped by default when subsampling
int	diagnosticSampleInterval Interval (in samples) at which to also sample port/node diagnostics.
int	errCacheLimit Number of error messages to cache before logging to MessagePacket in telemetry stream
int	maxSampleTries Maximum sampling tries
int	maxSummarySamples Sets the maximum number of samples that will be stored in the SummaryBlock.
int	nominalCurrentMa Nominal current draw (milliamp)
int	packetSetSize Max number of packets in each retrieved packet set.
int	peakCurrentMa Peak current draw (milliamp); this value is the peak current spike or individual spikes lasting longer than 50 microseconds drawn by the instrument over one sample period.
int	powerOnDelaySec
PowerPolicy	powerPolicy Instrument power policy.
boolean	rbnbAdvertiseService Advertise RBNB service on network (e.g.
int	rbnbArchiveFrames Number of frames of disk archive for RBNB DataTurbine
int	rbnbCacheFrames Number of frames of memory cache for RBNB DataTurbine
long[]	rbnbExcludeRecordTypes RecordTypes to exclude from the Turbinator
java.lang.String	rbnbServer Make data available to subscribers as it is acquired.
ScheduleSpecifier	sampleSchedule Sampling schedule.
long	sampleTimeoutMsec Sample timeout (msec)
int	startDelayMsec
int	summaryTriggerCount Sample interval between summaries
java.lang.String[]	summaryVars The names of the variables that will be summaryized.
boolean	timeSynch Time-synchronization flag; if true then synchronize instrument's clock to host clock.

Fields inherited from class org.mbari.siam.distributed.ServiceAttributes

_CONFIGURABLE_FILTER_OFF, _CONFIGURABLE_FILTER_ON, _log4j, advertiseService, className, extendedVersion, frameworkVersion, instrumentName, isiID, locationName, parentID, registryName, serviceName, serviceStatus, UUID

Constructor Summary

InstrumentServiceAttributes(DeviceServiceIF service)
Construct instrument service attributes, and associate it with specified service.

Method Summary

static InstrumentServiceAttributes	getAttributes() Return an InstrumentServiceAttributes object which is not associated with any particular service.
protected void	missingAttributeRequiredCallback(java.lang.String fieldName) Throw MissingPropertyException if specified attribute is mandatory.
protected void	requiredCheckValues() Throw InvalidPropertyException if any invalid values
protected boolean	requiredIsConfigurable(java.lang.String fieldName) Return true if specified field is "configurable", i.e.
protected void	setAttributeRequiredCallback(java.lang.String fieldName) Throw InvalidPropertyException if specified field has invalid value.

Methods inherited from class org.mbari.siam.distributed.ServiceAttributes

checkPropertyNames, checkValues, fromProperties, getConfigurableFields, getExtendedVersion, getHelp, getMnemonicValues, getTypeName, isConfigurable, missingAttributeCallback, setAttributeCallback, toConfigurableProperties, toProperties, toProperties, toPropertyStrings, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

currentLimitMa

public int currentLimitMa

Current limit (milliamp)

nominalCurrentMa

public int nominalCurrentMa

Nominal current draw (milliamp)

peakCurrentMa

public int peakCurrentMa

Peak current draw (milliamp); this value is the peak current spike or individual spikes lasting longer than 50 microseconds drawn by the instrument over one sample period.

maxSampleTries

public int maxSampleTries

Maximum sampling tries

startDelayMsec

public int startDelayMsec

sampleTimeoutMsec

public long sampleTimeoutMsec

Sample timeout (msec)

sampleSchedule

public ScheduleSpecifier sampleSchedule

Sampling schedule.

powerPolicy

public PowerPolicy powerPolicy

Instrument power policy.

commPowerPolicy

public PowerPolicy commPowerPolicy

Instrument communication policy.

timeSynch

public boolean timeSynch

Time-synchronization flag; if true then synchronize instrument's clock to host clock.

powerOnDelaySec

public int powerOnDelaySec

defaultSkipInterval

public int defaultSkipInterval

SensorDataPackets skipped by default when subsampling

packetSetSize

public int packetSetSize

Max number of packets in each retrieved packet set.

maxSummarySamples

public int maxSummarySamples

Sets the maximum number of samples that will be stored in the SummaryBlock. This will be the maximum number of samples used to calculate a summary.

summaryTriggerCount

public int summaryTriggerCount

Sample interval between summaries

summaryVars

public java.lang.String[] summaryVars

The names of the variables that will be summaryized. These should match the names that are put out by the DevicePacketParser if you want any actual summaries to occur.

errCacheLimit

public int errCacheLimit

Number of error messages to cache before logging to MessagePacket in telemetry stream

diagnosticSampleInterval

public int diagnosticSampleInterval

Interval (in samples) at which to also sample port/node diagnostics. A value of '0' means never sample.

dataShelfLifeHours

public float dataShelfLifeHours

By default don't telemeter packets older than dataShelfLifeHours. Negative value indicates 'infinite' shelf life.

rbnbServer

public java.lang.String rbnbServer

Make data available to subscribers as it is acquired. Zero-length or null value means do not publish.

rbnbCacheFrames

public int rbnbCacheFrames

Number of frames of memory cache for RBNB DataTurbine

rbnbArchiveFrames

public int rbnbArchiveFrames

Number of frames of disk archive for RBNB DataTurbine

rbnbAdvertiseService

public boolean rbnbAdvertiseService

Advertise RBNB service on network (e.g. with ZeroConf)

rbnbExcludeRecordTypes

public long[] rbnbExcludeRecordTypes

RecordTypes to exclude from the Turbinator

Constructor Detail

InstrumentServiceAttributes

public InstrumentServiceAttributes(DeviceServiceIF service)

Construct instrument service attributes, and associate it with specified service. As this is the only public constructor, it ensures that InstrumentServiceAttributes subclass instances will always be associated with a service.

Method Detail

setAttributeRequiredCallback

protected final void setAttributeRequiredCallback(java.lang.String fieldName)
                                           throws InvalidPropertyException

Description copied from class: ServiceAttributes

Throw InvalidPropertyException if specified field has invalid value.

Overrides:

setAttributeRequiredCallback in class ServiceAttributes

Throws:

InvalidPropertyException

missingAttributeRequiredCallback

protected final void missingAttributeRequiredCallback(java.lang.String fieldName)
                                               throws MissingPropertyException

Throw MissingPropertyException if specified attribute is mandatory.

Overrides:

missingAttributeRequiredCallback in class ServiceAttributes

Throws:

MissingPropertyException

requiredCheckValues

protected final void requiredCheckValues()
                                  throws InvalidPropertyException

Throw InvalidPropertyException if any invalid values

Overrides:

requiredCheckValues in class ServiceAttributes

Throws:

InvalidPropertyException

requiredIsConfigurable

protected final boolean requiredIsConfigurable(java.lang.String fieldName)

Return true if specified field is "configurable", i.e. should be converted to a property. This method can not be overrided outside of the framework, i.e. it is declared "final" within the framework.

Overrides:

requiredIsConfigurable in class ServiceAttributes

Parameters:

fieldName -

Returns:

true if field configurable

getAttributes

public static InstrumentServiceAttributes getAttributes()

Return an InstrumentServiceAttributes object which is not associated with any particular service.

Returns:

instrument service attributes