StateHelper


1   /*******************************************************************************
2    * Copyright (c) 2004, 2006 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  
14  /**
15   * A helper class that provides convenience methods for manipulating 
16   * state objects. <code>PlatformAdmin</code> provides an access point
17   * for a state helper.
18   * <p>
19   * Clients should not implement this interface.
20   * </p>
21   * @since 3.1
22   * @see PlatformAdmin#getStateHelper
23   */
24  public interface StateHelper {
25      /**
26       * Indicates that access is encouraged to an <code>ExportPackageDescription</code>.
27       */
28      public static int ACCESS_ENCOURAGED = 0x01;
29      /**
30       * Indicates that access is discouraged to an <code>ExportPackageDescription</code>.
31       */
32      public static int ACCESS_DISCOURAGED = 0x02;
33  
34      /**
35       * An option to include packages available from the execution environment when 
36       * getting the visible packages of a bundle.
37       * @see StateHelper#getVisiblePackages(BundleDescription, int)
38       */
39      public static int VISIBLE_INCLUDE_EE_PACKAGES = 0x01;
40  
41      /**
42       * Returns all bundles in the state depending on the given bundles. The given bundles
43       * appear in the returned array.
44       * 
45       * @param bundles the initial set of bundles
46       * @return an array containing bundle descriptions for the given roots and all
47       * bundles in the state that depend on them
48       */
49      public BundleDescription[] getDependentBundles(BundleDescription[] bundles);
50  
51      /**
52       * Returns all the prerequisite bundles in the state for the given bundles.  The given
53       * bundles appear in the returned array.
54       * @param bundles the inital set of bundles
55       * @return an array containing bundle descriptions for the given leaves and their
56       * prerequisite bundles in the state.
57       * @since 3.2
58       */
59      public BundleDescription[] getPrerequisites(BundleDescription[] bundles);
60  
61      /**
62       * Returns all unsatisfied constraints in the given bundle. Returns an 
63       * empty array if no unsatisfied constraints can be found.
64       * <p>
65       * Note that a bundle may have no unsatisfied constraints and still not be 
66       * resolved.
67       * </p>  
68       * 
69       * @param bundle the bundle to examine
70       * @return an array containing all unsatisfied constraints for the given bundle
71       */
72      public VersionConstraint[] getUnsatisfiedConstraints(BundleDescription bundle);
73  
74      /**
75       * Returns all unsatisfied constraints in the given bundles that have no possible supplier. 
76       * Returns an empty array if no unsatisfied leaf constraints can be found.
77       * <p>
78       * The returned constraints include only the unsatisfied constraints in the given 
79       * state that have no possible supplier (leaf constraints).  There may 
80       * be additional unsatisfied constraints in the given bundles but these will have at 
81       * least one possible supplier.  In this case the possible supplier of the constraint 
82       * is not resolved for some reason.  For example, a given state only has Bundles X and Y
83       * installed and Bundles X and Y have the following constraints:
84       * </p>
85       * <pre>
86       * Bundle X requires Bundle Y
87       * Bundle Y requires Bundle Z</pre>
88       * <p>
89       * In this case Bundle Y has an unsatisfied constraint leaf on Bundle Z.  This will 
90       * cause Bundle X's constraint on Bundle Y to be unsatisfied as well because the 
91       * bundles are involved in a dependency chain.  Bundle X's constraint on Bundle Y is 
92       * not considered a leaf because there is a possible supplier Y in the given state.
93       * </p>
94       * <p>
95       * Note that a bundle may have no unsatisfied constraints and still not be 
96       * resolved.
97       * </p>  
98       * 
99       * @param bundles the bundles to examine
100      * @return an array containing all unsatisfied leaf constraints for the given bundles
101      * @since 3.2
102      */
103     public VersionConstraint[] getUnsatisfiedLeaves(BundleDescription[] bundles);
104 
105     /**
106      * Returns whether the given package specification constraint is resolvable. 
107      * A package specification constraint may be 
108      * resolvable but not resolved, which means that the bundle that provides
109      * it has not been resolved for some other reason (e.g. another constraint 
110      * could not be resolved, another version has been picked, etc).
111      *  
112      * @param specification the package specification constraint to be examined
113      * @return <code>true</code> if the constraint can be resolved, 
114      * <code>false</code> otherwise
115      */
116     public boolean isResolvable(ImportPackageSpecification specification);
117 
118     /**
119      * Returns whether the given bundle specification constraint is resolvable. 
120      * A bundle specification constraint may be 
121      * resolvable but not resolved, which means that the bundle that provides
122      * it has not been resolved for some other reason (e.g. another constraint 
123      * could not be resolved, another version has been picked, etc).
124      *  
125      * @param specification the bundle specification constraint to be examined
126      * @return <code>true</code> if the constraint can be resolved, 
127      * <code>false</code> otherwise
128      */
129     public boolean isResolvable(BundleSpecification specification);
130 
131     /**
132      * Returns whether the given host specification constraint is resolvable. 
133      * A host specification constraint may be 
134      * resolvable but not resolved, which means that the bundle that provides
135      * it has not been resolved for some other reason (e.g. another constraint 
136      * could not be resolved, another version has been picked, etc).
137      *  
138      * @param specification the host specification constraint to be examined
139      * @return <code>true</code> if the constraint can be resolved, 
140      * <code>false</code> otherwise
141      */
142     public boolean isResolvable(HostSpecification specification);
143 
144     /**
145      * Sorts the given array of <strong>resolved</strong> bundles in pre-requisite order. If A 
146      * requires B, A appears after B. 
147      * Fragments will appear after all of their hosts. Constraints contributed by fragments will 
148      * be treated as if contributed by theirs hosts, affecting their position. This is true even if
149      * the fragment does not appear in the given bundle array.
150      * <p>
151      * Unresolved bundles are ignored.
152      * </p>
153      *  
154      * @param toSort an array of bundles to be sorted
155      * @return any cycles found 
156      */
157     public Object  [][] sortBundles(BundleDescription[] toSort);
158 
159     /**
160      * Returns a list of all packages that the specified bundle has access to which are
161      * exported by other bundles.  This takes into account all constraint specifications
162      * from the specified bundle (Import-Package, Require-Bundle etc).  A deep dependancy
163      * search is done for all packages which are available through the required bundles and 
164      * any bundles which are reexported.  This method also takes into account all directives
165      * which may be specified on the constraint specifications (e.g. uses, x-friends etc.) <p>
166      * 
167      * The returned list will not include any packages which are exported by the system bundle 
168      * on the behave of the running execution environment.  For example, when running on a 
169      * 1.4.2 JRE the system bundle will export the javax.xml.parsers package.  These types of 
170      * system packages will are not included in the returned list.
171      * <p>
172      * Same as calling getVisiblePackages(bundle, 0)
173      * @param bundle a bundle to get the list of packages for.
174      * @return a list of all packages that the specified bundle has access to which are
175      * exported by other bundles.
176      */
177     public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle);
178 
179     /**
180      * Returns a list of all packages that the specified bundle has access to which are
181      * exported by other bundles.  This takes into account all constraint specifications
182      * from the specified bundle (Import-Package, Require-Bundle etc).  A deep dependancy
183      * search is done for all packages which are available through the required bundles and 
184      * any bundles which are reexported.  This method also takes into account all directives
185      * which may be specified on the constraint specifications (e.g. uses, x-friends etc.) 
186      * @param bundle a bundle to get the list of packages for.
187      * @param options the options for selecting the visible packages
188      * @return a list of all packages that the specified bundle has access to which are
189      * exported by other bundles.
190      * @see StateHelper#VISIBLE_INCLUDE_EE_PACKAGES
191      * @since 3.3
192      */
193     public ExportPackageDescription[] getVisiblePackages(BundleDescription bundle, int options);
194 
195     /**
196      * Returns the access code that the specified <code>BundleDescription</code> has to the 
197      * specified <code>ExportPackageDescription</code>.
198      * @param bundle the bundle to find the access code for
199      * @param export the export to find the access code for
200      * @return the access code to the export.
201      * @see StateHelper#ACCESS_ENCOURAGED
202      * @see StateHelper#ACCESS_DISCOURAGED
203      */
204     public int getAccessCode(BundleDescription bundle, ExportPackageDescription export);
205 }
206
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags