Experiment with whats required of the various things described in section 10 of the Assembly spec. No clear idea what if anything would ever happen with this which is why its in contrib just looking at what the spec talks about and how or if its possible with Tuscany

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

1 files changed, 226 insertions, 0 deletions

diff --git a/sca-java-2.x/contrib/modules/section10/src/main/java/org/apache/tuscany/sca/something/Section10.java b/sca-java-2.x/contrib/modules/section10/src/main/java/org/apache/tuscany/sca/something/Section10.java
new file mode 100644
index 0000000000..009a9621fa
--- /dev/null
+++ b/sca-java-2.x/contrib/modules/section10/src/main/java/org/apache/tuscany/sca/something/Section10.java
@@ -0,0 +1,226 @@
+/*

+ * Licensed to the Apache Software Foundation (ASF) under one

+ * or more contributor license agreements.  See the NOTICE file

+ * distributed with this work for additional information

+ * regarding copyright ownership.  The ASF licenses this file

+ * to you under the Apache License, Version 2.0 (the

+ * "License"); you may not use this file except in compliance

+ * with the License.  You may obtain a copy of the License at

+ * 

+ *   http://www.apache.org/licenses/LICENSE-2.0

+ * 

+ * Unless required by applicable law or agreed to in writing,

+ * software distributed under the License is distributed on an

+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

+ * KIND, either express or implied.  See the License for the

+ * specific language governing permissions and limitations

+ * under the License.    

+ */

+

+package org.apache.tuscany.sca.something;

+

+import java.io.Reader;

+import java.util.List;

+

+import javax.xml.namespace.QName;

+

+import org.w3c.dom.Document;

+

+public interface Section10 {

+

+    /**

+     * 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

+     */

+    void installContribution(String uri, String contributionURL, List<String> dependentContributionURIs);

+

+    /* and i'd expect short forms of that for when you don't care or have the others:*/

+    String installContribution(String contributionURL);

+    void installContribution(String uri, String contributionURL);

+    

+    /**

+     * 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

+     */

+    void updateContribution(String uri, String contributionURL);

+

+    /**

+     * 4599 10.5.2 add Deployment Composite & update Deployment Composite

+     * 4600 Adds or updates a deployment composite using a supplied composite ("composite by value" – a data

+     * 4601 structure, not an existing resource in the Domain) to the contribution identified by a supplied contribution

+     * 4602 URI. The added or updated deployment composite is given a relative URI that matches the @name

+     * 4603 attribute of the composite, with a “.composite” suffix. Since all composites run within the context of a

+     * 4604 installed contribution (any component implementations or other definitions are resolved within that

+     * 4605 contribution), this functionality makes it possible for the deployer to create a composite with final

+     * 4606 configuration and wiring decisions and add it to an installed contribution without having to modify the

+     * 4607 contents of the root contribution.

+     * 4608 Also, in some use cases, a contribution might include only implementation code (e.g. PHP scripts). It is

+     * 4609 then possible for those to be given component names by a (possibly generated) composite that is added

+     * 4610 into the installed contribution, without having to modify the packaging.     * 

+     * 

+     * @param uri

+     * @param compositeXML

+     * @return

+     */

+    String addDeploymentComposite(String contriubutionURI, String compositeXML);

+

+    /* perhaps you may want other forms of that too, eg: */

+    String addDeploymentComposite(String contriubutionURI, Reader compositeXML);

+

+    /**

+     * 4599 10.5.2 add Deployment Composite & update Deployment Composite

+     * 4600 Adds or updates a deployment composite using a supplied composite ("composite by value" – a data

+     * 4601 structure, not an existing resource in the Domain) to the contribution identified by a supplied contribution

+     * 4602 URI. The added or updated deployment composite is given a relative URI that matches the @name

+     * 4603 attribute of the composite, with a “.composite” suffix. Since all composites run within the context of a

+     * 4604 installed contribution (any component implementations or other definitions are resolved within that

+     * 4605 contribution), this functionality makes it possible for the deployer to create a composite with final

+     * 4606 configuration and wiring decisions and add it to an installed contribution without having to modify the

+     * 4607 contents of the root contribution.

+     * 4608 Also, in some use cases, a contribution might include only implementation code (e.g. PHP scripts). It is

+     * 4609 then possible for those to be given component names by a (possibly generated) composite that is added

+     * 4610 into the installed contribution, without having to modify the packaging.     * 

+     * 

+     * @param uri

+     * @param compositeXML

+     * @return

+     */

+    String updateDeploymentComposite(String uri, String compositeXML);

+

+    /* and similar alternate form: */

+    String updateDeploymentComposite(String uri, Reader compositeXML);

+

+    /**

+     * 4611 11.4.310.5.3 remove Contribution

+     * 4612 Removes the deployed contribution identified by a supplied contribution URI.

+     * 

+     * @param contributionURI

+     */

+    void removeContribution(String contributionURI);

+

+    /**

+     * 4677 10.7.1 add To Domain-Level Composite

+     * 4678 This functionality adds the composite identified by a supplied URI to the Domain Level Composite. The

+     * 4679 supplied composite URI refers to a composite within an installed contribution. The composite's installed

+     * 4680 contribution determines how the composite’s artifacts are resolved (directly and indirectly). The supplied

+     * 4681 composite is added to the domain composite with semantics that correspond to the domain-level

+     * 4683 components become top-level components and the component services become externally visible

+     * 4684 services (eg. they would be present in a WSDL description of the Domain). The meaning of any promoted

+     * 4685 services and references in the supplied composite is not defined; since there is no composite scope

+     * 4686 outside the domain composite, the usual idea of promotion has no utility.

+     *  

+     * @param compositeURI

+     */

+    void addToDomainLevelComposite(String compositeURI);

+    

+    /**

+     * 4687 10.7.2 remove From Domain-Level Composite

+     * 4688 Removes from the Domain Level composite the elements corresponding to the composite identified by a

+     * 4689 supplied composite URI. This means that the removal of the components, wires, services and references

+     * 4690 originally added to the domain level composite by the identified composite.     * 

+     * @param compositeURI

+     */

+    void removeFromDomainLevelComposite(String compositeURI);

+

+    /**

+     * 10.7.3 get Domain-Level Composite

+     * Returns a <composite> definition that has an <include> line for each composite that had been added to

+     * the domain level composite. It is important to note that, in dereferencing the included composites, any

+     * referenced artifacts are resolved in terms of that installed composite.

+     * 

+     * @return

+     */

+    Document getDomainLevelComposite();

+    

+    /* that previous one returns a DOM Document but not sure what would be most appropriate, and having one return a string seems convenient: */

+    String getDomainLevelCompositeAsString();

+    

+    /**

+     * 4695 10.7.4 get QName Definition

+     * 4696 In order to make sense of the domain-level composite (as returned by get Domain-Level Composite), it

+     * 4697 needs to be possible to get the definitions for named artifacts in the included composites. This

+     * 4698 functionality takes the supplied URI of an installed contribution (which provides the context), a supplied

+     * 4699 qualified name of a definition to look up, and a supplied symbol space (as a QName, e.g.

+     * 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.     * 

+     * @param contributionURI

+     * @param definition

+     * @param symbolSpace

+     * @return

+     */

+    Object getQNameDefinition(String contributionURI, QName definition, QName symbolSpace);

+

+    

+    /* do we also need these following ones that are mentioned only indirectly in the spec? */

+    

+    /**

+     * 4783 ...component is stopped and restarted

+     * 

+     * So does there need to be start/stop component methods?

+     */

+    void startComponent(String componentURI);

+    void stopComponent(String componentURI);

+    

+    /**

+     * Section "10.5.3 remove Contribution" talks about removing a "deployed" contribution

+     * which really sounds like undeploy, does that contribution state then become installed

+     * or does it get removed entirely? Either way it seems like you'd want to be able 

+     * to explicitly install/deploy/undeploy/uninstall a contribution 

+     */

+    void deployContribution(String contributionURI);

+    void undeployContribution(String contributionURI);

+    

+

+    /**

+     * Probably want to be able to stop it all at once so a method called stop or shutdown or destroy

+     * though i guess it could be argued that this method may be somewhere else

+     */

+    void shutdown();

+    

+}