package org.osgi.service.resolver;

import org.osgi.framework.resource.Capability;

/**
 * <p>
 * During the resolution process it is necessary for the resolver to create
 * synthetic resources to represent the merge of bundles and fragments.
 * 
 * <p>
 * For example if we have one bundle A and two fragments X and Y then resolver
 * will create two synthetic resources AX and AY.
 * 
 * <p>
 * In order for the Environment to provide a policy for which synthetic resources
 * are preferred, both the host bundle and providing fragment need to be visible.
 * This interface must therefore be used on all synthetic resource elements created by a resolver.
 * 
 * <p>
 * The environment can then enforce the ordering policy when a capability that is
 * provided by a synthetic resource is added to the SortedSet returned by
 * {@link Environment#findProviders(org.osgi.framework.resource.Requirement)}.
 * 
 * <p>The following is a short example of how this may look in practice:
 * 
 * <pre>class PreferrSmallResourcesEnvironment implements Environment {
 *  private static final Comparator SIZE_COMPARATOR = new Comparator() {
 *    public int compare(Capability capA, Capability capB) {
 *      Resource hostA = capA.getResource();
 *      Resource hostB = capB.getResource();
 *
 *      Resource synthA = getSyntheticResource(hostA);
 *      Resource synthB = getSyntheticResource(hostA);
 *
 *      int sizeA = getSize(hostA) + getSize(synthA);
 *      int sizeB = getSize(hostB) + getSize(synthB);
 *
 *      if (sizeA > sizeB) {
 *        return +1;
 *      } else if (sizeA < sizeB) {
 *        return -1;
 *      } else {
 *        return 0;
 *      }
 *    }
 *
 *    private int getSize(Resource resource) {
 *      if (resource == null)
 *        return 0;
 *
 *      Capability contentCapability = getCapability(resource, ContentNamespace.CAPABILITY); 
 *
 *      if (contentCapability == null)
 *        return 0;
 *
 *      Integer size = (Integer) contentCapability.getAttributes().get(ContentNamespace.SIZE_ATTRIBUTE);
 *          
 *      return size == null ? Integer.MAX_VALUE : size;
 *    }
 *    
 *    private Capability getCapability(Resource res, String namespace) {
 *      List&lt;Capability&gt; caps = res.getCapabilities(namespace);
 *      return caps.isEmpty() ? null : caps.get(0);
 *    }
 *
 *    private Resource getSyntheticResource(Resource res) {
 *      if (res instanceof Synthetic) {
 *        return (Resource) ((Synthetic) res).getOriginal();
 *      } else {
 *        return null;
 *      }
 *    }
 *  };
 *
 *  private List repositories;
 *
 *  public PreferrSmallResourcesEnvironment(List repositories) {
 *    this.repositories = repositories;
 *  }
 *
 *  public SortedSet findProviders(Requirement requirement) {
 *    SortedSet caps = new ConcurrentSkipListSet(SIZE_COMPARATOR);
 *
 *    for (Repository r : repositories) {
 *      caps.addAll(r.findProviders(requirement));
 *    }
 *
 *    return caps;
 *  }
 *
 *  public boolean isEffective(Requirement requirement) {
 *    return true;
 *  }
 *
 *  public Map getWirings() {
 *    return Collections.EMPTY_MAP;
 *  }
 *}</pre>
 *
 * <p>A Synthetic capability must report the Host Bundle via the {@link Capability#getResource()} method.
 * It must also report the original Capability from the Fragment Bundle via the
 * {@link #getOriginal()} method. The Environment may then access the fragment resource that
 * this capability originates from via {@link Capability#getResource()}. 
 */
public interface Synthetic {
	Object getOriginal();
}

@@ -75,16 +75,109 @@
 ability;
+%0Aimport org.osgi.framework.resource.Requirement;%0Aimport org.osgi.framework.resource.Resource;
 %0A%0A/**%0A *
@@ -1486,27 +1486,28 @@
 %0A *%0A *      
-int
+long
  sizeA = get
@@ -1545,19 +1545,20 @@
  *      
-int
+long
  sizeB =
@@ -3612,16 +3612,208 @@
 hetic %7B%0A
+%09/**%0A%09 * The original %7B@link Capability%7D, %7B@link Requirement%7D or %7B@link Resource%7D that backs this synthetic%0A%09 * element.%0A%09 * %0A%09 * @return the original capability, requirement or resource%0A%09 */%0A
 %09Object 

update javadoc