org.mbari.siam.distributed
Class InstrumentServiceAttributes

java.lang.Object
  extended by org.mbari.siam.distributed.ServiceAttributes
      extended by 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:

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: 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


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.