org.mbari.siam.distributed
Class ServiceAttributes

java.lang.Object
  extended by org.mbari.siam.distributed.ServiceAttributes
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
InstrumentServiceAttributes

public class ServiceAttributes
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

The ServiceAttributes class provides a framework for representation of service state, which is an important component of service metadata. Each member variable whose name does not begin with underscore ("_") is treated as an "attribute". NOTE: any private member names MUST be preceded by underscore. Each instrument service contains an instance of ServiceAttributes (or subclass). As the service runs, the instrument service 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. ServiceAttributes 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:

The ServiceAttributes class can be extended by adding additional attribute members, and overriding the various callback methods. Attribute members must be declared non-static, and of one of the following types: Attributes can also be arrays of the above types.

Author:
Tom O'Reilly
See Also:
InstrumentServiceAttributes, Importable, Serialized Form

Field Summary
protected static boolean _CONFIGURABLE_FILTER_OFF
          Deal with all properties, configurable and non-configurable.
protected static boolean _CONFIGURABLE_FILTER_ON
          Deal with configurable attributes only.
protected static org.apache.log4j.Logger _log4j
          Log4j logger
 boolean advertiseService
          Advertise service on network (e.g.
 byte[] className
          ServiceAttributes subclass name.
 byte[] extendedVersion
          Application software version
 byte[] frameworkVersion
          SIAM framework software version
 java.lang.String instrumentName
          Instrument Name
 long isiID
          Unique ISI device ID.
 java.lang.String locationName
          Device location name
 long parentID
          Parent's ISI device ID.
 java.lang.String registryName
          Name for lookups in the Registry
 byte[] serviceName
          Service mnemonic name.
 int serviceStatus
          Instrument service status.
 java.lang.String UUID
          Instrument UUID
 
Constructor Summary
ServiceAttributes()
          Create attributes.
ServiceAttributes(DeviceServiceIF service)
          Create attributes object and associate it with specified service.
 
Method Summary
 void checkPropertyNames(java.util.Properties properties, boolean configurableOnly)
          Throw InvalidPropetyException if any property name does not correspond to anattribute.
 void checkValues()
          Called when all attributes have been parsed.
 void fromProperties(java.util.Properties properties, boolean unknownPropertyCheck)
          Set values in an object instance of a class from the ServiceAttributes hierarchy, according to input property string values.
 java.lang.reflect.Field[] getConfigurableFields(java.lang.Class c)
           
protected  java.lang.String getExtendedVersion()
          Return software version identifier of extensions to the framework, i.e.
 java.lang.String getHelp()
          Show valid property names and types.
 java.lang.String[] getMnemonicValues(java.lang.Class fieldType)
           
 java.lang.String getTypeName(java.lang.reflect.Field field)
           
protected  boolean isConfigurable(java.lang.String attributeName)
          Return true if specified attribute is "configurable", i.e.
protected  void missingAttributeCallback(java.lang.String attributeName)
          Called when specified attribute was not found.
protected  void missingAttributeRequiredCallback(java.lang.String fieldName)
          Throw MissingPropertyException if specified attribute is mandatory; at least one subclass must implement this method.
protected  void requiredCheckValues()
          Throw InvalidPropertyException if any invalid values; at least one subclass must implement this method.
protected  boolean requiredIsConfigurable(java.lang.String fieldName)
          Return true if specified field is "configurable", i.e.
protected  void setAttributeCallback(java.lang.String attributeName, java.lang.String valueString)
          Called when specified attribute has been found.
protected  void setAttributeRequiredCallback(java.lang.String fieldName)
          Throw InvalidPropertyException if specified field has invalid value.
 java.util.Properties toConfigurableProperties()
          Convert all configurable attributes to Java properties, for an object instance in the ServiceAttributes hierarchy.
 java.util.Properties toProperties()
          Convert attributes to Java properties, for an object instance in the ServiceAttributes hierarchy.
 java.util.Properties toProperties(java.lang.String[] attributeNames)
          Convert specified attributes to Java properties.
static java.lang.String toPropertyStrings(java.util.Properties properties)
          Convert to property string representation.
 java.lang.String toString()
          Convert to string representation, all attributes (configurable and non-configurable).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_log4j

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


_CONFIGURABLE_FILTER_ON

protected static final boolean _CONFIGURABLE_FILTER_ON
Deal with configurable attributes only.

See Also:
Constant Field Values

_CONFIGURABLE_FILTER_OFF

protected static final boolean _CONFIGURABLE_FILTER_OFF
Deal with all properties, configurable and non-configurable.

See Also:
Constant Field Values

serviceName

public byte[] serviceName
Service mnemonic name. Define as a byte array rather than String, since ServiceAttributes object might need to be passed over low-bandwidth link.


isiID

public long isiID
Unique ISI device ID.


parentID

public long parentID
Parent's ISI device ID.


UUID

public java.lang.String UUID
Instrument UUID


instrumentName

public java.lang.String instrumentName
Instrument Name


frameworkVersion

public byte[] frameworkVersion
SIAM framework software version


extendedVersion

public byte[] extendedVersion
Application software version


serviceStatus

public int serviceStatus
Instrument service status.


className

public byte[] className
ServiceAttributes subclass name.


registryName

public java.lang.String registryName
Name for lookups in the Registry


advertiseService

public boolean advertiseService
Advertise service on network (e.g. with ZeroConf)


locationName

public java.lang.String locationName
Device location name

Constructor Detail

ServiceAttributes

public ServiceAttributes()
Create attributes.


ServiceAttributes

public ServiceAttributes(DeviceServiceIF service)
Create attributes object and associate it with specified service.

Method Detail

toString

public java.lang.String toString()
Convert to string representation, all attributes (configurable and non-configurable).

Overrides:
toString in class java.lang.Object

getHelp

public java.lang.String getHelp()
Show valid property names and types.


getConfigurableFields

public java.lang.reflect.Field[] getConfigurableFields(java.lang.Class c)

getTypeName

public java.lang.String getTypeName(java.lang.reflect.Field field)

getMnemonicValues

public java.lang.String[] getMnemonicValues(java.lang.Class fieldType)

toPropertyStrings

public static java.lang.String toPropertyStrings(java.util.Properties properties)
Convert to property string representation.


toProperties

public java.util.Properties toProperties()
Convert attributes to Java properties, for an object instance in the ServiceAttributes hierarchy. The resulting properties are named after members of the ServiceAttributes class (or subclass). E.g. InstrumentServiceAttributes.toProperties() results in properties named mnemonicName, deviceID, timeSynch, etc.


toConfigurableProperties

public java.util.Properties toConfigurableProperties()
Convert all configurable attributes to Java properties, for an object instance in the ServiceAttributes hierarchy. The resulting properties are named after members of the ServiceAttributes class (or subclass). E.g. InstrumentServiceAttributes.toProperties() results in properties named mnemonicName, deviceID, timeSynch, etc.


toProperties

public java.util.Properties toProperties(java.lang.String[] attributeNames)
                                  throws InvalidPropertyException
Convert specified attributes to Java properties. Throws InvalidPropertyException if any input names do not correspond to an attribute.

Parameters:
attributeNames - Names of attributes to be converted
Returns:
Attributes in 'properties' form
Throws:
InvalidPropertyException

fromProperties

public final void fromProperties(java.util.Properties properties,
                                 boolean unknownPropertyCheck)
                          throws PropertyException
Set values in an object instance of a class from the ServiceAttributes hierarchy, according to input property string values. Input properties have names that map to object instance variables. E.g. InstrumentServiceAttributes.fromProperties() parses properties named mnemonicName, deviceID, timeSynch, etc.

Parameters:
properties - Input properties to be parsed
unknownPropertyCheck - set to true if method should check for unknown property names
Throws:
PropertyException

missingAttributeRequiredCallback

protected void missingAttributeRequiredCallback(java.lang.String fieldName)
                                         throws MissingPropertyException
Throw MissingPropertyException if specified attribute is mandatory; at least one subclass must implement this method.

Throws:
MissingPropertyException

setAttributeRequiredCallback

protected void setAttributeRequiredCallback(java.lang.String fieldName)
                                     throws InvalidPropertyException
Throw InvalidPropertyException if specified field has invalid value.

Parameters:
fieldName -
Throws:
InvalidPropertyException

requiredCheckValues

protected void requiredCheckValues()
                            throws InvalidPropertyException
Throw InvalidPropertyException if any invalid values; at least one subclass must implement this method.

Throws:
InvalidPropertyException

requiredIsConfigurable

protected 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.

Parameters:
fieldName -
Returns:
true if configurable

isConfigurable

protected boolean isConfigurable(java.lang.String attributeName)
Return true if specified attribute is "configurable", i.e. can be initialized at startup by a property. Subclasses can override this method.

Parameters:
attributeName - name of attribute to test
Returns:
true if configurable

missingAttributeCallback

protected void missingAttributeCallback(java.lang.String attributeName)
                                 throws MissingPropertyException
Called when specified attribute was not found. Throw MissingPropertyException if specified attribute is mandatory.

Parameters:
attributeName - name of missing attribute
Throws:
MissingPropertyException

setAttributeCallback

protected void setAttributeCallback(java.lang.String attributeName,
                                    java.lang.String valueString)
                             throws InvalidPropertyException
Called when specified attribute has been found. Throw InvalidPropertyException if specified attribute has invalid value. Note that the ServiceAttributes base class automatically validates the value type before setAttributeCallback() is invoked; so this method needs only to validate the value.

Parameters:
attributeName - name of parsed attribute
Throws:
InvalidPropertyException

checkValues

public void checkValues()
                 throws InvalidPropertyException
Called when all attributes have been parsed. Throw InvalidPropertyException if any invalid attribute values found

Throws:
InvalidPropertyException

getExtendedVersion

protected java.lang.String getExtendedVersion()
Return software version identifier of extensions to the framework, i.e. of the instrument service subclass code. Extensions can (and generally should) override this.

Returns:
"UNK" by defaule

checkPropertyNames

public final void checkPropertyNames(java.util.Properties properties,
                                     boolean configurableOnly)
                              throws InvalidPropertyException
Throw InvalidPropetyException if any property name does not correspond to anattribute.

Parameters:
properties - Properties object
configurableOnly - Property names must match configurable attribute names
Throws:
InvalidPropertyException


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.