State


1   /*******************************************************************************
2    * Copyright (c) 2003, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.osgi.service.resolver;
12  
13  import java.util.Dictionary  ;
14  
15  import org.osgi.framework.BundleException;
16  import org.osgi.framework.Version;
17  
18  /**
19   * The state of a system as reported by a resolver. This includes all bundles
20   * presented to the resolver relative to this state (i.e., both resolved and
21   * unresolved).
22   * <p>
23   * Clients may implement this interface.
24   * </p>
25   * @since 3.1
26   */
27  public interface State {
28      /**
29       * Adds the given bundle to this state.
30       * 
31       * @param description the description to add
32       * @return a boolean indicating whether the bundle was successfully added
33       */
34      public boolean addBundle(BundleDescription description);
35  
36      /**
37       * Returns a delta describing the differences between this state and the
38       * given state. The given state is taken as the base so the absence of a bundle
39       * in this state is reported as a deletion, etc.
40       *<p>Note that the generated StateDelta will contain BundleDeltas with one
41       *of the following types: BundleDelta.ADDED, BundleDelta.REMOVED and 
42       *BundleDelta.UPDATED</p>
43       * 
44       * @param baseState the base state
45       * @return a delta describing differences between this and the base state state 
46       */
47      public StateDelta compare(State baseState) throws BundleException;
48  
49      /**
50       * Removes a bundle description with the given bundle id.
51       * 
52       * @param bundleId the id of the bundle description to be removed
53       * @return the removed bundle description, or <code>null</code>, if a bundle
54       *  with the given id does not exist in this state
55       */
56      public BundleDescription removeBundle(long bundleId);
57  
58      /**
59       * Removes the given bundle description.
60       * 
61       * @param bundle the bundle description to be removed
62       * @return <code>true</code>, if if the bundle description was removed, 
63       *  <code>false</code> otherwise    
64       */
65      public boolean removeBundle(BundleDescription bundle);
66  
67      /**
68       * Updates an existing bundle description with the given description. 
69       * 
70       * @param newDescription the bundle description to replace an existing one
71       * @return <code>true</code>, if if the bundle description was updated, 
72       *  <code>false</code> otherwise    
73       */
74      public boolean updateBundle(BundleDescription newDescription);
75  
76      /**
77       * Returns the delta representing the changes from the time this state was
78       * first captured until now.
79       * 
80       * @return the state delta
81       */
82      public StateDelta getChanges();
83  
84      /**
85       * Returns descriptions for all bundles known to this state.
86       * 
87       * @return the descriptions for all bundles known to this state.
88       */
89      public BundleDescription[] getBundles();
90  
91      /**
92       * Returns the bundle descriptor for the bundle with the given id. 
93       * <code>null</code> is returned if no such bundle is found in 
94       * this state. 
95       * 
96       * @return the descriptor for the identified bundle
97       * @see BundleDescription#getBundleId()
98       */
99      public BundleDescription getBundle(long id);
100 
101     /**
102      * Returns the bundle descriptor for the bundle with the given name and
103      * version. A null value is returned if no such bundle is found in this state.
104      * A resolved bundle is always preferably returned over an unresolved bundle.
105      * If multiple bundles with the same resolution state are available, the bundle
106      * with the highest version number is returned if the <code>version<code> is
107      * null.
108      * 
109      * @param symbolicName symbolic name of the bundle to query
110      * @param version version of the bundle to query. null matches any bundle
111      * @return the descriptor for the identified bundle
112      */
113     public BundleDescription getBundle(String   symbolicName, Version version);
114 
115     /**
116      * Returns the bundle descriptor for the bundle with the given location
117      * identifier. null is returned if no such bundle is found in this state. 
118      * 
119      * @param location location identifier of the bundle to query
120      * @return the descriptor for the identified bundle
121      */
122     public BundleDescription getBundleByLocation(String   location);
123 
124     /**
125      * Returns the timestamp for this state. This
126      * correlates this timestamp to the system state. For example, if
127      * the system state timestamp is 4 but then some bundles are installed,
128      * the system state timestamp is updated. By comparing 4 to the current system
129      * state timestamp it is possible to detect if the states are out of sync.
130      * 
131      * @return the timestamp of this state
132      */
133     public long getTimeStamp();
134 
135     /**
136      * Sets the timestamp for this state
137      * @param newTimeStamp the new timestamp for this state
138      */
139     public void setTimeStamp(long newTimeStamp);
140 
141     /**
142      * Returns true if there have been no modifications to this state since the
143      * last time resolve() was called.
144      * 
145      * @return whether or not this state has changed since last resolved.
146      */
147     public boolean isResolved();
148 
149     /**
150      * Resolves the given version constraint with the given supplier. The given
151      * constraint object is destructively modified to reflect its new resolved
152      * state. Note that a constraint can be unresolved by passing null for 
153      * the supplier.
154      * <p>
155      * This method is intended to be used by resolvers in the process of
156      * determining which constraints are satisfied by which components.
157      * </p>
158      * 
159      * @param constraint the version constraint to update
160      * @param supplier the supplier which satisfies the constraint. May be null if 
161      * the constraint is to be unresolved.
162      * @throws IllegalStateException if this is not done during a call to
163      * <code>resolve</code>
164      */
165     public void resolveConstraint(VersionConstraint constraint, BaseDescription supplier);
166 
167     /**
168      * Sets whether or not the given bundle is selected in this state.
169      * <p>
170      * This method is intended to be used by resolvers in the process of
171      * determining which constraints are satisfied by which components.
172      * </p>
173      * 
174      * @param bundle the bundle to update
175      * @param status whether or not the given bundle is resolved, if false the other parameters are ignored
176      * @param hosts the host for the resolve fragment, can be <code>null</code>
177      * @param selectedExports the selected exported packages for this resolved bundle, can be <code>null</code>
178      * @param resolvedRequires the BundleDescriptions that resolve the required bundles for this bundle, can be <code>null</code>
179      * @param resolvedImports the exported packages that resolve the imports for this bundle, can be <code>null</code>
180      * @throws IllegalStateException if this is not done during a call to <code>resolve</code>
181      */
182     public void resolveBundle(BundleDescription bundle, boolean status, BundleDescription[] hosts, ExportPackageDescription[] selectedExports, BundleDescription[] resolvedRequires, ExportPackageDescription[] resolvedImports);
183 
184     /**
185      * Sets the given removal pending bundle to removal complete for this state.
186      * <p>
187      * This method is intended to be used by resolvers in the process of 
188      * resolving bundles.
189      * </p>
190      * @param bundle the bundle to set a removal complete.
191      * @throws IllegalStateException if this is not done during a call to
192      * <code>resolve</code>
193      */
194     public void removeBundleComplete(BundleDescription bundle);
195 
196     /**
197      * Adds a new <code>ResolverError</code> for the specified bundle.
198      * <p>
199      * This method is intended to be used by resolvers in the process of
200      * resolving.
201      * </p>
202      * 
203      * @param bundle the bundle to add a new <code>ResolverError</code> for
204      * @param type the type of <code>ResolverError</code> to add
205      * @param data the data for the <code>ResolverError</code>
206      * @param unsatisfied the unsatisfied constraint or null if the resolver error was not caused
207      * by an unsatisfied constraint.
208      * @throws IllegalStateException if this is not done during a call to <code>resolve</code>
209      * @since 3.2
210      */
211     public void addResolverError(BundleDescription bundle, int type, String   data, VersionConstraint unsatisfied);
212 
213     /**
214      * Removes all <code>ResolverError</code>s for the specified bundle.
215      * <p>
216      * This method is intended to be used by resolvers in the process of
217      * resolving.
218      * </p>
219      * 
220      * @param bundle the bundle to remove all <code>ResolverError</code>s for
221      * @throws IllegalStateException if this is not done during a call to <code>resolve</code>
222      * @since 3.2
223      */
224     public void removeResolverErrors(BundleDescription bundle);
225 
226     /**
227      * Returns all <code>ResolverError</code>s for the given bundle
228      * @param bundle the bundle to get all <code>ResolverError</code>s for
229      * @return all <code>ResolverError</code>s for the given bundle
230      * @since 3.2
231      */
232     public ResolverError[] getResolverErrors(BundleDescription bundle);
233 
234     /**
235      * Returns the resolver associated with this state. A state can work with
236      * at most one resolver at any given time. Similarly, a resolver can work
237      * with at most one state at a time.
238      * 
239      * @return the resolver for this state. null is returned if the state does
240      * not have a resolver
241      */
242     public Resolver getResolver();
243 
244     /**
245      * Sets the resolver associated with this state. A state can work with at
246      * most one resolver at any given time. Similarly, a resolver can work with
247      * at most one state at a time.
248      * <p>
249      * To ensure that this state and the given resovler are properly linked,
250      * the following expression must be included in this method if the given
251      * resolver (value) is not identical to the result of this.getResolver().
252      * 
253      * <pre>
254      *  if (this.getResolver() != value) value.setState(this);
255      * </pre>
256      * 
257      * </p>
258      */
259     // TODO what happens if you set the Resolver after some bundles have
260     // been added to the state but it is not resolved?  Should setting
261     // the resolver force a state to be unresolved?
262     public void setResolver(Resolver value);
263 
264     /**
265      * Resolves the constraints contained in this state using the resolver
266      * currently associated with the state and returns a delta describing the
267      * changes in resolved states and dependencies in the state.
268      * <p>
269      * Note that this method is typically implemented using
270      * 
271      * <pre>
272      *  this.getResolver().resolve();
273      * </pre>
274      * 
275      * and is the preferred path for invoking resolution. In particular, states
276      * should refuse to perform updates (@see #select() and
277      * #resolveConstraint()) if they are not currently involved in a resolution
278      * cycle.
279      * <p>
280      * Note the given state is destructively modified to reflect the results of
281      * resolution.
282      * </p>
283      * 
284      * @param incremental a flag controlling whether resolution should be incremental
285      * @return a delta describing the changes in resolved state and 
286      * interconnections
287      */
288     public StateDelta resolve(boolean incremental);
289 
290     /**
291      * Same as State.resolve(true);
292      */
293     public StateDelta resolve();
294 
295     /**
296      * Resolves the constraints contained in this state using the resolver
297      * currently associated with the state in a incremental, "least-perturbing" 
298      * mode, and returns a delta describing the changes in resolved states and 
299      * dependencies in the state.
300      * 
301      * @param discard an array containing descriptions for bundles whose 
302      *  current resolution state should be forgotten.  If <code>null</code>
303      *  then all the current removal pending BundleDescriptions are refreshed.
304      * @return a delta describing the changes in resolved state and 
305      *  interconnections
306      */
307     public StateDelta resolve(BundleDescription[] discard);
308 
309     /**
310      * Sets the version overrides which are to be applied during the resolutoin
311      * of this state. Version overrides allow external forces to
312      * refine/override the version constraints setup by the components in the
313      * state.
314      * 
315      * @param value
316      */
317     // TODO the exact form of this is not defined as yet.
318     public void setOverrides(Object   value);
319 
320     /**
321      * Returns descriptions for all bundles currently resolved in this state.
322      * 
323      * @return the descriptions for all bundles currently resolved in this
324      * state.
325      */
326     public BundleDescription[] getResolvedBundles();
327 
328     /**
329      * Returns whether this state is empty.
330      * @return <code>true</code> if this state is empty, <code>false</code> 
331      *  otherwise
332      */
333     public boolean isEmpty();
334 
335     /**
336      * Returns all exported packages in this state, according to the OSGi rules for resolution. 
337      * @see org.osgi.service.packageadmin.PackageAdmin#getExportedPackages(Bundle)
338      */
339     public ExportPackageDescription[] getExportedPackages();
340 
341     /**
342      * Returns all bundle descriptions with the given bundle symbolic name.
343      * @param symbolicName symbolic name of the bundles to query
344      * @return the descriptors for all bundles known to this state with the
345      * specified symbolic name.
346      */
347     public BundleDescription[] getBundles(String   symbolicName);
348 
349     /**
350      * Returns the factory that created this state.
351      * @return the state object factory that created this state 
352      */
353     public StateObjectFactory getFactory();
354 
355     /**
356      * Attempts to find an ExportPackageDescription that will satisfy a dynamic import
357      * for the specified requestedPackage for the specified importingBundle.  If no
358      * ExportPackageDescription is available that satisfies a dynamic import for the 
359      * importingBundle then <code>null</code> is returned.
360      * @param importingBundle the BundleDescription that is requesting a dynamic package
361      * @param requestedPackage the name of the package that is being requested
362      * @return the ExportPackageDescription that satisfies the dynamic import request; 
363      * a value of <code>null</code> is returned if none is available.
364      */
365     public ExportPackageDescription linkDynamicImport(BundleDescription importingBundle, String   requestedPackage);
366 
367     /**
368      * Sets the platform properties of the state.  The platform properties
369      * are used to match platform filters that are specified in Eclipse-PlatformFilter
370      * bundle manifest header.  The following propreties are supported by the
371      * state: <p>
372      * osgi.nl - the platform language setting<br>
373      * osgi.os - the platform operating system<br>
374      * osgi.arch - the platform architecture<br>
375      * osgi.ws - the platform windowing system<br>
376      * org.osgi.framework.system.packages - the packages exported by the system bundle <br>
377      * osgi.resolverMode - the resolver mode.  A value of "strict" will set the resolver mode to strict.<br>
378      * org.osgi.framework.executionenvironment - the comma separated list of supported execution environments <br>
379      * <p>
380      * The values used for the supported properties can be <tt>String</tt> type
381      * to specify a single value for the property or they can by <tt>String[]</tt>
382      * to specify a list of values for the property. 
383      * @param platformProperties the platform properties of the state
384      * @return false if the platformProperties specified do not change any of the
385      * supported properties already set.  If any of the supported property values 
386      * are changed as a result of calling this method then true is returned.
387      */
388     public boolean setPlatformProperties(Dictionary   platformProperties);
389 
390     /**
391      * Sets the platform properties of the state to a list of platform properties.  
392      * The platform properties are used to match platform filters that are specified 
393      * in Eclipse-PlatformFilter bundle manifest header. 
394      * @see #setPlatformProperties(Dictionary) for a list of supported properties.  
395      * 
396      * @param platformProperties a set of platform properties for the state
397      * @return false if the platformProperties specified do not change any of the
398      * supported properties already set.  If any of the supported property values 
399      * are changed as a result of calling this method then true is returned.
400      */
401     public boolean setPlatformProperties(Dictionary  [] platformProperties);
402 
403     /**
404      * Returns the list of platform properties currently set for this state.
405      * @return the list of platform properties currently set for this state.
406      */
407     public Dictionary  [] getPlatformProperties();
408 
409     /**
410      * Returns the list of system packages which are exported by the system bundle.  
411      * The list of system packages is set by the org.osgi.framework.system.packages
412      * value in the platform properties for this state.
413      * @see #setPlatformProperties(Dictionary)
414      * @return the list of system packages
415      */
416     public ExportPackageDescription[] getSystemPackages();
417 
418     /**
419      * Returns a state helper object. State helpers provide convenience methods 
420      * for manipulating states. 
421      * <p>
422      * A possible implementation for this
423      * method would provide the same single StateHelper instance to all clients.
424      * </p>
425      * 
426      * @return a state helper
427      * @see StateHelper
428      * @since 3.2
429      */
430     public StateHelper getStateHelper();
431 
432     /**
433      * Returns the highest bundle ID.  The value -1 is returned if no 
434      * bundles exist in this state.
435      * <p>
436      * Note that this method returns the highest bundle ID the ever existed in this 
437      * this state object.  This bundle may have been removed from the state.
438      * @return the highest bundle ID.
439      * @since 3.3
440      */
441     public long getHighestBundleId();
442 }
443
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags