Package hec.heclib.dss

Class DSSPathname

java.lang.Object
hec.heclib.dss.DSSPathname
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DSSPathAndFilename
public class DSSPathname extends Object implements Cloneable, Serializable
DSSPathname manages a DSS pathname. A pathname is used as a key to lookup data in a DSS database. DSSPathname has methods to manage the six parts of a DSS file (A,B,C,D,E,F)
See Also:

  • Field Details

    • SECONDS_FROM_E_PART

      public static final int SECONDS_FROM_E_PART
      Operation (via input status value) to retrieve interval seconds from E part for getTsIntervalInfo()
      See Also:

    • E_PART_FROM_SECONDS

      public static final int E_PART_FROM_SECONDS
      Operation (via input status value) to retrieve E part from interval seconds for getTsIntervalInfo()
      See Also:

    • START_ENUMERATION

      public static final int START_ENUMERATION
      Operation (via input status value) to start enumerating intervals for getTsIntervalInfo()
      See Also:

    • CONTINUE_ENUMERATION

      public static final int CONTINUE_ENUMERATION
      Operation (via input status value) to continue enumerating intervals for getTsIntervalInfo()
      See Also:

    • STATUS_ERROR

      public static final int STATUS_ERROR
      Output status for getTsIntervalInfo()
      See Also:

    • STATUS_ENUMERATION_EXHAUSTED

      public static final int STATUS_ENUMERATION_EXHAUSTED
      Output status for getTsIntervalInfo()
      See Also:

    • STATUS_REGULAR_TS

      public static final int STATUS_REGULAR_TS
      Output status for getTsIntervalInfo()
      See Also:

    • STATUS_IRREGULAR_TS

      public static final int STATUS_IRREGULAR_TS
      Output status for getTsIntervalInfo()
      See Also:

    • BLOCK_INTERVAL_1DAY

      public static final int BLOCK_INTERVAL_1DAY
      Block size indicator for 1 Day block size
      See Also:

    • BLOCK_INTERVAL_1MONTH

      public static final int BLOCK_INTERVAL_1MONTH
      Block size indicator for 1 Month block size
      See Also:

    • BLOCK_INTERVAL_1YEAR

      public static final int BLOCK_INTERVAL_1YEAR
      Block size indicator for 1 Year block size
      See Also:

    • BLOCK_INTERVAL_1DECADE

      public static final int BLOCK_INTERVAL_1DECADE
      Block size indicator for 1 Decade block size
      See Also:

    • BLOCK_INTERVAL_1CENTURY

      public static final int BLOCK_INTERVAL_1CENTURY
      Block size indicator for 1 Century block size
      See Also:

    • VALUE_INTERVAL_1WEEK

      public static final int VALUE_INTERVAL_1WEEK
      Number of seconds that represents 1Week interval (actual seconds; interval always starts on Sunday)
      See Also:

    • VALUE_INTERVAL_TRI_MONTH

      public static final int VALUE_INTERVAL_TRI_MONTH
      Number of seconds that represents Tri-Month interval (not actual seconds; interval always on 1st, 11th, or 21st)
      See Also:

    • VALUE_INTERVAL_SEMI_MONTH

      public static final int VALUE_INTERVAL_SEMI_MONTH
      Number of seconds that represents Semi-Month interval (not actual seconds; interval always on 1st or 16th)
      See Also:

    • VALUE_INTERVAL_1MONTH

      public static final int VALUE_INTERVAL_1MONTH
      Number of seconds that represents 1Month interval (not actual seconds; interval always on 1st)
      See Also:

    • VALUE_INTERVAL_1YEAR

      public static final int VALUE_INTERVAL_1YEAR
      Number of seconds that represents 1Year interval (not actual seconds; interval always on January 1st)
      See Also:

    • _defaultAPart

      protected static String _defaultAPart

    • _defaultBPart

      protected static String _defaultBPart

    • _defaultCPart

      protected static String _defaultCPart

    • _defaultDPart

      protected static String _defaultDPart

    • _defaultEPart

      protected static String _defaultEPart

    • _defaultFPart

      protected static String _defaultFPart

    • _pathname

      protected String _pathname

    • _aPart

      protected String _aPart

    • _bPart

      protected String _bPart

    • _cPart

      protected String _cPart

    • _dPart

      protected String _dPart

    • _ePart

      protected String _ePart

    • _fPart

      protected String _fPart

    • _delimiter

      public String _delimiter

    • _dirty

      protected boolean _dirty

    • _empty

      protected boolean _empty

  • Constructor Details

    • DSSPathname

      public DSSPathname()

    • DSSPathname

      public DSSPathname(String pathname)

  • Method Details

    • setDefaultAPart

      public static void setDefaultAPart(String partName)

    • setDefaultBPart

      public static void setDefaultBPart(String partName)

    • setDefaultCPart

      public static void setDefaultCPart(String partName)

    • setDefaultDPart

      public static void setDefaultDPart(String partName)

    • setDefaultEPart

      public static void setDefaultEPart(String partName)

    • setDefaultFPart

      public static void setDefaultFPart(String partName)

    • clearDefaultParts

      public static void clearDefaultParts()

    • defaultAPart

      public static String defaultAPart()

    • defaultBPart

      public static String defaultBPart()

    • defaultCPart

      public static String defaultCPart()

    • defaultDPart

      public static String defaultDPart()

    • defaultEPart

      public static String defaultEPart()

    • defaultFPart

      public static String defaultFPart()

    • getDefaultAPart

      public static String getDefaultAPart()

    • getDefaultBPart

      public static String getDefaultBPart()

    • getDefaultCPart

      public static String getDefaultCPart()

    • getDefaultDPart

      public static String getDefaultDPart()

    • getDefaultEPart

      public static String getDefaultEPart()

    • getDefaultFPart

      public static String getDefaultFPart()

    • aPart

      public String aPart()

    • bPart

      public String bPart()

    • cPart

      public String cPart()

    • dPart

      public String dPart()

    • ePart

      public String ePart()

    • fPart

      public String fPart()

    • getAPart

      public String getAPart()

    • getBPart

      public String getBPart()

    • getCPart

      public String getCPart()

    • getDPart

      public String getDPart()

    • getEPart

      public String getEPart()

    • getFPart

      public String getFPart()

    • clone

      public Object clone()
      Overrides:
      clone in class Object

    • setCwmsTsId

      public void setCwmsTsId(boolean isCwmsTsId)

    • isCwmsTsId

      public boolean isCwmsTsId()

    • getParts

      public String[] getParts()

    • setParts

      public void setParts(String[] parts)

    • pathname

      public String pathname()

    • getPathname

      public String getPathname()

    • getPathname

      public String getPathname(boolean removeCollection)
      Get the pathname with any collection part removed If no collection, returns normal pathname
      Parameters:
      removeCollection - boolean
      Returns:
      String

    • getPathnameParts

      public String getPathnameParts()

    • setAPart

      public void setAPart(String partName)

    • setBPart

      public void setBPart(String partName)

    • setCPart

      public void setCPart(String partName)

    • setDPart

      public void setDPart(String partName)

    • setRealEPart

      public void setRealEPart(String partName)

    • setEPart

      public void setEPart(String partName)

    • setFPart

      public void setFPart(String partName)

    • setCollectionSequence

      public void setCollectionSequence(String collectionSequence)
      Set the collection sequence for this pathname To remove the collection sequence, send null Pathname does not have to be set first If the F part does not have a sequence, this will be added If the F part has a sequence, then this will replace If the F part has a sequence, then a null will remove the sequence
      Parameters:
      collectionSequence - String

    • getCollectionSequence

      public String getCollectionSequence()
      Returns the collection sequence from the F part of the pathname The collection sequence is only the 6 character ID string - it does not include the "C:" or "|" part of the collection If not a valid collection, returns null
      Returns:
      String

    • setCollectionSequence

      public void setCollectionSequence(int sequenceNumber)
      Sets the pathname to have a collection sequence ID with the number specified The pathname does not have to have a collection ID - this will make one If the pathname has a collection ID, this will override the current ID Calling setPathname with a collection or setFPart will override this call; call setCollectionSequence afterwards, if your pathname already has a collection ID
      Parameters:
      sequenceNumber - int

    • getCollectionSequence

      public static String getCollectionSequence(int sequenceNumber)
      Returns a 6 character collection string, given the sequence number The string will not include the "C:" or "|" characters
      Parameters:
      sequenceNumber - int
      Returns:
      String

    • isaCollectionPath

      public static boolean isaCollectionPath(String pathname)
      Determines if the pathname supplied meets the conventions of a collection Collections are identified by an F part of /C:000000|REST OF FPART/ Where 000000 is generally a sequence number, for example /YUBA/SMARTSVILLE/FLOW/01JAN1997/1HOUR/C:000042|OPERATION A/ The collections sequence (000042) must be 6 characters long
      Parameters:
      pathname - String
      Returns:
      boolean

    • isSameCollection

      public static boolean isSameCollection(String pathname1, String pathname2)
      Determines if two pathnames are in the same collection The D (Date) part is ignored and can be a different date or a date span or anything. Because The E part has to be the same.
      Parameters:
      pathname1 - String
      pathname2 - String
      Returns:
      boolean

    • getCollectionSequence

      public static String getCollectionSequence(String pathname)
      Get the sequence from a collection path. A sequence is the individual indentifying part of the collection It is usually a number, but is not restricted to that (the sequence is returned as a string) Collections are identified by an F part of /C:000000|REST OF FPART/ Where 000000 is the sequence, for example /YUBA/SMARTSVILLE/FLOW/01JAN1997/1HOUR/C:000042|OPERATION A/ The collections sequence (000042) must be 6 characters long
      Parameters:
      pathname - String
      Returns:
      sequence String, or null if not a collection path

    • setPathname

      public int setPathname(String path)

    • setPathnameParts

      public int setPathnameParts(String pathnameParts)

    • setDefaultPathnameParts

      public int setDefaultPathnameParts(String pathnameParts)

    • isValidPathname

      public static boolean isValidPathname(String pathname)
      Performs rudimentary formatting check on a pathname string. Checks that the maximum pathname length is not exceeded and that there are six pathname parts separated by seven slashes "/".
      Parameters:
      pathname - DSS pathname to be checked
      Returns:
      true if pathnamame is valid

    • areSamePathnames

      public static boolean areSamePathnames(String pathname1, String pathname2, boolean compareDpart)

    • isSamePathname

      public boolean isSamePathname(String path, boolean compareDpart)

    • isTimeSeries

      public boolean isTimeSeries()
      checks if this is a dss time series. Looks at d-part to decide. cwms time series will return false
      Returns:
      true if this is a dss time series

    • getPairedDataX

      public String getPairedDataX()

    • getPairedDataY

      public String getPairedDataY()

    • formPathname

      public void formPathname()

    • getRetrievePath

      public String getRetrievePath()

    • parsePathname

      public static int parsePathname(String path, int[] slashPositions)

    • parseDssPath

      public static Vector<String> parseDssPath(String pathname)

    • dirty

      public boolean dirty()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • hasBeenSet

      public boolean hasBeenSet()

    • pathnameToTsId

      public static String pathnameToTsId(String pathname, String type)

    • getParameterTypeString

      public static String getParameterTypeString(String dssType)

    • makeNice

      public static String makeNice(String s)

    • tsIdToPathname

      public static String tsIdToPathname(String tsId, int minsPerValue)

    • buildPathnameFromParts

      public static String buildPathnameFromParts(String aPart, String bPart, String cPart, String dPart, String ePart, String fPart)
      Build a pathname from parts. Coded to have the same behavior as a JNI call to Hec_zpath() except that null pathname parts are now acceptable (caused JNI to blow up)
      Parameters:
      aPart - The A pathname part
      bPart - The B pathname part
      cPart - The C pathname part
      dPart - The D pathname part
      ePart - The E pathname part
      fPart - The F pathname part
      Returns:
      the pathname built from the parts

    • getPathnamePartPositions

      public static int getPathnamePartPositions(String pathname, int[] startPositions, int[] endPositions, int[] lengths)
      Retrieves the start position, end position, and length of pathname parts in a pathname
      Parameters:
      pathname - The pathname. Must contain at least 7 slashes (/). Everything before the first slash and after the last slash is ignored.
      startPositions - Receives the pathname part start positions (A part in element 0, etc...). May be null if start positions are not required, or less than 6 elements if later start positions are not required
      endPositions - Receives the pathname part end positions (A part in element 0, etc...). May be null if end positions are not required, or less than 6 elements if later start positions are not required
      lengths - Receives the pathname part lengths (A part in element 0, etc...). May be null if lengths are not required or less than 6 elements if later lengths are not requires.
      Returns:

    • getPathnamePartsFromLine

      public static int getPathnamePartsFromLine(String inputLine, stringContainer aPart, stringContainer bPart, stringContainer cPart, stringContainer dPart, stringContainer ePart, stringContainer fPart)
      Parses a line with part names specified like "A=Apart, C=Cpart", etc... into actual pathname parts
      Parameters:
      inputLine - the input line to parse
      aPart - if not null, receives any A part specified in the input line
      bPart - if not null, receives any B part specified in the input line
      cPart - if not null, receives any C part specified in the input line
      dPart - if not null, receives any D part specified in the input line
      ePart - if not null, receives any E part specified in the input line
      fPart - if not null, receives any F part specified in the input line
      Returns:
      -1 if the input line doesn't contain any "=" characters; 0 otherwise

    • getRegularTsEPartFromInterval

      public static String getRegularTsEPartFromInterval(int dssVersion, int interval, int[] status)
      Retrieve the regular time series E pathname part that corresponds to the specified interval. For DSS 6 it behaves the same as a JNI call to Hec_getEPartFromInterval(interval, status)
      Parameters:
      dssVersion - the version of DSS to retrieve the E part for
      interval - the interval to retrieve the E part for. For DSS 7 in must be in seconds; for DSS 6 it must be in minutes
      status - if not null and length > 0, receives the status code. Will be 0 for valid intervals, otherwise -1
      Returns:
      the corresponding E part if the interval is valid, otherwise an empty string

    • getTSIntervalSeconds

      public static int getTSIntervalSeconds(String ePart, int[] block)
      Retrieves the interval in seconds and the optionally the block size for a DSS time series E pathname part. The E part is case insensitive and may be the beginning substring of a valid E part.

      Block sizes are as follows:

      Regular E Part Block Size Irregular E Part Block Size
      IR-Day 1Day
      IR-Month 1Month
      IR-Year 1Year
      IR-Decade 1Decade
      IR-Century 1Century
      1Second 1Day ~1Second 1Day
      2Second 1Day ~2Second 1Day
      3Second 1Day ~3Second 1Day
      4Second 1Day ~4Second 1Day
      5Second 1Day ~5Second 1Day
      6Second 1Day ~6Second 1Day
      10Second 1Day ~10Second 1Day
      15Second 1Day ~15Second 1Day
      20Second 1Day ~20Second 1Day
      30Second 1Day ~30Second 1Day
      1Minute 1Day ~1Minute 1Day
      2Minute 1Day ~2Minute 1Day
      3Minute 1Day ~3Minute 1Day
      4Minute 1Day ~4Minute 1Day
      5Minute 1Day ~5Minute 1Day
      6Minute 1Day ~6Minute 1Day
      10Minute 1Day ~10Minute 1Day
      12Minute 1Day ~12Minute 1Day
      15Minute 1Month ~15Minute 1Day
      20Minute 1Month ~20Minute 1Day
      30Minute 1Month ~30Minute 1Month
      1Hour 1Month ~1Hour 1Month
      2Hour 1Month ~2Hour 1Month
      3Hour 1Month ~3Hour 1Month
      4Hour 1Month ~4Hour 1Month
      6Hour 1Month ~6Hour 1Year
      8Hour 1Month ~8Hour 1Year
      12Hour 1Month ~12Hour 1Year
      1Day 1Year ~1Day 1Year
      1Week 1Decade ~1Week 1Decade
      Tri-Month 1Decade ~Semi-Month 1Decade
      Semi-Month 1Decade ~Tri-Month 1Decade
      1Month 1Decade ~1Month 1Century
      1Year 1Century ~1Year 1Century

      Parameters:
      ePart - The time series DSS E pathname part
      block - If non-null and length > 0, element 0 receives the block size for both regular and irregular time series. Note that block sizes for regular TS intervals and their associated pseudo TS intervals are not necessarily the same.
      • 1 if block size = 1Day
      • 2 if block size = 1Month
      • 3 if block size = 1Year
      • 4 if block size = 1Decade
      • 5 if block size = 1Century
      Returns:
      • interval seconds for valid regular TS E part
      •  0 for invalid E part
      • -1 if irregular block size = 1Day
      • -2 if irregular block size = 1Month
      • -3 if irregular block size = 1Year
      • -4 if irregular block size = 1Decade
      • -5 if irregular block size = 1Century

    • getTSBlockInfo

      public static int getTSBlockInfo(String ePart, int julian, int[] blockStartDate, int[] blockInterval, int[] valueInterval, int[] valuesPerBlock)
      Retrieves the block information for a specified time series E pathname part and julian date
      Parameters:
      ePart - The irregular TS E pathname part to retrieve the info for
      julian - The julian day to retrieve the info for
      blockStartDate - If non-null and length > 2, elements 0, 1, and 2 receive the year, month, and day of the block start date, respectively
      blockInterval - If non-null and length > 0, element 0 receives the block size
      • 1 - 1Day
      • 2 - 1Month
      • 3 - 1Year
      • 4 - 1Decade
      • 5 - 1Century
      valueInterval - If non-null and length > 0, element 0 receives the number of seconds in the interval for regular TS E pathname parts or 0 for irregular TS E pathname parts
      valuesPerBlock - If non-null and length > 0, element[0] receives the number of values stored in each block for regular TS E pathname pats or 0 for irregular TS E pathname parts
      Returns:
      0 on success, -1 on error

    • getTsIntervalInfo

      public static void getTsIntervalInfo(int[] seconds, stringContainer ePart, int[] valuesPerBlock, int[] status) throws Exception
      Retrieves information for an interval, or enumerates available intervals. To conform with the behavior of the native call
      • no pseudo-regular intervals (i.e., beginning with '~') are enumerated
      • no regular intervals < 1MIN are enumerated
      • interval names are converted to DSS 6 conventions on output
      Parameters:
      seconds - Element 0 either specifies a regular TS interval in seconds to retrieve the E Part name for, or receives the number of seconds in the specified or enumerated E Part (including irregular TS). Output values will be
      • interval seconds for valid regular TS E part
      •  0 for invalid E part
      • -1 if irregular TS block size = 1Day (the E part is IR-DAY or a pseudo-regular TS < ~30MINUTE)
      • -2 if irregular TS block size = 1Month (the E part is IR-MONTH or a pseudo-regular TS >= ~30MINUTE and < ~6HOUR)
      • -3 if irregular TS block size = 1Year (the E part is IR-YEAR or a pseudo-regular TS >= ~6HOUR and < ~1WEEK)
      • -4 if irregular TS block size = 1Decade (the E part is IR-DECADE or a pseudo-regular TS >= ~1WEEK and < ~1MONTH)
      • -5 if irregular TS block size = 1Century (the E part is IR-CENTURY or a pseudo-regular TS >= ~1MONTH)
      ePart - Either specifies the E Part name to retrieve the interval minutes for, or receives the E Part name for the specified or enumerated interval minutes
      valuesPerBlock - Element 0 receives the number of values in a block for regular TS, otherwise 0
      status -
      • INPUT: Element 0 specifies the desired operation
        • 1 to retrieve interval minutes from E part
        • 2 to retrieve E part form interval minutes
        • 3 to begin enumerating intervals
        • 4 to continue enumerating intervals
      • OUTPUT: Element 0 receives the status
        • 0 if specified E Part is regular or end of enumeration
        • 1 if specified E Part is irregular
        • 4 if in enumeration
        • -1 for error
      Throws:
      Exception

    • incrementInterval

      public static HecTime incrementInterval(HecTime topOfInterval, int intervalSeconds, int incrementCount)
      Increments a time by a specified interval and count. The interval may be a value interval (1Second..1Year) or a block interval (1Day..1Century)
      Parameters:
      topOfInterval - The time to increment. If not already at the top of the interval specified in intervalSeconds, the first increment (if there are more than one) will only move the time to the top of the next interval (or previous interval if intervalCount < 0);
      intervalSeconds - The value interval seconds or block interval indicator if < 0:
      • -1 - block interval of 1Day
      • -2 - block interval of 1Month
      • -3 - block interval of 1Year
      • -4 - block interval of 1Decade
      • -5 - block interval of 1Century
      incrementCount - The number of intervals to increment the time by. May be < 0 for decrementing
      Returns:
      The incremented/decremented time or null if intervalSeconds doesn't represent a valid value interval or block interval

    • incrementTSPathname

      public static String incrementTSPathname(String basePathname, int incrementCount, int[] status)
      Builds a new time series pathname from an existing one and a number of blocks to increment
      Parameters:
      basePathname - The pathname to build the new pathname from
      incrementCount - The number blocks to increment (< 0 for decrement). Calendar length of block is determined from pathname.
      status - If non-null and length > 0, element 0 receives 0 on success, otherwise -1
      Returns:
      The new pathname on success, otherwise null

    • getTSTopOfInterval

      public static HecTime getTSTopOfInterval(HecTime t, int intervalSeconds, int offsetSeconds)
      Gets the time at beginning top of a specified interval that includes a specified time, optionally offsetting the top of the interval by a specified amount.
      Parameters:
      t - The time that is included in the interval (including start of interval, excluding end of interval)
      intervalSeconds - The interval that includes time t. Can be determined from an E Pathname part by getTSIntervalSeconds(String, int[]).
      offsetSeconds - The optional amount of time to offset the top of the interval by
      Returns:
      The time at the beginning of the interval (optionally offset by offsetSeconds) that includes time t

    • getTSIntervalOffset

      public static int getTSIntervalOffset(HecTime t, int intervalSeconds)
      Gets the offset from the beginning of a specified interval that includes a specified time
      Parameters:
      t - The time to determine the interval offset for
      intervalSeconds - The interval that includes time t. Can be determined from an E Pathname part by getTSIntervalSeconds(String, int[]).
      Returns:
      The offset from the beginning of the interval to time t

    • irregularEPartName

      public static String irregularEPartName(int regularIntervalSeconds, boolean usePrts, boolean useRegularTimeBlock)
      Generates an irregular TS E pathname part from a regular interval specified in seconds. The generated E part can either follow the pseudo-regular time series (PRTS) pattern (regular time series E part prepended with "~") or a traditional irregular time series E part (e.g, "IR-Day"). If a traditional time series E part is generated, it may be for the block size normally used for the PRTS E part or for the block size used for the regular interval time series (for use in replicating the behavior of Heclib.Hec_zpseudorts(String, int[], int)).
      Parameters:
      regularIntervalSeconds - The number of seconds the regular interval to base the E part from. Can be determined from a regular time series E Pathname part by getTSIntervalSeconds(String, int[]).
      usePrts -
      • true - generate a pseudo-regular time series E part
      • false - generate a traditional irregular time series E part
      useRegularTimeBlock -
      Returns:
      The irregular TS E pathname part if successful, or null if regularIntervalSeconds is not a valid regular interval.

    • irregularPathname

      public static String irregularPathname(String pathname, int[] regularIntervalSeconds, boolean usePrts, boolean useRegularTimeBlock) throws Exception
      Converts a specified pathname to an irregular TS pathname based on a regular interval specified in seconds. The generated pathname can either follow the pseudo-regular time series (PRTS) pattern (have a regular time series E part prepended with "~") or be traditional irregular time series pathname (e.g, have an E part like "IR-Day"). If a traditional time series pathname is generated, the E Part may be for the block size normally used for the PRTS E part or for the block size used for the specified rectular interval (for use in replicating the behavior of Heclib.Hec_zpseudorts(String, int[], int)).
      Parameters:
      pathname - The pathname to convert.
      regularIntervalSeconds - The number of seconds the regular interval to base the E part from. Can be determined from a regular time series E Pathname part by getTSIntervalSeconds(String, int[]).
      usePrts -
      • true - generate a pseudo-regular time series E part
      • false - generate a traditional irregular time series E part
      useRegularTimeBlock -
      Returns:
      The irregular TS pathname part if successful, or null if pathname is invalid or regularIntervalSeconds is not a valid regular interval.
      Throws:
      Exception