Richard S. Hall | dfd78a4 | 2012-05-11 20:19:02 +0000 | [diff] [blame] | 1 | /* |
Carsten Ziegeler | 3314f91 | 2014-07-30 07:22:32 +0000 | [diff] [blame^] | 2 | * Copyright (c) OSGi Alliance (2011, 2013). All Rights Reserved. |
Richard S. Hall | dfd78a4 | 2012-05-11 20:19:02 +0000 | [diff] [blame] | 3 | * |
| 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 |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 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. |
| 15 | */ |
| 16 | |
| 17 | package org.osgi.resource; |
| 18 | |
| 19 | import java.util.List; |
Carsten Ziegeler | 3314f91 | 2014-07-30 07:22:32 +0000 | [diff] [blame^] | 20 | import org.osgi.annotation.versioning.ConsumerType; |
Richard S. Hall | dfd78a4 | 2012-05-11 20:19:02 +0000 | [diff] [blame] | 21 | |
| 22 | /** |
| 23 | * A wiring for a resource. A wiring is associated with a resource and |
| 24 | * represents the dependencies with other wirings. |
| 25 | * |
| 26 | * <p> |
| 27 | * Instances of this type must be <i>effectively immutable</i>. That is, for a |
| 28 | * given instance of this interface, the methods defined by this interface must |
| 29 | * always return the same result. |
| 30 | * |
| 31 | * @ThreadSafe |
Carsten Ziegeler | 3314f91 | 2014-07-30 07:22:32 +0000 | [diff] [blame^] | 32 | * @author $Id: 935272fa914a9cc0020549c43a3857acad2c45cc $ |
Richard S. Hall | dfd78a4 | 2012-05-11 20:19:02 +0000 | [diff] [blame] | 33 | */ |
Carsten Ziegeler | 3314f91 | 2014-07-30 07:22:32 +0000 | [diff] [blame^] | 34 | @ConsumerType |
Richard S. Hall | dfd78a4 | 2012-05-11 20:19:02 +0000 | [diff] [blame] | 35 | public interface Wiring { |
| 36 | /** |
| 37 | * Returns the capabilities provided by this wiring. |
| 38 | * |
| 39 | * <p> |
| 40 | * Only capabilities considered by the resolver are returned. For example, |
| 41 | * capabilities with {@link Namespace#CAPABILITY_EFFECTIVE_DIRECTIVE |
| 42 | * effective} directive not equal to {@link Namespace#EFFECTIVE_RESOLVE |
| 43 | * resolve} are not returned. |
| 44 | * |
| 45 | * <p> |
| 46 | * A capability may not be required by any wiring and thus there may be no |
| 47 | * {@link #getProvidedResourceWires(String) wires} for the capability. |
| 48 | * |
| 49 | * <p> |
| 50 | * A wiring for a non-fragment resource provides a subset of the declared |
| 51 | * capabilities from the resource and all attached fragment |
| 52 | * resources<sup>†</sup>. Not all declared capabilities may be |
| 53 | * provided since some may be discarded. For example, if a package is |
| 54 | * declared to be both exported and imported, only one is selected and the |
| 55 | * other is discarded. |
| 56 | * <p> |
| 57 | * A wiring for a fragment resource with a symbolic name must provide |
| 58 | * exactly one {@code osgi.identity} capability. |
| 59 | * <p> |
| 60 | * † The {@code osgi.identity} capability provided by attached |
| 61 | * fragment resource must not be included in the capabilities of the host |
| 62 | * wiring. |
| 63 | * |
| 64 | * @param namespace The namespace of the capabilities to return or |
| 65 | * {@code null} to return the capabilities from all namespaces. |
| 66 | * @return A list containing a snapshot of the {@link Capability}s, or an |
| 67 | * empty list if this wiring provides no capabilities in the |
| 68 | * specified namespace. For a given namespace, the list contains the |
Carsten Ziegeler | 3314f91 | 2014-07-30 07:22:32 +0000 | [diff] [blame^] | 69 | * capabilities in the order the capabilities were specified in the |
Richard S. Hall | dfd78a4 | 2012-05-11 20:19:02 +0000 | [diff] [blame] | 70 | * manifests of the {@link #getResource() resource} and the attached |
| 71 | * fragment resources<sup>†</sup> of this wiring. There is no |
| 72 | * ordering defined between capabilities in different namespaces. |
| 73 | */ |
| 74 | List<Capability> getResourceCapabilities(String namespace); |
| 75 | |
| 76 | /** |
| 77 | * Returns the requirements of this wiring. |
| 78 | * |
| 79 | * <p> |
| 80 | * Only requirements considered by the resolver are returned. For example, |
| 81 | * requirements with {@link Namespace#REQUIREMENT_EFFECTIVE_DIRECTIVE |
| 82 | * effective} directive not equal to {@link Namespace#EFFECTIVE_RESOLVE |
| 83 | * resolve} are not returned. |
| 84 | * |
| 85 | * <p> |
| 86 | * A wiring for a non-fragment resource has a subset of the declared |
| 87 | * requirements from the resource and all attached fragment resources. Not |
| 88 | * all declared requirements may be present since some may be discarded. For |
| 89 | * example, if a package is declared to be optionally imported and is not |
| 90 | * actually imported, the requirement must be discarded. |
| 91 | * |
| 92 | * @param namespace The namespace of the requirements to return or |
| 93 | * {@code null} to return the requirements from all namespaces. |
| 94 | * @return A list containing a snapshot of the {@link Requirement}s, or an |
| 95 | * empty list if this wiring uses no requirements in the specified |
Carsten Ziegeler | 3314f91 | 2014-07-30 07:22:32 +0000 | [diff] [blame^] | 96 | * namespace. For a given namespace, the list contains the |
| 97 | * requirements in the order the requirements were specified in the |
| 98 | * manifests of the {@link #getResource() resource} and the attached |
| 99 | * fragment resources of this wiring. There is no ordering defined |
| 100 | * between requirements in different namespaces. |
Richard S. Hall | dfd78a4 | 2012-05-11 20:19:02 +0000 | [diff] [blame] | 101 | */ |
| 102 | List<Requirement> getResourceRequirements(String namespace); |
| 103 | |
| 104 | /** |
| 105 | * Returns the {@link Wire}s to the provided {@link Capability capabilities} |
| 106 | * of this wiring. |
| 107 | * |
| 108 | * @param namespace The namespace of the capabilities for which to return |
| 109 | * wires or {@code null} to return the wires for the capabilities in |
| 110 | * all namespaces. |
| 111 | * @return A list containing a snapshot of the {@link Wire}s for the |
| 112 | * {@link Capability capabilities} of this wiring, or an empty list |
| 113 | * if this wiring has no capabilities in the specified namespace. |
| 114 | * For a given namespace, the list contains the wires in the order |
| 115 | * the capabilities were specified in the manifests of the |
| 116 | * {@link #getResource() resource} and the attached fragment |
| 117 | * resources of this wiring. There is no ordering defined between |
| 118 | * capabilities in different namespaces. |
| 119 | */ |
| 120 | List<Wire> getProvidedResourceWires(String namespace); |
| 121 | |
| 122 | /** |
| 123 | * Returns the {@link Wire}s to the {@link Requirement requirements} in use |
| 124 | * by this wiring. |
| 125 | * |
| 126 | * @param namespace The namespace of the requirements for which to return |
| 127 | * wires or {@code null} to return the wires for the requirements in |
| 128 | * all namespaces. |
| 129 | * @return A list containing a snapshot of the {@link Wire}s for the |
| 130 | * {@link Requirement requirements} of this wiring, or an empty list |
| 131 | * if this wiring has no requirements in the specified namespace. |
| 132 | * For a given namespace, the list contains the wires in the order |
| 133 | * the requirements were specified in the manifests of the |
| 134 | * {@link #getResource() resource} and the attached fragment |
| 135 | * resources of this wiring. There is no ordering defined between |
| 136 | * requirements in different namespaces. |
| 137 | */ |
| 138 | List<Wire> getRequiredResourceWires(String namespace); |
| 139 | |
| 140 | /** |
| 141 | * Returns the resource associated with this wiring. |
| 142 | * |
| 143 | * @return The resource associated with this wiring. |
| 144 | */ |
| 145 | Resource getResource(); |
| 146 | } |