Uploaded image for project: 'FUSE ESB'
  1. FUSE ESB
  2. ESB-1128 Doc - Review of "Deploying into the OSGi Container"
  3. ESB-1134

Doc - Chapter 4 - "Deploying into the OSGi Container" >"Deploying Features"

    Details

    • Type: Sub-task
    • Status: Resolved
    • Priority: Major
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: 4.2.0-fuse-01-00
    • Component/s: None
    • Labels:
      None

      Gliffy Diagrams

        Activity

        Hide
        eglynn1 Eoghan Glynn added a comment -

        p49.

        "it is generally impractical to treat a bundle as the basic unit of deployment."

        This statement is a bit too strong I think, given that the bundle would be considered the basic deployable unit by users already familiar with OSGi. It might be better to re-phrase as something like:

        "it is often convenient to aggregate inter-dependent or related bundles into a larger unit of deployment."

        p50.

        "Essentially, a feature is created by adding a new feature element to a special
        kind of XML file, known as a feature repository."

        Often referred to synonymously as as a "features URL". Neither terminology is really satisfactory, especially the former as it connotes a centralized location where all the bundles are stored (like a maven repository or the OBR) which of course it isn't. So it might make sense to emphasize the point that a features repository is really just an aggregation of references to inter-dependent or related bundles, not a location where the bundles themselves are stored.

        "Create a local feature repository"

        The reference to locality may be confusing as the standard features repos shipping with the ESB would also be available locally (under the <smx_install_dir>/system dir) as well as being remotely accessible via the fusesource maven repo. You might want to call it a custom features repository instead.

        "<features>
        </features>"

        The top-level features element may optionally be decorated with a name attribute. See for example

        <smx_install_dir>/system/org/apache/felix/karaf/apache-felix-karaf/1.4.0-fuse-01-00/apache-felix-karaf-1.4.0-fuse-01-00-features.xml:
        <features name="karaf-1.4.0-fuse-01-00">

        If the name isn't specified, Karaf will default to a generic name like "repo-0".

        "Add the local repository URL to the features service"

        Cart before the horse somewhat? Surely some feature elements should be defined in the new features repo before running features:addUrl?

        "In order to make the new feature repository available to the Apache Felix kernel ..."

        Repeated used of 'kernel' in this sentence may confuse, given that we switched over from the old ServiceMix Kernel to Apache Felix Karaf for this release. May be better as:

        "In order to make the new feature repository available to the Karaf features service ..."

        p51.

        karaf@root> features:listUrl
        mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.1.0-psc-01-00RC1/xml/features
        mvn:org.apache.servicemix.camel/features/4.1.0-psc-01-00RC1/xml/features
        file:C:/Projects/features.xml
        mvn:org.apache.ode/ode-jbi-karaf/1.3.3-psc-01-00RC1/xml/features
        mvn:org.apache.felix.karaf/apache-felix-karaf/1.2.0-psc-01-00RC1/xml/features
        mvn:org.apache.servicemix/apache-servicemix/4.1.0-psc-01-00RC1/xml/features

        Replace all "psc-01-00RC1" with "fuse-01-00".

        "You can optionally specify a version attribute on the feature element, if you want to keep track of the
        feature's version number."

        It would be more a case of assigning a non-zero version to the feature, as opposed to just keeping track of the version. When versions are used, a specific version of a particular feature can be specified, e.g.

        features:install cxf-jaxrs 4.2.0-fuse-01-00

        "To check whether the kernel successfully parses the new feature entry"

        Similar comment to the above, probably best to refer to it as the features service.

        "but you should be able to find the entry for your new feature (in this
        case, example-camel-bundle) by scrolling back through the listing."

        or by simply shortening the list to only those features are actually installed via the -i,--installed option:

        karaf@root> features:list -i

        or by grep'ing for the particulat feature

        karaf@root> features:list | grep example-camel-bundle

        "The features:refreshUrl command forces the kernel to reread all the feature repositories"

        Unless you specify a URL argument, in which case only that repo is refreshed.

        p52.

        "Each child feature element contains the name of a feature on which the
        current feature depends."

        A version can be specified as well, e.g.

          <feature name='camel-core' version='2.2.0-fuse-01-00'>
            <feature version="2.5.6.SEC01">spring</feature>
            ...
          <feature>

        This encodes a dependency of the camel-core feature (v. 2.2.0-fuse-01-00) on the spring feature (v. 2.5.6.SEC01).

        "When you deploy a feature with dependent features,
        the dependency mechanism checks whether or not the dependent features
        are available in the container. If not, the dependency mechanism automatically
        loads the missing dependencies (and any recursive dependencies)."

        Maybe better to use "installed" and "installs" as opposed to "available" and "loads".

        "For example, for the custom FUSE Mediation Router feature,
        example-camel-bundle, you can specify explicitly which standard Apache
        Camel features it depends on."

        This could confuse in the sense of implying the Apache version of the camel features were being depended on, as opposed to the FUSE versions, especially since the next example refers to unversioned camel-core etc features.

        "<feature>camel-spring</feature>
        <feature>camel-osgi</feature>"

        These two features have been superceeded by the single camel-spring-osgi feature.

        p53.

        "Where the name attribute of the config element specifies the scope of the
        property settings"

        In config admin service terminology, this is the persistent ID or PID, as opposed to the scope.
        You also should specify that this config value may over-ridden via a properties file called:

        <smx_install_dir>/etc/org.fusesource.fuseesb.example.cfg

        which could be created via your favourite text editor or via the karaf shell commands:

        karaf@root> config:edit org.fusesource.fuseesb.example
        karaf@root> config:propset prefix MyOtherTransform
        karaf@root> config:update

        "consider the following Spring XML file that accesses the OSGi
        configuration properties using Spring DM"

        Would it be worth also giving a blueprint example of property placeholder substitution?

        p55.

        "/etc/org.apache.servicemix.features.cfg"

        Should read: etc/org.apache.felix.karaf.features.cfg

        "You can modify the configuration to customize the features that are installed
        as FUSE ESB kernel starts up."

        Note the featuresBoot etc. only have an impact the first time the features service is booted. So in order to pick up any changes, you would need to clear the slate by deleting the data/cache directory.

        "Hot deployment"

        Missing some text here?

        General:

        Would it be worth also noting that Karaf exposes a FeaturesService MBean? This provides attributes that allow the features & repos to be browsed and also operations allowing the repos & features to installed/uninstalled.

        Show
        eglynn1 Eoghan Glynn added a comment - p49. "it is generally impractical to treat a bundle as the basic unit of deployment." This statement is a bit too strong I think, given that the bundle would be considered the basic deployable unit by users already familiar with OSGi. It might be better to re-phrase as something like: "it is often convenient to aggregate inter-dependent or related bundles into a larger unit of deployment." — p50. "Essentially, a feature is created by adding a new feature element to a special kind of XML file, known as a feature repository." Often referred to synonymously as as a "features URL". Neither terminology is really satisfactory, especially the former as it connotes a centralized location where all the bundles are stored (like a maven repository or the OBR) which of course it isn't. So it might make sense to emphasize the point that a features repository is really just an aggregation of references to inter-dependent or related bundles, not a location where the bundles themselves are stored. "Create a local feature repository" The reference to locality may be confusing as the standard features repos shipping with the ESB would also be available locally (under the <smx_install_dir>/system dir) as well as being remotely accessible via the fusesource maven repo. You might want to call it a custom features repository instead. "<features> </features>" The top-level features element may optionally be decorated with a name attribute. See for example <smx_install_dir>/system/org/apache/felix/karaf/apache-felix-karaf/1.4.0-fuse-01-00/apache-felix-karaf-1.4.0-fuse-01-00-features.xml: <features name="karaf-1.4.0-fuse-01-00"> If the name isn't specified, Karaf will default to a generic name like "repo-0". "Add the local repository URL to the features service" Cart before the horse somewhat? Surely some feature elements should be defined in the new features repo before running features:addUrl? "In order to make the new feature repository available to the Apache Felix kernel ..." Repeated used of 'kernel' in this sentence may confuse, given that we switched over from the old ServiceMix Kernel to Apache Felix Karaf for this release. May be better as: "In order to make the new feature repository available to the Karaf features service ..." — p51. karaf@root> features:listUrl mvn:org.apache.servicemix.nmr/apache-servicemix-nmr/1.1.0-psc-01-00RC1/xml/features mvn:org.apache.servicemix.camel/features/4.1.0-psc-01-00RC1/xml/features file:C:/Projects/features.xml mvn:org.apache.ode/ode-jbi-karaf/1.3.3-psc-01-00RC1/xml/features mvn:org.apache.felix.karaf/apache-felix-karaf/1.2.0-psc-01-00RC1/xml/features mvn:org.apache.servicemix/apache-servicemix/4.1.0-psc-01-00RC1/xml/features Replace all "psc-01-00RC1" with "fuse-01-00". "You can optionally specify a version attribute on the feature element, if you want to keep track of the feature's version number." It would be more a case of assigning a non-zero version to the feature, as opposed to just keeping track of the version. When versions are used, a specific version of a particular feature can be specified, e.g. features:install cxf-jaxrs 4.2.0-fuse-01-00 "To check whether the kernel successfully parses the new feature entry" Similar comment to the above, probably best to refer to it as the features service. "but you should be able to find the entry for your new feature (in this case, example-camel-bundle) by scrolling back through the listing." or by simply shortening the list to only those features are actually installed via the -i,--installed option: karaf@root> features:list -i or by grep'ing for the particulat feature karaf@root> features:list | grep example-camel-bundle "The features:refreshUrl command forces the kernel to reread all the feature repositories" Unless you specify a URL argument, in which case only that repo is refreshed. — p52. "Each child feature element contains the name of a feature on which the current feature depends." A version can be specified as well, e.g. <feature name='camel-core' version='2.2.0-fuse-01-00'> <feature version="2.5.6.SEC01">spring</feature> ... <feature> This encodes a dependency of the camel-core feature (v. 2.2.0-fuse-01-00) on the spring feature (v. 2.5.6.SEC01). "When you deploy a feature with dependent features, the dependency mechanism checks whether or not the dependent features are available in the container. If not, the dependency mechanism automatically loads the missing dependencies (and any recursive dependencies)." Maybe better to use "installed" and "installs" as opposed to "available" and "loads". "For example, for the custom FUSE Mediation Router feature, example-camel-bundle, you can specify explicitly which standard Apache Camel features it depends on." This could confuse in the sense of implying the Apache version of the camel features were being depended on, as opposed to the FUSE versions, especially since the next example refers to unversioned camel-core etc features. "<feature>camel-spring</feature> <feature>camel-osgi</feature>" These two features have been superceeded by the single camel-spring-osgi feature. — p53. "Where the name attribute of the config element specifies the scope of the property settings" In config admin service terminology, this is the persistent ID or PID, as opposed to the scope . You also should specify that this config value may over-ridden via a properties file called: <smx_install_dir>/etc/org.fusesource.fuseesb.example.cfg which could be created via your favourite text editor or via the karaf shell commands: karaf@root> config:edit org.fusesource.fuseesb.example karaf@root> config:propset prefix MyOtherTransform karaf@root> config:update "consider the following Spring XML file that accesses the OSGi configuration properties using Spring DM" Would it be worth also giving a blueprint example of property placeholder substitution? — p55. "/etc/org.apache.servicemix.features.cfg" Should read: etc/org.apache.felix.karaf.features.cfg "You can modify the configuration to customize the features that are installed as FUSE ESB kernel starts up." Note the featuresBoot etc. only have an impact the first time the features service is booted. So in order to pick up any changes, you would need to clear the slate by deleting the data/cache directory. "Hot deployment" Missing some text here? — General: Would it be worth also noting that Karaf exposes a FeaturesService MBean? This provides attributes that allow the features & repos to be browsed and also operations allowing the repos & features to installed/uninstalled.
        Hide
        fbolton Fintan Bolton added a comment -

        Giving a blueprint example of property-placeholder substitution sounds like a good idea, but I don't have any examples for it. The only think I could find on it is the following page from Karaf:

        http://felix.apache.org/site/45-security-framework.html

        This example seems to exploit a non-standard feature of Apache Geronimo. Is this the recommended approach?

        Show
        fbolton Fintan Bolton added a comment - Giving a blueprint example of property-placeholder substitution sounds like a good idea, but I don't have any examples for it. The only think I could find on it is the following page from Karaf: http://felix.apache.org/site/45-security-framework.html This example seems to exploit a non-standard feature of Apache Geronimo. Is this the recommended approach?
        Hide
        eglynn1 Eoghan Glynn added a comment -

        Fintan,

        That JAAS example is showing something a little different, specifically substituting in system properties as opposed to config admin service properties. The former is very useful too, and in fact we use the Geronimo custom namespace internally in the blueprint configs for the Karaf and SMX bundles for this purpose. However it would not be a direct analogue for the Spring-DM example in the docco, which is based on the config admin service.

        To illustrate the difference, here's a kinda cool example that uses both approaches. The defaults for the config admin service properties may in this case be over-ridden by system properties, so both property placeholders are in play. So for example, if destinationName property isn't set in etc/org.apache.servicemix.jbi.cluster.config.cfg, then its value may be over-ridden via JAVA_OPTS="-Dservicemix.cluster.destination=myClusterQueue".

        Show
        eglynn1 Eoghan Glynn added a comment - Fintan, That JAAS example is showing something a little different, specifically substituting in system properties as opposed to config admin service properties. The former is very useful too, and in fact we use the Geronimo custom namespace internally in the blueprint configs for the Karaf and SMX bundles for this purpose. However it would not be a direct analogue for the Spring-DM example in the docco, which is based on the config admin service. To illustrate the difference, here's a kinda cool example that uses both approaches. The defaults for the config admin service properties may in this case be over-ridden by system properties, so both property placeholders are in play. So for example, if destinationName property isn't set in etc/org.apache.servicemix.jbi.cluster.config.cfg, then its value may be over-ridden via JAVA_OPTS="-Dservicemix.cluster.destination=myClusterQueue".
        Hide
        fbolton Fintan Bolton added a comment -

        Thanks, Eoghan!

        That is indeed a very nifty example, but I think I should probably discuss it in chapter 8 (Deploying an OSGi Service), which is where I discuss Blueprint configuration in more detail.

        Show
        fbolton Fintan Bolton added a comment - Thanks, Eoghan! That is indeed a very nifty example, but I think I should probably discuss it in chapter 8 (Deploying an OSGi Service), which is where I discuss Blueprint configuration in more detail.
        Hide
        eglynn1 Eoghan Glynn added a comment -

        Fintan - for the next ESB release, you should probably include a description of the new features:desc and features:tree commands, assuming this patch is applied

        Show
        eglynn1 Eoghan Glynn added a comment - Fintan - for the next ESB release, you should probably include a description of the new features:desc and features:tree commands, assuming this patch is applied
        Hide
        fbolton Fintan Bolton added a comment -

        After some investigation, I have realized that it would not be a good idea to document those Blueprint configuration extensions after all. These schemas are non-standard and currently in a state of considerable flux. E.g. they have recently moved from a sandbox location in http://geronimo.apache.org to the new Apache Aries incubator project, http://incubator.apache.org/aries. Consequently, all of the associated XSD namespaces have also changed.

        Show
        fbolton Fintan Bolton added a comment - After some investigation, I have realized that it would not be a good idea to document those Blueprint configuration extensions after all. These schemas are non-standard and currently in a state of considerable flux. E.g. they have recently moved from a sandbox location in http://geronimo.apache.org to the new Apache Aries incubator project, http://incubator.apache.org/aries . Consequently, all of the associated XSD namespaces have also changed.
        Hide
        fbolton Fintan Bolton added a comment -

        All of the relevant corrections have now been incorporated into the guide.

        Show
        fbolton Fintan Bolton added a comment - All of the relevant corrections have now been incorporated into the guide.

          People

          • Assignee:
            Unassigned
            Reporter:
            fbolton Fintan Bolton
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: