Package org.eclipse.equinox.p2.engine

Interface IProfileRegistry

  • public interface IProfileRegistry
    This encapsulates the access to the profile registry. It deals with persistence in a transparent way.
    Since:
    2.0
    Restriction:
    This interface is not intended to be implemented by clients.
    Restriction:
    This interface is not intended to be extended by clients.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String SELF
      A special profile id representing the profile of the currently running system.
      static java.lang.String SERVICE_NAME
      Service name constant for the profile registry service.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      IProfile addProfile​(java.lang.String id)
      Add the given profile to this profile registry.
      IProfile addProfile​(java.lang.String id, java.util.Map<java.lang.String,​java.lang.String> properties)
      Add the given profile to this profile registry.
      boolean containsProfile​(java.lang.String profileId)
      Returns whether this profile registry contains a profile with the given id.
      IProfile getProfile​(java.lang.String id)
      Return the profile in the registry that has the given id.
      IProfile getProfile​(java.lang.String id, long timestamp)
      Return the profile in the registry that has the given id and timestamp.
      IProfile[] getProfiles()
      Return an array of profiles known to this registry.
      java.util.Map<java.lang.String,​java.lang.String> getProfileStateProperties​(java.lang.String id, long timestamp)
      Return all properties for a particular profile state.
      java.util.Map<java.lang.String,​java.lang.String> getProfileStateProperties​(java.lang.String id, java.lang.String key)
      Return a map of profile timestamps to values for all profile states that contain the given property key.
      boolean isCurrent​(IProfile profile)
      Check if the given profile from this profile registry is up-to-date.
      long[] listProfileTimestamps​(java.lang.String id)
      Return an array of timestamps in ascending order for the profile id in question.
      void removeProfile​(java.lang.String id)
      Remove the given profile from this profile registry.
      void removeProfile​(java.lang.String id, long timestamp)
      Remove the given profile snapshot from this profile registry.
      IStatus removeProfileStateProperties​(java.lang.String id, long timestamp, java.util.Collection<java.lang.String> keys)
      Remove all properties with matching keys from the given profile state.
      IStatus setProfileStateProperties​(java.lang.String id, long timestamp, java.util.Map<java.lang.String,​java.lang.String> properties)
      Set properties on a specific profile state.
      IStatus setProfileStateProperty​(java.lang.String id, long timestamp, java.lang.String key, java.lang.String value)
      Set a specific property on a specific profile state.

    • Field Detail

      • SELF

        static final java.lang.String SELF
        A special profile id representing the profile of the currently running system. This constant can be used when invoking getProfile(String) to obtain the profile of the currently running system. Note that a given profile registry may not have a defined self profile, for example if the running system doesn't have a profile, or resides in a different profile registry.
        See Also:
        Constant Field Values

      • SERVICE_NAME

        static final java.lang.String SERVICE_NAME
        Service name constant for the profile registry service.

    • Method Detail

      • getProfile

        IProfile getProfile​(java.lang.String id)
        Return the profile in the registry that has the given id. If it does not exist, then return null.
        Parameters:
        id - the profile identifier
        Returns:
        the profile or null

      • getProfile

        IProfile getProfile​(java.lang.String id,
                    long timestamp)
        Return the profile in the registry that has the given id and timestamp. If it does not exist, then return null.
        Parameters:
        id - the profile identifier
        timestamp - the profile's timestamp
        Returns:
        the profile or null

      • listProfileTimestamps

        long[] listProfileTimestamps​(java.lang.String id)
        Return an array of timestamps in ascending order for the profile id in question. If there are none, then return an empty array.
        Parameters:
        id - the id of the profile to list timestamps for
        Returns:
        the array of timestamps

      • getProfiles

        IProfile[] getProfiles()
        Return an array of profiles known to this registry. If there are none, then return an empty array.
        Returns:
        the array of profiles

      • addProfile

        IProfile addProfile​(java.lang.String id)
             throws ProvisionException
        Add the given profile to this profile registry.
        Parameters:
        id - the profile id
        Returns:
        the new empty profile
        Throws:
        ProvisionException - if a profile with the same id is already present in the registry.

      • addProfile

        IProfile addProfile​(java.lang.String id,
                    java.util.Map<java.lang.String,​java.lang.String> properties)
             throws ProvisionException
        Add the given profile to this profile registry.
        Parameters:
        id - the profile id
        properties - the profile properties
        Returns:
        the new empty profile
        Throws:
        ProvisionException - if a profile with the same id is already present in the registry.

      • containsProfile

        boolean containsProfile​(java.lang.String profileId)
        Returns whether this profile registry contains a profile with the given id.
        Parameters:
        profileId - The id of the profile to search for
        Returns:
        true if this registry contains a profile with the given id, and false otherwise.

      • removeProfile

        void removeProfile​(java.lang.String id,
                   long timestamp)
            throws ProvisionException
        Remove the given profile snapshot from this profile registry. This method has no effect if this registry does not contain a profile with the given id and timestamp. The current profile cannot be removed using this method. When a particular profile state is removed from the registry, the corresponding profile state properties for that particular state are also removed.
        Parameters:
        id - the profile to remove
        timestamp - the timestamp of the profile to remove
        Throws:
        ProvisionException - if the profile with the specified id and timestamp is the current profile.

      • removeProfile

        void removeProfile​(java.lang.String id)
        Remove the given profile from this profile registry. This method has no effect if this registry does not contain a profile with the given id. When a profile is removed from the registry, all of its associated profile state properties are removed as well.
        Parameters:
        id - the profile to remove

      • isCurrent

        boolean isCurrent​(IProfile profile)
        Check if the given profile from this profile registry is up-to-date.
        Parameters:
        profile - the profile to check
        Returns:
        boolean true if the profile is current; false otherwise.

      • setProfileStateProperties

        IStatus setProfileStateProperties​(java.lang.String id,
                                  long timestamp,
                                  java.util.Map<java.lang.String,​java.lang.String> properties)
        Set properties on a specific profile state. Overwrite existing properties if present.
        Parameters:
        id - the identifier of the profile
        timestamp - the timestamp of the profile
        properties - the properties to set on the profile
        Returns:
        status object indicating success or failure
        Throws:
        java.lang.NullPointerException - if either id or properties are null
        Since:
        2.1

      • setProfileStateProperty

        IStatus setProfileStateProperty​(java.lang.String id,
                                long timestamp,
                                java.lang.String key,
                                java.lang.String value)
        Set a specific property on a specific profile state. Overwrite existing properties if present.

        Use of this method is discouraged if multiple properties will be set on the same state since the implementation of this method may access the file-system with each call. Callers should use setProfileStateProperties(String, long, Map) instead.

        Parameters:
        id - the profile identifier
        timestamp - the timestamp of the profile
        key - the property key to set
        value - the property value to set
        Returns:
        status object indicating success or failure
        Throws:
        java.lang.NullPointerException - if any of id, key or value is null
        Since:
        2.1

      • getProfileStateProperties

        java.util.Map<java.lang.String,​java.lang.String> getProfileStateProperties​(java.lang.String id,
                                                                                 long timestamp)
        Return all properties for a particular profile state. Both the key and the values are String. Return an empty map if there was a problem accessing the properties.

        There is no guarantee that all state timestamps returned will still exist in the registry since the user could delete profile states from the file system.

        Parameters:
        id - the profile identifier
        timestamp - the profile timestamp
        Returns:
        a property map of key value pairs. An empty map if the profile state has no properties or does not exist
        Throws:
        java.lang.NullPointerException - if profile id is null.
        Since:
        2.1

      • getProfileStateProperties

        java.util.Map<java.lang.String,​java.lang.String> getProfileStateProperties​(java.lang.String id,
                                                                                 java.lang.String key)
        Return a map of profile timestamps to values for all profile states that contain the given property key. Both the key and value are of type String. Return an empty map if there was a problem accessing the properties.

        There is no guarantee that all state timestamps returned will still exist in the registry since the user could delete profile states from the file system.

        Parameters:
        id - the profile identifier
        key - the property key
        Returns:
        A map of timestamp and values for the given key. An empty map if no states define the given key.
        Throws:
        java.lang.NullPointerException - if the profile id or key is null.
        Since:
        2.1

      • removeProfileStateProperties

        IStatus removeProfileStateProperties​(java.lang.String id,
                                     long timestamp,
                                     java.util.Collection<java.lang.String> keys)
        Remove all properties with matching keys from the given profile state. Non-existent keys are ignored. If the state does not exist the method performs a no-op and returns normally. If the keys parameter is null then remove all properties from the profile state.
        Parameters:
        id - the profile identifier
        timestamp - the profile timestamp
        keys - the property keys to remove, or null
        Returns:
        a status object indicating success or failure
        Throws:
        java.lang.NullPointerException - if the profile id is null.
        Since:
        2.1