Resolver


1   /*******************************************************************************
2    * Copyright (c) 2003, 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  import java.util.Comparator  ;
14  import java.util.Dictionary  ;
15  /**
16   * An implementation of a resolver which resolves the constraints of the bundles
17   * in a system.
18   * <p>
19   * Clients may implement this interface.
20   * </p>
21   * @since 3.1
22   */
23  public interface Resolver {
24  
25      /**
26       * Resolves the state associated with this resolver and returns an array of
27       * bundle deltas describing the changes.. The state and version bindings
28       * for the various bundles and packages in this state are updated and a
29       * array containing bundle deltas describing the changes returned.
30       * <p>
31       * This method is intended to be called only by State objects in response
32       * to a user invocation of State.resolve(). States will typically refuse to
33       * update their constituents (see State.resolveBundle() and
34       * State.resolveConstraint()) if their resolve method is not currently
35       * being invoked.
36       * </p>
37       * <p>
38       * Note the given state is destructively modified to reflect the results of
39       * resolution.
40       * </p>
41       * @param discard the list of bundles to discard the resolve status and 
42       * reresolve.  A <tt>null</tt> value indicates that all currently unresolved
43       * bundles in the state should be resolved.
44       * @param platformProperties the platform properties used to match platform filters
45       * against.  A <tt>null</tt> value indicates that the system properties should
46       * be used to match against
47       */
48      public void resolve(BundleDescription[] discard, Dictionary  [] platformProperties);
49  
50      /**
51       * Flushes this resolver of any stored/cached data it may be keeping to
52       * facilitate incremental processing on its associated state. This is
53       * typicaly used when switching the resolver's state object.
54       */
55      public void flush();
56  
57      /**
58       * Returns the state associated with this resolver. A state can work with
59       * at most one resolver at any given time. Similarly, a resolver can work
60       * with at most one state at a time.
61       * 
62       * @return the state for this resolver. null is returned if the resolver
63       * does not have a state
64       */
65      public State getState();
66  
67      /**
68       * Sets the state associated with this resolver. A state can work with at
69       * most one resolver at any given time. Similarly, a resolver can work with
70       * at most one state at a time.
71       * <p>
72       * To ensure that this resolver and the given state are properly linked,
73       * the following expression must be included in this method if the given
74       * state (value) is not identical to the result of this.getState().
75       * </p>
76       * 
77       * <pre>
78       *  if (this.getState() != value) value.setResolver(this);
79       * </pre>
80       */
81      public void setState(State value);
82  
83      /**
84       * Notifies the resolver a bundle has been added to the state.
85       * @param bundle
86       */
87      public void bundleAdded(BundleDescription bundle);
88  
89      /**
90       * Notifies the resolver a bundle has been removed from the state.
91       * @param bundle the bundle description to remove
92       * @param pending indicates if the bundle to be remove has current dependents and
93       * will pend complete removal until the bundle has been re-resolved.
94       */
95      public void bundleRemoved(BundleDescription bundle, boolean pending);
96  
97      /**
98       * Notifies the resolver a bundle has been updated in the state.
99       * @param newDescription the new description
100      * @param existingDescription the existing description
101      * @param pending indicates if the bundle to be updated has current dependents and
102      * will pend complete removal until the bundle has been re-resolved.
103      */
104     public void bundleUpdated(BundleDescription newDescription, BundleDescription existingDescription, boolean pending);
105 
106     /**
107      * Attempts to find an ExportPackageDescription that will satisfy a dynamic import
108      * for the specified requestedPackage for the specified importingBundle.  If no
109      * ExportPackageDescription is available that satisfies a dynamic import for the 
110      * importingBundle then <code>null</code> is returned.
111      * @param importingBundle the BundleDescription that is requesting a dynamic package
112      * @param requestedPackage the name of the package that is being requested
113      * @return the ExportPackageDescription that satisfies the dynamic import request; 
114      * a value of <code>null</code> is returned if none is available.
115      */
116     public ExportPackageDescription resolveDynamicImport(BundleDescription importingBundle, String   requestedPackage);
117 
118     /**
119      * Sets the selection policy for this resolver.  A selection policy is used to sort 
120      * possible suppliers of a version constraint in descending order.  That is an order
121      * which is from most desired to least desired.  The objects passed to the 
122      * selection policy {@link Comparator#compare(Object, Object)} method 
123      * will be of type {@link BaseDescription}.  The selection policy should return a 
124      * negative number, zero, or a positive number depending on if the first object is 
125      * more desired, equal amount of desire, or less desired than the second object respectively.
126      * <p>
127      * If no selection policy is set then a default policy will be used which sorts according
128      * to the following rules: 
129      * <ol>
130      * <li> The resolution status of the bundle which supplies the base description.  Resolved bundles take priority over unresolved ones.
131      * <li> The version of the base description.  Higher versions take priority over lower versions.
132      * <li> The bundle ID which supplies the base description.  Lower IDs take priority over higher IDs. 
133      * </ol>
134      * @param selectionPolicy the selection policy for this resolver
135      * @since 3.2
136      */
137     public void setSelectionPolicy(Comparator   selectionPolicy);
138 
139     /**
140      * Returns the selection policy for this resolver or null if it is not set 
141      * @return the selection policy for this resolver or null if it is not set
142      * @since 3.2 
143      */
144     public Comparator   getSelectionPolicy();
145 }
146
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags