Start cleaning up JavaDoc and changes coming to light while doing that: move getDeployer and getAssemblyFactory from Node to NodeFactory, change getInstalledContribution to return an assembly Contribution instead of an InstalledContribution, rename deployDeployables to runDeployables

git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@959582 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 90 insertions, 49 deletions

diff --git a/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/Node.java b/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/Node.java
index fdf62b4bb2..28520cb2c1 100644
--- a/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/Node.java
+++ b/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/Node.java
@@ -31,51 +31,59 @@ import org.apache.tuscany.sca.contribution.Contribution;
 import org.apache.tuscany.sca.contribution.processor.ContributionReadException;
 import org.apache.tuscany.sca.deployment.Deployer;
 import org.apache.tuscany.sca.monitor.ValidationException;
-import org.apache.tuscany.sca.node2.impl.InstalledContribution;
 import org.apache.tuscany.sca.runtime.ActivationException;
 import org.oasisopen.sca.NoSuchServiceException;
 
 public interface Node {
 
     /**
-     * 4577 10.5.1 install Contribution & update Contribution
-     * 4578 Creates or updates an installed contribution with a supplied root contribution, and installed at a supplied
-     * 4579 base URI. A supplied dependent contribution list (<export/> elements) specifies the contributions that are
-     * 4580 used to resolve the dependencies of the root contribution and other dependent contributions. These
-     * 4581 override any dependent contributions explicitly listed via the @location attribute in the import statements
-     * 4582 of the contribution.
-     * 4583 SCA follows the simplifying assumption that the use of a contribution for resolving anything also means
-     * 4584 that all other exported artifacts can be used from that contribution. Because of this, the dependent
-     * 4585 contribution list is just a list of installed contribution URIs. There is no need to specify what is being used
-     * 4586 from each one.
-     * 4587 Each dependent contribution is also an installed contribution, with its own dependent contributions. By
-     * 4588 default these dependent contributions of the dependent contributions (which we will call indirect
-     * 4589 dependent contributions) are included as dependent contributions of the installed contribution. However,
-     * 4590 if a contribution in the dependent contribution list exports any conflicting definitions with an indirect
-     * 4591 dependent contribution, then the indirect dependent contribution is not included (i.e. the explicit list
-     * 4592 overrides the default inclusion of indirect dependent contributions). Also, if there is ever a conflict
-     * 4593 between two indirect dependent contributions, then the conflict MUST be resolved by an explicit entry in
-     * 4594 the dependent contribution list.
-     * 4595 [ASM12009]
-     * 4596 Note that in many cases, the dependent contribution list can be generated. In particular, if the creator of
-     * 4597 a Domain is careful to avoid creating duplicate definitions for the same qualified name, then it is easy for
-     * 4598 this list to be generated by tooling.     * 
-     * @param uri
-     * @param contributionURL
+     * Creates an installed contribution from a supplied root contribution and installed at a supplied base URI.
+     * See section 10.5.1 of the Assembly Specification.
+     * 
+     * @param uri  the base uri of where to install the contribution
+     * @param contributionURL  the URL where the contribution is located
+     * @param metaDataURL  the location of an optional generated Contribution Metadata Document. See section 10.2.2
+     *               of the Assembly Specification. May be null.
+     * @param dependentContributionURIs  specifies the contributions that are used to resolve the dependencies of the 
+     *               root contribution and other dependent contributions. May be null.
+     * @param runDeployables  true if the composites defined as deployable in the contributions sca-contribution.xml
+     *               file or supplied metaData file should be run, false if they should not be. 
+     * 
      * @throws ContributionReadException 
      * @throws ActivationException 
      * @throws ValidationException 
      */
-    void installContribution(String uri, String contributionURL, String metaDataURL, List<String> dependentContributionURIs, boolean deployDeployables) throws ContributionReadException, ActivationException, ValidationException;
-    void installContribution(Contribution contribution, List<String> dependentContributionURIs, boolean deployDeployables) throws ContributionReadException, ActivationException, ValidationException;
+    void installContribution(String uri, String contributionURL, String metaDataURL, List<String> dependentContributionURIs, boolean runDeployables) throws ContributionReadException, ActivationException, ValidationException;
 
+    /**
+     * Creates an installed contribution from a supplied Contribution object.
+     * See section 10.5.1 of the Assembly Specification.
+     * 
+     * @param contribution  the Contribution object
+     * @param dependentContributionURIs  specifies the contributions that are used to resolve the dependencies of the 
+     *               root contribution and other dependent contributions. May be null.
+     * @param runDeployables  true if the composites defined as deployable in the contributions sca-contribution.xml
+     *               file or supplied metaData file should be run, false if they should not be. 
+     * 
+     * @throws ContributionReadException 
+     * @throws ActivationException 
+     * @throws ValidationException 
+     */
+    void installContribution(Contribution contribution, List<String> dependentContributionURIs, boolean runDeployables) throws ContributionReadException, ActivationException, ValidationException;
+
+    /**
+     * Creates an installed contribution from a supplied root contribution.
+     * See section 10.5.1 of the Assembly Specification.
+     * 
+     * @param contributionURL  the URL where the contribution is located
+     * @return the URI where the contribution was installed
+     * 
+     * @throws ContributionReadException 
+     * @throws ActivationException 
+     * @throws ValidationException 
+     */
     String installContribution(String contributionURL) throws ContributionReadException, ActivationException, ValidationException;
     
-    /* Useful short forms of that for when you don't care or have the others (but leave out for now to keep as simple as possible):
-    void installContribution(String uri, String contributionURL) throws ContributionReadException, ActivationException, ValidationException;
-    String installContribution(String contributionURL, boolean autoDeploy) throws ContributionReadException, ActivationException, ValidationException;
-    */
-    
     /**
      * 4577 10.5.1 install Contribution & update Contribution
      * 4578 Creates or updates an installed contribution with a supplied root contribution, and installed at a supplied
@@ -210,7 +218,7 @@ public interface Node {
      * 4700 wsdl:PortTypeportType). The result is a single definition, in whatever form is appropriate for that
      * 4701 definition type.
      * 4702 Note that this, like all the other domain-level operations, is a conceptual operation. Its capabilities need to
-     * 4703 exist in some form, but not necessarily as a service operation with exactly this signature.     * 
+     * 4703 exist in some form, but not necessarily as a service operation with exactly this signature.     
      * @param contributionURI
      * @param definition
      * @param symbolSpace
@@ -228,11 +236,23 @@ public interface Node {
      */
     <T> T getService(Class<T> interfaze, String serviceURI) throws NoSuchServiceException;    
 
-    /* do we also need these following ones that are mentioned only indirectly in the spec? */
-    
+    /**
+     * Get a contributions deployed composites.
+     * @param contributionURI  the contribution URI
+     * @return the List of deployed composites
+     */
     List<String> getDeployedCompostes(String contributionURI);
+
+    /**
+     * Get the URIs of all the contributions installed on this Node
+     * @return the list of installed contribution URIs
+     */
     List<String> getInstalledContributions();
-    InstalledContribution getInstalledContribution(String uri);
-    Deployer getDeployer();
-    AssemblyFactory getAssemblyFactory();
+
+    /**
+     * Get an installed Contribution
+     * @param uri  the URI of the contribution
+     * @return the Contribution
+     */
+    Contribution getInstalledContribution(String uri);
 }
diff --git a/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/NodeFactory.java b/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/NodeFactory.java
index 36f49416f1..13ede41b1d 100644
--- a/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/NodeFactory.java
+++ b/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/NodeFactory.java
@@ -42,6 +42,7 @@ public class NodeFactory {
     private ExtensionPointRegistry extensionPointRegistry;
     private CompositeActivator compositeActivator;
     private ExtensibleDomainRegistryFactory domainRegistryFactory;
+    private RuntimeAssemblyFactory assemblyFactory;
 
     // TODO: keep this method?
     public static Node createNode() {
@@ -76,7 +77,7 @@ public class NodeFactory {
         extensionPointRegistry.start();
 
         FactoryExtensionPoint modelFactories = extensionPointRegistry.getExtensionPoint(FactoryExtensionPoint.class);
-        AssemblyFactory assemblyFactory = new RuntimeAssemblyFactory(extensionPointRegistry);
+        this.assemblyFactory = new RuntimeAssemblyFactory(extensionPointRegistry);
         modelFactories.addFactory(assemblyFactory);
 
         UtilityExtensionPoint utilities = extensionPointRegistry.getExtensionPoint(UtilityExtensionPoint.class);
@@ -94,4 +95,21 @@ public class NodeFactory {
 //        domainRegistryFactory.getEndpointRegistry(config.getProperty("reguri"), config.getProperty("defaultDomainName"));
 
     }
+    /**
+     * Get the Deployer. The Deployer can be used to create contribution artifacts 
+     * when configuring a Node programatically.
+     * @return the Deployer
+     */
+    public Deployer getDeployer() {
+        return deployer;
+    }
+    
+    /**
+     * Get the AssemblyFactory. The AssemblyFactory can be used to create contribution
+     * artifact contents when configuring a Node programatically.
+     * @return the AssemblyFactory
+     */
+    public AssemblyFactory getAssemblyFactory() {
+        return assemblyFactory;
+    }
 }
diff --git a/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/impl/NodeImpl.java b/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/impl/NodeImpl.java
index 0a849784c5..a52770860d 100644
--- a/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/impl/NodeImpl.java
+++ b/sca-java-2.x/trunk/modules/domain-node/src/main/java/org/apache/tuscany/sca/node2/impl/NodeImpl.java
@@ -81,14 +81,14 @@ public class NodeImpl implements Node {
         return uri;
     }
     
-    public void installContribution(String uri, String contributionURL, String metaDataURL, List<String> dependentContributionURIs, boolean deployDeployables) throws ContributionReadException, ActivationException, ValidationException {
+    public void installContribution(String uri, String contributionURL, String metaDataURL, List<String> dependentContributionURIs, boolean runDeployables) throws ContributionReadException, ActivationException, ValidationException {
         Monitor monitor = deployer.createMonitor();
         Contribution contribution = deployer.loadContribution(URI.create(uri), IOHelper.getLocationAsURL(contributionURL), monitor);
         monitor.analyzeProblems();
         if (metaDataURL != null) {
             mergeContributionMetaData(metaDataURL, contribution);
         }
-        installContribution(contribution, dependentContributionURIs, deployDeployables);
+        installContribution(contribution, dependentContributionURIs, runDeployables);
     }
 
     private void mergeContributionMetaData(String metaDataURL, Contribution contribution) throws ValidationException {
@@ -105,12 +105,12 @@ public class NodeImpl implements Node {
         contribution.getExports().addAll(metaData.getExports());
     }
     
-    public void installContribution(Contribution contribution, List<String> dependentContributionURIs, boolean deployDeployables) throws ContributionReadException, ActivationException, ValidationException {
+    public void installContribution(Contribution contribution, List<String> dependentContributionURIs, boolean runDeployables) throws ContributionReadException, ActivationException, ValidationException {
         InstalledContribution ic = new InstalledContribution(contribution.getURI(), contribution.getLocation(), contribution, dependentContributionURIs);
         installedContributions.put(contribution.getURI(), ic);
-        if (deployDeployables) {
+        if (runDeployables) {
             for (Composite c : ic.getDefaultDeployables()) {
-                deployComposite(c, ic);
+                runComposite(c, ic);
             }
         }
     }
@@ -128,7 +128,7 @@ public class NodeImpl implements Node {
             throw new IllegalArgumentException("contribution not installed: " + contributionURI);
         }
         String compositeArtifcatURI = deployer.attachDeploymentComposite(ic.getContribution(), composite, true);
-        deployComposite(composite, ic);
+        runComposite(composite, ic);
         return compositeArtifcatURI;
     }
 
@@ -141,7 +141,7 @@ public class NodeImpl implements Node {
         String relativeURI = compositeURI.substring(contributionURI.endsWith("/") ? contributionURI.length() : contributionURI.length()+1);
         for (Artifact a : ic.getContribution().getArtifacts()) {
             if (a.getURI().equals(relativeURI)) {
-                deployComposite((Composite) a.getModel(), ic);
+                runComposite((Composite) a.getModel(), ic);
                 return;
             }
         }
@@ -251,8 +251,11 @@ public class NodeImpl implements Node {
         return new ArrayList<String>(installedContributions.keySet());
     }
 
-    public InstalledContribution getInstalledContribution(String uri) {
-        return installedContributions.get(uri);
+    public Contribution getInstalledContribution(String uri) {
+        if (installedContributions.containsKey(uri)) {
+            return installedContributions.get(uri).getContribution();
+        }
+        throw new IllegalArgumentException("no contribution found for: " + uri);
     }
 
     protected String getContributionUriForArtifact(String artifactURI) {
@@ -269,7 +272,7 @@ public class NodeImpl implements Node {
         return contributionURI;
     }
 
-    protected void deployComposite(Composite c, InstalledContribution ic) throws ActivationException {
+    protected void runComposite(Composite c, InstalledContribution ic) throws ActivationException {
         List<Contribution> dependentContributions = new ArrayList<Contribution>();
         if (ic.getDependentContributionURIs() != null) {
             // if the install specified dependent uris use just those contributions