Skip to content

Commit

Permalink
[featurelauncher] Updates to the specification based on implementatio…
Browse files Browse the repository at this point in the history
…n experience

* Separate Artifact Repository constants into their own file and remove REMOTE from the constant names
* InstalledFeature should allow users to see what the result of decoration was
* Clarify the ordering of ArtifactRepositories that are added to FeatureRuntime operations

Signed-off-by: Tim Ward <[email protected]>
  • Loading branch information
timothyjward committed Oct 16, 2024
1 parent ad6256d commit bc20dc1
Show file tree
Hide file tree
Showing 5 changed files with 159 additions and 86 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,11 @@

package org.osgi.service.featurelauncher;

import java.net.URI;
import java.util.Map;

import org.osgi.service.feature.FeatureConfiguration;
import org.osgi.service.feature.FeatureExtension;
import org.osgi.service.feature.FeatureExtension.Kind;
import org.osgi.service.feature.FeatureExtension.Type;
import org.osgi.service.feature.ID;
import org.osgi.service.featurelauncher.repository.ArtifactRepository;

/**
* Defines standard constants for the Feature Launcher specification.
Expand Down Expand Up @@ -108,67 +104,4 @@ private FeatureLauncherConstants() {
* defines the start level configuration for the bundles in the feature
*/
public static final String BUNDLE_START_LEVELS = "bundle-start-levels";

/**
* The configuration property key used to set the repository name when
* creating an {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_NAME = "name";

/**
* The configuration property key used to set the repository user when
* creating an {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_USER = "user";

/**
* The configuration property key used to set the repository password when
* creating an {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_PASSWORD = "password";

/**
* The configuration property key used to set the bearer token when creating
* an {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_BEARER_TOKEN = "token";

/**
* The configuration property key used to set that SNAPSHOT release versions
* are enabled for an {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_SNAPSHOTS_ENABLED = "snapshot";

/**
* The configuration property key used to set that release versions are
* enabled for an {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_RELEASES_ENABLED = "release";

/**
* The configuration property key used to set the trust store to be used
* when accessing a remote {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_TRUST_STORE = "truststore";

/**
* The configuration property key used to set the trust store format to be
* used when accessing a remote {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_TRUST_STORE_FORMAT = "truststoreFormat";

/**
* The configuration property key used to set the trust store password to be
* used when accessing a remote {@link ArtifactRepository} using
* {@link FeatureLauncher#createRepository(URI, Map)}
*/
public static final String REMOTE_ARTIFACT_REPOSITORY_TRUST_STORE_PASSWORD = "truststorePassword";
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
/*******************************************************************************
* Copyright (c) Contributors to the Eclipse Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
*******************************************************************************/

package org.osgi.service.featurelauncher.repository;

import java.net.URI;
import java.util.Map;

/**
* Defines standard constants for creating {@link ArtifactRepository} instances
* using the {@link ArtifactRepositoryFactory}
*
* @author $Id$
*/
public final class ArtifactRepositoryConstants {
private ArtifactRepositoryConstants() {
// non-instantiable
}

/**
* The configuration property key used to set the repository name when
* creating an {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_NAME = "name";

/**
* The configuration property key used to set the repository user when
* creating an {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_USER = "user";

/**
* The configuration property key used to set the repository password when
* creating an {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_PASSWORD = "password";

/**
* The configuration property key used to set the bearer token when creating
* an {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_BEARER_TOKEN = "token";

/**
* The configuration property key used to set that SNAPSHOT release versions
* are enabled for an {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_SNAPSHOTS_ENABLED = "snapshot";

/**
* The configuration property key used to set that release versions are
* enabled for an {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_RELEASES_ENABLED = "release";

/**
* The configuration property key used to set the trust store to be used
* when accessing a remote {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_TRUST_STORE = "truststore";

/**
* The configuration property key used to set the trust store format to be
* used when accessing a remote {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_TRUST_STORE_FORMAT = "truststoreFormat";

/**
* The configuration property key used to set the trust store password to be
* used when accessing a remote {@link ArtifactRepository} using
* {@link ArtifactRepositoryFactory#createRepository(URI, Map)}
*/
public static final String ARTIFACT_REPOSITORY_TRUST_STORE_PASSWORD = "truststorePassword";
}
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,10 @@ public interface OperationBuilder<T extends OperationBuilder<T>> {
* is already set for the given name then it will be replaced. Passing a
* <code>null</code> {@link ArtifactRepository} will remove the
* repository from this operation.
* <p>
* {@link ArtifactRepository} instances are stored in the order that
* they are added, and this order defines the order in which they will
* be queried.
*
* @param name the name to use for this repository
* @param repository the repository
Expand All @@ -143,6 +147,10 @@ T addRepository(String name,
* {@link #addRepository(String, ArtifactRepository)} has the same name
* as a default repository then the added repository will override the
* default repository.
* <p>
* Default repositories are always added after any added by
* {@link #addRepository(String, ArtifactRepository)}, and are therefore
* the last to be queried.
*
* @param include
* @return <code>this</code>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
import java.util.List;

import org.osgi.annotation.versioning.ProviderType;
import org.osgi.service.feature.ID;
import org.osgi.service.feature.Feature;
import org.osgi.service.featurelauncher.FeatureLauncher;

/**
Expand All @@ -35,9 +35,30 @@
public interface InstalledFeature {

/**
* @return The {@link ID} of the installed feature
* @return The {@link Feature} that was installed. This will be identical to
* {@link #getOriginalFeature()} unless the feature was decorated
* during installation. If decoration did occur then
* {@link #isDecorated()} will return <code>true</code> and this
* method will return the decorated feature.
*/
public ID getFeatureId();
public Feature getFeature();

/**
* @return The undecorated {@link Feature} that was originally used in the
* operation. If no decoration occurred then {@link #isDecorated()}
* will return <code>false</code> and this method will return the
* same value as {@link #getFeature()};
*/
public Feature getOriginalFeature();

/**
* @return <code>true</code> if the original feature was decorated by one or
* more decorators. If <code>true</code> then the undecorated
* feature will be available from {@link #getOriginalFeature()} and
* the actual feature used will be available from
* {@link #getFeature()}.
*/
public boolean isDecorated();

/**
* Is this a feature installed by {@link FeatureLauncher}
Expand Down
46 changes: 30 additions & 16 deletions osgi.specs/docbook/160/service.feature.launcher.xml
Original file line number Diff line number Diff line change
Expand Up @@ -303,51 +303,51 @@
<itemizedlist>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_NAME"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_NAME"
xrefstyle="hyperlink"/> - The name for this repository</para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_USER"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_USER"
xrefstyle="hyperlink"/> - The user name to use for authenticating with this repository</para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_PASSWORD"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_PASSWORD"
xrefstyle="hyperlink"/> - The password to use for authenticating with this repository</para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_BEARER_TOKEN"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_BEARER_TOKEN"
xrefstyle="hyperlink"/> - A bearer token to use when authenticating with this repository</para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_SNAPSHOTS_ENABLED"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_SNAPSHOTS_ENABLED"
xrefstyle="hyperlink"/> - A <code>Boolean</code> indicating that SNAPSHOT versions are
supported. Defaults to <code>true</code></para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_RELEASES_ENABLED"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_RELEASES_ENABLED"
xrefstyle="hyperlink"/> - A <code>Boolean</code> indicating that release versions are
supported. Defaults to <code>true</code></para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_TRUST_STORE"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_TRUST_STORE"
xrefstyle="hyperlink"/> - A trust store to use when validating a server certificate. May be a file
system path or a <code>data</code> URI as defined by <xref linkend="service.featurelauncher-data.uri"
xrefstyle="hyperlink"/>.</para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_TRUST_STORE_FORMAT"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_TRUST_STORE_FORMAT"
xrefstyle="hyperlink"/> - The format of the trust store to use when validating a server certificate.</para>
</listitem>
<listitem>
<para><xref
linkend="org.osgi.service.featurelauncher.FeatureLauncherConstants.REMOTE_ARTIFACT_REPOSITORY_TRUST_STORE_PASSWORD"
linkend="org.osgi.service.featurelauncher.repository.ArtifactRepositoryConstants.ARTIFACT_REPOSITORY_TRUST_STORE_PASSWORD"
xrefstyle="hyperlink"/> - The password to use when validating the trust store integrity.</para>
</listitem>
</itemizedlist>
Expand Down Expand Up @@ -849,7 +849,7 @@ fw.waitForStop(0);
<row>
<entry><para><code>-d</code></para><para><code>--decorator</code></para></entry>

<entry><para>A class name</para></entry>
<entry><para>A&#160;class&#160;name[,&lt;class&#160;name&gt;]</para></entry>

<entry><para>Provides the name of a decorator class that should be used when launching
the feature. The decorator class must be public, available on the classpath, and have a
Expand All @@ -860,8 +860,9 @@ fw.waitForStop(0);
<row>
<entry><para><code>-e</code></para><para><code>--extension-handler</code></para></entry>

<entry><para>&lt;extension&#160;name&gt;,
&lt;class&#160;name&gt;</para></entry>
<entry><para>&lt;extension&#160;name&gt;=
&lt;class&#160;name&gt;[,&lt;extension&#160;name&gt;=
&lt;class&#160;name&gt;]</para></entry>

<entry><para>Provides the name of an extension, and the extension handler class that should
be used to handle the extension when launching the feature. The extension handler class must
Expand Down Expand Up @@ -1187,10 +1188,23 @@ fw.waitForStop(0);

<itemizedlist>
<listitem>
<para>The <xref
linkend="org.osgi.service.feature.ID" xrefstyle="hyperlink"/> of the
Feature from <xref
linkend="org.osgi.service.featurelauncher.runtime.InstalledFeature.getFeatureId--"
<para>The installed <xref
linkend="org.osgi.service.feature.Feature" xrefstyle="hyperlink"/> from <xref
linkend="org.osgi.service.featurelauncher.runtime.InstalledFeature.getFeature--"
xrefstyle="hyperlink"/>. This will include any decoration as described in <xref
linkend="service.featurelauncher-feature.decoration" xrefstyle="hyperlink"/>
</para>
</listitem>
<listitem>
<para>The original undecorated <xref
linkend="org.osgi.service.feature.Feature" xrefstyle="hyperlink"/> from <xref
linkend="org.osgi.service.featurelauncher.runtime.InstalledFeature.getOriginalFeature--"
xrefstyle="hyperlink"/>
</para>
</listitem>
<listitem>
<para>Whether this installed feature was decorated using <xref
linkend="org.osgi.service.featurelauncher.runtime.InstalledFeature.isDecorated--"
xrefstyle="hyperlink"/>
</para>
</listitem>
Expand Down

0 comments on commit bc20dc1

Please sign in to comment.