Package org.apache.sling.installer.api

Class InstallableResource

  • public class InstallableResource
extends java.lang.Object
    A piece of data that can be installed by the OsgiInstaller Currently the OSGi installer supports bundles and configurations, but it can be extended by additional task factories supporting other formats. The installable resource contains as much information as the client can provide. An input stream or dictionary is mandatory everything else is optional. All optional values will be tried to be evaluated by the OSGi installer. If such evaluation fails the resource will be ignore during installation. If the client provides a configuration it should use the resource type TYPE_PROPERTIES. Otherwise the resource type TYPE_FILE should be used. These two generic types are transformed by resource transformer services to the appropriate resource type like bundle or configuration etc. This frees the client from having any knowledge about the provided data. However, if the client has the knowledge about the data it can provided a specific resource type. The provider should provide a digest for files (input streams). The installer will calculate a digest for dictionaries, regardless if the provider provided a dictionary.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String BUNDLE_START_LEVEL
      Optional parameter in the dictionary if a bundle is installed.
      static int DEFAULT_PRIORITY
      Default resource priority
      static java.lang.String INSTALLATION_HINT
      Optional parameter in the dictionary if a resource (not a dict) is installed.
      static java.lang.String RESOURCE_IS_TEMPLATE
      Optional parameter to be passed in the dictionary.
      static java.lang.String RESOURCE_URI_HINT
      Optional parameter in the dictionary if a resource (not a dict) is installed.
      static java.lang.String TYPE_BUNDLE
      The type for a bundle - in this case getInputStream() must return an input stream to the bundle.
      static java.lang.String TYPE_CONFIG
      The type for a configuration - in this case getDictionary() must return a dictionary with the configuration.
      static java.lang.String TYPE_FILE
      The type for all other provided data like a bundle etc.
      static java.lang.String TYPE_PROPERTIES
      The type for properties - in this case getDictionary() should contain a dictionary or the getInputStream() should point to a property or configuration file.

    • Constructor Summary

      Constructors 
      Constructor Description
      InstallableResource​(java.lang.String id, java.io.InputStream is, java.util.Dictionary<java.lang.String,​java.lang.Object> dict, java.lang.String digest, java.lang.String type, java.lang.Integer priority)
      Create a data object - this is a simple constructor just using the values as they are provided.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.Dictionary<java.lang.String,​java.lang.Object> getDictionary()
      Return this resource's dictionary.
      java.lang.String getDigest()
      Return this resource's digest.
      java.lang.String getId()
      Return this data's id.
      java.io.InputStream getInputStream()
      Return an input stream with the data of this resource.
      int getPriority()
      Return the priority of this resource.
      java.lang.String getType()
      Return the type of this resource.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • TYPE_PROPERTIES

        public static final java.lang.String TYPE_PROPERTIES
        The type for properties - in this case getDictionary() should contain a dictionary or the getInputStream() should point to a property or configuration file.
        Since:
        3.1
        See Also:
        Constant Field Values

      • TYPE_FILE

        public static final java.lang.String TYPE_FILE
        The type for all other provided data like a bundle etc. In this case getInputStream() must return an input stream to the data. getDictionary() might return additional information.
        Since:
        3.1
        See Also:
        Constant Field Values

      • TYPE_BUNDLE

        public static final java.lang.String TYPE_BUNDLE
        The type for a bundle - in this case getInputStream() must return an input stream to the bundle. getDictionary() might return additional information. This type should only be used if the client really knows that the provided data is a bundle.
        See Also:
        Constant Field Values

      • TYPE_CONFIG

        public static final java.lang.String TYPE_CONFIG
        The type for a configuration - in this case getDictionary() must return a dictionary with the configuration. This type should only be used if the client really knows that the provided data is an OSGi configuration.
        See Also:
        Constant Field Values

      • BUNDLE_START_LEVEL

        public static final java.lang.String BUNDLE_START_LEVEL
        Optional parameter in the dictionary if a bundle is installed. If this is set with a valid start level, the bundle is installed in that start level.
        See Also:
        Constant Field Values

      • INSTALLATION_HINT

        public static final java.lang.String INSTALLATION_HINT
        Optional parameter in the dictionary if a resource (not a dict) is installed. This parameter might be used by the installation task for any purpose like bundle start level etc.
        Since:
        3.1
        See Also:
        Constant Field Values

      • RESOURCE_URI_HINT

        public static final java.lang.String RESOURCE_URI_HINT
        Optional parameter in the dictionary if a resource (not a dict) is installed. If this parameter is specified, the installer uses the URI to get the input stream of the resource! Usually the installer copies the resource into the file system and uses this copy. To optimize this, if the URI of the resource is always available (like a file URI), this property can be used to avoid copying the resource. It is only evaluated if the resource type is either unknown (null) or TYPE_FILE and a digest for the resource is delivered. The value of this property is a string. This property might also be set for an UpdateHandler in order to give a hint for the (file) name the resource or dictionary should have.
        Since:
        3.1.2
        See Also:
        Constant Field Values

      • RESOURCE_IS_TEMPLATE

        public static final java.lang.String RESOURCE_IS_TEMPLATE
        Optional parameter to be passed in the dictionary. If this property is set (the value is ignored), this artifact acts like a template: If the artifact is changed into a new artifact and later this new artifact is deleted, the installer will not revert to the template. Without this property, the installer would install the original artifact again. For example: if a configuration is installed and then changed through configuration admin, a new artifact for the new configuration is created and managed. If now this configuration is deleted through configuration admin and the original configuration is not marked as a template, the original configuration is applied: the delete through config admin is not a remove of the configuration but a revert to the initial version. If the initial configuration is marked as template with this property, the removal of the changed configuration results in a real removal.
        Since:
        3.2.0
        See Also:
        Constant Field Values

      • DEFAULT_PRIORITY

        public static final int DEFAULT_PRIORITY
        Default resource priority
        See Also:
        Constant Field Values

    • Constructor Detail

      • InstallableResource

        public InstallableResource​(java.lang.String id,
                           java.io.InputStream is,
                           java.util.Dictionary<java.lang.String,​java.lang.Object> dict,
                           java.lang.String digest,
                           java.lang.String type,
                           java.lang.Integer priority)
        Create a data object - this is a simple constructor just using the values as they are provided.
        Parameters:
        id - Unique id for the resource, For auto detection of the resource type, the id should contain an extension like .jar, .cfg etc.
        is - The input stream to the data or
        dict - A dictionary with data
        digest - A digest of the data - providers should make sure to set a digest. Calculating a digest by the installer can be very expensive for input streams
        type - The resource type if known, otherwise TYPE_PROPERTIES or TYPE_FILE
        priority - Optional priority - if not specified DEFAULT_PRIORITY is used
        Throws:
        java.lang.IllegalArgumentException - if something is wrong

    • Method Detail

      • getId

        public java.lang.String getId()
        Return this data's id. It is opaque for the OsgiInstaller but should uniquely identify the resource within the namespace of the used installation mechanism.
        Returns:
        The id.

      • getType

        public java.lang.String getType()
        Return the type of this resource.
        Returns:
        The resource type or null if the type is unknown for the client.

      • getInputStream

        public java.io.InputStream getInputStream()
        Return an input stream with the data of this resource. Null if resource contains a configuration instead. Caller is responsible for closing the stream. If this resource is of type CONFIG it must not return an input stream and if this resource is of type BUNDLE it must return an input stream!
        Returns:
        The input stream or null.

      • getDictionary

        public java.util.Dictionary<java.lang.String,​java.lang.Object> getDictionary()
        Return this resource's dictionary. Null if resource contains an InputStream instead. If this resource is of type CONFIG it must return a dictionary and if this resource is of type BUNDLE it might return a dictionary!
        Returns:
        The resource's dictionary or null.

      • getDigest

        public java.lang.String getDigest()
        Return this resource's digest. Not necessarily an actual md5 or other digest of the data, can be any string that changes if the data changes.
        Returns:
        The digest or null

      • getPriority

        public int getPriority()
        Return the priority of this resource. Priorities are used to decide which resource to install when several are registered for the same OSGi entity (bundle, config, etc.)
        Returns:
        The priority.

      • toString

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