org.jmythapi.protocol.response
Interface IVersionableValue

All Known Implementing Classes:

IProgramFlags.Flags, IProgramRecordingDupInType.Flags, IProgramRecordingStatus.Status

public interface IVersionableValue

An interface for flags and enumeration constants whose values are protocol-version dependent.

This interface is a marker interface for IFlag- or Enum-properties, whose values have changed between different MythTv-protocol versions.
A flag or properties marked with this interface is capable to return different property values for different protocol versions.

Usage example:

Defining protocol-version dependent values:

In the following example the enumeration property TUNER_BUSY had a value of 12 for the protocol range [00,19) and a value of -8 for the protocol range [19,-1).

 public interface IProgramRecordingStatus extends IVersionable {
    public static enum Status implements IVersionableValue {
      ...
      TUNER_BUSY(
         // 00 <= protocol < 19
         VersionablePair.valueOf(PROTO_VERSION_00, 12),
         // 19 <= protocol
         VersionablePair.valueOf(PROTO_VERSION_19, -8) 
      ),
      ...
    }
 }
 

In the next example the value of the flag FL_WATCHED has changed in protocol version 57.

 public interface IProgramFlags extends IVersionable, IFlagGroup<IProgramFlags.Flags> {
    public static enum Flags implements IFlag, IVersionableValue {
       ...
       FL_WATCHED(			
          // 31 <= protocol < 57
          VersionablePair.valueOf(PROTO_VERSION_31, 0x00000800),	
          // 57 <= protocol		
          VersionablePair.valueOf(PROTO_VERSION_57, 0x00000200)  
       ),
       ...
    }
 }
 

Accessing protocol-version dependent values:

The following example shows how a protocol-version dependent value can be queried at runtime:

   // the following will return 12 
   Integer value1 = IProgramRecordingStatus.Status.TUNER_BUSY.getValue(PROTO_VERSION_05);
   
   // the following will return -8
   Integer value2 = IProgramRecordingStatus.Status.TUNER_BUSY.getValue(PROTO_VERSION_20);
 

Using the EnumUtils class:

The EnumUtils class provides additional methods to work with versionable values.
An example to query the value of an enumeration constant:

   // the following will return 12 
   Integer value1 = EnumUtils.getVersionableValue(PROTO_VERSION_05, IProgramRecordingStatus.Status.TUNER_BUSY);
   
   // the following will return -8
   Integer value2 = EnumUtils.getVersionableValue(PROTO_VERSION_20, IProgramRecordingStatus.Status.TUNER_BUSY);
 

An example how a value can be converted back to the proper enumeration constant:

    // the following returns TUNER_BUSY
    IProgramRecordingStatus.Status status = EnumUtils.getVersionableValueEnum(IProgramRecordingStatus.Status.class,PROTO_VERSION_19,-8);
 

See Also:

EnumUtils.getVersionableValueEnum(Class, ProtocolVersion, Long), EnumUtils.getVersionableValue(ProtocolVersion, IVersionableValue)

Nested Class Summary

static class

IVersionableValue.VersionablePair

Method Summary

Long	getValue(ProtocolVersion protoVersion) Returns the actual property value for the given protocol version.
IVersionableValue.VersionablePair[]	getValues() Gets all possible values for the given property.

Method Detail

getValues

IVersionableValue.VersionablePair[] getValues()

Gets all possible values for the given property.

There are some restrictions to the content of the array:

• If a property has only one value over time, the array only contains a single value, e.g. FL_BOOKMARK(0x00000010).
• If a property has multiple values over time, the array contains multiple pairs. The first part of a value pair is the protocol version when the new value was introduced, the second number is the property value itself.
  E.g. FL_INUSERECORDING(VersionablePair.valueOf(PROTO_VERSION_21,0x00000020),VersionablePair.valueOf(PROTO_VERSION_57,0x00100000)).

Returns:

all possible values for the given property.

getValue

Long getValue(ProtocolVersion protoVersion)

Returns the actual property value for the given protocol version.

Parameters:

protoVersion - the protocol version

Returns:

the property value for the given protocol version