1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
/*******************************************************************************
* Copyright (c) 2008, 2010 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.equinox.p2.repository;
import java.net.URI;
import org.eclipse.equinox.p2.core.IProvisioningAgent;
import org.eclipse.equinox.p2.query.IQueryable;
/**
* The common base class for metadata and artifact repository managers.
* <p>
* A repository manager keeps track of a set of known repositories, and provides
* caching of these known repositories to avoid unnecessary loading of repositories
* from the disk or network.
* </p>
* <p>
* All {@link URI} instances provided to a repository manager must be absolute.
* </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @since 2.0
*/
public interface IRepositoryManager<T> extends IQueryable<T> {
/**
* Constant used to indicate that all enabled repositories are of interest.
*/
public static final int REPOSITORIES_ALL = 0;
/**
* Constant used to indicate that only system repositories are of interest.
* @see IRepository#PROP_SYSTEM
* @see #getKnownRepositories(int)
*/
public static final int REPOSITORIES_SYSTEM = 1 << 0;
/**
* Constant used to indicate that only non-system repositories are of interest.
* @see IRepository#PROP_SYSTEM
* @see #getKnownRepositories(int)
*/
public static final int REPOSITORIES_NON_SYSTEM = 1 << 1;
/**
* Constant used to indicate that only local repositories are of interest. Any
* repository that requires network communication will be omitted when
* this flag is used.
* @see #getKnownRepositories(int)
*/
public static final int REPOSITORIES_LOCAL = 1 << 2;
/**
* Constant used to indicate that only remote repositories are of interest. Any
* repository that doesn't require network communication will be omitted when
* this flag is used.
* @see #getKnownRepositories(int)
*/
public static final int REPOSITORIES_NON_LOCAL = 1 << 4;
/**
* Constant used to indicate that only disabled repositories are of interest.
* When this flag is used, all enabled repositories will be ignored and
* all disabled repositories that match the remaining filters will be returned.
* @see #getKnownRepositories(int)
*/
public static final int REPOSITORIES_DISABLED = 1 << 3;
/**
* Constant used to indicate that a repository manager should only load the
* repository if the repository is modifiable.
* @see IRepository#isModifiable()
*/
public static final int REPOSITORY_HINT_MODIFIABLE = 1 << 0;
/**
* Adds the repository at the given location to the list of repositories tracked by
* this repository manager. This method does not attempt to contact or load
* the repository, and makes no attempt to determine whether there is a valid
* repository at the provided location.
* <p>
* If there is a known disabled repository at the given location, it will become
* enabled as a result of this method. Thus the caller can be guaranteed that
* there is a known, enabled repository at the given location when this method returns.
*
* @param location The absolute location of the repository to add
* @see #isEnabled(URI)
*/
public void addRepository(URI location);
/**
* Returns whether a repository at the given location is in the list of repositories
* tracked by this repository manager.
*
* @param location The absolute location of the repository to look for
* @return <code>true</code> if the repository is known to this manager,
* and <code>false</code> otherwise
*/
public boolean contains(URI location);
/**
* Returns the provisioning agent in charge of this repository manager
* @return The provisioning agent.
*/
public IProvisioningAgent getAgent();
/**
* Returns the artifact repository locations known to the repository manager.
* <p>
* Note that the repository manager does not guarantee that a valid repository
* exists at any of the returned locations at any particular moment in time.
* A subsequent attempt to load a repository at any of the given locations may
* or may not succeed.
*
* @param flags an integer bit-mask indicating which repositories should be
* returned. <code>REPOSITORIES_ALL</code> can be used as the mask when
* all enabled repositories should be returned. Disabled repositories are automatically
* excluded unless the {@link #REPOSITORIES_DISABLED} flag is set.
* @return the locations of the repositories managed by this repository manager.
*
* @see #REPOSITORIES_ALL
* @see #REPOSITORIES_SYSTEM
* @see #REPOSITORIES_NON_SYSTEM
* @see #REPOSITORIES_LOCAL
* @see #REPOSITORIES_DISABLED
*/
public URI[] getKnownRepositories(int flags);
/**
* Returns the property associated with the repository at the given URI,
* without loading the repository.
* <p>
* Note that only the repository properties referenced below are tracked by the
* repository manager itself. For all other properties, this method will return <code>null</code>.
* Only values for the properties that are already known by a repository manager will be returned.
* </p>
* <p>
* If a client wishes to retrieve a property value from a repository
* regardless of the cost of retrieving it, the client should load the
* repository and then retrieve the property from the repository itself.
* </p>
*
* @param location the absolute URI of the repository in question
* @param key the String key of the property desired
* @return the value of the property, or <code>null</code> if the repository
* does not exist, the value does not exist, or the property value
* could not be determined without loading the repository.
*
* @see IRepository#getProperties()
* @see #setRepositoryProperty(URI, String, String)
* @see IRepository#PROP_NAME
* @see IRepository#PROP_NICKNAME
* @see IRepository#PROP_DESCRIPTION
* @see IRepository#PROP_SYSTEM
*/
public String getRepositoryProperty(URI location, String key);
/**
* Sets the property associated with the repository at the given URI,
* without loading the repository.
* <p>
* This method stores properties in a cache in the repository manager and does
* not write the property to the backing repository. This is useful for making
* repository properties available without incurring the cost of loading the repository.
* When the repository is loaded, it will overwrite any conflicting properties that
* have been set using this method. Only the repository properties referenced
* below can be stored by the repository manager; attempts to set other
* repository properties will be ignored.
* </p>
* <p>
* To persistently set a property on a repository, clients must load
* the repository and call {@link IRepository#setProperty(String, String)}.
* </p>
*
* @param location the absolute URI of the repository in question
* @param key the String key of the property desired
* @param value the value to set the property to
* @see #getRepositoryProperty(URI, String)
* @see IRepository#setProperty(String, String)
* @see IRepository#PROP_NAME
* @see IRepository#PROP_NICKNAME
* @see IRepository#PROP_DESCRIPTION
* @see IRepository#PROP_SYSTEM
*/
public void setRepositoryProperty(URI location, String key, String value);
/**
* Returns the enablement value of a repository. Disabled repositories are known
* to the repository manager, but are never used in the context of provisioning
* operations. Disabled repositories are useful as a form of bookmark to indicate that a
* repository location is of interest, but not currently used.
* <p>
* Note that enablement is a property of the repository manager and not a property
* of the affected repository. The enablement of the repository is discarded when
* a repository is removed from the repository manager.
*
* @param location The absolute location of the repository whose enablement is requested
* @return <code>true</code> if the repository is enabled, and
* <code>false</code> if it is not enabled, or if the repository location
* is not known to the repository manager.
* @see #REPOSITORIES_DISABLED
* @see #setEnabled(URI, boolean)
*/
public boolean isEnabled(URI location);
/**
* Removes the repository at the given location from the list of
* repositories known to this repository manager. The underlying
* repository is not deleted. This method has no effect if the given
* repository is not already known to this repository manager.
*
* @param location The absolute location of the repository to remove
* @return <code>true</code> if a repository was removed, and
* <code>false</code> otherwise.
*/
public boolean removeRepository(URI location);
/**
* Sets the enablement of a repository. Disabled repositories are known
* to the repository manager, but are never used in the context of provisioning
* operation. Disabled repositories are useful as a form of bookmark to indicate that a
* repository location is of interest, but not currently used.
* <p>
* Note that enablement is a property of the repository manager and not a property
* of the affected repository. The enablement of the repository is discarded when
* a repository is removed from the repository manager.
* <p>
* This method has no effect if the given repository location is not known to the
* repository manager.
*
* @param location The absolute location of the repository to enable or disable
* @param enablement <code>true</code>to enable the repository, and
* <code>false</code> to disable the repository
* @see #REPOSITORIES_DISABLED
* @see #isEnabled(URI)
*/
public void setEnabled(URI location, boolean enablement);
}
|
