2
* Copyright (c) OSGi Alliance (2011, 2012). All Rights Reserved.
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
17
package org.osgi.service.resolver;
19
import java.util.Collection;
20
import java.util.Collections;
21
import java.util.List;
23
import org.osgi.resource.Capability;
24
import org.osgi.resource.Requirement;
25
import org.osgi.resource.Resource;
26
import org.osgi.resource.Wiring;
29
* A resolve context provides resources, options and constraints to the
30
* potential solution of a {@link Resolver#resolve(ResolveContext) resolve}
36
* <li>Specify the mandatory and optional resources to resolve. The mandatory
37
* and optional resources must be consistent and correct. For example, they must
38
* not violate the singleton policy of the implementer.</li>
39
* <li>Provide {@link Capability capabilities} that the Resolver can use to
40
* satisfy {@link Requirement requirements} via the
41
* {@link #findProviders(Requirement)} method</li>
42
* <li>Constrain solutions via the {@link #getWirings()} method. A wiring
43
* consists of a map of existing {@link Resource resources} to {@link Wiring
45
* <li>Filter requirements that are part of a resolve operation via the
46
* {@link #isEffective(Requirement)}.</li>
50
* A resolver may call the methods on the resolve context any number of times
51
* during a resolve operation using any thread. Implementors should ensure that
52
* this class is properly thread safe.
55
* Except for {@link #insertHostedCapability(List, HostedCapability)}, the
56
* resolve context methods must be <i>idempotent</i>. This means that resources
57
* must have constant capabilities and requirements and the resolve context must
58
* return a consistent set of capabilities, wires and effective requirements.
61
* @version $Id: f92eae32ab6fadb25e13d226458d6af50e8dcbba $
63
public abstract class ResolveContext {
65
* Return the resources that must be resolved for this resolve context.
68
* The default implementation returns an empty collection.
70
* @return The resources that must be resolved for this resolve context. May
71
* be empty if there are no mandatory resources.
73
public Collection<Resource> getMandatoryResources() {
74
return emptyCollection();
78
* Return the resources that the resolver should attempt to resolve for this
79
* resolve context. Inability to resolve one of the specified resources will
80
* not result in a resolution exception.
83
* The default implementation returns an empty collection.
85
* @return The resources that the resolver should attempt to resolve for
86
* this resolve context. May be empty if there are no mandatory
89
public Collection<Resource> getOptionalResources() {
90
return emptyCollection();
93
private static <T> Collection<T> emptyCollection() {
94
return Collections.EMPTY_LIST;
98
* Find Capabilities that match the given Requirement.
100
* The returned list contains {@link Capability} objects where the Resource
101
* must be the declared Resource of the Capability. The Resolver can then
102
* add additional {@link HostedCapability} objects with the
103
* {@link #insertHostedCapability(List, HostedCapability)} method when it,
104
* for example, attaches fragments. Those {@link HostedCapability} objects
105
* will then use the host's Resource which likely differs from the declared
106
* Resource of the corresponding Capability.
109
* The returned list is in priority order such that the Capabilities with a
110
* lower index have a preference over those with a higher index. The
111
* resolver must use the
112
* {@link #insertHostedCapability(List, HostedCapability)} method to add
113
* additional Capabilities to maintain priority order. In general, this is
114
* necessary when the Resolver uses Capabilities declared in a Resource but
115
* that must originate from an attached host.
118
* Each returned Capability must match the given Requirement. This implies
119
* that the filter in the Requirement must match as well as any namespace
120
* specific directives. For example, the mandatory attributes for the
121
* {@code osgi.wiring.package} namespace.
123
* @param requirement The requirement that a resolver is attempting to
124
* satisfy. Must not be {@code null}.
125
* @return A list of {@link Capability} objects that match the specified
128
public abstract List<Capability> findProviders(Requirement requirement);
131
* Add a {@link HostedCapability} to the list of capabilities returned from
132
* {@link #findProviders(Requirement)}.
135
* This method is used by the {@link Resolver} to add Capabilities that are
136
* hosted by another Resource to the list of Capabilities returned from
137
* {@link #findProviders(Requirement)}. This function is necessary to allow
138
* fragments to attach to hosts, thereby changing the origin of a
139
* Capability. This method must insert the specified HostedCapability in a
140
* place that makes the list maintain the preference order. It must return
141
* the index in the list of the inserted {@link HostedCapability}.
143
* @param capabilities The list returned from
144
* {@link #findProviders(Requirement)}. Must not be {@code null}.
145
* @param hostedCapability The HostedCapability to insert in the specified
146
* list. Must not be {@code null}.
147
* @return The index in the list of the inserted HostedCapability.
150
public abstract int insertHostedCapability(List<Capability> capabilities, HostedCapability hostedCapability);
153
* Test if a given requirement should be wired in the resolve operation. If
154
* this method returns {@code false}, then the resolver should ignore this
155
* requirement during the resolve operation.
158
* The primary use case for this is to test the {@code effective} directive
159
* on the requirement, though implementations are free to use any effective
162
* @param requirement The Requirement to test. Must not be {@code null}.
163
* @return {@code true} if the requirement should be considered as part of
164
* the resolve operation.
166
public abstract boolean isEffective(Requirement requirement);
169
* Returns the wirings for existing resolved resources.
172
* For example, if this resolve context is for an OSGi framework, then the
173
* result would contain all the currently resolved bundles with each
174
* bundle's current wiring.
177
* Multiple calls to this method for this resolve context must return the
180
* @return The wirings for existing resolved resources. The returned map is
183
public abstract Map<Resource, Wiring> getWirings();
added
removed
src/main/java/org/osgi/service/resolver/ResolveContext.java
