/**
 * Service interface that manages artifacts contributed to a Tuscany runtime.
 *
 * @version $Rev: 499649523009 $ $Date: 2007-0103-2427 1810:4038:5524 -08000700 (WedTue, 2427 JanMar 2007) $
 */
public interface ContributionService {
    /**
     * Contribute an artifact to the SCA Domain. The type of the contribution is
     * determined by the Content-Type of the
     * resource or, if that is undefined,
     * by some implementation-specific means (such as mapping an extension in the
     * the URL's path).
     * 
     * @param contributionURI The URI that is used as the contribution unique ID. 
     * @param sourceURL the location of the resource containing the artifact
     * @return@param astoreInRepository URIflag that uniquely identifies this identifies if you want to copy the
     *            contribution withinto the SCA Domainrepository
     * @throws DeploymentException if there was a problem with the contribution
     * @throws IOException         if there was a problem reading the resource
     */
    URIvoid contribute(URI contributionURI, URL sourceURL, boolean contributionstoreInRepository) throws DeploymentException, ContributionException,
        IOException;

    /**
     * Contribute an artifact to the SCA Domain.
     * 
     * @param sourcecontributionURI The URI that is used  an identifier for as the sourcecontribution of this contributionunique ID.
     * @param contributioncontributionContent a stream containing the resource being
     *            contributed; the stream will not be closed but the read
     *            position after the call is undefined
     * @throws DeploymentException if there was reada positionproblem afterwith the call is undefined contribution
     * @throws IOException if there was a problem reading the stream
     * @param contentType  the type of contribution being made; must be a valid Content-Type value as specified by <a/
    void contribute(URI contributionURI, InputStream contributionContent)
        throws ContributionException, IOException;

    /**
     * Get the model for an installed contribution
     * 
     * @param contribution The URI of an installed contribution
     * @return  href="http://www.ietf.org/rfc/rfc2045.txt">RFC2045</a> and must not be null @return a URIThe model for the contribution or null if there is no such
     *         contribution
     */
    Contribution getContribution(URI contribution);

    /**
     * Adds thator uniquelyupdates identifiesa thisdeployment contributioncomposite withinusing thea SCAsupplied Domaincomposite
     * @throws DeploymentException if there was a problem with the contribution ("composite by value" - a data structure, not an existing resource in the
     * domain) to the contribution identified by a supplied contribution URI.
     * @throws IOException The added or updated deployment composite is given a relative URI that
     * matches the "name" attribute of ifthe therecomposite, waswith a problem reading the stream ".composite"
     * suffix.
     */
    URIvoid contributeaddDeploymentComposite(URI source, InputStream contribution, StringObject contentType) throws DeploymentException, IOExceptioncomposite);
    
    /**
     * Remove a contribution from the SCA domain
     * 
     * @param contribution The URI of the contribution
     * @throws DeploymentException
     */
    void remove(URI contribution) throws DeploymentExceptionContributionException;
    
    /**
     * Resolve an artifact by QName within the contribution
     * 
     * @param <T> The java type of the artifact such as javax.wsdl.Definition
     * @param contribution The URI of the contribution
     * @param definitionType The java type of the artifact
     * @param namespace The namespace of the artifact
     * @param name The name of the artifact
     * @return The resolved artifact
     */
    <T> T resolve(URI contribution, Class<T> definitionType, String namespace, String name);
    
    /**
     * Resolve the reference to an artifact by the location URI within the given contribution. 
     * contribution. Some typical use cases are:
     * <ul>
     * <li>Reference a XML schema using
     * {http://www.w3.org/2001/XMLSchema-instance}schemaLocation or
     * <li>Reference a list of WSDLs using
     * {http://www.w3.org/2004/08/wsdl-instance}wsdlLocation
     * </ul>
     * 
     * @param contribution The URI of the contribution
     * @param namespace The namespace of the artifact. This is for validation
     *            purpose. If the namespace is null, then no check will be
     *  then      no check will be performed.  
     * @param uri The location URI
     * @param baseURI The URI of the base artifact where the reference is
     *            declared
     * @return The URL of the resolved artifact
     */
    URL resolve(URI contribution, String namespace, URI uri, URI baseURI);
}