org.jmythapi.protocol.utils
Class EnumUtils

java.lang.Object
  org.jmythapi.utils.GenericEnumUtils
      org.jmythapi.protocol.utils.EnumUtils

public class EnumUtils
extends GenericEnumUtils

This class provides enumeration related utility function.

This class provides methods to filter or find enumeration properties for a given protocol version.
The methods of this utility class are used by IPropertyAware objects to get and set their property values. Furthermore IVersionableValue flags or enumeration constants using this class to determine the current value of a flag or property.

See the parent class of this class for additional methods regarding enumeration constants.
See the javadoc of the provided methods for some usage examples of this class.

See Also:

IPropertyAware, IVersionableValue

Field Summary

Fields inherited from class org.jmythapi.utils.GenericEnumUtils

logger

Constructor Summary

EnumUtils()

Method Summary

static <E extends Enum<E>> List<String>	getDefaultValuesList(Class<E> enumClass, ProtocolVersion protoVersion) Gets the default value of all constants of a given enumeration class.
static <E extends Enum<E>> E	getEnum(Class<E> propsClass, ProtocolVersion protoVersion, int position) Returns a single Enum-property at the given position (in the backend response array) depending on the given protocol-version.
static <E extends Enum<E>> E	getEnum(Class<E> propsClass, ProtocolVersion protoVersion, String propName) Returns the Enum property for the given name and the given protocol version.
static <E extends Enum<E>> int	getEnumLength(Class<E> propsClass, ProtocolVersion protoVersion) Returns the amount of enum properties that are supported in the given protocol version.
static <E extends Enum<E>> Set<String>	getEnumNames(Class<E> propsClass, ProtocolVersion protoVersion) Returns the names of all Enum properties that are available for the given protocol version.
static <E extends Enum<E>> int	getEnumPosition(Enum<E> enumProp, ProtocolVersion protoVersion) Returns the position of the Enum property in the backend response-array, depending on the given current version.
static <E extends Enum<E>> EnumSet<E>	getEnums(Class<E> propsClass, ProtocolVersion protoVersion) Gets a set of Enum properties from a given Enum type which are supported in the given protocol versions.
static <E extends Enum<E>> EnumMap<E,ProtocolVersionRange>	getEnumVersionMap(Class<E> propsClass) Returns a map of enumeration properties.
static <E extends Enum<E>> ProtocolVersionRange	getEnumVersionRange(Enum<E> enumProp) Returns the version-range information for a given enum property.
static Long	getVersionableValue(ProtocolVersion protoVersion, IVersionableValue versionableValue) Returns the actual property value for the given protocol version.
static <E extends Enum<E> & IVersionableValue> E	getVersionableValueEnum(Class<E> propsClass, ProtocolVersion protoVersion, Long value) Determines the Enum property which has the given value when using the given protocol-version.

Methods inherited from class org.jmythapi.utils.GenericEnumUtils

copyEnumValues, copyEnumValues, getDefaultValuesList, getEnumDataType, getEnumDefaultValue, getEnumDefaultValue, getEnumMapping, getEnumNameMap, getEnumNameMap, getEnumStringType, getEnumStringType

Methods inherited from class java.lang.Object

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

Constructor Detail

EnumUtils

public EnumUtils()

Method Detail

getEnumLength

public static <E extends Enum<E>> int getEnumLength(Class<E> propsClass,
                                                    ProtocolVersion protoVersion)

Returns the amount of enum properties that are supported in the given protocol version.

Usage example:

 int length = 0;
 
 // will return 30
 length = EnumUtils.getEnumLength(IProgramInfo.Props.class, PROTO_VERSION_00);
 
 // will return 32
 length = EnumUtils.getEnumLength(IProgramInfo.Props.class, PROTO_VERSION_03);
 
 // will return 47
 length = EnumUtils.getEnumLength(IProgramInfo.Props.class, PROTO_VERSION_56);
 
 // will return 41
 length = EnumUtils.getEnumLength(IProgramInfo.Props.class, PROTO_VERSION_57);
 

Type Parameters:

E - the Enum type

Parameters:

propsClass - the Enum class

protoVersion - the protocol version

Returns:

the amount of properties supported in the given protocol version

getEnumVersionRange

public static <E extends Enum<E>> ProtocolVersionRange getEnumVersionRange(Enum<E> enumProp)

Returns the version-range information for a given enum property.

If a property is not annotated with the MythProtoVersionAnnotation, then the property is seen to be valid in the version-range [0,-1).
If a enum property is annotated with MythProtocolSkipProperty, then the property is ignored and null is returned.

Parameters:

enumProp - the Enum property

Returns:

the version-range of the property or null if the property should be skipped.

getEnumVersionMap

public static <E extends Enum<E>> EnumMap<E,ProtocolVersionRange> getEnumVersionMap(Class<E> propsClass)

Returns a map of enumeration properties. For each property the version-range is returned in which the enumeration property is supported.

Usage example:

    EnumMap<IProgramInfo.Props, ProtocolVersionRange> enumVersions = EnumUtils.getEnumVersionMap(IProgramInfo.Props.class);
    System.out.println("Property               | Version Range");
    for(Entry<IProgramInfo.Props, ProtocolVersionRange> enumVersion : enumVersions.entrySet()) {
       System.out.println(String.format(
          "%-22s | %s",
          enumVersion.getKey(), enumVersion.getValue()
       ));
    }
 

The above example will print out the following table:

 TITLE                  | [00,-1)
 SUBTITLE               | [00,-1)
 DESCRIPTION            | [00,-1)
 SEASON                 | [67,-1)
 EPISODE                | [67,-1)
 CATEGORY               | [00,-1)
 CHANNEL_ID             | [00,-1)
 CHANNEL_NUMBER         | [00,-1)
 CHANNEL_SIGN           | [00,-1)
 CHANNEL_NAME           | [00,-1)
 PATH_NAME              | [00,-1)
 FILESIZE_HIGH          | [00,57)
 FILESIZE_LOW           | [00,57)
 FILESIZE               | [57,-1)
 START_DATE_TIME        | [00,-1)
 END_DATE_TIME          | [00,-1)
 DUPLICATE              | [00,57)
 SHAREABLE              | [00,57)
 FIND_ID                | [00,-1)
 HOSTNAME               | [00,-1)
 SOURCE_ID              | [00,-1)
 CARD_ID                | [00,-1)
 INPUT_ID               | [00,-1)
 REC_PRIORITY           | [00,-1)
 REC_STATUS             | [00,-1)
 REC_ID                 | [00,-1)
 REC_TYPE               | [00,-1)
 REC_DUPS               | [00,03)
 DUP_IN                 | [03,-1)
 DUP_METHOD             | [03,-1)
 REC_START_TIME         | [00,-1)
 REC_END_TIME           | [00,-1)
 REPEAT                 | [00,57)
 PROGRAM_FLAGS          | [00,-1)
 REC_GROUP              | [03,-1)
 CHAN_COMM_FREE         | [03,57)
 CHANNEL_OUTPUT_FILTERS | [06,-1)
 SERIES_ID              | [08,-1)
 PROGRAM_ID             | [08,-1)
 INETREF                | [67,-1)
 LAST_MODIFIED          | [11,-1)
 STARS                  | [12,-1)
 ORIGINAL_AIRDATE       | [12,-1)
 HAS_AIRDATE            | [15,57)
 TIMESTRETCH            | [18,23)
 PLAY_GROUP             | [23,-1)
 REC_PRIORITY2          | [25,-1)
 PARENT_ID              | [31,-1)
 STORAGE_GROUP          | [32,-1)
 AUDIO_PROPERTIES       | [35,-1)
 VIDEO_PROPERTIES       | [35,-1)
 SUBTITLE_TYPE          | [35,-1)
 YEAR                   | [41,-1)
 

Type Parameters:

E - the Enum Type

Parameters:

propsClass - the Enum class

Returns:

a map with the version-range information for each property

getEnums

public static <E extends Enum<E>> EnumSet<E> getEnums(Class<E> propsClass,
                                                      ProtocolVersion protoVersion)

Gets a set of Enum properties from a given Enum type which are supported in the given protocol versions.

Usage example:

    EnumSet<IProgramInfo.Props> props = EnumUtils.getEnums(IProgramInfo.Props.class, PROTO_VERSION_00);
 

Type Parameters:

E - the Enum Type

Parameters:

propsClass - the Enum class

protoVersion - the protocol version

Returns:

all enum properties that are supported in the given protocol version

getEnumPosition

public static <E extends Enum<E>> int getEnumPosition(Enum<E> enumProp,
                                                      ProtocolVersion protoVersion)

Returns the position of the Enum property in the backend response-array, depending on the given current version.

Usage example:

In the following example the second call will return -1 because the property WATCHING_RECORDING is unknown in protocol version 0.

    // the following will return 3
    int pos1 = EnumUtils.getEnumPosition(IRemoteEncoderState.State.WATCHING_RECORDING, PROTO_VERSION_57)
    
    // the following will return -1
    int pos2 = EnumUtils.getEnumPosition(IRemoteEncoderState.State.WATCHING_RECORDING, PROTO_VERSION_00)
 

Type Parameters:

E - the Enum type

Parameters:

enumProp - the Enum property

protoVersion - the protocol version

Returns:

the position of the property in the response array.

getEnum

public static <E extends Enum<E>> E getEnum(Class<E> propsClass,
                                            ProtocolVersion protoVersion,
                                            String propName)

Returns the Enum property for the given name and the given protocol version.

If the specified property-name is not available for the given protocol version, null is returned.

Usage example:

In the following example the first call returns null, because the property was introduced first in version <@code 45}.

    // the following will return null
    IRemoteEncoderState.State state1 = EnumUtils.getEnum(IRemoteEncoderState.State.class,PROTO_VERSION_44,"WATCHING_VIDEO");
 
    // the following will return State.WATCHING_VIDEO
    IRemoteEncoderState.State state2 = EnumUtils.getEnum(IRemoteEncoderState.State.class,PROTO_VERSION_45,"WATCHING_VIDEO");
 

Type Parameters:

E - the Enum type

Parameters:

propsClass - the Enum class

protoVersion - the protocol version

propName - the property name

Returns:

the found Enum property or null

getEnum

public static <E extends Enum<E>> E getEnum(Class<E> propsClass,
                                            ProtocolVersion protoVersion,
                                            int position)

Returns a single Enum-property at the given position (in the backend response array) depending on the given protocol-version.

Usage example:

    // the following will return State.WATCHING_RECORDING
    IRemoteEncoderState.State state1 = EnumUtils.getEnum(IRemoteEncoderState.State.class, PROTO_VERSION_30, 3);
 
    // the following will return State.WATCHING_VIDEO
    IRemoteEncoderState.State state2 = EnumUtils.getEnum(IRemoteEncoderState.State.class, PROTO_VERSION_57, 3);
 

Type Parameters:

E - the Enum Type

Parameters:

propsClass - the class of the Enum

protoVersion - the protocol version

position - the position of the enum

Returns:

the enum property at the given position

getEnumNames

public static <E extends Enum<E>> Set<String> getEnumNames(Class<E> propsClass,
                                                           ProtocolVersion protoVersion)

Returns the names of all Enum properties that are available for the given protocol version.

Usage example:

    // getting the names of all properties for protocol version 00
    Set<String> programProps = EnumUtils.getEnumNames(IProgramInfo.Props.class, PROTO_VERSION_00);
 

Type Parameters:

E - the Enum Type

Parameters:

propsClass - the class of the Enum

protoVersion - the protocol version

Returns:

a set of enum-properties that are supported in the given protocol version

getVersionableValueEnum

public static <E extends Enum<E> & IVersionableValue> E getVersionableValueEnum(Class<E> propsClass,
                                                                               ProtocolVersion protoVersion,
                                                                               Long value)

Determines the Enum property which has the given value when using the given protocol-version.

Usage example:

The following example the property NOT_LISTED has a value of 6 in protocol version 19, but a value of 13 in protocol version 17. In protocol version 33 the value 13 belongs to the property OTHER_SHOWING.

   IProgramRecordingStatus.Status status = null;
 
   // will return Status.NOT_LISTED
   status = EnumUtils.getVersionableValueEnum(IProgramRecordingStatus.Status.class,PROTO_VERSION_19,6);
 
   // will return Status.NOT_LISTED
   status = EnumUtils.getVersionableValueEnum(IProgramRecordingStatus.Status.class,PROTO_VERSION_17,13);
 
   // will return Status.OTHER_SHOWING
   status = EnumUtils.getVersionableValueEnum(IProgramRecordingStatus.Status.class, PROTO_VERSION_33,13);
 

Type Parameters:

E - the Enum Type

Parameters:

propsClass - the class of the enum property

protoVersion - the given protocol version

value - the value of the property

Returns:

the found Enum property or null if no matching property could be found.

getVersionableValue

public static Long getVersionableValue(ProtocolVersion protoVersion,
                                       IVersionableValue versionableValue)

Returns the actual property value for the given protocol version.

Usage example:

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

Parameters:

protoVersion - the protocol version

Returns:

the property value for the given protocol version

getDefaultValuesList

public static <E extends Enum<E>> List<String> getDefaultValuesList(Class<E> enumClass,
                                                                    ProtocolVersion protoVersion)

Gets the default value of all constants of a given enumeration class.

This function uses the MythParameterDefaultValue annotation to determine the default value for a given enumeration-constant. If no annotation can be found, null is returned.

This function is mainly used when creating a new IPropertyAware object, to init the object with default parameter values.

Type Parameters:

E - the type of the enumeration constant

Parameters:

enumClass - the enumeration class

Returns:

the default value or null.