Skip to content

Commit

Permalink
Merge pull request osgi#768 from osgi/design/386
Browse files Browse the repository at this point in the history
[featurelauncher] Updates to the specification based on implementation experience
  • Loading branch information
timothyjward authored Oct 16, 2024
2 parents b833699 + bc20dc1 commit eb36027
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 eb36027

Please sign in to comment.