| 1 |
/******************************************************************************* |
| 2 |
* Copyright (c) 2005, 2012 IBM Corporation and others. |
| 3 |
* |
| 4 |
* This program and the accompanying materials |
| 5 |
* are made available under the terms of the Eclipse Public License 2.0 |
| 6 |
* which accompanies this distribution, and is available at |
| 7 |
* https://www.eclipse.org/legal/epl-2.0/ |
| 8 |
* |
| 9 |
* SPDX-License-Identifier: EPL-2.0 |
| 10 |
* |
| 11 |
* Contributors: |
| 12 |
* IBM Corporation - initial API and implementation |
| 13 |
* Ericsson AB - ongoing development |
| 14 |
*******************************************************************************/ |
| 15 |
package org.eclipse.equinox.p2.engine; |
| 16 |
|
| 17 |
import java.util.Map; |
| 18 |
import org.eclipse.core.runtime.IProgressMonitor; |
| 19 |
import org.eclipse.equinox.p2.core.IProvisioningAgent; |
| 20 |
import org.eclipse.equinox.p2.metadata.IInstallableUnit; |
| 21 |
import org.eclipse.equinox.p2.query.*; |
| 22 |
|
| 23 |
/** |
| 24 |
* Represents the state of a profile in a profile registry at a given moment in time. |
| 25 |
* Note this object contains only a snapshot of a particular profile state, and will |
| 26 |
* never be updated if subsequent changes are made to this profile. A client should |
| 27 |
* never retain an {@link IProfile} instance, but rather retain the profile id and obtain |
| 28 |
* the current state of the profile from the profile registry only when required. |
| 29 |
* |
| 30 |
* @noimplement This interface is not intended to be implemented by clients. |
| 31 |
* @noextend This interface is not intended to be extended by clients. |
| 32 |
* @since 2.0 |
| 33 |
*/ |
| 34 |
public interface IProfile extends IQueryable<IInstallableUnit> { |
| 35 |
|
| 36 |
/** |
| 37 |
* Constant used to indicate that an installable unit is not locked in anyway. |
| 38 |
* @see #PROP_PROFILE_LOCKED_IU |
| 39 |
*/ |
| 40 |
public static int LOCK_NONE = 0; |
| 41 |
/** |
| 42 |
* Constant used to indicate that an installable unit is locked so that it may |
| 43 |
* not be uninstalled. |
| 44 |
* @see #PROP_PROFILE_LOCKED_IU |
| 45 |
*/ |
| 46 |
public static int LOCK_UNINSTALL = 1 << 0; |
| 47 |
/** |
| 48 |
* Constant used to indicate that an installable unit is locked so that it may |
| 49 |
* not be updated. |
| 50 |
* @see #PROP_PROFILE_LOCKED_IU |
| 51 |
*/ |
| 52 |
public static int LOCK_UPDATE = 1 << 1; |
| 53 |
|
| 54 |
/** |
| 55 |
* A property key (value <code>"org.eclipse.equinox.p2.type.lock"</code>) for an |
| 56 |
* integer property indicating how an installable unit is locked in its profile. |
| 57 |
* The integer is a bit-mask indicating the different locks defined on the installable |
| 58 |
* unit. The property should be obtained from a profile using |
| 59 |
* IProfile#getInstallableUnitProperty(IInstallableUnit, String). |
| 60 |
* |
| 61 |
* @see #LOCK_UNINSTALL |
| 62 |
* @see #LOCK_UPDATE |
| 63 |
* @see #LOCK_NONE |
| 64 |
*/ |
| 65 |
public static final String PROP_PROFILE_LOCKED_IU = "org.eclipse.equinox.p2.type.lock"; //$NON-NLS-1$ |
| 66 |
|
| 67 |
/** |
| 68 |
* A property key (value <code>"org.eclipse.equinox.p2.type.root"</code>) for a |
| 69 |
* boolean property indicating whether an installable unit should be considered |
| 70 |
* a root of the install. Typically this means the unit will appear to the end user |
| 71 |
* as a top-level installed item. The property should be obtained from a profile using |
| 72 |
* IProfile#getInstallableUnitProperty(IInstallableUnit, String). |
| 73 |
* |
| 74 |
* @see #LOCK_UNINSTALL |
| 75 |
* @see #LOCK_UPDATE |
| 76 |
* @see #LOCK_NONE |
| 77 |
*/ |
| 78 |
public static final String PROP_PROFILE_ROOT_IU = "org.eclipse.equinox.p2.type.root"; //$NON-NLS-1$ |
| 79 |
|
| 80 |
/** |
| 81 |
* Profile property constant indicating the install folder for the profile. |
| 82 |
*/ |
| 83 |
public static final String PROP_INSTALL_FOLDER = "org.eclipse.equinox.p2.installFolder"; //$NON-NLS-1$ |
| 84 |
/** |
| 85 |
* Profile property constant indicating the configuration folder for the profile. |
| 86 |
*/ |
| 87 |
public static final String PROP_CONFIGURATION_FOLDER = "org.eclipse.equinox.p2.configurationFolder"; //$NON-NLS-1$ |
| 88 |
/** |
| 89 |
* Profile property constant indicating the location of the launcher configuration file for the profile. |
| 90 |
*/ |
| 91 |
public static final String PROP_LAUNCHER_CONFIGURATION = "org.eclipse.equinox.p2.launcherConfiguration"; //$NON-NLS-1$ |
| 92 |
|
| 93 |
/** |
| 94 |
* Profile property constant indicating the installed language(s) for the profile. |
| 95 |
*/ |
| 96 |
public static final String PROP_NL = "org.eclipse.equinox.p2.nl"; //$NON-NLS-1$ |
| 97 |
/** |
| 98 |
* Profile property constant for a string property indicating a user visible short |
| 99 |
* textual description of this profile. May be empty or <code>null</code>, and |
| 100 |
* generally will be for non-top level install contexts. |
| 101 |
*/ |
| 102 |
public static final String PROP_DESCRIPTION = "org.eclipse.equinox.p2.description"; //$NON-NLS-1$ |
| 103 |
/** |
| 104 |
* Profile property constant for a string property indicating a user visible name of this profile. |
| 105 |
* May be empty or <code>null</code>, and generally will be for non-top level |
| 106 |
* install contexts. |
| 107 |
*/ |
| 108 |
public static final String PROP_NAME = "org.eclipse.equinox.p2.name"; //$NON-NLS-1$ |
| 109 |
/** |
| 110 |
* Profile property constant indicating the list of environments |
| 111 |
* (e.g., OS, WS, ...) in which a profile can operate. The value of the property |
| 112 |
* is a comma-delimited string of key/value pairs. |
| 113 |
*/ |
| 114 |
public static final String PROP_ENVIRONMENTS = "org.eclipse.equinox.p2.environments"; //$NON-NLS-1$ |
| 115 |
/** |
| 116 |
* Profile property constant for a boolean property indicating if the profiling |
| 117 |
* is roaming. A roaming profile is one whose physical install location varies |
| 118 |
* and is updated whenever it runs. |
| 119 |
*/ |
| 120 |
public static final String PROP_ROAMING = "org.eclipse.equinox.p2.roaming"; //$NON-NLS-1$ |
| 121 |
/** |
| 122 |
* Profile property constant indicating the bundle pool cache location. |
| 123 |
*/ |
| 124 |
public static final String PROP_CACHE = "org.eclipse.equinox.p2.cache"; //$NON-NLS-1$ |
| 125 |
|
| 126 |
/** |
| 127 |
* Profile property constant indicating a shared read-only bundle pool cache location. |
| 128 |
*/ |
| 129 |
public static final String PROP_SHARED_CACHE = "org.eclipse.equinox.p2.cache.shared"; //$NON-NLS-1$ |
| 130 |
|
| 131 |
/** |
| 132 |
* Profile property constant for a boolean property indicating if update features should |
| 133 |
* be installed in this profile |
| 134 |
*/ |
| 135 |
public static final String PROP_INSTALL_FEATURES = "org.eclipse.update.install.features"; //$NON-NLS-1$ |
| 136 |
|
| 137 |
/** |
| 138 |
* Profile state meta property key. Can be used to mark a profile state that should be hidden. |
| 139 |
* The value of the property is not relevant as the property's existence is enough. Although <code>true</code> |
| 140 |
* would be a typical value. |
| 141 |
* |
| 142 |
* @since 2.1 |
| 143 |
*/ |
| 144 |
public static final String STATE_PROP_HIDDEN = "org.eclipse.equinox.p2.state.hidden"; //$NON-NLS-1$ |
| 145 |
|
| 146 |
/** |
| 147 |
* Profile state metadata property key used to associate with a profile state a user readable name. |
| 148 |
* @since 2.1 |
| 149 |
*/ |
| 150 |
public static final String STATE_PROP_TAG = "org.eclipse.equinox.p2.state.tag"; //$NON-NLS-1$ |
| 151 |
|
| 152 |
/** |
| 153 |
* Profile state metadata property key used to represent the state of the user profile when running in shared install. |
| 154 |
* The value for this property could be: {@link IProfile#STATE_SHARED_INSTALL_VALUE_INITIAL}, {@link IProfile#STATE_SHARED_INSTALL_VALUE_BEFOREFLUSH} or {@link IProfile#STATE_SHARED_INSTALL_VALUE_NEW} |
| 155 |
* @since 2.3 |
| 156 |
*/ |
| 157 |
public static final String STATE_PROP_SHARED_INSTALL = "org.eclipse.equinox.p2.state.shared"; //$NON-NLS-1$ |
| 158 |
|
| 159 |
/** |
| 160 |
* Value to represent a user profile the first time it is created. |
| 161 |
* @since 2.3 |
| 162 |
*/ |
| 163 |
public static final String STATE_SHARED_INSTALL_VALUE_INITIAL = "initial"; //$NON-NLS-1$ |
| 164 |
/** |
| 165 |
* Value to represent a user profile before it is being flushed because the base had changed. |
| 166 |
* @since 2.3 |
| 167 |
*/ |
| 168 |
public static final String STATE_SHARED_INSTALL_VALUE_BEFOREFLUSH = "beforeFlush"; //$NON-NLS-1$ |
| 169 |
/** |
| 170 |
* Value to represent the new user profile created once the base profile has been flushed. |
| 171 |
* @since 2.3 |
| 172 |
*/ |
| 173 |
public static final String STATE_SHARED_INSTALL_VALUE_NEW = "new"; //$NON-NLS-1$ |
| 174 |
|
| 175 |
/** |
| 176 |
* Profile property constant for additional parameters of the downloading stats(e.g., package=jee&os=linux). |
| 177 |
* @since 2.2 |
| 178 |
*/ |
| 179 |
public static final String PROP_STATS_PARAMETERS = "org.eclipse.equinox.p2.stats.parameters"; //$NON-NLS-1$ |
| 180 |
|
| 181 |
/** |
| 182 |
* Returns the provisioning agent that manages this profile |
| 183 |
* @return A provisioning agent. |
| 184 |
*/ |
| 185 |
public IProvisioningAgent getProvisioningAgent(); |
| 186 |
|
| 187 |
/** |
| 188 |
* Returns the id of this profile, unique within a given profile registry |
| 189 |
* @return the profile id |
| 190 |
*/ |
| 191 |
public String getProfileId(); |
| 192 |
|
| 193 |
/** |
| 194 |
* Returns the profile property associated with the given key, |
| 195 |
* or <code>null</code> if this property is not present |
| 196 |
* @param key The property kid |
| 197 |
* @return the property value, or <code>null</code> |
| 198 |
*/ |
| 199 |
public String getProperty(String key); |
| 200 |
|
| 201 |
/** |
| 202 |
* Returns the profile property associated with the given installable unit. |
| 203 |
* @param iu the installable unit to return the property for |
| 204 |
* @param key the property key |
| 205 |
* @return the property value, or <code>null</code> if no such property is defined |
| 206 |
*/ |
| 207 |
public String getInstallableUnitProperty(IInstallableUnit iu, String key); |
| 208 |
|
| 209 |
/** |
| 210 |
* Returns an unmodifiable map of all profile properties. |
| 211 |
* @return a map of all profile properties. |
| 212 |
*/ |
| 213 |
public Map<String, String> getProperties(); |
| 214 |
|
| 215 |
/** |
| 216 |
* Returns an unmodifiable map of all profile properties associated with the given |
| 217 |
* installable unit in this profile. |
| 218 |
* @param iu the installable unit to return profile properties for |
| 219 |
* @return an unmodifiable map of installable unit profile properties |
| 220 |
*/ |
| 221 |
public Map<String, String> getInstallableUnitProperties(IInstallableUnit iu); |
| 222 |
|
| 223 |
/** |
| 224 |
* Returns a timestamp describing when this profile snapshot was created. |
| 225 |
* @return A profile timestamp |
| 226 |
*/ |
| 227 |
public long getTimestamp(); |
| 228 |
|
| 229 |
/** |
| 230 |
* Returns the installable units in this profile that match the given query. In a shared |
| 231 |
* install, this will include both the installable units in the shared base location, and in |
| 232 |
* the current user's private install area. |
| 233 |
* @param query The query to use for matching. |
| 234 |
* @param monitor a progress monitor, or <code>null</code> if progress |
| 235 |
* reporting is not desired |
| 236 |
* @return The installable units that match the given query |
| 237 |
*/ |
| 238 |
public IQueryResult<IInstallableUnit> available(IQuery<IInstallableUnit> query, IProgressMonitor monitor); |
| 239 |
|
| 240 |
} |