Class CatalogID


  • public final class CatalogID
    extends java.lang.Object
    A unique identifier for a particular version of a particular plug-in bundle. This ID consists of two parts: a UUID that is unique to a given plug-in bundle, and an encoded date that identifies the version.
    Author:
    Chris Jennings
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        CatalogID()
      Creates an ID with a new UUID and the current time.
        CatalogID​(CatalogID parent)
      Creates an ID with a UUID taken from the ID of an existing bundle and the current time.
        CatalogID​(java.util.UUID uuid)
      Creates an ID with the given UUID and the current time.
      protected CatalogID​(java.util.UUID uuid, java.util.GregorianCalendar date)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareDates​(CatalogID rhs)
      Compares the date of this ID with another ID, without considering whether the UUIDs match.
      boolean equals​(java.lang.Object obj)
      Returns true if this ID and rhs are equal, meaning that rhs is also an ID, and its UUID and date match exactly.
      static CatalogID extractCatalogID​(java.lang.String text)
      If a string contains an ID string description of the form CATALOGID{uuid:date} returns it as a CatalogID.
      static CatalogID getCatalogID​(java.io.File bundleFile)
      Get a bundle's catalog ID.
      java.util.GregorianCalendar getDate()
      Returns the date (timestamp) for this ID.
      java.lang.String getFormattedDate()
      Returns the ID's date as a string formatted for ease of reading by the user.
      java.util.UUID getUUID()
      Returns the unique identifier (UUID) for this ID.
      int hashCode()  
      boolean isOlderThan​(CatalogID rhs)
      Compares this ID to another ID and returns true if and only if they have the same UUID and the date of rhs is newer than the date of this ID.
      static void main​(java.lang.String[] args)
      A command line tool for creating and updating IDs.
      boolean sameUUID​(CatalogID rhs)
      Compares the UUID of this ID with another ID returns true if and only if they are the same.
      static void setCatalogID​(java.io.File bundleFile, CatalogID id)
      Change a bundle's catalog id.
      java.lang.String toDateString()  
      java.lang.String toString()  
      java.lang.String toUUIDString()  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • CatalogID

        public CatalogID()
        Creates an ID with a new UUID and the current time. This is used when adding a new bundle to a catalog.
      • CatalogID

        public CatalogID​(CatalogID parent)
        Creates an ID with a UUID taken from the ID of an existing bundle and the current time. This is used to update an existing bundle when a new version becomes available.
        Parameters:
        parent -
      • CatalogID

        public CatalogID​(java.util.UUID uuid)
        Creates an ID with the given UUID and the current time.
        Parameters:
        uuid - the UUID part of the new ID
      • CatalogID

        protected CatalogID​(java.util.UUID uuid,
                            java.util.GregorianCalendar date)
    • Method Detail

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • toDateString

        public java.lang.String toDateString()
      • toUUIDString

        public java.lang.String toUUIDString()
      • getFormattedDate

        public java.lang.String getFormattedDate()
        Returns the ID's date as a string formatted for ease of reading by the user.
        Returns:
        a nicely formated string for the ID's timestamp
      • extractCatalogID

        public static CatalogID extractCatalogID​(java.lang.String text)
        If a string contains an ID string description of the form CATALOGID{uuid:date} returns it as a CatalogID. Otherwise returns null.
        Parameters:
        text - the string to parse
        Returns:
        the bundle ID contained in the string, or null
      • sameUUID

        public boolean sameUUID​(CatalogID rhs)
        Compares the UUID of this ID with another ID returns true if and only if they are the same.
        Parameters:
        rhs - the ID to compare UUIDs with
        Returns:
        true if both IDs have the same UUID
      • equals

        public boolean equals​(java.lang.Object obj)
        Returns true if this ID and rhs are equal, meaning that rhs is also an ID, and its UUID and date match exactly.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the object to test for equality
        Returns:
        true is and only if the this is equal to rhs
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • isOlderThan

        public boolean isOlderThan​(CatalogID rhs)
        Compares this ID to another ID and returns true if and only if they have the same UUID and the date of rhs is newer than the date of this ID.
        Parameters:
        rhs - the ID to compare this ID to
        Returns:
        true if both IDs have the same UUID and this ID is older than the rhs ID
      • compareDates

        public int compareDates​(CatalogID rhs)
        Compares the date of this ID with another ID, without considering whether the UUIDs match. Returns a negative value if rhs is newer, zero if they are the same, or a positive value if this ID is newer.
        Parameters:
        rhs - the ID to compare this ID to
        Returns:
        a negative, zero, or positive value as this ID is older, the same age, or newer than the specified ID
      • getUUID

        public java.util.UUID getUUID()
        Returns the unique identifier (UUID) for this ID.
        Returns:
        this ID's UUID part
      • getDate

        public java.util.GregorianCalendar getDate()
        Returns the date (timestamp) for this ID.
        Returns:
        this ID's date part
      • getCatalogID

        public static CatalogID getCatalogID​(java.io.File bundleFile)
                                      throws java.io.IOException
        Get a bundle's catalog ID. If the bundle is Web-safe, it is first unwrapped to a temporary file. The bundle's root file is located, and it will be parsed and its embedded ID will be returned. Note that if you might wish to access the rest of the plug-in's root file content, it will be more efficient to use code similar to the following:
         PluginBundle bundle = new PluginBundle( bundleFile );
         PluginRoot root = pb.getPluginRoot();
         id = root.getCatalogID();
         // do other things with the root file
         
        Parameters:
        bundleFile - the plug-in bundle to extract an ID from
        Returns:
        the UUID listed in the root file, or null
        Throws:
        java.io.IOException - if an error occurs while parsing the UUID
      • setCatalogID

        public static void setCatalogID​(java.io.File bundleFile,
                                        CatalogID id)
                                 throws java.io.IOException
        Change a bundle's catalog id. This involves copying the bundle to a temporary location, then writing over the original bundle but replacing the eons-plugin root file to include the new UUID.
        Parameters:
        bundleFile - the file that contains a plug-in bundle
        id - the new ID
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.NullPointerException - if bundleFile is null
      • main

        public static void main​(java.lang.String[] args)
        A command line tool for creating and updating IDs. It accepts zero or more arguments with the following form:
        [--touch]  [--xfile] [--tfile] [n...] [existing ID...]
        Where:
        --touch
        generate and print the date part of an ID with current timestamp
        --xfile
        will extract and print the ID from plug-in bundle 'file'
        --tfile
        will generate or touch the ID in plug-in bundle 'file'
        n
        a series of one or more integers will generate a group of that many IDs
        existing ID
        using an existing ID will touch the ID (make the date current)
        Generated IDs and timestamps are printed to the output stream, unless using the --t option (in which case the root file of the bundle itself is modified).
        Parameters:
        args - the command line arguments for the tool