You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2016/02/01 18:45:53 UTC
[45/51] [abbrv] [partial] brooklyn-docs git commit: move subdir from
incubator up a level as it is promoted to its own repo (first non-incubator
commit!)
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/concepts/policies.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/concepts/policies.md b/brooklyn-docs/guide/concepts/policies.md
deleted file mode 100644
index 495e57f..0000000
--- a/brooklyn-docs/guide/concepts/policies.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-title: Policies
-layout: website-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-Policies perform the active management enabled by Brooklyn. Entities can have zero or more ``Policy`` instances attached to them.
-
-Policies can subscribe to sensors from entities or run periodically, and
-when they run they can perform calculations, look up other values, and if deemed necessary invoke effectors or emit sensor values from the entity with which they are associated.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/concepts/stop-start-restart-behaviour.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/concepts/stop-start-restart-behaviour.md b/brooklyn-docs/guide/concepts/stop-start-restart-behaviour.md
deleted file mode 100644
index 916ea5c..0000000
--- a/brooklyn-docs/guide/concepts/stop-start-restart-behaviour.md
+++ /dev/null
@@ -1,65 +0,0 @@
----
-title: Stop/start/restart behaviour
-layout: website-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-Many entities expose `start`, `stop` and `restart` effectors. The semantics of these operations (and the parameters they take) depends on the type of entity.
-
-## Top-level applications
-A top-level application is a grouping of other entities, pulling them together into the "application" of your choice. This could range from a single app-server, to an app that is a composite of a no-sql cluster (e.g. MongoDB sharded cluster, or Cassandra spread over multiple datacenters), a cluster of load-balanced app-servers, message brokers, etc.
-
-### start(Collection<Location>)
-This will start the application in the given location(s). Each child-entity within the application will be started concurrently, passing the location(s) to each child.
-The start effector will be called automatically when the application is deployed through the catalog.
-Is is strongly recommended to not call start again.
-
-### stop()
-Stop will terminate the application and all its child entities (including releasing all their resources).
-The application will also be unmanaged, **removing** it from Brooklyn.
-
-### restart()
-This will invoke `restart()` on each child-entity concurrently (with the default values for the child-entity's restart effector parameters).
-Is is strongly recommended to not call this, unless the application has been explicitly written to implement restart.
-
-## Software Process (e.g MySql, Tomcat, JBoss app-server, MongoDB)
-
-### start(Collection<Location>)
-This will start the software process in the given location.
-If a machine location is passed in, then the software process is started there.
-If a cloud location is passed in, then a new VM will be created in that cloud - the software process will be **installed+launched** on that new VM.
-
-The start effector will have been called automatically when deploying an application through the catalog.
-In normal usage, do not invoke start again.
-
-If calling `start()` a second time, with no locations passed in (e.g. an empty list), then it will go through the start sequence on the existing location from the previous call.
-It will **install+customize+launch** the process.
-For some entities, this could be *dangerous*. The customize step might execute a database initialisation script, which could cause data to be overwritten (depending how the initialisation script was written).
-
-If calling `start()` a second time with additional locations, then these additional locations will be added to the set of locations.
-In normal usage it is not recommended.
-This could be desired behaviour if the entity had previously been entirely stopped (including its VM terminated) - but for a simple one-entity app then you might as well have deleted the entire app and created a new one.
-
-
-### stop(boolean stopMachine)
-If `stopMachine==true`, this effector will stop the software process and then terminate the VM (if a VM had been created as part of `start()`). This behaviour is the inverse of the first `start()` effector call.
-When stopping the software process, it does not uninstall the software packages / files.
-
-If `stopMachine==false`, this effector will stop just the software process (leaving the VM and all configuration files / install artifacts in place).
-
-### restart(boolean restartMachine, boolean restartChildren)
-This will restart the software process.
-
-If `restartMachine==true`, it will also terminate the VM and create a new VM. It will then install+customize+launch the software process on the new VM. It is equivalent of invoking `stop(true)` and then `start(Collections.EMPTY_LIST)`.
-If `restartMachine==false`, it will first attempt to stop the software process (which should be a no-op if the process is not running), and will then start the software process (without going through the **install+customize** steps).
-
-If `restartChildren==true`, then after restarting itself it will call `restart(restartMachine, restartChildren)` on each child-entity concurrently.
-
-## Recommended operations
-
-The recommended operations to invoke to stop just the software process, and then to restart it are:
-
-* Select the software process entity in the tree (*not* the parent application, but the child of that application).
-* Invoke `stop(stopMachine=false)`
-* Invoke `restart(restartMachine=false, restartChildren=false)`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/code/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/code/index.md b/brooklyn-docs/guide/dev/code/index.md
deleted file mode 100644
index bf2e22a..0000000
--- a/brooklyn-docs/guide/dev/code/index.md
+++ /dev/null
@@ -1,97 +0,0 @@
----
-title: About the Code
-layout: website-normal
----
-
-## The Basics
-
-Brooklyn is available at [GitHub apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn). Check it out using:
-
-{% highlight bash %}
-git clone git@github.com:apache/incubator-brooklyn.git
-cd brooklyn
-{% endhighlight %}
-
-Build it with:
-
-{% highlight bash %}
-mvn clean install
-{% endhighlight %}
-
-And launch it with:
-
-{% highlight bash %}
-cd usage/dist/target/brooklyn-dist/
-bin/brooklyn launch
-{% endhighlight %}
-
-{% comment %}
-TODO examples
-Plenty of examples are in the **examples** sub-dir,
-described [here]({{site.path.guide}}/use/examples).
-{% endcomment %}
-
-Information on using Brooklyn -- configuring locations (in `brooklyn.properties`)
-and adding new projects to a catalog -- can be found in the [User's Guide]({{site.path.guide}}).
-This document is intended to help people become familiar with the codebase.
-
-## Project Structure
-
-Brooklyn is split into the following projects and sub-projects:
-
-* **``camp``**: the components for a server which speaks with the CAMP REST API and understands the CAMP YAML plan language
-* **``api``**: the pure-Java interfaces for interacting with the system
-* **``core``**: the base class implementations for entities and applications, entity traits, locations, policies, sensor and effector support, tasks, and more
-* **``locations``**: specific location integrations
- * **``jclouds``**: integration with many cloud APIs and providers via Apache jclouds
-* **``policies``**: collection of useful policies for automating entity activity
-* **``software``**: entities which are mainly launched by launched software processes on machines, and collections thereof
- * **``base``**: software process lifecycle abstract classes and drivers (e.g. SSH)
- * **``webapp``**: web servers (JBoss, Tomcat), load-balancers (Nginx), and DNS (Geoscaling)
- * **``database``**: relational databases (SQL)
- * **``nosql``**: datastores other than RDBMS/SQL (often better in distributed environments)
- * **``messaging``**: messaging systems, including Qpid, Apache MQ, RabbitMQ
- * **``monitoring``**: monitoring tools, including Monit
- * **``osgi``**: OSGi servers
- * **...**
-* **``utils``**: projects with lower level utilities
- * **common**: Utility classes and methods developed for Brooklyn but not dependent on Brooklyn
- * **groovy**: Groovy extensions and utility classes and methods developed for Brooklyn but not dependent on Brooklyn
- * **jmx/jmxmp-ssl-agent**: An agent implementation that can be attached to a Java process, to give expose secure JMXMP
- * **jmx/jmxrmi-agent**: An agent implementation that can be attached to a Java process, to give expose JMX-RMI without requiring all high-number ports to be open
- * **rest-swagger**: Swagger REST API utility classes and methods developed for Brooklyn but not dependent on Brooklyn
- * **test-support**: Test utility classes and methods developed for Brooklyn but not dependent on Brooklyn
-* **``usage``**: projects which make Brooklyn easier to use, either for end-users or Brooklyn developers
- * **all**: maven project to supply a shaded JAR (containing all dependencies) for convenience
- * **archetypes**: A maven archetype for easily generating the structure of new downstream projects
- * **camp**: Brooklyn bindings for the CAMP REST API
- * **cli**: backing implementation for Brooklyn's command line interface
- * **dist**: builds brooklyn as a downloadable .zip and .tar.gz
- * **jsgui**: Javascript web-app for the brooklyn management web console (builds a WAR)
- * **launcher**: for launching brooklyn, either using a main method or invoked from the cli project
- * **logback-includes**: Various helpful logback XML files that can be included; does not contain logback.xml
- * **logback-xml**: Contains a logback.xml that references the include files in brooklyn-logback-includes
- * **rest-api**: The API classes for the Brooklyn REST api
- * **rest-client**: A client Java implementation for using the Brooklyn REST API
- * **rest-server**: The server-side implementation of the Brooklyn REST API
- * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts)
- * **qa**: longevity and stress tests
- * **test-support**: provides Brooklyn-specific support for tests, used by nearly all projects in scope ``test``
-* **``docs``**: the markdown source code for this documentation
-* **``examples``**: some canonical examples
-* **``sandbox``**: various projects, entities and policies which the Brooklyn Project is incubating
-
-
-## Next Steps
-
-If you're interested in building and editing the code, check out:
-
-* [Maven setup](../env/maven-build.html)
-* [IDE setup](../env/ide/)
-* [Tests](tests.html)
-* [Tips](../tips/)
-* [Remote Debugging](../tips/debugging-remote-brooklyn.html)
-
-Where things aren't documented **please ask us** at
-[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)
-so we can remedy this!
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/code/licensing.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/code/licensing.md b/brooklyn-docs/guide/dev/code/licensing.md
deleted file mode 100644
index 8f031e0..0000000
--- a/brooklyn-docs/guide/dev/code/licensing.md
+++ /dev/null
@@ -1,122 +0,0 @@
----
-title: License Considerations
-layout: website-normal
----
-
-The Apache Software Foundation, quite rightly, place a high standard on code provenance and license compliance. The
-Apache license is flexible and compatible with many other types of license, meaning there is generally little problem
-with incorporating other open source works into Brooklyn (with GPL being the notable exception). However diligence is
-required to ensure that the project is legally sound, and third parties are rightfully credited where appropriate.
-
-This page is an interpretation of the [Apache Legal Previously Asked Questions](http://www.apache.org/legal/resolved.html)
-page as it specifically applies to the Brooklyn project, such as how we organise our code and the releases that we make.
-However this page is not authoritative; if there is any conflict between this page and the Previously Asked Questions or
-other Apache Legal authority, they will take precedence over this page.
-
-If you have any doubt, please ask on the Brooklyn mailing list, and/or the Apache Legal mailing list.
-
-
-What code licenses can we bundle?
----------------------------------
-
-Apache Legal maintains the ["Category A" list](http://www.apache.org/legal/resolved.html#category-a), which is a list
-of licenses that are compatible with the Apache License; that is, code under these licenses can be imported into
-Brooklyn without violating Brooklyn's Apache License nor the code's original license (subject to correctly modifying
-the `LICENSE` and/or `NOTICE` files; see below).
-
-Apache Legal also maintain the ["Category X" list](http://www.apache.org/legal/resolved.html#category-x). Code licensed
-under a Category X license **cannot** be imported into Brooklyn without violating either Brooklyn's Apache license or
-the code's original license.
-
-There is also a ["Category B" list](http://www.apache.org/legal/resolved.html#category-b), which are licenses that are
-compatible with the Apache license only under certain circumstances. In practice, this means that we can declare a
-dependency on a library licensed under a Category B license, and bundle the binary build of the library in our binary
-builds, but we cannot import its source code into the Brooklyn codebase.
-
-If the code you are seeking to import does not appear on any of these lists, check to see if the license content is the
-same as a known license. For example, many projects actually use a BSD license but do not label it as "The BSD License".
-If you are still not certain about the license, please ask on the Brooklyn mailing list, and/or the Apache Legal mailing
-list.
-
-
-About LICENSE and NOTICE files
-------------------------------
-
-Apache Legal requires that *each* artifact that the project releases contains a `LICENSE` and `NOTICE` file that is
-*accurate for the contents of that artifact*. This means that, potentially, **every artifact that Brooklyn releases may
-contain a different `LICENSE` and `NOTICE` file**. In practice, it's not usually that complicated and there are only a
-few variations of these files needed.
-
-Furthermore, *accurate* `LICENSE` and `NOTICE` files means that it correctly attributes the contents of the artifact,
-and it does not contain anything unnecessary. This provision is what prevents us creating a mega LICENSE file and using
-it in every single artifact we release, because in many cases it will contain information that is not relevant to an
-artifact.
-
-What is a correct `LICENSE` and `NOTICE` file?
-
-* A correct `LICENSE` file is one that contains the text of the licence of any part of the code. The Apache Software
- License V2 will naturally be the first part of this file, as it's the license which we use for all the original code
- in Brooklyn. If some *Category A* licensed third-party code is bundled with this artifact, then the `LICENSE` file
- should identify what the third-party code is, and include a copy of its license. For example, if jquery is bundled
- with a web app, the `LICENSE` file would include a note jquery.js, its copyright and its license (MIT), and include a
- full copy of the MIT license.
-* A correct `NOTICE` file contains notices required by bundled third-party code above and beyond that which we have
- already noted in `LICENSE`. In practice modifying `NOTICE` is rarely required beyond the initial note about Apache
- Brooklyn. See [What Are Required Third-party Notices?](http://www.apache.org/legal/resolved.html#required-third-party-notices)
- for more information
-
-
-Applying LICENSE and NOTICE files to Brooklyn
----------------------------------------------
-
-When the Brooklyn project makes a release, we produce and release the following types of artifacts:
-
-1. One source release artifact
-2. One binary release artifact
-3. A large number of Maven release artifacts
-
-Therefore, our source release, our binary release, and every one of our Maven release artifacts, must **each** have
-their own, individually-tailored, `LICENSE` and `NOTICE` files.
-
-To some extent, this is automated, using scripts in `usage/dist/licensing`;
-but this must be manually run, and wherever source code is included or a project has insufficient information in its POM,
-you'll need to add project-specific metadata (with a project-specific `source-inclusions.yaml` file and/or in the
-dist project's `overrides.yaml` file). See the README.md in that project's folder for more information.
-
-### Maven artifacts
-
-Each Maven module will generally produce a JAR file from code under `src/main`, and a JAR file from code under
-`src/test`. (There are some exceptions which may produce different artifacts.)
-
-If the contents of the module are purely Apache Brooklyn original code, and the outputs are JAR files, then *no action
-is required*. The default build process will incorporate a general-purpose `LICENSE` and `NOTICE` file into all built
-JAR files. `LICENSE` will contain just a copy of the Apache Software License v2, and `NOTICE` will contain just the
-module's own notice fragment.
-
-However you will need to take action if either of these conditions are true:
-
-* the module produces an artifact that is **not** a JAR file - for example, the jsgui project produces a WAR file;
-* the module bundles third-party code that requires a change to `LICENSE` and/or `NOTICE`.
-
-In this case you will need to disable the automatic insertion of `LICENSE` and `NOTICE` and insert your own versions
-instead.
-
-For an example of a JAR file with customized `LICENSE`/`NOTICE` files, refer to the `usage/cli` project.
-For an example of a WAR file with customized `LICENSE`/`NOTICE` files, refer to the `usage/jsgui` project.
-
-### The source release
-
-In practice, the source release contains nothing that isn't in the individual produced Maven artifacts (the obvious
-difference about it being source instead of binary isn't relevant). Therefore, the source release `LICENSE` and `NOTICE`
-can be considered to be the union of every Maven artifact's `LICENSE` and `NOTICE`. The amalgamated files are kept in
-the root of the repository.
-
-### The binary release
-
-This is the trickiest one to get right. The binary release includes everything that is in the source and Maven releases,
-**plus every Java dependency of the project**. This means that the binary release is pulling in many additional items,
-each of which have their own license, and which will therefore impact on `LICENSE` and `NOTICE`.
-
-Therefore you must inspect every file that is present in the binary distribution, ascertain its license status, and
-ensure that `LICENSE` and `NOTICE` are correct.
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/code/tests.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/code/tests.md b/brooklyn-docs/guide/dev/code/tests.md
deleted file mode 100644
index a19f814..0000000
--- a/brooklyn-docs/guide/dev/code/tests.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-layout: website-normal
-title: Tests
-toc: /guide/toc.json
----
-
-We have the following tests groups:
-
-* normal (i.e. no group) -- should run quickly, not need internet, and not side effect the machine (apart from a few /tmp files)
-* Integration -- deploys locally, may read and write from internet, takes longer.
- If you change an entity, rerun the relevant integration test to make sure all is well!
-* Live -- deploys remotely, may provision machines (but should clean up, getting rid of them in a try block)
-* Live-sanity -- a sub-set of "Live" that can be run regularly; a trade-off of optimal code coverage for the
- time/cost of those tests.
-* WIP -- short for "work in progress", this will disable the test from being run by the normal brooklyn maven profiles,
- while leaving the test enabled so that one can work on it in IDEs or run the selected test(s) from the command line.
-* Acceptance -- this (currently little-used) group is for very long running tests, such as soak tests
-
-To run these from the command line, use something like the following:
-
-* normal: `mvn clean install`
-* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true --fail-never`
-* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true --fail-never`
-* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true --fail-never`
-
-To run a single test, use something like the following:
-
-* run a single test class: `mvn -Dtest=org.apache.brooklyn.enricher.stock.EnrichersTest -DfailIfNoTests=false test`
-* run a single test method: `mvn -Dtest=org.apache.brooklyn.enricher.stock.EnrichersTest#testAdding -DfailIfNoTests=false test`
-
-<!-- TODO describe how to run each of these, as a group, and individually; and profiles -->
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/env/ide/eclipse.include.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/env/ide/eclipse.include.md b/brooklyn-docs/guide/dev/env/ide/eclipse.include.md
deleted file mode 100644
index c3a7a06..0000000
--- a/brooklyn-docs/guide/dev/env/ide/eclipse.include.md
+++ /dev/null
@@ -1,6 +0,0 @@
-- Groovy Plugin: GRECLIPSE from
- [dist.springsource.org/snapshot/GRECLIPSE/e4.5/](http://dist.springsource.org/snapshot/GRECLIPSE/e4.5/);
- Be sure to include Groovy 2.3 compiler support and Maven-Eclipse (m2e) support.
- More details including download sites for other versions can be found at the [Groovy Eclipse Plugin site](http://docs.groovy-lang.org/latest/html/documentation/#section-groovyeclipse).
-
-- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse)
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/env/ide/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/env/ide/index.md b/brooklyn-docs/guide/dev/env/ide/index.md
deleted file mode 100644
index 60ad11d..0000000
--- a/brooklyn-docs/guide/dev/env/ide/index.md
+++ /dev/null
@@ -1,108 +0,0 @@
----
-layout: website-normal
-title: IDE Setup
-toc: /guide/toc.json
----
-
-Gone are the days when IDE integration always just works... Maven and Eclipse fight,
-neither quite gets along perfectly with Groovy,
-git branch switches (sooo nice) can be slow, etc etc.
-
-But with a bit of a dance the IDE can still be your friend,
-making it much easier to run tests and debug.
-
-As a general tip, don't always trust the IDE to build correctly; if you hit a snag,
-do a command-line ``mvn clean install`` (optionally with ``-DskipTests``)
-then refresh the project.
-
-See instructions below for specific IDEs.
-
-
-## Eclipse
-
-The default Eclipse downloads already include all of the plugins needed for
-working with the Brooklyn project. Optionally you can install the
-Groovy and TestNG plugins, but they are not required for building the project.
-You can install these using Help -> Install New Software, or from the Eclipse Marketplace:
-
-{% readj eclipse.include.md %}
-
-As of this writing, Eclipse 4.5 and Eclipse 4.4 are commonly used,
-and the codebase can be imported (Import -> Existing Maven Projects)
-and successfully built and run inside an IDE.
-However there are quirks, and mileage may vary. Disable ``Build Automatically``
-from the ``Project`` menu if the IDE is slow to respond.
-
-If you encounter issues, the following hints may be helpful:
-
-* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later".
- The build-helper connector is useful if you're prompted for it, but
- do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway).
- You can manually mark as permanently ignored certain errors;
- this updates the pom.xml (and should be current).
-
-* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh
- can be useful to re-populate files which need to be copied to `target/`
-
-* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files
- (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install
- from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix
- `.classpath`s).
- Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure)
- or the filesystem, or use
- the following command to remove these rogue blocks in the generated `.classpath` files:
-
-{% highlight bash %}
-% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \;
-{% endhighlight %}
-
-* You may need to ensure ``src/main/{java,resources}`` is created in each project dir,
- if (older versions) complain about missing directories,
- and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists):
-
-{% highlight bash %}
-find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \;
-{% endhighlight %}
-
-If the pain starts to be too much, come find us on IRC #brooklyncentral or
-[elsewhere]({{site.path.website}}/community/) and we can hopefully share our pearls.
-(And if you have a tip we haven't mentioned please let us know that too!)
-
-
-
-## IntelliJ IDEA
-
-To develop or debug Brooklyn in IntelliJ, you will need to ensure that the Groovy and TestNG plugins are installed
-via the IntelliJ IDEA | Preferences | Plugins menu. Once installed, you can open Brooklyn from the root folder,
-(e.g. ``~/myfiles/brooklyn``) which will automatically open the subprojects.
-
-Brooklyn has informally standardized on arranging `import` statements as per Eclipse's default configuration.
-IntelliJ's default configuration is different, which can result in unwanted "noise" in commits where imports are
-shuffled backward and forward between the two types - PRs which do this will likely fail the review. To avoid this,
-reconfigure IntelliJ to organize imports similar to Eclipse. See [this StackOverflow answer](http://stackoverflow.com/a/17194980/68898)
-for a suitable configuration.
-
-
-## Netbeans
-
-Tips from Netbeans users wanted!
-
-
-
-## Debugging Tips
-
-To debug Brooklyn, create a launch configuration which launches the ``BrooklynJavascriptGuiLauncher`` class. NOTE: You may
-need to add additional projects or folders to the classpath of the run configuration (e.g. add the brooklyn-software-nosql
-project if you wish to deploy a MongoDBServer). You will also need to ensure that the working directory is set to the jsgui
-folder. For IntelliJ, you can set the 'Working directory' of the Run/Debug Configuration to ``$MODULE_DIR$/../jsgui``. For
-Eclipse, use the default option of ``${workspace_loc:brooklyn-jsgui}``.
-
-To debug the jsgui (the Brooklyn web console), you will need to build Brooklyn with -DskipOptimization to prevent the build from minifying the javascript.
-When building via the command line, use the command ``mvn clean install -DskipOptimization``, and if you are using IntelliJ IDEA, you can add the option
-to the Maven Runner by clicking on the Maven Settings icon in the Maven Projects tool window and adding the ``skipOptimization`` property with no value.
-
-When running at the command line you can enable remote connections so that one can attach a debugger to the Java process:
- Run Java with the following on the command line or in JAVA_OPTS: ``-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005``
-
-To debug a brooklyn instance that has been run with the above JAVA_OPTS, create a remote build configuration (IntelliJ -
-Run | Edit Configurations | + | Remote) with the default options, ensuring the port matches the address specified in JAVA_OPTS.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/env/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/env/index.md b/brooklyn-docs/guide/dev/env/index.md
deleted file mode 100644
index 8e1e422..0000000
--- a/brooklyn-docs/guide/dev/env/index.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Dev Environment
-layout: website-normal
-breadcrumbs:
-- /website/documentation/index.md
-- ../index.md
-- index.md
-children:
-- maven-build.md
-- ide/
----
-
-{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/env/maven-build.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/env/maven-build.md b/brooklyn-docs/guide/dev/env/maven-build.md
deleted file mode 100644
index 275cea2..0000000
--- a/brooklyn-docs/guide/dev/env/maven-build.md
+++ /dev/null
@@ -1,180 +0,0 @@
----
-layout: website-normal
-title: Maven Build
-toc: /guide/toc.json
----
-
-## The Basics
-
-To build the code, you need Maven (v3) installed and Java (v1.7+).
-With that in place, you should be able to build everything with a:
-
-{% highlight bash %}
-% mvn clean install
-{% endhighlight %}
-
-Key things to note if you're new to Maven:
-
-* You may need more JVM memory, e.g. at the command-line (or in `.profile`):
-
- ``export MAVEN_OPTS="-Xmx1024m -Xms512m -XX:MaxPermSize=256m"``
-
-* You can do this in specific projects as well.
-
-* Add ``-DskipTests`` to skip tests.
-
-* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests
- ([tests described here](../code/tests.html))
-
-* Nearly all the gory details are in the root ``pom.xml``, which is referenced by child project poms.
-
-* You can also open and use the code in your favourite IDE,
- although you may hit a few **[snags](ide/)**
- (that link has some tips for resolving them too)
-
-
-## When the RAT Bites
-
-We use RAT to ensure that all files are compliant to Apache standards. Most of the time you shouldn't see it or need to know about it, but if it detects a violation, you'll get a message such as:
-
- [ERROR] Failed to execute goal org.apache.rat:apache-rat-plugin:0.10:check (default) on project brooklyn-parent: Too many files with unapproved license: 1 See RAT report in: /Users/alex/Data/cloudsoft/dev/gits/brooklyn/target/rat.txt -> [Help 1]
-
-If there's a problem, see the file `rat.txt` in the `target` directory of the failed project. (Maven will show you this link in its output.)
-
-Often the problem is one of the following:
-
-* You've added a file which requires the license header but doesn't have it
-
- **Resolution:** Simply copy the header from another file
-
-* You've got some temporary files which RAT things should have headers
-
- **Resolution:** Move the files away, add headers, or turn off RAT (see below)
-
-* The project structure has changed and you have stale files (e.g. in a `target` directory)
-
- **Resolution:** Remove the stale files, e.g. with `git clean -df` (and if needed a `find . -name target -prune -exec rm -rf {} \;` to delete folders named `target`)
-
-To disable RAT checking on a build, set `rat.ignoreErrors`, e.g. `mvn -Drat.ignoreErrors=true clean install`. (But note you will need RAT to pass in order for a PR to be accepted!)
-
-If there is a good reason that a file, pattern, or directory should be permanently ignored, that is easy to add inside the root `pom.xml`.
-
-
-## Other Handy Hints
-
-* On some **Ubuntu** (e.g. 10.4 LTS) maven v3 is not currently available from the repositories.
- Some instructions for installing at are [at superuser.com](http://superuser.com/questions/298062/how-do-i-install-maven-3).
-
-* The **mvnf** script
- ([get the gist here](https://gist.github.com/2241800))
- simplifies building selected projects, so if you just change something in ``software-webapp``
- and then want to re-run the examples you can do:
-
- ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}``
-
-## Appendix: Sample Output
-
-A healthy build will look something like the following,
-including a few warnings (which we have looked into and
-understand to be benign and hard to get rid of them,
-although we'd love to if anyone can help!):
-
-{% highlight bash %}
-% mvn clean install
-[INFO] Scanning for projects...
-[INFO] ------------------------------------------------------------------------
-[INFO] Reactor Build Order:
-[INFO]
-[INFO] Brooklyn Parent Project
-[INFO] Brooklyn Utilities to Support Testing (listeners etc)
-[INFO] Brooklyn Logback Includable Configuration
-[INFO] Brooklyn Common Utilities
-[INFO] Brooklyn Groovy Utilities
-[INFO] Brooklyn API
-
-...
-
-[WARNING] Ignoring project type war - supportedProjectTypes = [jar]
-
-...
-
-[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in ~/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar
-
-...
-
-[INFO] — maven-assembly-plugin:2.3:single (build-distribution-dir) @ brooklyn-dist —
-[INFO] Reading assembly descriptor: src/main/config/build-distribution-dir.xml
-{% comment %}BROOKLYN_VERSION{% endcomment %}[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.9.0-SNAPSHOT; it doesn't have an associated file or directory.
-[INFO] Copying files to ~/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist
-[WARNING] Assembly file: ~/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment.
-
-...
-
-[INFO] — maven-assembly-plugin:2.3:single (build-distribution-archive) @ brooklyn-dist —
-[INFO] Reading assembly descriptor: src/main/config/build-distribution-archive.xml
-{% comment %}BROOKLYN_VERSION{% endcomment %}[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.9.0-SNAPSHOT; it doesn't have an associated file or directory.
-{% comment %}BROOKLYN_VERSION{% endcomment %}[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.9.0-SNAPSHOT-dist.tar.gz
-{% comment %}BROOKLYN_VERSION{% endcomment %}[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.9.0-SNAPSHOT; it doesn't have an associated file or directory.
-
-...
-
-[WARNING] Don't override file /Users/aled/repos/apache/incubator-brooklyn/usage/archetypes/quickstart/target/test-classes/projects/integration-test-1/project/brooklyn-sample/src/main/resources/sample-icon.png
-
-...
-
-[INFO] Reactor Summary:
-[INFO]
-[INFO] Brooklyn Parent Project ........................... SUCCESS [3.072s]
-[INFO] Brooklyn Utilities to Support Testing (listeners etc) SUCCESS [3.114s]
-[INFO] Brooklyn Logback Includable Configuration ......... SUCCESS [0.680s]
-[INFO] Brooklyn Common Utilities ......................... SUCCESS [7.263s]
-[INFO] Brooklyn Groovy Utilities ......................... SUCCESS [5.193s]
-[INFO] Brooklyn API ...................................... SUCCESS [2.146s]
-[INFO] Brooklyn Test Support ............................. SUCCESS [2.517s]
-[INFO] CAMP Server Parent Project ........................ SUCCESS [0.075s]
-[INFO] CAMP Base ......................................... SUCCESS [4.079s]
-[INFO] Brooklyn REST Swagger Apidoc Utilities ............ SUCCESS [1.983s]
-[INFO] Brooklyn Logback Configuration .................... SUCCESS [0.625s]
-[INFO] CAMP Server ....................................... SUCCESS [5.446s]
-[INFO] Brooklyn Core ..................................... SUCCESS [1:24.122s]
-[INFO] Brooklyn Policies ................................. SUCCESS [44.425s]
-[INFO] Brooklyn Hazelcast Storage ........................ SUCCESS [7.143s]
-[INFO] Brooklyn Jclouds Location Targets ................. SUCCESS [16.488s]
-[INFO] Brooklyn Secure JMXMP Agent ....................... SUCCESS [8.634s]
-[INFO] Brooklyn JMX RMI Agent ............................ SUCCESS [2.315s]
-[INFO] Brooklyn Software Base ............................ SUCCESS [28.538s]
-[INFO] Brooklyn Network Software Entities ................ SUCCESS [3.896s]
-[INFO] Brooklyn OSGi Software Entities ................... SUCCESS [4.589s]
-[INFO] Brooklyn Web App Software Entities ................ SUCCESS [17.484s]
-[INFO] Brooklyn Messaging Software Entities .............. SUCCESS [7.106s]
-[INFO] Brooklyn Database Software Entities ............... SUCCESS [5.229s]
-[INFO] Brooklyn NoSQL Data Store Software Entities ....... SUCCESS [11.901s]
-[INFO] Brooklyn Monitoring Software Entities ............. SUCCESS [4.027s]
-[INFO] Brooklyn CAMP REST API ............................ SUCCESS [15.285s]
-[INFO] Brooklyn REST API ................................. SUCCESS [4.489s]
-[INFO] Brooklyn REST Server .............................. SUCCESS [30.270s]
-[INFO] Brooklyn REST Client .............................. SUCCESS [7.007s]
-[INFO] Brooklyn REST JavaScript Web GUI .................. SUCCESS [24.397s]
-[INFO] Brooklyn Launcher ................................. SUCCESS [15.923s]
-[INFO] Brooklyn Command Line Interface ................... SUCCESS [9.279s]
-[INFO] Brooklyn All Things ............................... SUCCESS [13.875s]
-[INFO] Brooklyn Distribution ............................. SUCCESS [49.370s]
-[INFO] Brooklyn Quick-Start Project Archetype ............ SUCCESS [12.053s]
-[INFO] Brooklyn Examples Aggregator Project .............. SUCCESS [0.085s]
-[INFO] Brooklyn Examples Support Aggregator Project - Webapps SUCCESS [0.053s]
-[INFO] hello-world-webapp Maven Webapp ................... SUCCESS [0.751s]
-[INFO] hello-world-sql-webapp Maven Webapp ............... SUCCESS [0.623s]
-[INFO] Brooklyn Simple Web Cluster Example ............... SUCCESS [5.398s]
-[INFO] Brooklyn Global Web Fabric Example ................ SUCCESS [3.176s]
-[INFO] Brooklyn Simple Messaging Publish-Subscribe Example SUCCESS [3.217s]
-[INFO] Brooklyn NoSQL Cluster Examples ................... SUCCESS [6.790s]
-[INFO] Brooklyn QA ....................................... SUCCESS [7.117s]
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 8:33.983s
-[INFO] Finished at: Mon Jul 21 14:56:46 BST 2014
-[INFO] Final Memory: 66M/554M
-[INFO] ------------------------------------------------------------------------
-
-{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/index.md b/brooklyn-docs/guide/dev/index.md
deleted file mode 100644
index 2c294b6..0000000
--- a/brooklyn-docs/guide/dev/index.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Developer Guide
-layout: website-normal
-menu_parent: /website/documentation/
-breadcrumbs:
-- /website/documentation/index.md
-- /guide/dev/index.md
-children:
-- env/
-- code/
-- { link: "http://github.com/apache/incubator-brooklyn", title: "GitHub" }
-- code/tests.md
-- code/licensing.md
-- tips/
-- tips/logging.md
-- tips/debugging-remote-brooklyn.md
-- { link: "https://brooklyn.apache.org/v/latest/misc/javadoc", title: "Javadoc" }
----
-
-{% comment %}
-TODO
-
-The Developer Guide contains information on working with the Brooklyn codebase.
-
-Of particular note to people getting started, there is:
-
-* Help with Maven
-* Help with Git
-* Help setting up IDE's
-
-And for the Brooklyn codebase itself, see:
-
-* Project structure
-* Areas of Special Hairiness
-
-(All links are TODO.)
-{% endcomment %}
-
-{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/tips/debugging-remote-brooklyn.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/tips/debugging-remote-brooklyn.md b/brooklyn-docs/guide/dev/tips/debugging-remote-brooklyn.md
deleted file mode 100644
index 2465f0b..0000000
--- a/brooklyn-docs/guide/dev/tips/debugging-remote-brooklyn.md
+++ /dev/null
@@ -1,138 +0,0 @@
----
-layout: website-normal
-title: Brooklyn Remote Debugging
-toc: /guide/toc.json
----
-
-Usually during development, you will be running Brooklyn from your IDE (see [IDE Setup](../env/ide/)), in which case
-debugging is as simple as setting a breakpoint. There may however be times when you need to debug an existing remote
-Brooklyn instance (often referred to as Resident Brooklyn, or rBrooklyn) on another machine, usually in the cloud.
-
-Thankfully, the tools are available to do this, and setting it up is quite straightforward. The steps are as follows:
-
-* [Getting the right source code version](#sourceCodeVersion)
-* [Starting Brooklyn with a debug listener](#startingBrooklyn)
-* [Creating an SSH tunnel](#sshTunnel)
-* [Connecting your IDE](#connectingIDE)
-
-## <a name="sourceCodeVersion"></a>Getting the right source code version
-The first step is to ensure that your local copy of the source code is at the version used to build the remote Brooklyn
-instance. The git commit that was used to build Brooklyn is available via the REST API:
-
- http://<remote-address>:<remote-port>/v1/server/version
-
-This should return details of the build as a JSON string similar to the following (formatted for clarity):
-
-{% highlight json %}
-{
- "version": "0.9.0-SNAPSHOT", {% comment %}BROOKLYN_VERSION{% endcomment %}
- "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224",
- "buildBranch": "UNKNOWN"
-}
-{% endhighlight %}
-
-The value that we're interested in is `buildSha1`. This is the git commit that was used to build Brooklyn. We can now
-checkout and build the Brooklyn code at this commit by running the following in the root of your Brooklyn repo:
-
-{% highlight bash %}
-% git checkout c0fdc15291702281acdebf1b11d431a6385f5224
-% mvn clean install -DskipTests
-{% endhighlight %}
-
-Whilst building the code isn't strictly necessary, it can help prevent some IDE issues.
-
-## <a name="startingBrooklyn"></a>Starting Brooklyn with a debug listener
-By default, Brooklyn does not listen for a debugger to be attached, however this behaviour can be set by setting JAVA_OPTS,
-which will require a restart of the Brooklyn node. To do this, SSH to the remote Brooklyn node and run the following in the
-root of the Brooklyn installation:
-
-{% highlight bash %}
-# NOTE: Running this kill command will lose existing apps and machines if persistence is disabled.
-% kill `cat pid_java`
-% export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n"
-% bin/brooklyn launch &
-{% endhighlight %}
-
-If `JAVA_OPTS` is not set, Brooklyn will automatically set it to `"-Xms256m -Xmx1g -XX:MaxPermSize=256m"`, which is why
-we have prepended the agentlib settings with these values here.
-
-You should see the following in the console output:
-
- Listening for transport dt_socket at address: 8888
-
-This will indicate the Brooklyn is listening on port 8888 for a debugger to be attached.
-
-## <a name="sshTunnel"></a>Creating an SSH tunnel
-
-If port 8888 is accessible on the remote Brooklyn server, then you can skip this step and simply use the address of the
-server in place of 127.0.0.1 in the [Connecting your IDE](#connectingIDE) section below. It will normally be possible to
-make the port accessible by configuring Security Groups, iptables, endpoints etc., but for a quick ad-hoc connection it's
-usually simpler to create an SSH tunnel. This will create an open SSH connection that will redirect traffic from a port
-on a local interface via SSH to a port on the remote machine. To create the tunnel, run the following on your local
-machine:
-
-{% highlight bash %}
-# replace this with the address or IP of the remote Brooklyn node
-REMOTE_HOST=<remote-address>
-# if you wish to use a different port, this value must match the port specified in the JAVA_OPTS
-REMOTE_PORT=8888
-# if you wish to use a different local port, this value must match the port specified in the IDE configuration
-LOCAL_PORT=8888
-# set this to the login user you use to SSH to the remote Brooklyn node
-SSH_USER=root
-# The private key file used to SSH to the remote node. If you use a password, see the alternative command below
-PRIVATE_KEY_FILE=~/.ssh/id_rsa
-
-% ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
-{% endhighlight %}
-
-If you use a password to SSH to the remote Brooklyn node, simply remove the `-i $PRIVATE_KEY_FILE` section like so:
-
- ssh -YNf -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
-
-If you are using a password to connect, you will be prompted to enter your password to connect to the remote node upon
-running the SSH command.
-
-The SSH tunnel should now be redirecting traffic from port 8888 on the local 127.0.0.1 network interface via the SSH
-tunnel to port 8888 on the remote 127.0.0.1 interface. It should now be possible to connect the debugger and start
-debugging.
-
-## <a name="connectingIDE"></a> Connecting your IDE
-
-Setting up your IDE will differ depending upon which IDE you are using. Instructions are given here for Eclipse and
-IntelliJ, and have been tested with Eclipse Luna and IntelliJ Ultimate 14.
-
-### Eclipse Setup
-
-To debug using Eclipse, first open the Brooklyn project in Eclipse (see [IDE Setup](../env/ide/)).
-
-Now create a debug configuration by clicking `Run` | `Debug Configurations...`. You will then be presented with the
-Debug Configuration dialog.
-
-Select `Remote Java Application` from the list and click the 'New' button to create a new configuration. Set the name
-to something suitable such as 'Remote debug on 8888'. The Project can be set to any of the Brooklyn projects, the
-Connection Type should be set to 'Standard (Socket Attach)'. The Host should be set to either localhost or 127.0.0.1
-and the Port should be set to 8888. Click 'Debug' to start debugging.
-
-### IntelliJ Setup
-
-To debug using IntelliJ, first open the Brooklyn project in IntelliJ (see [IDE Setup](../env/ide/)).
-
-Now create a debug configuration by clicking `Run` | `Edit Configurations`. You will then be presented with the
-Run/Debug Configurations dialog.
-
-Click on the `+` button and select 'Remote' to create a new remote configuration. Set the name to something suitable
-such as 'Remote debug on 8888'. The first three sections simply give the command line arguments for starting the java
-process using different versions of java, however we have already done this in
-[Starting Brooklyn with a debug listener](#startingBrooklyn). The Transport option should be set to 'Socket', the Debugger Mode should be set to 'Attach', the
-Host should be set to localhost or 127.0.0.1 (or the address of the remote machine if you are not using an SSH tunnel),
-and the Port should be set to 8888. The 'Search sources' section should be set to `<whole project>`. Click OK to save the
-configuration, then select the configuration from the configurations drop-down and click the debug button to start
-debugging.
-
-### Testing
-
-The easiest way to test that remote debugging has been setup correctly is to set a breakpoint and see if it is hit. An
-easy place to start is to create a breakpoint in the `ServerResource.java` class, in the `getStatus()`
-method.
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/tips/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/tips/index.md b/brooklyn-docs/guide/dev/tips/index.md
deleted file mode 100644
index 858c2c6..0000000
--- a/brooklyn-docs/guide/dev/tips/index.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-layout: website-normal
-title: Miscellaneous Tips and Tricks
----
-
-## General Good Ways of Working
-
-* If working on something which could be contributed to Brooklyn,
- do it in a project under the ``sandbox`` directory.
- This means we can accept pulls more easily (as sandbox items aren't built as part of the main build)
- and speed up collaboration.
-
-* When debugging an entity, make sure the [brooklyn.SSH logger](logging.html) is set to DEBUG and accessible.
-
-* Use tests heavily! These are pretty good to run in the IDE (once you've completed [IDE setup]({{site.path.guide}}/dev/env/ide/)),
- and far quicker to spot problems than runtime, plus we get early-warning of problems introduced in the future.
- (In particular, Groovy's laxity with compilation means it is easy to introduce silly errors which good test coverage will find much faster.)
-
-* If you hit inexplicable problems at runtime, try clearing your Maven caches,
- or the brooklyn-relevant parts, under ``~/.m2/repository``.
- Also note your IDE might be recompiling at the same time as a Maven command-line build,
- so consider turning off auto-build.
-
-* When a class or method becomes deprecated, always include ``@deprecated`` in the Javadoc
- e.g. "``@deprecated since 0.7.0; instead use {@link ...}``"
- * Include when it was deprecated
- * Suggest what to use instead -- e.g. link to alternative method, and/or code snippet, etc.
- * Consider logging a warning message when a deprecated method or config option is used,
- saying who is using it (e.g. useful if deprecated config keys are used in yaml) --
- if it's a method which might be called a lot, some convenience for "warn once per entity" would be helpful)
- * See the [Java deprecation documentation](https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html)
-
-
-<a name="EntityDesign"></a>
-
-## Entity Design Tips
-
-* Look at related entities and understand what they've done, in particular which
- sensors and config keys can be re-used.
- (Many are inherited from interfaces, where they are declared as constants,
- e.g. ``Attributes`` and ``UsesJmx``.)
-
-* Understand the location hierarchy: software process entities typically get an ``SshMachineLocation``,
- and use a ``*SshDriver`` to do what they need. This will usually have a ``MachineProvisioningLocation`` parent, e.g. a
- ``JcloudsLocation`` (e.g. AWS eu-west-1 with credentials) or possibly a ``LocalhostMachineProvisioningLocation``.
- Clusters will take such a ``MachineProvisioningLocation`` (or a singleton list); fabircs take a list of locations.
- Some PaaS systems have their own location model, such as ``OpenShiftLocation``.
-
-Finally, don't be shy about [talking with others]({{site.path.website}}/community/),
-that's far better than spinning your wheels (or worse, having a bad experience),
-plus it means we can hopefully improve things for other people!
-
-
-## Project Maintenance
-
-* Adding a new project may need updates to ``/pom.xml`` ``modules`` section and ``usage/all`` dependencies
-
-* Adding a new example project may need updates to ``/pom.xml`` and ``/examples/pom.xml`` (and the documentation too!)
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/dev/tips/logging.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/dev/tips/logging.md b/brooklyn-docs/guide/dev/tips/logging.md
deleted file mode 100644
index 7c4543c..0000000
--- a/brooklyn-docs/guide/dev/tips/logging.md
+++ /dev/null
@@ -1,143 +0,0 @@
----
-title: Logging
-layout: website-normal
----
-
-## Logging: A Quick Overview
-
-For logging, we use **logback** which implements the slf4j API.
-This means you can use any slf4j compliant logging framework,
-with a default configuration which just works out of the box
-and bindings to the other common libraries (``java.util.logging``, ``log4j``, ...)
-if you prefer one of those.
-
-To use:
-
-* **Users**:
-If using a brooklyn binary installation, simply edit the ``logback.xml``
-or ``logback-custom.xml`` supplied in the archive, sometimes in a ``conf/``
-directory.
-
-* **Developers**:
-When setting up a new project, if you want logging it is recommended to include
-the ``brooklyn-logback-xml`` project as an *optional* and *provided* maven dependency,
-and then to put custom logging configuration in either ``logback-custom.xml`` or ``logback-main.xml``,
-as described below.
-
-
-## Customizing Your Logging
-
-The project ``brooklyn-logback-xml`` supplies a ``logback.xml`` configuration,
-with a mechanism which allows it to be easily customized, consumed, and overridden.
-You may wish to include this as an *optional* dependency so that it is not forced
-upon downstream projects. This ``logback.xml`` file supplied contains just one instruction,
-to include ``logback-main.xml``, and that file in turn includes:
-
-* ``logback-custom.xml``
-* ``brooklyn/logback-appender-file.xml``
-* ``brooklyn/logback-appender-stdout.xml``
-* ``brooklyn/logback-logger-excludes.xml``
-* ``brooklyn/logback-debug.xml``
-
-For the most common customizations, simply create a ``logback-custom.xml`` on your classpath
-(ensuring it is loaded *before* brooklyn classes in classpath ordering in the pom)
-and supply your customizations there:
-
-{% highlight xml %}
-<included>
- <!-- filename to log to -->
- <property name="logging.basename" scope="context" value="acme-app" />
-
- <!-- additional loggers -->
- <logger name="com.acme.app" level="DEBUG"/>
-</included>
-{% endhighlight %}
-
-For other configuration, you can override individual files listed above.
-For example:
-
-* To remove debug logging, create a trivial ``brooklyn/logback-debug.xml``,
- containing simply ``<included/>``.
-* To customise stdout logging, perhaps to give it a threshhold WARN instead of INFO,
- create a ``brooklyn/logback-appender-stdout.xml`` which defines an appender STDOUT.
-* To discard all brooklyn's default logging, create a ``logback-main.xml`` which
- contains your configuration. This should look like a standard logback
- configuration file, except it should be wrapped in ``<included>`` XML tags rather
- than ``<configuration>`` XML tags (because it is included from the ``logback.xml``
- which comes with ``brooklyn-logback-xml``.)
-* To redirect all jclouds logging to a separate file include ``brooklyn/logback-logger-debug-jclouds.xml``.
- This redirects all logging from ``org.jclouds`` and ``jclouds`` to one of two files: anything
- logged from Brooklyn's persistence thread will end up in a `persistence.log`, everything else
- will end up in ``jclouds.log``.
-
-You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``.
-If you do, logback will detect multiple files with that name and will scream at you.
-If you wish to supply your own ``logback.xml``, do **not** include ``brooklyn-logback-xml``.
-(Alternatively you can include a ``logback.groovy`` which causes logback to ignore ``logback.xml``.)
-
-You can set a specific logback config file to use with:
-
-{% highlight bash %}
--Dlogback.configurationFile=/path/to/config.xml
-{% endhighlight %}
-
-
-## Assemblies
-
-When building an assembly, it is recommended to create a ``conf/logback.xml`` which
-simply includes ``logback-main.xml`` (which comes from the classpath). Users of the assembly
-can then edit the ``logback.xml`` file in the usual way, or they can plug in to the configuration
-mechanisms described above, by creating files such as ``logback-custom.xml`` under ``conf/``.
-
-Including ``brooklyn-logback-xml`` as an *optional* and *provided* dependency means everything
-should work correctly in IDE's but it will not include the extra ``logback.xml`` file in the assembly.
-(Alternatively if you include the ``conf/`` dir in your IDE build, you should exclude this dependency.)
-
-With this mechanism, you can include ``logback-custom.xml`` and/or other files underneath
-``src/main/resources/`` of a project, as described above (for instance to include custom
-logging categories and define the log file name) and it should get picked up,
-both in the IDE and in the assembly.
-
-
-## Tests
-
-Brooklyn projects ``test`` scope includes the ``brooklyn-utils-test-support`` project
-which supplies a ``logback-test.xml``. logback uses this file in preference to ``logback.xml``
-when available (ie when running tests). However the ``logback-test.xml`` Brooklyn uses
-includes the same ``logback-main.xml`` call path above, so your configurations should still work.
-
-The only differences of the ``logback-test.xml`` configuration is that:
-
-* Debug logging is included for all Brooklyn packages
-* The log file is called ``brooklyn-tests.log``
-
-
-## Caveats
-
-* logback uses SLF4J version 1.6 which is **not compatible** with 1.5.x.
- If you have dependent projects using 1.5.x (such as older Grails) things may break.
-
-* If you're not getting the logging you expect in the IDE, make sure
- ``src/main/resources`` is included in the classpath.
- (In eclipse, right-click the project, the Build Path -> Configure,
- then make sure all dirs are included (All) and excluded (None) --
- ``mvn clean install`` should do this for you.)
-
-* You may find that your IDE logs to a file ``brooklyn-tests.log``
- if it doesn't distinguish between test build classpaths and normal classpaths.
-
-* Logging configuration using file overrides such as this is very sensitive to
- classpath order. To get a separate `brooklyn-tests.log` file during testing,
- for example, the `brooklyn-test-support` project with scope `test` must be
- declared as a dependency *before* `brooklyn-logback-includes`, due to the way
- both files declare `logback-appender-file.xml`.
-
-* Similarly note that the `logback-custom.xml` file is included *after*
- logging categories and levels are declared, but before appenders are declared,
- so that logging levels declared in that file dominate, and that
- properties from that file apply to appenders.
-
-* Finally remember this is open to improvement. It's the best system we've found
- so far but we welcome advice. In particular if it could be possible to include
- files from the classpath with wildcards in alphabetical order, we'd be able
- to remove some of the quirks listed above (though at a cost of some complexity!).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/glossary.json
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/glossary.json b/brooklyn-docs/guide/glossary.json
deleted file mode 100644
index b201aba..0000000
--- a/brooklyn-docs/guide/glossary.json
+++ /dev/null
@@ -1,22 +0,0 @@
-[
- {
- "term": "location, !location:",
- "description": "A server or resource to which Apache Brooklyn can deploy applications"
- },
- {
- "term": "blueprint",
- "description": "A descriptor or pattern which describes how Apache Brooklyn should deploy applications"
- },
- {
- "term": "entity",
- "description": "A software package or service Apache Brooklyn can interact with"
- },
- {
- "term": "sensor, !<code>sensor",
- "description": "A sensor is a property of an Apache Brooklyn entity, updated in real-time"
- },
- {
- "term": "effector",
- "description": "Effectors are tools Apache Brooklyn provides, that allow you to manipulate the live entities within an application"
- }
-]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/index.md b/brooklyn-docs/guide/index.md
deleted file mode 100644
index cdb3b46..0000000
--- a/brooklyn-docs/guide/index.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: User Guide
-layout: website-normal
-breadcrumbs:
-- /website/documentation/index.md
-- index.md
-children:
-- { path: /guide/start/index.md }
-- { path: /guide/misc/download.md }
-- { path: /guide/concepts/index.md }
-- { path: /guide/yaml/index.md }
-- { path: /guide/java/index.md }
-- { path: /guide/ops/index.md }
-- { path: /guide/misc/index.md }
----
-
-This is the Brooklyn User Guide for v{{ site.brooklyn-version }}:
-
-{% include list-children.html %}
-
-If you are working with the Brooklyn codebase itself, also see the [Developer Guide](dev/) for this version.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/java/archetype.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/java/archetype.md b/brooklyn-docs/guide/java/archetype.md
deleted file mode 100644
index 3a87027..0000000
--- a/brooklyn-docs/guide/java/archetype.md
+++ /dev/null
@@ -1,64 +0,0 @@
----
-title: Creating from a Maven Archetype
-layout: website-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-### Maven Archetype
-
-Brooklyn includes a maven archetype, which can be used to create the project structure for a new application.
-
-This can be done interactively using:
-{% highlight bash %}
-$ mvn archetype:generate
-{% endhighlight %}
-
-The user will be prompted for the archetype to use (i.e. group "io.brooklyn"
-and artifact "brooklyn-archetype-quickstart"), as well as options for the project
-to be created.
-
-Alternatively, all options can be supplied at the command line. For example,
-if creating a project named "autobrick" for "com.acme":
-
-{% highlight bash %}
-$ mvn archetype:generate \
- -DarchetypeGroupId=org.apache.brooklyn \
- -DarchetypeArtifactId=brooklyn-archetype-quickstart \
- -DarchetypeVersion={{ site.brooklyn-version }} \
- -DgroupId=com.acme -DartifactId=autobrick \
- -Dversion=0.1.0-SNAPSHOT \
- -DpackageName=com.acme.autobrick \
- -DinteractiveMode=false
-{% endhighlight %}
-
-This will create a directory with the artifact name (e.g. "autobrick" in the example above).
-Note that if run from a directory containing a pom, it will also modify that pom to add this as a module!
-
-The project will contain an example app. You can run this, and also replace it with your own
-application code.
-
-To build, run the commands:
-
-{% highlight bash %}
-$ cd autobrick
-$ mvn clean install assembly:assembly
-{% endhighlight %}
-
-The assembly command will build a complete standalone distribution archive in `target/autobrick-0.1.0-SNAPSHOT-dist.tar.gz`,
-suitable for redistribution and containing `./start.sh` in the root.
-
-An unpacked equivalent is placed in `target/autobrick-0.1.0-SNAPSHOT-dist`,
-thus you can run the single-node sample locally with:
-
-{% highlight bash %}
-$ cd target/autobrick-0.1.0-SNAPSHOT-dist/autobrick-0.1.0-SNAPSHOT/
-$ ./start.sh launch --single
-{% endhighlight %}
-
-This `start.sh` script has all of the same options as the default `brooklyn` script,
-including `./start.sh help` and the `--location` argument for `launch`,
-with a couple of extra `launch` options for the sample blueprints in the archetype project:
-
-- `./start.sh launch --single` will launch a single app-server instance
-- `./start.sh launch --cluster` will launch a cluster of app-servers
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/java/common-usage.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/java/common-usage.md b/brooklyn-docs/guide/java/common-usage.md
deleted file mode 100644
index 8f0ed32..0000000
--- a/brooklyn-docs/guide/java/common-usage.md
+++ /dev/null
@@ -1,140 +0,0 @@
----
-title: Common Classes and Entities
-layout: website-normal
----
-
-<!-- TODO old, needs work (refactoring!) and use of java_link -->
-
-### Entity Class Hierarchy
-
-By convention in Brooklyn the following words have a particular meaning, both as types (which extend ``Group``, which extends ``Entity``) and when used as words in other entities (such as ``TomcatFabric``):
-
-- *Cluster* - a homogeneous collection of entities
-- *Fabric* - a multi-location collection of entities, with one per location; often used with a cluster per location
-- *Stack* - heterogeneous (mixed types of children)
-- *Application* - user's entry point
-
-<!---
-TODO
--->
-
-- *entity spec* defines an entity, so that one or more such entities can be created; often used by clusters/groups to define how to instantiate new children.
-- *entity factories* are often used by clusters/groups to define how to instantiate new children.
-- *traits* (mixins) providing certain capabilities, such as Resizable and Balanceable
-- *Resizable* entities can re-sized dynamically, to increase/decrease the number of child entities.
-- *Movable* entities can be migrated between *balanceable containers*.
-- *Balanceable containers* can contain *movable* entities, where each contained entity is normally associated with
- a piece of work within that container.
-
-### Off-the-Shelf Entities
-
-brooklyn includes a selection of entities already available for use in applications,
-including appropriate sensors and effectors, and in some cases include Cluster and Fabric variants.
-(These are also useful as templates for writing new entities.)
-
-These include:
-
-- **Web**: Tomcat, JBoss, Jetty (external), Play (external); nginx; GeoScaling
-- **Data**: MySQL, Redis, MongoDB, Infinispan, GemFire (external)
-- **Containers**: Karaf
-- **Messaging**: ActiveMQ, Qpid, Rabbit MQ
-- **PaaS**: Cloud Foundry, Stackato; OpenShift
-
-
-### Sensors
-
-Sensors are typically defined as static named fields on the Entity subclass. These define the channels of events and activity that interested parties can track remotely. For example:
-{% highlight java %}
-/** a sensor for saying hi (illustrative), carrying a String value
- which is typically the name of the person to whom we are saying hi */
-public static final Sensor<String> HELLO_SENSOR = ...
-
-{% endhighlight %}
-
-If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If it may be remote, you can subscribe to it through various APIs.
-
-Sensors are used by operators and policies to monitor health and know when to invoke the effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through the ``ManagementContext``.
-
-Often ``Policy`` instances will subscribe to sensor events on their associated entity or its children; these events might be an ``AttributeValueEvent`` – an attribute value being reported on change or periodically – or something transient such as ``LogMessage`` or a custom ``Event`` such as "TOO_HOT".
-
-<!---
-TODO check classes above; is this much detail needed here?
--->
-
-Sensor values form a map-of-maps. An example of some simple sensor information is shown below in JSON:
-
- {
- config : {
- url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql"
- status : "running"
- }
- workrate : {
- msgsPerSec : 432
- }
- }
-
-Sensor values are defined as statics, which can be used to programmatically drive the subscription.
-
-A range of `Feed` instances are available to simplify reading sensor information.
-
-
-### Effectors
-
-Like sensors and config info, effectors are also static fields on the Entity class. These describe actions available on the entity, similar to methods. Their implementation includes details of how to invoke them, typically this is done by calling a method on the entity. Effectors are typically defined as follows:
-
-{% highlight java %}
-/** an effector which returns no value,
- but which causes the entity to emit a HELLO sensor event */
-public static Effector<Void> SAY_HI = ...
-
-{% endhighlight %}
-
-Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may take an entity if context is not clear, and it takes parameters as named parameters or a Map.
-
-Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that ``task.get()`` is a blocking function that will wait until a value is available before returning.
-
-The management framework ensures that execution occurs on the machine where the ``Entity`` is mastered, with progress, result, and/or any errors reported back to the caller. It does this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances. The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these can be tracked externally (and relocated if the Entity is remastered to a different location).
-
-It is worth noting that where a method corresponds to an effector, direct invocation of that method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely.
-
-
-### Tasks and the Execution Manager
-
-The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating these with given **tags**.
-Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard ``Executor``, although it also supports ``Callable`` arguments including Groovy closures, and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts a few other named parameters, including ``description``, which allow additional metadata to be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks, which can be inspected through methods on the ``Task`` interface.
-
-By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a ``Task`` that is submitted), execution can be associated with various categories. This allows easy viewing can be examined by calling
-``ExecutionManager.getTasksWithTag(...)``.
-
-The following example uses Groovy, with time delays abused for readability. brooklyn's test cases check this using mutexes, which is recommended.
-
- ExecutionManager em = []
- em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) })
- em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) })
- assert em.getTasksWithTag("a").size()==2
- assert em.getTasksWithTag("a").every { Task t -> !t.isDone() }
- Thread.sleep(1500)
- assert em.getTasksWithTag("a").size()==2
- assert em.getTasksWithTag("a").every { Task t -> t.isDone() }
-
-It is possible to define `ParallelTask` and sequential `Task` instancess
-and to specify inter-task relationships with `TaskPreprocessor` instances.
-This allows building quite sophisticated workflows relatively easily.
-
-Continuing the example above, submitting a `SequentialTask`
-or specifying ``em.setTaskPreprocessorForTag("a", SingleThreadedExecution.class)``
-will cause ``Two Mississippi`` to run after ``One Mississippi`` completes.
-
-It is also possible to register `ScheduledTask` instances which run periodically.
-
-**The `Tasks` factory supplies a number of conveniences including builders to make working with tasks easier
-and should be the entry point in most cases.**
-
-
-
-### Subscriptions and the Subscription Manager
-
-In addition to scheduled tasks, tasks can triggered by subscriptions on other events including sensors.
-
-To register low-level listeners to events, use the `SubscriptionManager` API.
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/java/defining-and-deploying.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/java/defining-and-deploying.md b/brooklyn-docs/guide/java/defining-and-deploying.md
deleted file mode 100644
index 8f56000..0000000
--- a/brooklyn-docs/guide/java/defining-and-deploying.md
+++ /dev/null
@@ -1,125 +0,0 @@
----
-title: Defining and Deploying
-layout: website-normal
----
-
-## Intro
-
-This walkthrough will set up a sample application which you can use as foundation for creating your own applications.
-
-The sample application is a three tier web service, composed of:
-
-* an Nginx load-balancer
-* a cluster of JBoss appservers
-* a MySQL database
-
-## Define your Application Blueprint
-
-An application blueprint is defined as a Java class, as follows:
-
-{% highlight java %}
-public class ClusterWebServerDatabaseSample extends AbstractApplication {
- @Override
- public void init() {
- MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class));
- ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class));
- }
-}
-{% endhighlight %}
-
-The file `ClusterWebServerDatabaseSample.java` in `src/main/java/com/acme/sample/brooklyn/sample/app/`
-provides a template to follow.
-
-
-## Deploying the Application
-
-If you have not already done so, follow the instructions
-[here]({{site.path.guide}}/ops/locations/) to create a `brooklyn.properties`
-file containing credentials for your preferred cloud provider.
-
-To launch this application, build the project and run the `start.sh` script in the resulting assembly:
-
-{% highlight bash %}
-$ mvn clean assembly:assembly
-
-$ cd target/brooklyn-sample-0.1.0-SNAPSHOT-dist/brooklyn-sample-0.1.0-SNAPSHOT/
-
-$ ./start.sh launch \
- --app com.acme.sample.brooklyn.sample.app.ClusterWebServerDatabaseSample \
- --location jclouds:aws-ec2:eu-west-1
-{% endhighlight %}
-
-(Amazon is used in this walkthrough, but lots of targets are supported,
-including `--location localhost`, fixed IP addresses, and
-everything supported by [jclouds](http://jclouds.org), from OpenStack to Google Compute.)
-
-Your console will inform you that it has started a Brooklyn console at [http://localhost:8081](http://localhost:8081)
-
-[](wt-starting.png)
-
-The management console provides a view on to the entities that launched,
-including the hierarchy (appservers grouped into a cluster) and their locations.
-
-Brooklyn collects information from these entities ("sensors"),
-aggregates these for clusters and other groups (using "enrichers"),
-and exposes operations ("effectors") that can be performed on entities.
-
-[](wt-tree-jboss-sensors.png)
-
-## What Next?
-
-In addition to the sample project created by the archetype, with its README and
-`assembly` build, you can find additional code related to this example included with Brooklyn as the ``simple-web-cluster`` example.
-{% comment %}
-described [in detail here]({{site.path.guide}}/use/examples/webcluster).
-{% endcomment %}
-
-For your applications, you might want to mix in other data stores, messaging systems, or on-line services including PaaS.
-Brooklyn supports some of these out-of-the-box, including a wide-range of tools which it can use Whirr to provision, such as Hadoop.
-But if you have something you don't see,
-[let us know]({{site.path.website}}/community/) --
-we want to work with you to
-[write a new entity]({{site.path.guide}}/java/entity.html) or
-[policy]({{site.path.guide}}/java/policy.html)
-and [contribute it]({{site.path.website}}/developers/how-to-contribute.html).
-
-
-<!--
-
-Alternatively you can just add a ``main`` method to the application class as follows:
-
-{% highlight java %}
- public static void main(String[] argv) {
- List<String> args = Lists.newArrayList(argv);
- String port = CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
- String location = CommandLineUtil.getCommandLineOption(args, "--location", DEFAULT_LOCATION);
-
- BrooklynServerDetails server = BrooklynLauncher.newLauncher()
- .webconsolePort(port)
- .launch();
-
- Location loc = server.getManagementContext().getLocationRegistry().resolve(location);
-
- StartableApplication app = new WebClusterDatabaseExample()
- .appDisplayName("Brooklyn WebApp Cluster with Database example")
- .manage(server.getManagementContext());
-
- app.start(ImmutableList.of(loc));
-
- Entities.dumpInfo(app);
- }
-{% endhighlight %}
-
-Compile and run this with the [``brooklyn-all`` jar]({{site.path.guide}}/start/download.html) on the classpath,
-pointing at your favourite WAR on your filesystem.
-(If the ``import`` packages aren't picked up correctly,
-you can cheat by looking at [the file in Github](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/src/main/java/brooklyn/demo/WebClusterDatabaseExample.java);
-and you'll find a sample WAR which uses the database as configured above
-[here](https://http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/io/brooklyn/).)
- TODO example webapp url
-
-If you want to adventure beyond ``localhost`` (the default),
-simply supply the your favourite cloud (e.g. ``aws-ec2:eu-west-1``)
-with credentials set up as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config).
-
--->
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/guide/java/entities.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/guide/java/entities.md b/brooklyn-docs/guide/java/entities.md
deleted file mode 100644
index b83bfc9..0000000
--- a/brooklyn-docs/guide/java/entities.md
+++ /dev/null
@@ -1,223 +0,0 @@
----
-title: Custom Entity Development
-layout: website-normal
----
-
-This section details how to create new custom application components or groups as brooklyn entities.
-
-The Entity Lifecycle
---------------------
-
-- Importance of serialization, ref to How mananagement works
-- Parents and Membership (groups)
-
-What to Extend -- Implementation Classes
-----------------------------------------
-
-- entity implementation class hierarchy
-
- - `SoftwareProcess` as the main starting point for base entities (corresponding to software processes),
- and subclasses such as `VanillaJavaApp`
- - `DynamicCluster` (multiple instances of the same entity in a location) and
- `DynamicFabric` (clusters in multiple location) for automatically creating many instances,
- supplied with an `EntityFactory` (e.g. `BaseEntityFactory`) in the `factory` flag
- - `AbstractGroup` for collecting entities which are parented elsewhere in the hierachy
- - `AbstractEntity` if nothing else fits
-
-- traits (mixins, otherwise known as interfaces with statics) to define available config keys, sensors, and effectors;
- and conveniences e.g. ``StartableMethods.{start,stop}`` is useful for entities which implement ``Startable``
-
-- the ``Entities`` class provides some generic convenience methods; worth looking at it for any work you do
-
-A common lifecycle pattern is that the ``start`` effector (see more on effectors below) is invoked,
-often delegating either to a driver (for software processes) or children entities (for clusters etc).
-
-
-Configuration
--------------
-<!---
-TODO: why to use config?
--->
-
-- AttributeSensorAndConfigKey fields can be automatically converted for ``SoftwareProcess``.
- This is done in ``preStart()``. This must be done manually if required for other entities,
- often with ``ConfigToAttributes.apply(this)``.
-
-- Setting ports is a special challenge, and one which the ``AttributeSensorAndConfigKey`` is particularly helpful for,
- cf ``PortAttributeSensorAndConfigKey`` (a subclass),
- causing ports automatically get assigned from a range and compared with the target ``PortSupplied`` location.
-
- Syntax is as described in the PortRange interface. For example, "8080-8099,8800+" will try port 8080, try sequentially through 8099, then try from 8800 until all ports are exhausted.
-
- This is particularly useful on a contended machine (localhost!). Like ordinary configuration, the config is done by the user, and the actual port used is reported back as a sensor on the entity.
-
-- Validation of config values can be applied by supplying a ``Predicate`` to the ``constraint`` of a ConfigKey builder.
- Constraints are tested after an entity is initialised and before an entity managed.
- Useful predicates include:
- - ``StringPredicates.isNonBlank``: require that a String key is neither null nor empty.
- - ``ResourcePredicates.urlExists``: require that a URL that is loadable by Brooklyn. Use this to
- confirm that necessary resources are available to the entity.
- - ``Predicates.in``: require one of a fixed set of values.
- - ``Predicates.containsPattern``: require that a value match a regular expression pattern.
-
- An important caveat is that only constraints on config keys that are on an entity's type hierarchy can be
- tested automatically. Brooklyn has no knowledge of the true type of other keys until they are retrieved with a
- ``config().get(key)``.
-
-
-Implementing Sensors
---------------------
-
-- e.g. HTTP, JMX
-
-Sensors at base entities are often retrieved by feeds which poll the entity's corresponding instance in the real world.
-The ``SoftwareProcess`` provides a good example; by subclassing it and overriding the ``connectSensors()`` method
-you could wire some example sensors using the following:
-
-{% highlight java %}
-public void connectSensors() {
- super.connectSensors()
-
- httpFeed = HttpFeed.builder()
- .entity(this)
- .period(200)
- .baseUri(mgmtUrl)
- .poll(new HttpPollConfig<Boolean>(SERVICE_UP)
- .onSuccess(HttpValueFunctions.responseCodeEquals(200))
- .onError(Functions.constant(false)))
- .poll(new HttpPollConfig<Integer>(REQUEST_COUNT)
- .onSuccess(HttpValueFunctions.jsonContents("requestCount", Integer.class)))
- .build();
-}
-
-@Override
-protected void disconnectSensors() {
- super.disconnectSensors();
- if (httpFeed != null) httpFeed.stop();
-}
-{% endhighlight %}
-
-In this example (a simplified version of ``JBoss7Server``), the url returns metrics in JSON.
-We report the entity as up if we get back an http response code of 200, or down if any other response code or exception.
-We retrieve the request count from the response body, and convert it to an integer.
-
-Note the first line (``super.connectSensors()``); as one descends into specific convenience subclasses (such as for Java web-apps), the work done by the parent class's overridden methods may be relevant, and will want to be invoked or even added to a resulting list.
-
-For some sensors, and often at compound entities, the values are obtained by monitoring values of other sensors on the same (in the case of a rolling average) or different (in the case of the average of children nodes) entities. This is achieved by policies, described below.
-
-Implementing Effectors
-----------------------
-
-The ``Entity`` interface defines the sensors and effectors available. The entity class provides
-wiring for the sensors, and the effector implementations. In simple cases it may be straightforward
-to capture the behaviour of the effectors in a simple methods.
-For example deploying a WAR to a cluster can be done as follows:
-
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-<!---
-TODO show an effector which recurses across children
--->
-
-For some entities, specifically base entities, the implementation of effectors might need other tools (such as SSH), and may vary by location, so having a single implementation is not appropriate.
-
-The problem of multiple inheritance (e.g. SSH functionality and entity inheritance) and multiple implementations (e.g. SSH versus Windows) is handled in brooklyn using delegates called _drivers_.
-
-In the implementations of ``JavaWebApp`` entities, the behaviour which the entity always does is captured in the entity class (for example, breaking deployment of multiple WARs into atomic actions), whereas implementations which is specific to a particular entity and driver (e.g. using scp to copy the WARs to the right place and install them, which of course is different among appservers, or using an HTTP or JMX management API, again where details vary between appservers) is captured in a driver class.
-
-Routines which are convenient for specific drivers can then be inherited in the driver class hierarchy. For example, when passing JMX environment variables to Java over SSH, ``JavaSoftwareProcessSshDriver`` extends ``AbstractSoftwareProcessSshDriver`` and parents ``JBoss7SshDriver``.
-
-<!---
-TODO more drivers such as jmx, etc are planned
--->
-
-Testing
--------
-
-* Unit tests can make use of `SimulatedLocation` and `TestEntity`, and can extend `BrooklynAppUnitTestSupport`.
-* Integration tests and use a `LocalhostMachineProvisioningLocation`, and can also extend `BrooklynAppUnitTestSupport`.
-
-
-<a name="SoftwareProcess-lifecycle"></a>
-
-SoftwareProcess Lifecycle
--------------------------
-
-`SoftwareProcess` is the common super-type of most integration components (when implementing in Java).
-
-See ``JBoss7Server`` and ``MySqlNode`` for exemplars.
-
-The methods called in a `SoftwareProcess` entity's lifecycle are described below. The most important steps are shown in bold (when writing a new entity, these are the methods most often implemented).
-
-* Initial creation (via `EntitySpec` or YAML):
- * **no-arg constructor**
- * **init**
- * add locations
- * apply initializers
- * add enrichers
- * add policies
- * add children
- * manages entity (so is discoverable by other entities)
-
-* Start:
- * provisions new machine, if the location is a `MachineProvisioningLocation`
- * creates new driver
- * **calls `getDriverInterface`**
- * Infers the concrete driver class from the machine-type,
- e.g. by default it adds "Ssh" before the word "Driver" in "JBoss7Driver".
- * instantiates the driver, **calling the constructor** to pass in the entity itself and the machine location
- * sets attributes from config (e.g. for ports being used)
- * calls `entity.preStart()`
- * calls `driver.start()`, which:
- * runs pre-install command (see config key `pre.install.command`)
- * uploads install resources (see config keys `files.install` and `templates.install`)
- * **calls `driver.install()`**
- * runs post-install command (see config key `post.install.command`)
- * **calls `driver.customize()`**
- * uploads runtime resources (see config keys `files.runtime` and `templates.runtime`)
- * runs pre-launch command (see config key `pre.launch.command`)
- * **calls `driver.launch()`**
- * runs post-launch command (see config key `post.launch.command`)
- * calls `driver.postLaunch()`
- * calls `entity.postDriverStart()`, which:
- * calls `enity.waitForEntityStart()` - **waits for `driver.isRunning()` to report true**
- * **calls `entity.connectSensors()`**
- * calls `entity.waitForServicUp()`
- * calls `entity.postStart()`
-
-* Restart:
- * If restarting machine...
- * calls `entity.stop()`, with `stopMachine` set to true.
- * calls start
- * restarts children (if configured to do so)
- * Else (i.e. not restarting machine)...
- * calls `entity.preRestart()`
- * calls `driver.restart()`
- * **calls `driver.stop()`**
- * **calls `driver.launch()`**
- * calls `driver.postLaunch()`
- * restarts children (if configured to do so)
- * calls `entity.postDriverStart()`, which:
- * calls `enity.waitForEntityStart()` - **polls `driver.isRunning()`**, waiting for true
- * calls `entity.waitForServicUp()`
- * calls `entity.postStart()`
-
-* Stop:
- * calls `entity.preStopConfirmCustom()` - aborts if exception.
- * calls `entity.preStop()`
- * stops the process:
- * stops children (if configured to do so)
- * **calls `driver.stop()`**
- * stops the machine (if configured to do so)
- * calls `entity.postStop()`
-
-* Rebind (i.e. when Brooklyn is restarted):
- * **no-arg constructor**
- * reconstitutes entity (e.g. setting config and attributes)
- * If entity was running...
- * calls `entity.rebind()`; if previously started then:
- * creates the driver (same steps as for start)
- * calls `driver.rebind()`
- * **calls `entity.connectSensors()`**
- * attaches policies, enrichers and persisted feeds
- * manages the entity (so is discoverable by other entities)