Merge branch topologymodeler-packaging into master

CHANGELOG.md

@@ -15,6 +15,7 @@ This is similar to [Angular's CHANGELOG.md](https://github.com/angular/angular/b
 ## [unreleased]
 
 ### Changed
+- Add automated allocation of topologies to cloud providers
 - Add versioning for TOSCA definitions
 - Fix maven tests for junit5
 - Add a subtype in the inheritance view

checkstyle-suppressions.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  ~ Copyright (c) 2018 Contributors to the Eclipse Foundation
+  ~
+  ~ See the NOTICE file(s) distributed with this work for additional
+  ~ information regarding copyright ownership.
+  ~
+  ~ This program and the accompanying materials are made available under the
+  ~ terms of the Eclipse Public License 2.0 which is available at
+  ~ http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+  ~ which is available at https://www.apache.org/licenses/LICENSE-2.0.
+  ~
+  ~ SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+<!DOCTYPE suppressions PUBLIC
+    "-//Puppy Crawl//DTD Suppressions 1.1//EN"
+    "http://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
+
+<suppressions>
+    <suppress files="[\\/]gen[\\/]" checks="[a-zA-Z0-9]*"/>
+</suppressions>

checkstyle.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  ~ Copyright (c) 2017 Contributors to the Eclipse Foundation
+  ~ Copyright (c) 2017-2018 Contributors to the Eclipse Foundation
   ~
   ~ See the NOTICE file(s) distributed with this work for additional
   ~ information regarding copyright ownership.
@@ -41,4 +41,7 @@
         </module>
         -->
     </module>
+    <module name="SuppressionFilter">
+        <property name="file" value="checkstyle-suppressions.xml"/>
+    </module>
 </module>

docs/adr/0027-use-dasherization-for-filenames.md

@@ -21,6 +21,10 @@ Chosen option: "Dasherization", because
 * clear separation of parts of the name
 * consistent to other URLs (which are typically lowercase)
 
+## Links
+
+* GADR: https://github.com/adr/gadr-misc/blob/master/gadr--filename-convention.md
+
 ## License
 
 Copyright (c) 2018 Contributors to the Eclipse Foundation

docs/dev/ToolChain-initialization.md

@@ -44,7 +44,7 @@ Windows:
 
 ## Steps to initialize the TOSCA repository
 
-Please go to the [quick start guide](../user/quickstart.md).
+Please go to the [quick setup guide](../user/quicksetup.md).
 
 ## Steps to initialize the IDE
 

docs/user/FAQ.md

@@ -1,5 +1,71 @@
 # FAQ
 
-## Q: On Mac OS X, I neither can delete a node template nor a relationship template.
+## Q: What is TOSCA?
+
+A: The Topology and Orchestration Specification for Cloud Applications (TOSCA) is an OASIS standard to describe the deployment and management of applications in a portable manner. 
+Based on standard-compliant TOSCA runtimes, such as the OpenTOSCA ecosystem, the deployment and management can be automated. 
+For more details see our [Notes on TOSCA](https://eclipse.github.io/winery/tosca/).
+
+## Q: What is a CSAR?
+
+A: Cloud Service Archive (CSAR) is a packaging format defined by the TOSCA specification, which enables to bundle modeled TOSCA components in a self-contained manner. 
+Besides the TOSCA elements, the executable artifacts are packed as well.
+In winery, you can model a service template and export it as a CSAR. 
+This CSAR can be loaded into the OpenTOSCA container in order to deploy your application. 
+
+## Q: How can I start the OpenTOSCA ecosystem?
+
+A: You can start the ecosystem by simply using Docker Compose or by using installation scripts. 
+Please refer to the [OpenTOSCA Getting Started guide](https://www.opentosca.org/sites/use_opentosca.html) for more details.
+
+## Q: Is there an open repository for TOSCA types?
+
+A: Yes! We provide a [github repository](https://github.com/OpenTOSCA/tosca-definitions-public) compatible to Winery, which contains several service templates, node types, etc. 
+To use this repository with a Winery docker container, please refer to the corresponding [configuration instructions](https://github.com/OpenTOSCA/opentosca-docker#how-to-clone-a-private-tosca-definitions-repository-to-be-used-with-winery).
+
+## Q: Where can I find a quick start guide to model node types?
+
+A: You can find a Winery quick start guide about modeling node types in our [Quickstart](quickstart.md).
+
+## Q: How can I export my modeled application as a CSAR?
+
+A: Select the tab *Services Templates*.
+From the listed service templates, select the one you want to export. 
+In the detailed view, press *Export* and then choose the option *CSAR (XML)*.
+
+## Q: My modeled node type became the suffix name *wip*? what does this mean?
+
+A: This means your node type has a *work in progress* (wip) version. That is, this node type can and might be changed. 
+Once you are done, you can do a release of your node type. In this way, Winery will not allow changes in the (released) node type anymore.
+
+## Q: How can I release a node type?
+
+A: Select the tab *Node Types*.
+From the listed node types, select the one you want to release. 
+In the detailed view, press *Versions* and then choose the option *Release management version*.
+
+## Q: On Mac OS X, I can neither delete a node template nor a relationship template.
 
 A: Select the node template (or the relationship template) and press <kbd>fn</kbd> + <kbd>backspace</kbd>.
+
+## Q: Where can I get more help?
+
+A: If you need support, contact us at *opentosca@iaas.uni-stuttgart.de*.
+
+## Q: How can I contribute to Winery?
+
+A: Please see the [contributing guide](https://github.com/eclipse/winery/blob/master/CONTRIBUTING.md).
+
+## License
+
+Copyright (c) 2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0

docs/user/TargetAllocation.md

@@ -0,0 +1,73 @@
+# Target Allocation
+
+(see [Splitting](Splitting))
+
+In the repository UI the topology of a Service Template can be allocated to Cloud Providers by clicking the cloud icon and entering the needed information.
+Cloud Providers for the Node Templates of the topology are selected based on already assigned target locations and three different criteria.
+Each criteria provides the functionality to only assign target locations or also inject Node Templates of these locations based on the Split & Match method.
+The resulting topologies are saved in the repository under the same namespace and name as the original topology but with the added suffix "-assigned" or "-allocated" and the number of the generated topology.
+The target locations are not case sensitive.
+
+Like the Split & Match method, this functionality assumes that topologies are modeled in a specific way:
+- Node Templates have requirements
+- at least one Node Template in the topology has a target location
+- the target locations correspond to a cloud provider namespace containing Service Templates by the cloud provider with matching capabilites
+- only the Node Templates without incoming hostedOn Relationship Templates have target locations assigned
+
+Note: the Split & Match method also supports topology completion and injection of topology fragments with multiple Node Templates.
+This is not considered here.
+
+## Criteria
+
+### Minimal amount of host components
+
+Distribute the existing target labels so that PaaS Node Templates are preferred and the resulting topology has a minimal amount of Node Templates.
+
+### Fulfillment of policies
+
+Select target locations based on non functional requirements modeled as Policy Templates.
+
+Additional requirements:
+- Node Templates without incoming hostedOn Relationship Templates have Policies
+- names of policies are unique in the topology (name has to be used as ID as Policies have no IDs)
+
+The selection is performed by comparing the Policies of the topology with the Policies of the fragments of the cloud providers.
+For the comparison the Policies have to have the same type.
+The comparison is performed by operators, which can be selected in the GUI modal.
+These operators compare one specified property of the Policies.
+At the moment, only primitive data types modeled as Winery Key-Value properties are supported for comparison.
+
+### Minimal amount of external connectsTo Relationship Templates
+
+Distribute target locations so that amount of external connectsTo Relationship Templates is minimal.
+A Relationship Template is considered external if it connects Node Templates of different target locations.
+Note: a randomized algorithm is used, so results can vary.
+
+Additional requirements:
+- each Node Template without incoming Relationship Templates and without target location is (transitively) connected to at least one Node Template with target location
+
+## Combination of criteria & topology generation
+
+Each criteria generates permutations of all possibile target location distributions and matching Node Templates of the Cloud Providers.
+As this can result in the generation of many topologies, which can take a long time, an upper bound of topologies to generate can be specified in the GUI modal ("topology generation cap").
+
+Generated topologies can also be filtered by the different criteria.
+For example, topologies generated by the "Minimal amount of host components" can be filtered for minimal external connectsTos.
+This enables the fulfillment of multiple criteria and the narrowing of the generated topologies.
+
+As target locations can also only be assigned without injecting matching Node Templates from the Cloud Providers, the preferred target location distribution can also be selected manually.
+After the selection, matching Node Templates can be injected using on of the criteria or the Split & Match functionality.
+
+## License
+
+Copyright (c) 2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0

docs/user/generateIA.md

@@ -0,0 +1,59 @@
+# Generate an Implementation Artifact for a Node Type Interface
+
+To specify what a node type should do, the user can define an *interface* and the *operations* provided by this interface. 
+Once the operations of a node type are defined, artifacts (e.g., shell scripts, .war files) implementing these operations need to be modeled. 
+For this, Winery provides an option to **automatically generate a stub java maven project** to build a **.war file** for a defined interface. 
+This can be done in the *Interface* tab of the node type view by pressing *Generate Implementation Artifact*. 
+A node type implementation will be automatically generated as well, if it does not exist yet.
+Once you get a confirmation that the artifact was generated, please press *Save*.
+
+ ![3-AddUbuntuNodeType](graphics/modeling/3-AddUbuntuNodeType.jpg)
+
+To download the generated stub java main project, go to the detailed view of the artifact template and press *ZIP*. 
+
+ ![7-AddUbuntuNodeType](graphics/modeling/7-AddUbuntuNodeType.jpg)
+
+Unzip the archive generated by Winery into a location of your choice. In the root folder, you can find a *README.txt* explaining in details how to edit, build and upload the .war file to the implementation artifact in Winery. 
+A summary of this is provided below.
+For the next steps, maven and Eclipse are required. Furthermore, maven commands are executed in the root folder of the implementation artifact.
+
+## Create an Eclipse Project
+ - Run: mvn eclipse:eclipse
+ - Open Eclipse
+ - *File* -> *Import* -> *Existing Project into Workspace* -> click *Next*
+ - Click *Browse* and select folder where you unzipped the generated implementation artifact
+ - Select the project from the list and click *Finish*
+
+## Test your Implementation Artifact
+ - Run: mvn clean package tomcat7:run-war
+ - Open this page to see the list of available services: http://localhost:9090/services/
+ - This page also links the WSDL
+ - With the WSDL your're able to test your IA using SOAPui or other tools.
+
+## Upload your Implementation Artifact
+ You have two options to do this:
+
+### 1) Automatically (to the Winery instance this IA project was generated with)
+ - Run: mvn deploy
+ - The WAR is directly uploaded into the correct ArtifactTemplate, previous versions will be overwritten.
+
+### 2) Manually
+ - Run: mvn clean package
+ - Locate the WAR file in the /target folder
+ - Open Winery in your browser, locate the artifact template representing this implementation artifact.
+ - Upload the WAR file to the artifact template in the tab *Files*
+
+
+## License
+
+Copyright (c) 2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0

docs/user/index.md

@@ -7,15 +7,17 @@ For more information on TOSCA see [our TOSCA information page](../tosca/).
 
 - [overview](overview.md) - overview on Winery
 - [FAQ](FAQ.md) - frequently asked questions
-- [Quickstart](quickstart.md) - shows how to model a node type and a topology in Winery
-- [Modeling Guide](modeling-guide.md) - Guide how to use Winery
+- [Quick Setup](quicksetup.md) - shows how to setup the winery repository for TOSCA definitions
+- [Quickstart](quickstart.md) - shows how to use Winery to model a node type and a topology
 
 ## Features
 
 - [Splitting](Splitting) - splitting functionality
+- [Target Allocation](TargetAllocation) - select best suited Cloud Provider for topologies
 - [TopologyCompletion](TopologyCompletion) - topology completion with a [Tutorial](TopologyCompletionTutorial)
 - [XaaSPackager](XaaSPackager) - Enables reusing modeled topologies as templates for single applications
 - [Compliance Checking](ComplianceChecking.md) - Enables compliance checking of Topology Templates based on reusable Compliance Rules  
+- [Implementation Artifact Generation](generateIA.md) - Shows how to generate and update an implementation artifact of type .war
 
 ## Background Literature