HiRISE

HiRISE.HiPlan.Data_Slacker
Class DLinkFile

java.lang.Object
  extended by HiRISE.HiPlan.Data_Slacker.DLinkFile

public final class DLinkFile
extends Object

A representation of an MTT downlink volume file. Such a file consists of a key-value header and a list of records, one record per line, describing periods of MRO downlink activity (downlink passes).

This class is functionally comparable to the MTT DLink class. It does not, however, require SPICE and it does not require the MTT planning layer to be instantiated.

File Header

The downlink volume file's header is of the following form:

        # FILE_TYPE: DATA_VOLUME_DRAIN
        # START_TIME: 2012-085T00:00:00
        # STOP_TIME: 2012-099T00:06:32
        # PAYLOAD_BREAKDOWN (PERCENTAGE)
        # HIRISE: 35.000000
        # CRISM: 30.000000
        # CTX: 13.000000
        # MARCI: 7.000000
        # SHARAD: 15.000000
        # ELECTRA: 0.000000
        ##

The FILE_TYPE keyword and value (DATA_VOLUME_DRAIN) identify the file as a downlink volume file. The START_TIME and STOP_TIME key-value pairs identify the file's coverage.

The remainder of the header outlines each instrument's allocation of each downlink pass. If a particular pass consists of 9 megabits (Mb) and if HiRISE has 35% of the downlink (as above), then HiRISE is guaranteed 3.15 Mb.

(In practice, some instruments do not use their allotment of downlink for every pass. In such cases, the remainder is able to be used by the other instruments. The allocation in the headers is therefore effectively a minimum guarantee. There is no maximum guarantee, however.)

These values are available via methods of this class, e.g., getHirisePercent() and getStartTime().

Records

A typical record has the following form:

        2012-085T02:47:25.000,2012-085T03:33:23.000,X,9103707584

It consists of the start and stop times of the pass, the pass band, and the number of total bits allocated to the downlink. Each such record in the downlink volume file is represented by a DLinkRecord object.

Version:
1.4
Author:
Christian Schaller - UA/PIRL
See Also:
"Mars Target Tool Downlink Volume File Software Interface Specification (JPL MRO SEQ033)"

Nested Class Summary
static class DLinkFile.DLinkFileException
          An exception that indicates a problem with a DLinkFile.
 
Field Summary
static String COMMENT_MARKER
          The comment marker.
static String CRISM_PERCENT
          The CRISM_PERCENT header keyword.
static String CTX_PERCENT
          The CTX_PERCENT header keyword.
static String ELECTRA_PERCENT
          The ELECTRA_PERCENT header keyword.
static String EOH
          The end-of-header marker.
static String FILE_TYPE
          The FILE_TYPE header keyword.
static String FILE_TYPE_VALUE
          The FILE_TYPE header value.
static String HEADER_MARKER
          The marker used in the header to indicate a header keyword-value pair.
static String HIRISE_PERCENT
          The HIRISE_PERCENT header keyword.
static String ID
          Class identification name with source code version and date.
static String MARCI_PERCENT
          The MARCI_PERCENT header keyword.
static double MINIMUM_DRAIN_DURATION
          The minimum value of the drain duration for an SSR drain event.
static String PAYLOAD_BREAKDOWN
          The PAYLOAD_BREAKDOWN pseudo-header keyword.
static String SHARAD_PERCENT
          The SHARAD_PERCENT header keyword.
static String START_TIME
          The START_TIME header keyword.
static String STOP_TIME
          The STOP_TIME header keyword.
 
Constructor Summary
DLinkFile(File file)
          Creates a new DLinkFile from an input file.
DLinkFile(String filename)
          Creates a new DLinkFile from an input filename.
 
Method Summary
 double getCrismPercent()
          Gets the CRISM downlink percentage.
 double getCtxPercent()
          Gets the CTX downlink percentage.
 double getElectraPercent()
          Gets the ELECTRA downlink percentage.
 String getFilename()
          Gets the filename of this downlink volume file.
 double getHirisePercent()
          Gets the HiRISE downlink percentage.
 double getMarciPercent()
          Gets the MARCI downlink percentage.
 List<DLinkRecord> getRecords()
          Gets this file's complete list of downlink volume records.
 List<DLinkRecord> getRecords(DLinkRecord.DownlinkBand band)
          Gets this file's list of downlink volume records for a particular downlink band.
 double getSharadPercent()
          Gets the SHARAD downlink percentage.
 List<SsrDrain> getSsrDrains(double percent)
          Gets a list of SSR drains from this file for a given downlink percentage.
 List<SsrDrain> getSsrDrains(double percent, DLinkRecord.DownlinkBand band)
          Gets a list of SSR drains from this file for a particular downlink band and given a particular downlink percentage.
 Date getStartTime()
          Gets the start time from the file's header.
 Date getStopTime()
          Gets the stop time from the file's header.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

FILE_TYPE

public static final String FILE_TYPE
The FILE_TYPE header keyword. Its value must be DATA_VOLUME_DRAIN for the file to be a downlink volume file.

See Also:
Constant Field Values

FILE_TYPE_VALUE

public static final String FILE_TYPE_VALUE
The FILE_TYPE header value. If the FILE_TYPE keyword does not have this value (DATA_VOLUME_DRAIN), the file is not a downlink volume file.

See Also:
Constant Field Values

START_TIME

public static final String START_TIME
The START_TIME header keyword. Its value is the start time of the first record in the file.

See Also:
Constant Field Values

STOP_TIME

public static final String STOP_TIME
The STOP_TIME header keyword. Its value is the stop time of the last record in the file.

See Also:
Constant Field Values

PAYLOAD_BREAKDOWN

public static final String PAYLOAD_BREAKDOWN
The PAYLOAD_BREAKDOWN pseudo-header keyword. It does not have a value, nor does it have a purpose other than to serve as an annotation in the header.

See Also:
Constant Field Values

HIRISE_PERCENT

public static final String HIRISE_PERCENT
The HIRISE_PERCENT header keyword. Its value is the percentage of each downlink pass allocated to HiRISE.

See Also:
Constant Field Values

CRISM_PERCENT

public static final String CRISM_PERCENT
The CRISM_PERCENT header keyword. Its value is the percentage of each downlink pass allocated to CRISM.

See Also:
Constant Field Values

CTX_PERCENT

public static final String CTX_PERCENT
The CTX_PERCENT header keyword. Its value is the percentage of each downlink pass allocated to CTX.

See Also:
Constant Field Values

MARCI_PERCENT

public static final String MARCI_PERCENT
The MARCI_PERCENT header keyword. Its value is the percentage of each downlink pass allocated to MARCI.

See Also:
Constant Field Values

SHARAD_PERCENT

public static final String SHARAD_PERCENT
The SHARAD_PERCENT header keyword. Its value is the percentage of each downlink pass allocated to SHARAD.

See Also:
Constant Field Values

ELECTRA_PERCENT

public static final String ELECTRA_PERCENT
The ELECTRA_PERCENT header keyword. Its value is the percentage of each downlink pass allocated to ELECTRA.

See Also:
Constant Field Values

HEADER_MARKER

public static final String HEADER_MARKER
The marker used in the header to indicate a header keyword-value pair.

See Also:
Constant Field Values

COMMENT_MARKER

public static final String COMMENT_MARKER
The comment marker.

See Also:
Constant Field Values

EOH

public static final String EOH
The end-of-header marker.

See Also:
Constant Field Values

MINIMUM_DRAIN_DURATION

public static final double MINIMUM_DRAIN_DURATION
The minimum value of the drain duration for an SSR drain event. The value used here is 15 seconds, which is probably not even a large enough minimum duration: It's highly unlikely the DSN will be downlinking MRO for anything under a minute, which itself seems pretty low.

See Also:
Constant Field Values
Constructor Detail

DLinkFile

public DLinkFile(File file)
          throws DLinkFile.DLinkFileException,
                 IOException
Creates a new DLinkFile from an input file. The input file may be either a downlink volume file proper or an MTT state file that contains a DLINK keyword and value; in the latter case, the state file's downlink volume file is used instead.

Downlink volume files use the .dlink filename extension. State files use .nk.

Parameters:
file - the downlink volume or state file.
Throws:
DLinkFile.DLinkFileException - if the file is not a downlink volume file or if it has errors.
IOException - if there is a problem reading the file.
NullPointerException - if the file is null.
IllegalArgumentException - if the file does not exist or is not readable or is not a downlink volume file (or a state file).

DLinkFile

public DLinkFile(String filename)
          throws DLinkFile.DLinkFileException,
                 IOException
Creates a new DLinkFile from an input filename. The input filename may be that of either a downlink volume file proper or an MTT state file that contains a DLINK keyword and value; in the latter case, the state file's downlink volume file is used instead.

Downlink volume files use the .dlink filename extension. State files use .nk.

Parameters:
filename - the downlink volume or state filename.
Throws:
DLinkFile.DLinkFileException - if the file is not a downlink volume file or if it has errors.
IOException - if there is a problem reading the file.
NullPointerException - if the file is null.
IllegalArgumentException - if the filename is empty or if the file does not exist or is not readable or is not a downlink volume file (or a state file).
Method Detail

getFilename

public String getFilename()
Gets the filename of this downlink volume file. If the file was constructed from a downlink volume file directly, this method returns that file's name. If it was constructed from a state file, this method returns the state file's DLINK keyword value, which is the name of the downlink volume file.

Returns:
the downlink volume filename.

getStartTime

public Date getStartTime()
Gets the start time from the file's header. The start time is the start time of the earliest downlink pass.

Returns:
the start time.

getStopTime

public Date getStopTime()
Gets the stop time from the file's header. The stop time is the stop time of the last downlink pass.

Returns:
the stop time.

getHirisePercent

public double getHirisePercent()
Gets the HiRISE downlink percentage. This value is the amount of each downlink pass guaranteed to HiRISE. Note that this value is a percentage, not a fraction. If HiRISE is allocated 35% of the downlink, this method returns 35, not 0.35.

Returns:
the HiRISE downlink percentage.

getCrismPercent

public double getCrismPercent()
Gets the CRISM downlink percentage. This value is the amount of each downlink pass guaranteed to CRISM. Note that this value is a percentage, not a fraction. If CRISM is allocated 35% of the downlink, this method returns 35, not 0.35.

Returns:
the CRISM downlink percentage.

getCtxPercent

public double getCtxPercent()
Gets the CTX downlink percentage. This value is the amount of each downlink pass guaranteed to CTX. Note that this value is a percentage, not a fraction. If CTX is allocated 35% of the downlink, this method returns 35, not 0.35.

Returns:
the CTX downlink percentage.

getMarciPercent

public double getMarciPercent()
Gets the MARCI downlink percentage. This value is the amount of each downlink pass guaranteed to MARCI. Note that this value is a percentage, not a fraction. If MARCI is allocated 35% of the downlink, this method returns 35, not 0.35.

Returns:
the MARCI downlink percentage.

getSharadPercent

public double getSharadPercent()
Gets the SHARAD downlink percentage. This value is the amount of each downlink pass guaranteed to SHARAD. Note that this value is a percentage, not a fraction. If SHARAD is allocated 35% of the downlink, this method returns 35, not 0.35.

Returns:
the SHARAD downlink percentage.

getElectraPercent

public double getElectraPercent()
Gets the ELECTRA downlink percentage. This value is the amount of each downlink pass guaranteed to ELECTRA. Note that this value is a percentage, not a fraction. If ELECTRA is allocated 35% of the downlink, this method returns 35, not 0.35.

Returns:
the ELECTRA downlink percentage.

getRecords

public List<DLinkRecord> getRecords()
Gets this file's complete list of downlink volume records. Note that each record shows the total downlink volume for its pass, not that of a particular instrument.

Returns:
the list of downlink records.

getRecords

public List<DLinkRecord> getRecords(DLinkRecord.DownlinkBand band)
Gets this file's list of downlink volume records for a particular downlink band. Since MRO's Ka-band exciter is non-functioning, downlink volume files typically contain only X-band passes. It is thus almost a certainty that this method invoked with DLinkRecord.DownlinkBand.KA_BAND returns an empty list, while this method invoked with DLinkRecord.DownlinkBand.X_BAND returns the file's complete list of downlink volume records.

Note that each record shows the total downlink volume for its pass, not that of a particular instrument.

If band is null, this method returns the complete list of records.

Parameters:
band - the downlink band, which may be null.
Returns:
this file's list of records for the given band.

getSsrDrains

public List<SsrDrain> getSsrDrains(double percent,
                                   DLinkRecord.DownlinkBand band)
Gets a list of SSR drains from this file for a particular downlink band and given a particular downlink percentage. Note that the percentage is an actual percentage, not a fraction. If the drains are to have 35% of the pass allocated (for HiRISE, for example), percent must be 35, not 0.35.

If band is null, this method returns the complete list of records.

Records whose duration is less than MINIMUM_DRAIN_DURATION are skipped. Sometimes a DLINK file will have what appears to be a truncated downlink event, but the data volume of the downlink is not proportionally scaled. For example, an event truncated to two-seconds in the creation of the file might have a datavolume of 2000 megabits, leading to an absurd downlink rate of 2 Mbps.

Parameters:
percent - the percentage of available downlink allocated the drains.
band - the downlink band, which may be null.
Returns:
a list of SSR drains.

getSsrDrains

public List<SsrDrain> getSsrDrains(double percent)
Gets a list of SSR drains from this file for a given downlink percentage. Note that the percentage is an actual percentage, not a fraction. If the drains are to have 35% of the pass allocated (for HiRISE, for example), percent must be 35, not 0.35.

All downlink volume records in this file are converted to SSR drains.

Parameters:
percent - the percentage of available downlink allocated the drains.
Returns:
a list of SSR drains.

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona