org.jmythapi.protocol.annotation
Annotation Type MythProtoVersionAnnotation

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD,PARAMETER,TYPE})
public @interface MythProtoVersionAnnotation

This annotation specifies a MythTV protocol version range.

Depending on the MythTV protocol version the backend is speaking, different protocol commands are supported and the required request- and received response-parameters may be different. This annotation is used to specify for which MythTV-protocol versions a given protocol-request-command or protocol response-parameter is valid. It specifies a version range as an open interval.

Protocol Version Range examples:

• [3,10):
  A command or property was introduced in protocol version 03, but was removed in protocol version 10. Therefore it can only be used till version 09.
• [20,-1):
  A command or property was introduced in protocol version 20 and is still available in the last version
• [0,20):
  A command or property was introduced in the first known MythTV version, but was removed in protocol version 20. Therefore the element can be used till version 19.
• [0,-1):
  A command or property is supported starting with the first MythTV version and is still available in the last version.

Protocol Versions:

See here for enumeration constants defining all known versions of the MythTV protocol.

The latest supported protocol version can be determined via ProtocolVersion.getMaxVersion().
The current version used by a MythTV backend connection or protocol element can be determined via IVersionable.getVersionNr().
Different version can be compared using Enum.compareTo(E).

Usage Examples

This section shows how the version annotation can be used on functions, function parameters or enumeration constants.

Annotation on functions:

In the following example the method getNextFreeRecorder was introduced in version 03 and is still valid, because no upper bound was specified.

 import static org.jmythapi.protocol.ProtocolVersion.PROTO_VERSION_03;
 
 public interface IBackend extends Closeable {
 	
     @MythProtoVersionAnnotation(from=PROTO_VERSION_03)
     public abstract IRecorderInfo getNextFreeRecorder() throws IOException;
     
 }
 

In the next example the backend method reactivateRecording was introduced in version 05 but was removed in version 19.

 import static org.jmythapi.protocol.ProtocolVersion.PROTO_VERSION_05;
 import static org.jmythapi.protocol.ProtocolVersion.PROTO_VERSION_19;
 ...
 
 public interface IBackend {
   ...
   /**
    * @since 05
    * @deprecated 19
    */
   @MythProtoVersionAnnotation(from = PROTO_VERSION_05, to = PROTO_VERSION_19)
   public abstract boolean reactivateRecording(IProgramInfo programInfo) throws IOException;
   ...
 }
 

Please note that many functions are usable (maybe with some restrictions) beyond the given protocol range, if an alternative set of functions can be used to achieve the same result. If such an "extended" version-range is available for a function, then the toFallback and fromFallback properties of the annotation are specified, and the version numbers are mentioned as "fallback-from"- and "fallback-to"-version in the functions javadoc.

Annotation on Enumeration constants:

In the next example the enum property REPEAT was removed in protocol version 57 and the property REC_GROUP was added in version 03.

 import static org.jmythapi.protocol.ProtocolVersion.PROTO_VERSION_03;
 import static org.jmythapi.protocol.ProtocolVersion.PROTO_VERSION_57;
 
 public interface IProgramInfo {
   public static enum Props {
     ...
     @MythProtoVersionAnnotation(to=PROTO_VERSION_57)
     REPEAT,	    
     ...
     @MythProtoVersionAnnotation(from=PROTO_VERSION_03)
     REC_GROUP,
     ...
   }
 }
 

Annotation on function parameters

Method parameters can also be marked with the version annotation. Parameters that are not supported in the current protocol version are just ignored or are converted into other reasonable values if possible. Read the javadoc of the method for the exact behavior.

   /**
    * @since 00
    */
   @MythProtoVersionAnnotation(from = PROTO_VERSION_00)
   public IFileTransfer annotateFileTransfer(
      String fileName,
      @MythProtoVersionAnnotation(from = PROTO_VERSION_29) Boolean useReadAhead,
      @MythProtoVersionAnnotation(from = PROTO_VERSION_29) Integer retries,
      @MythProtoVersionAnnotation(from = PROTO_VERSION_44) String storageGroup
    ) throws IOException;
 

Javadoc Taglet

There is a new javadoc-taglet @mythProtoVersionRange that generates an additional table in javadoc, showing the protocol-range of an element including some metadata about the protocol- versions, e.g. the commit date or a link to the Git revision when the element was added or removed to the protocol.
See here for an example.

Additional Metadata:

Its also possible to add additional metadata to a MythProtoVersionAnnotation or to a ProtocolVersion constant. See ProtocolVersionInfo for details.
This additional metadata is only used for documentation purposes and will be displayed by the @mythProtoVersionRange taglet.

See Also:

ProtocolVersion, ProtocolVersionInfo, MythProtoVersionMetadata, IVersionable

Optional Element Summary

ProtocolVersion	from Gets the MythTV-protocol version when a command or parameter was introduced.
ProtocolVersion[]	fromFallback Gets fallback versions.
MythProtoVersionMetadata[]	fromInfo Gets metadata about the lower protocol range.
ProtocolVersion	to Gets the version when a command or parameter was removed.
ProtocolVersion[]	toFallback Gets fallback versions.
MythProtoVersionMetadata[]	toInfo Gets metadata about the higher protocol range.

from

public abstract ProtocolVersion from

Gets the MythTV-protocol version when a command or parameter was introduced.

Returns:

the protocol version when a command or parameter was introduced.

Default:

org.jmythapi.protocol.ProtocolVersion.PROTO_VERSION_00

fromInfo

public abstract MythProtoVersionMetadata[] fromInfo

Gets metadata about the lower protocol range.

This metadata could be, e.g. the SVN-Revision or Git commit when the command or property was introduced.

Returns:

metadata about the command- or property-introduction

Default:

{}

to

public abstract ProtocolVersion to

Gets the version when a command or parameter was removed.

Returns:

the MythTV-protocol version when the command was removed. -1 means that the command is still valid.

Default:

org.jmythapi.protocol.ProtocolVersion.PROTO_VERSION_LATEST

toInfo

public abstract MythProtoVersionMetadata[] toInfo

Gets metadata about the higher protocol range.

This metadata could be, e.g. the SVN-Revision or Git commit when the command or property was removed.

Returns:

metadata about the command- or property-removal.

Default:

{}

fromFallback

public abstract ProtocolVersion[] fromFallback

Gets fallback versions. This versions are set, if the given protocol element can be used beyond the given protocol range, by using a fallback code.

Returns:

the fallback versions

Default:

{}

toFallback

public abstract ProtocolVersion[] toFallback

Gets fallback versions. This versions are set, if the given protocol element can be used beyond the given protocol range, by using a fallback code.

Returns:

the fallback versions

Default:

{}