winery/README.md

   1 # Winery
   2 Winery is a Web-based environment to graphically model TOSCA topologies and plans managing these topologies.
   3 It is an Eclipse project and thus support is available through its project page https://projects.eclipse.org/projects/soa.winery.
   4 Winery is also part of the OpenTOSCA ecosystem where more information is available at http://www.opentosca.org.
   5
   6 **The code and the linked libraries are NOT approved by Eclipse Legal. Dependencies are fetched from external mirrors and not from an Eclipse repository.**
   7
   8 ## Runtime Requirements
   9 * Java 7
  10 * Servlet 3.0 capable container (e.g., Tomcat 7)
  11
  12 ## Development Information
  13
  14 Winery uses maven and [bower] for fetching dependencies and building.
  15 Bower has to be installed manually as described in the next section.
  16
  17 ## Install bower
  18
  19 1. Install [nodejs]. Just use the latest version to get the latest node package manager (npm).
  20 1. Run `npm install -g bower`
  21 1. Ensure that `git` is in your path: Some javascript libraries are fetched via git.
  22
  23
  24 ## Make models available
  25
  26 The models are versioned aside from the main project.
  27 Go into each model directory (`org.eclipse.winery.model.csar.toscametafile`, `org.eclipse.winery.model.selfservice`, `org.eclipse.winery.model.tosca`) and do a `mvn install`.
  28
  29
  30 ## Making the wars
  31 Run `mvn clean package`.
  32 In case [bower] fails, try to investigate using `mvn package -X`.
  33 You can start bower manually in `org.eclipse.winery.repository` and `org.eclipse.winery.topologymodeler` by issuing `bower install`.
  34
  35 There are two WARs generated:
  36
  37 * `org.eclipse.winery.repository/target/winery.war` and
  38 * `org.eclipse.winery.topologymodeler/target/winery-topologymodeler.war`
  39
  40 They can be deployed on a Tomcat runtime environment.
  41
  42 ## Branches
  43 The `master` branch is always compiling and all tests should go through.
  44 It contains the most recent improvements.
  45 All other branches are real development branches and might event not compile.
  46
  47 There are no explicit branches for stable versions as winery is currently in development-only mode.
  48
  49 ## Projects
  50
  51 ### Model projects
  52 Each of these projects are versioned separately.
  53
  54 * org.eclipse.winery.model.csar.toscametafile: model for TOSCA meta files contained in a CSAR
  55 * org.eclipse.winery.model.selfservice: model for the self service portal
  56 * org.eclipse.winery.model.tosca: model for TOCSA
  57
  58 ### Support projects
  59 * org.eclipse.winery.highlevelrestapi: support library to REST calls.
  60
  61 ### Winery itself
  62 Versioned together to ease development.
  63
  64 * org.eclipse.winery.common: Used in repository and topology modeler
  65 * org.eclipse.winery.generators.ia: Implementation Artifact Generator, used as component in the repository
  66 * org.eclipse.winery.repository: the repository including a JSP-based UI
  67 * org.eclipse.winery.repository.client: Java-client for the repository
  68 * org.eclipse.winery.topologymodeler: Graph-based modeler for topology templates
  69
  70 ## Next steps
  71 Winery currently is far from being a production ready modeling tool.
  72 The next steps are:
  73
  74 * UI design improvements
  75   * Have Orion support `XML` as language. See also [Bug 421284][bug421284]
  76 * Add more usability features to the topology modeler
  77 * Remove non-required files from components/ directory to reduce the file size of the WAR file
  78   * This has to be done by submitting patches to `bower.json` of the upstream libraries
  79 * Develop a plugin-system for user-defined editors. For instance, a constraint has a type. If a type is known to Winery, it can present a specific plugin to edit the type content instead of a generic XML editor.
  80 * Rework file storage. Currently, files are stored along with their definitions. A new storage should store all files in one place and use an SHA1 id to uniquely identify the file. Then, it does not make any difference if storing a WAR, an XSD, or an WSDL.
  81 * Add a real DAO layer to enable querying the available TOSCA contents using SQL or similar query language
  82
  83 Currently, `.jsp` files package HTML and JS.
  84 We plan to use frameworks such as [TerrificJS] to provide a better modularity.
  85 This follows Nicholas Zakas' "[Scalable JavaScript Application Architecture]".
  86
  87 ## Known issues
  88 * XSD Type declarations are not directly supported
  89 ** Declared types are converted to imports during a CSAR Import
  90 ** Editing of XSDs is not possible
  91 * **The XSD of OASIS TOSCA v1.0 has been modified**
  92 ** An Implementation Artifact may carry a `name` attribute
  93 ** The contents of properties of Boundary Definitions are processed in `lax` mode
  94
  95 ## Eclipse setup
  96 This howto is based on [Eclipse Standard 4.3].
  97 First of all, generate a war to have all dependencies fetched by maven.
  98
  99 ### Required plugins
 100 * JST Server Adapters Extensions
 101 * Eclipse Java EE Developer Tools
 102 * Eclipse Java Web Developer Tools
 103 * [m2e-wtp]: Maven Integration for WTP
 104 * [AnyEdit](http://andrei.gmxhome.de/anyedit/) for ensuring that tabs are always used
 105 ** Configure: Window -> Preferences -> General / Editors / AnyEdit Tools -> "Auto - Convert EXCLUSION file list" -> "Add filter" -> "*.java", "Convert...": 4 spaces for a tab
 106
 107 ### Optional plugins
 108 * [Eclipse Code Recommenders](http://www.eclipse.org/recommenders/)
 109 * [VJET JavaScript IDE](http://www.eclipse.org/proposals/webtools.vjet/)
 110
 111 ### Make Winery projects known to Eclipse
 112 1. Import all projects
 113   * Use "Existing Maven Projects". `mvn eclips:m2eclipse` currently does not enable "maven" in eclipse.
 114 2. For each project: right click, –> Team –> Share Project –> Git –> Next –> check "Use or create repository in parent folder of project" –> Finish
 115 3. At `org.eclipse.winery.repository` and ` org.eclipse.winery.topologymodeler`:
 116   * Right click -> Properties -> JavaScript -> Include Path -> Source -> Expand folder -> Select "Excluded" -> "Edit..."
 117   * Exclusion Patterns: Add multiple -> Select "3rd party" -> "OK"
 118   * Exclusion Patterns: Add multiple -> Select "components" -> "OK"
 119   * "Finish" -> "OK"
 120
 121 ### Setup Tomcat
 122 1. Open servers window: Window -> Show View -> Other -> Server -> Servers
 123 2. New server wizard... -> Apache -> Tomcat v7.0 Server -> Next -> Winery -> Add -> Finish
 124 3. Rename the Server to "Apache Tomcat v7.0"
 125
 126 Now you can see the Tomcat v7.0 Server at localhost [Stopped, Republish] in your server window.
 127 Select it and click on the green play button in the window.
 128
 129 Now winery can be viewed at http://localhost:8080/winery/
 130
 131 ### Configure Winery (optional)
 132 The repository location can be changed:
 133 Copy `winery.properties` to `path-to-workspace\.metadata\.plugins\org.eclipse.wst.server.core\tmp0\wtpwebapps\winery`.
 134
 135 ### Trouble shooting
 136 * In case some JavaScript libraries cannot be found by the browser, execute `bower prune`, `bower install`, `bower update` in both `org.eclipse.winery.repository` and `org.eclipse.winery.topologymodeler`.
 137 * See [README.md of the repository](org.eclipse.winery.repository/README.md)
 138 * See [README.md of the topology modeler](org.eclipse.winery.topologymodeler/README.md)
 139
 140 #### Libraries
 141
 142 * Do NOT update to jQuery 2.1.0. When using with firefox, line 5571 in jquery.js fails: `divStyle is null`. That means `window.getComputedStyle( div, null );` returned null, too.
 143 * Do NOT update to jsPlumb 1.5.5. The new connection type determination does not play well together with Winery's usage of jsPlumb.
 144
 145 ## Acknowledgements
 146 The initial code contribution has been supported by the [Federal Ministry of Economics and Technology] as part of the [CloudCycle project] (01MD11023).
 147
 148 ## License
 149 Copyright (c) 2012-2014 University of Stuttgart.
 150
 151 All rights reserved. This program and the accompanying materials
 152 are made available under the terms of the [Eclipse Public License v1.0]
 153 and the [Apache License v2.0] which both accompany this distribution,
 154 and are available at http://www.eclipse.org/legal/epl-v10.html
 155 and http://www.apache.org/licenses/LICENSE-2.0
 156
 157 Contributors:
 158 * Oliver Kopp - initial API and implementation
 159
 160 ## Literature
 161
 162 ### About TOSCA
 163 * Binz, T., Breiter, G., Leymann, F., Spatzier, T.: Portable Cloud Services Using TOSCA. IEEE Internet Computing 16(03), 80--85 (May 2012). [DOI:10.1109/MIC.2012.43]
 164 * Topology and Orchestration Specification for Cloud Applications Version 1.0. 25 November 2013. OASIS Standard. http://docs.oasis-open.org/tosca/TOSCA/v1.0/os/TOSCA-v1.0-os.html
 165 * OASIS: Topology and Orchestration Specification for Cloud Applications (TOSCA) Primer Version 1.0 (2013)
 166
 167 See http://www.opentosca.org/#publications for a list of publications in the OpenTOSCA ecosystem.
 168
 169 ### Programming
 170 * Joshua Bloch. Effective Java, 2nd edition. Addison-Wesley
 171
 172  [bug421284]: https://bugs.eclipse.org/bugs/show_bug.cgi?id=421284
 173  [bower]: https://github.com/bower/bower
 174  [DOI:10.1109/MIC.2012.43]: http://dx.doi.org/10.1109/MIC.2012.43
 175  [nodejs]: http://nodejs.org/download/
 176  [Eclipse Public License v1.0]: http://www.eclipse.org/legal/epl-v10.html
 177  [Eclipse Standard 4.3]: http://www.eclipse.org/downloads/
 178  [Apache License v2.0]: http://www.apache.org/licenses/LICENSE-2.0.html
 179  [Federal Ministry of Economics and Technology]: http://www.bmwi.de/EN/root.html
 180  [CloudCycle project]: http://www.cloudcycle.org/en/
 181  [m2eclipse]: http://eclipse.org/m2e/
 182  [m2e-wtp]: http://eclipse.org/m2e-wtp/
 183  [Scalable JavaScript Application Architecture]: http://www.slideshare.net/nzakas/scalable-javascript-application-architecture-2012
 184  [TerrificJS]: http://terrifically.org/