Return-Path: X-Original-To: apmail-brooklyn-commits-archive@minotaur.apache.org Delivered-To: apmail-brooklyn-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id EFD04C986 for ; Wed, 17 Dec 2014 17:25:15 +0000 (UTC) Received: (qmail 54991 invoked by uid 500); 17 Dec 2014 17:25:14 -0000 Delivered-To: apmail-brooklyn-commits-archive@brooklyn.apache.org Received: (qmail 54911 invoked by uid 500); 17 Dec 2014 17:25:14 -0000 Mailing-List: contact commits-help@brooklyn.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@brooklyn.incubator.apache.org Delivered-To: mailing list commits@brooklyn.incubator.apache.org Received: (qmail 54769 invoked by uid 99); 17 Dec 2014 17:25:14 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 17 Dec 2014 17:25:14 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,T_RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Wed, 17 Dec 2014 17:23:38 +0000 Received: (qmail 47420 invoked by uid 99); 17 Dec 2014 17:23:36 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 17 Dec 2014 17:23:36 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id B689A82F429; Wed, 17 Dec 2014 17:23:35 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: heneveld@apache.org To: commits@brooklyn.incubator.apache.org Date: Wed, 17 Dec 2014 17:23:45 -0000 Message-Id: <1c3de33403244e7d9d90c4b2652a10e3@git.apache.org> In-Reply-To: <3b889e77b7b8430eb1a3930a4f65b0f9@git.apache.org> References: <3b889e77b7b8430eb1a3930a4f65b0f9@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [11/50] [abbrv] incubator-brooklyn git commit: move version-specific things to "guide" X-Virus-Checked: Checked by ClamAV on apache.org move version-specific things to "guide" "guide" is where versioned content will live when primary website is moved in (to "website" dir); note this does not yet build; update fixing that to follow Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/ba6612ec Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/ba6612ec Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/ba6612ec Branch: refs/heads/master Commit: ba6612ecdb0427a5350c5a62f56c23b019f3a590 Parents: a78cd74 Author: Alex Heneveld Authored: Mon Dec 15 16:54:07 2014 +0000 Committer: Alex Heneveld Committed: Wed Dec 17 02:02:54 2014 +0000 ---------------------------------------------------------------------- docs/dev/build/debugging-remote-brooklyn.md | 140 ------- docs/dev/build/developers-catalog.xml | 87 ---- docs/dev/build/eclipse.include.md | 15 - docs/dev/build/ide.md | 123 ------ docs/dev/build/index.md | 184 -------- docs/dev/build/tests.md | 26 -- docs/dev/build/toc.json | 8 - docs/dev/code/entity.md | 91 ---- docs/dev/code/index.include.md | 99 ----- docs/dev/code/index.md | 7 - docs/dev/code/policy.md | 47 --- docs/dev/code/toc.json | 10 - docs/dev/how-to-contrib.md | 38 -- docs/dev/index.md | 7 - docs/dev/links.md | 18 - docs/dev/tips/index.md | 50 --- docs/dev/tips/local-artifact-repo.md | 32 -- docs/dev/tips/logging.md | 144 ------- docs/dev/tips/release.md | 286 ------------- docs/dev/tips/standards.md | 15 - docs/dev/tips/toc.json | 14 - docs/dev/tips/update-docs.md | 70 ---- docs/dev/toc.json | 26 -- .../dev/build/debugging-remote-brooklyn.md | 140 +++++++ docs/guide/dev/build/developers-catalog.xml | 87 ++++ docs/guide/dev/build/eclipse.include.md | 15 + docs/guide/dev/build/ide.md | 123 ++++++ docs/guide/dev/build/index.md | 184 ++++++++ docs/guide/dev/build/tests.md | 26 ++ docs/guide/dev/build/toc.json | 8 + docs/guide/dev/code/entity.md | 91 ++++ docs/guide/dev/code/index.include.md | 99 +++++ docs/guide/dev/code/index.md | 7 + docs/guide/dev/code/policy.md | 47 +++ docs/guide/dev/code/toc.json | 10 + docs/guide/dev/how-to-contrib.md | 38 ++ docs/guide/dev/index.md | 7 + docs/guide/dev/links.md | 18 + docs/guide/dev/tips/index.md | 50 +++ docs/guide/dev/tips/local-artifact-repo.md | 32 ++ docs/guide/dev/tips/logging.md | 144 +++++++ docs/guide/dev/tips/release.md | 286 +++++++++++++ docs/guide/dev/tips/standards.md | 15 + docs/guide/dev/tips/toc.json | 14 + docs/guide/dev/tips/update-docs.md | 70 ++++ docs/guide/dev/toc.json | 26 ++ docs/guide/index.md | 8 + docs/guide/license/index.md | 18 + docs/guide/license/license.md | 194 +++++++++ docs/guide/license/toc.json | 4 + docs/guide/meta/brooklyn-gpg-public-key.asc | 21 + docs/guide/meta/contact.include.md | 9 + docs/guide/meta/contact.md | 7 + docs/guide/meta/irc.md | 31 ++ docs/guide/meta/toc.json | 8 + docs/guide/meta/verify.md | 36 ++ docs/guide/meta/versions.md | 110 +++++ docs/guide/start/docs-summary.include.md | 7 + docs/guide/start/docs-summary.md | 9 + docs/guide/start/download.md | 185 ++++++++ docs/guide/start/index.include.md | 50 +++ docs/guide/start/index.md | 8 + docs/guide/start/known-issues.md | 28 ++ docs/guide/start/release-notes.md | 56 +++ docs/guide/start/toc.json | 10 + docs/guide/start/video.md | 7 + docs/guide/start/walkthrough/index.md | 240 +++++++++++ .../walkthrough/wt-deployed-application-700.png | Bin 0 -> 176494 bytes .../walkthrough/wt-deployed-application.png | Bin 0 -> 127347 bytes .../guide/start/walkthrough/wt-starting-700.png | Bin 0 -> 303892 bytes docs/guide/start/walkthrough/wt-starting.png | Bin 0 -> 332710 bytes .../walkthrough/wt-tree-jboss-sensors-700.png | Bin 0 -> 268853 bytes .../start/walkthrough/wt-tree-jboss-sensors.png | Bin 0 -> 169929 bytes docs/guide/toc-menu.json | 20 + docs/guide/toc.json | 21 + docs/guide/use/api/index.md | 11 + docs/guide/use/contact.md | 7 + docs/guide/use/examples/before-begin.include.md | 57 +++ .../console-geoscaling-details-w700.png | Bin 0 -> 167441 bytes .../console-geoscaling-details.png | Bin 0 -> 176651 bytes .../global-web-fabric/console-map-w700.png | Bin 0 -> 201060 bytes .../examples/global-web-fabric/console-map.png | Bin 0 -> 331520 bytes .../geopaas-deployed-app-w700.png | Bin 0 -> 153738 bytes .../global-web-fabric/geopaas-deployed-app.png | Bin 0 -> 114615 bytes .../use/examples/global-web-fabric/index.md | 378 +++++++++++++++++ docs/guide/use/examples/index.md | 18 + docs/guide/use/examples/messaging/index.md | 183 ++++++++ .../nosql-cassandra/cassandra.include.md | 282 +++++++++++++ .../guide/use/examples/nosql-cassandra/index.md | 7 + docs/guide/use/examples/simple-web-cluster.md | 9 + docs/guide/use/examples/toc.json | 13 + docs/guide/use/examples/webcluster.md | 9 + docs/guide/use/examples/webcluster/index.md | 7 + .../examples/webcluster/webcluster.include.md | 124 ++++++ .../use/guide/defining-applications/Chef.png | Bin 0 -> 36222 bytes .../defining-applications/advanced-concepts.md | 137 ++++++ .../guide/defining-applications/archetype.md | 64 +++ .../defining-applications/basic-concepts.md | 95 +++++ ...ooklyn-flow-websequencediagrams.com-w400.png | Bin 0 -> 58518 bytes .../brooklyn-flow-websequencediagrams.com.png | Bin 0 -> 106928 bytes .../defining-applications/chef-blueprints.md | 277 ++++++++++++ .../guide/defining-applications/common-usage.md | 145 +++++++ .../defining-applications/creating-yaml.md | 417 +++++++++++++++++++ .../defining-applications/deploying-yaml.md | 37 ++ .../example_files/tomcat_multi-location.java | 15 + .../example_files/tomcat_nginx.java | 17 + .../example_files/tomcat_simple.java | 9 + .../appserver-clustered-w-db-concise.yaml | 15 + .../example_yaml/appserver-clustered-w-db.yaml | 18 + .../appserver-configured-in-config.yaml | 6 + .../example_yaml/appserver-configured.yaml | 5 + .../appserver-w-db-other-flavor.yaml | 17 + .../example_yaml/appserver-w-db.yaml | 15 + .../example_yaml/appserver-w-policy.yaml | 26 ++ .../example_yaml/cluster-vm.yaml | 12 + .../example_yaml/mysql-chef-1.yaml | 24 ++ .../example_yaml/mysql-chef-2.yaml | 28 ++ .../simple-appserver-with-location-byon.yaml | 12 + .../simple-appserver-with-location.yaml | 8 + .../example_yaml/simple-appserver.yaml | 4 + .../example_yaml/simple-vm.yaml | 8 + .../example_yaml/vanilla-bash-netcat-file.yaml | 6 + .../vanilla-bash-netcat-restarter.yaml | 20 + .../vanilla-bash-netcat-w-client.yaml | 72 ++++ .../example_yaml/vanilla-bash-netcat.yaml | 18 + .../use/guide/defining-applications/examples.md | 120 ++++++ .../defining-applications/service-state.md | 73 ++++ .../use/guide/defining-applications/toc.json | 19 + .../web-console-yaml-700.png | Bin 0 -> 138229 bytes .../defining-applications/web-console-yaml.png | Bin 0 -> 661136 bytes .../defining-applications/yaml-reference.md | 183 ++++++++ docs/guide/use/guide/entities/index.md | 133 ++++++ docs/guide/use/guide/entities/toc.json | 12 + docs/guide/use/guide/extras/index.md | 160 +++++++ docs/guide/use/guide/extras/toc.json | 11 + docs/guide/use/guide/guide_toc.json | 25 ++ docs/guide/use/guide/index.md | 33 ++ docs/guide/use/guide/locations/index.md | 104 +++++ docs/guide/use/guide/locations/toc.json | 1 + docs/guide/use/guide/management/index.md | 407 ++++++++++++++++++ docs/guide/use/guide/management/toc.json | 18 + .../management/webconsole-dashboard-w400.png | Bin 0 -> 137463 bytes .../guide/management/webconsole-dashboard.png | Bin 0 -> 214723 bytes .../guide/management/webconsole-detail-w400.png | Bin 0 -> 111993 bytes .../use/guide/management/webconsole-detail.png | Bin 0 -> 165359 bytes docs/guide/use/guide/persistence/index.md | 289 +++++++++++++ docs/guide/use/guide/persistence/toc.json | 16 + docs/guide/use/guide/policies/index.md | 129 ++++++ docs/guide/use/guide/policies/toc.json | 8 + .../use/guide/quickstart/brooklyn.properties | 324 ++++++++++++++ docs/guide/use/guide/quickstart/catalog.xml | 23 + ...cation-catalog-web-cluster-with-db-large.png | Bin 0 -> 131618 bytes ...talog-web-cluster-with-db-location-large.png | Bin 0 -> 152721 bytes ...ion-catalog-web-cluster-with-db-location.png | Bin 0 -> 86425 bytes ...-application-catalog-web-cluster-with-db.png | Bin 0 -> 76065 bytes .../images/add-application-modal-yaml.png | Bin 0 -> 68401 bytes .../images/jboss7-cluster-policies-large.png | Bin 0 -> 157883 bytes .../images/jboss7-cluster-policies.png | Bin 0 -> 94056 bytes .../images/my-db-activities-large.png | Bin 0 -> 208313 bytes .../quickstart/images/my-db-activities.png | Bin 0 -> 130262 bytes .../images/my-web-cluster-starting.png | Bin 0 -> 32948 bytes .../my-web-cluster-stop-confirm-large.png | Bin 0 -> 148155 bytes .../images/my-web-cluster-stop-confirm.png | Bin 0 -> 79280 bytes .../quickstart/images/my-web-summary-large.png | Bin 0 -> 178785 bytes .../guide/quickstart/images/my-web-summary.png | Bin 0 -> 80583 bytes .../use/guide/quickstart/images/my-web.png | Bin 0 -> 83081 bytes docs/guide/use/guide/quickstart/index.md | 221 ++++++++++ .../use/guide/quickstart/my-web-cluster.yaml | 19 + .../guide/quickstart/policies-and-catalogs.md | 66 +++ docs/guide/use/guide/quickstart/toc.json | 4 + docs/guide/use/guide/toc.json | 25 ++ docs/guide/use/index.md | 9 + docs/guide/use/toc.json | 12 + docs/index.md | 8 - docs/license/index.md | 18 - docs/license/license.md | 194 --------- docs/license/toc.json | 4 - docs/meta/brooklyn-gpg-public-key.asc | 21 - docs/meta/contact.include.md | 9 - docs/meta/contact.md | 7 - docs/meta/irc.md | 31 -- docs/meta/toc.json | 8 - docs/meta/verify.md | 36 -- docs/meta/versions.md | 110 ----- docs/start/docs-summary.include.md | 7 - docs/start/docs-summary.md | 9 - docs/start/download.md | 185 -------- docs/start/index.include.md | 50 --- docs/start/index.md | 8 - docs/start/known-issues.md | 28 -- docs/start/release-notes.md | 56 --- docs/start/toc.json | 10 - docs/start/video.md | 7 - docs/start/walkthrough/index.md | 240 ----------- .../walkthrough/wt-deployed-application-700.png | Bin 176494 -> 0 bytes .../walkthrough/wt-deployed-application.png | Bin 127347 -> 0 bytes docs/start/walkthrough/wt-starting-700.png | Bin 303892 -> 0 bytes docs/start/walkthrough/wt-starting.png | Bin 332710 -> 0 bytes .../walkthrough/wt-tree-jboss-sensors-700.png | Bin 268853 -> 0 bytes .../start/walkthrough/wt-tree-jboss-sensors.png | Bin 169929 -> 0 bytes docs/toc-menu.json | 20 - docs/toc.json | 21 - docs/use/api/index.md | 11 - docs/use/contact.md | 7 - docs/use/examples/before-begin.include.md | 57 --- .../console-geoscaling-details-w700.png | Bin 167441 -> 0 bytes .../console-geoscaling-details.png | Bin 176651 -> 0 bytes .../global-web-fabric/console-map-w700.png | Bin 201060 -> 0 bytes .../examples/global-web-fabric/console-map.png | Bin 331520 -> 0 bytes .../geopaas-deployed-app-w700.png | Bin 153738 -> 0 bytes .../global-web-fabric/geopaas-deployed-app.png | Bin 114615 -> 0 bytes docs/use/examples/global-web-fabric/index.md | 378 ----------------- docs/use/examples/index.md | 18 - docs/use/examples/messaging/index.md | 183 -------- .../nosql-cassandra/cassandra.include.md | 282 ------------- docs/use/examples/nosql-cassandra/index.md | 7 - docs/use/examples/simple-web-cluster.md | 9 - docs/use/examples/toc.json | 13 - docs/use/examples/webcluster.md | 9 - docs/use/examples/webcluster/index.md | 7 - .../examples/webcluster/webcluster.include.md | 124 ------ docs/use/guide/defining-applications/Chef.png | Bin 36222 -> 0 bytes .../defining-applications/advanced-concepts.md | 137 ------ .../guide/defining-applications/archetype.md | 64 --- .../defining-applications/basic-concepts.md | 95 ----- ...ooklyn-flow-websequencediagrams.com-w400.png | Bin 58518 -> 0 bytes .../brooklyn-flow-websequencediagrams.com.png | Bin 106928 -> 0 bytes .../defining-applications/chef-blueprints.md | 277 ------------ .../guide/defining-applications/common-usage.md | 145 ------- .../defining-applications/creating-yaml.md | 417 ------------------- .../defining-applications/deploying-yaml.md | 37 -- .../example_files/tomcat_multi-location.java | 15 - .../example_files/tomcat_nginx.java | 17 - .../example_files/tomcat_simple.java | 9 - .../appserver-clustered-w-db-concise.yaml | 15 - .../example_yaml/appserver-clustered-w-db.yaml | 18 - .../appserver-configured-in-config.yaml | 6 - .../example_yaml/appserver-configured.yaml | 5 - .../appserver-w-db-other-flavor.yaml | 17 - .../example_yaml/appserver-w-db.yaml | 15 - .../example_yaml/appserver-w-policy.yaml | 26 -- .../example_yaml/cluster-vm.yaml | 12 - .../example_yaml/mysql-chef-1.yaml | 24 -- .../example_yaml/mysql-chef-2.yaml | 28 -- .../simple-appserver-with-location-byon.yaml | 12 - .../simple-appserver-with-location.yaml | 8 - .../example_yaml/simple-appserver.yaml | 4 - .../example_yaml/simple-vm.yaml | 8 - .../example_yaml/vanilla-bash-netcat-file.yaml | 6 - .../vanilla-bash-netcat-restarter.yaml | 20 - .../vanilla-bash-netcat-w-client.yaml | 72 ---- .../example_yaml/vanilla-bash-netcat.yaml | 18 - .../use/guide/defining-applications/examples.md | 120 ------ .../defining-applications/service-state.md | 73 ---- docs/use/guide/defining-applications/toc.json | 19 - .../web-console-yaml-700.png | Bin 138229 -> 0 bytes .../defining-applications/web-console-yaml.png | Bin 661136 -> 0 bytes .../defining-applications/yaml-reference.md | 183 -------- docs/use/guide/entities/index.md | 133 ------ docs/use/guide/entities/toc.json | 12 - docs/use/guide/extras/index.md | 160 ------- docs/use/guide/extras/toc.json | 11 - docs/use/guide/guide_toc.json | 25 -- docs/use/guide/index.md | 33 -- docs/use/guide/locations/index.md | 104 ----- docs/use/guide/locations/toc.json | 1 - docs/use/guide/management/index.md | 407 ------------------ docs/use/guide/management/toc.json | 18 - .../management/webconsole-dashboard-w400.png | Bin 137463 -> 0 bytes .../guide/management/webconsole-dashboard.png | Bin 214723 -> 0 bytes .../guide/management/webconsole-detail-w400.png | Bin 111993 -> 0 bytes docs/use/guide/management/webconsole-detail.png | Bin 165359 -> 0 bytes docs/use/guide/persistence/index.md | 289 ------------- docs/use/guide/persistence/toc.json | 16 - docs/use/guide/policies/index.md | 129 ------ docs/use/guide/policies/toc.json | 8 - docs/use/guide/quickstart/brooklyn.properties | 324 -------------- docs/use/guide/quickstart/catalog.xml | 23 - ...cation-catalog-web-cluster-with-db-large.png | Bin 131618 -> 0 bytes ...talog-web-cluster-with-db-location-large.png | Bin 152721 -> 0 bytes ...ion-catalog-web-cluster-with-db-location.png | Bin 86425 -> 0 bytes ...-application-catalog-web-cluster-with-db.png | Bin 76065 -> 0 bytes .../images/add-application-modal-yaml.png | Bin 68401 -> 0 bytes .../images/jboss7-cluster-policies-large.png | Bin 157883 -> 0 bytes .../images/jboss7-cluster-policies.png | Bin 94056 -> 0 bytes .../images/my-db-activities-large.png | Bin 208313 -> 0 bytes .../quickstart/images/my-db-activities.png | Bin 130262 -> 0 bytes .../images/my-web-cluster-starting.png | Bin 32948 -> 0 bytes .../my-web-cluster-stop-confirm-large.png | Bin 148155 -> 0 bytes .../images/my-web-cluster-stop-confirm.png | Bin 79280 -> 0 bytes .../quickstart/images/my-web-summary-large.png | Bin 178785 -> 0 bytes .../guide/quickstart/images/my-web-summary.png | Bin 80583 -> 0 bytes docs/use/guide/quickstart/images/my-web.png | Bin 83081 -> 0 bytes docs/use/guide/quickstart/index.md | 221 ---------- docs/use/guide/quickstart/my-web-cluster.yaml | 19 - .../guide/quickstart/policies-and-catalogs.md | 66 --- docs/use/guide/quickstart/toc.json | 4 - docs/use/guide/toc.json | 25 -- docs/use/index.md | 9 - docs/use/toc.json | 12 - 300 files changed, 7700 insertions(+), 7700 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/build/debugging-remote-brooklyn.md ---------------------------------------------------------------------- diff --git a/docs/dev/build/debugging-remote-brooklyn.md b/docs/dev/build/debugging-remote-brooklyn.md deleted file mode 100644 index d924804..0000000 --- a/docs/dev/build/debugging-remote-brooklyn.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -layout: guide-normal -title: Brooklyn Remote Debugging -toc: /toc.json ---- - -Usually during development, you will be running Brooklyn from your IDE (see [IDE Setup](ide.html)), 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) - -## 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://:/v1/server/version -``` - -This should return details of the build as a JSON string similar to the following (formatted for clarity): - -```JSON -{ - "version": "0.7.0-SNAPSHOT", - "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224", - "buildBranch": "UNKNOWN" -} -``` - -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: - -``` -git checkout c0fdc15291702281acdebf1b11d431a6385f5224 -mvn clean install -DskipTests -``` - -Whilst building the code isn't strictly necessary, it can help prevent some IDE issues. - -## 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: - -``` -# 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 & -``` - -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. - -## 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: - -``` -# replace this with the address or IP of the remote Brooklyn node -REMOTE_HOST= -# 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 - -``` - -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. - -## 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](ide.html)). - -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](ide.html)). - -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 ``. 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/incubator-brooklyn/blob/ba6612ec/docs/dev/build/developers-catalog.xml ---------------------------------------------------------------------- diff --git a/docs/dev/build/developers-catalog.xml b/docs/dev/build/developers-catalog.xml deleted file mode 100644 index f190024..0000000 --- a/docs/dev/build/developers-catalog.xml +++ /dev/null @@ -1,87 +0,0 @@ - - - Brooklyn Developers Catalog - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-SNAPSHOT/brooklyn-example-simple-web-cluster-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-SNAPSHOT/brooklyn-example-global-web-fabric-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-SNAPSHOT/brooklyn-example-global-web-fabric-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-portable-cloudfoundry/0.7.0-SNAPSHOT/brooklyn-example-portable-cloudfoundry-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-SNAPSHOT/brooklyn-example-simple-web-cluster-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.7.0-SNAPSHOT/brooklyn-example-hello-world-sql-webapp-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-messaging-pubsub/0.7.0-SNAPSHOT/brooklyn-example-simple-messaging-pubsub-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-parent/0.7.0-SNAPSHOT/brooklyn-examples-parent-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-webapp/0.7.0-SNAPSHOT/brooklyn-example-hello-world-webapp-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-nosql-cluster/0.7.0-SNAPSHOT/brooklyn-example-simple-nosql-cluster-0.7.0-SNAPSHOT.jar - file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-webapps-parent/0.7.0-SNAPSHOT/brooklyn-examples-webapps-parent-0.7.0-SNAPSHOT.jar - - - - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/build/eclipse.include.md ---------------------------------------------------------------------- diff --git a/docs/dev/build/eclipse.include.md b/docs/dev/build/eclipse.include.md deleted file mode 100644 index b1cf5ea..0000000 --- a/docs/dev/build/eclipse.include.md +++ /dev/null @@ -1,15 +0,0 @@ - -- Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases), or for kepler [http://download.eclipse.org/releases/kepler](http://download.eclipse.org/releases/kepler) - (typically bundled with Eclipse or available in the default update site set) - -- Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates) - (typically bundled with Eclipse or available in the default update site set) - -- Groovy Plugin: GRECLIPSE from - [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3) - (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2) - or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)). - Be sure to include Groovy 2.3.4 compiler support and Maven-Eclipse (m2e) support. - More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin). - -- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/build/ide.md ---------------------------------------------------------------------- diff --git a/docs/dev/build/ide.md b/docs/dev/build/ide.md deleted file mode 100644 index bdc7478..0000000 --- a/docs/dev/build/ide.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -layout: guide-normal -title: IDE Setup -toc: /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 - -If you're an Eclipse user, you'll probably want the Maven (m2e) plugin -and the Groovy Eclipse plugin (used for testing and examples primarily). -You may also want Git and TestNG plugins. -You can install these using Help -> Install New Software, or from the Eclipse Marketplace: - -{% readj eclipse.include.md %} - -As of this writing, Eclipse 4.2 and Eclipse 4.3 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. - -If you encounter issues, the following hints may be helpful: - -* If you attempt to import projects before the plugins are installed, you may encounter errors such as - '``No marketplace entries found to handle maven-compiler-plugin:2.3.2:compile in Eclipse``', - and the projects will not be recognized as java projects. If you do, simply cancel the import - (or delete the imported projects if they have been imported) and install the plugins as described above. - If you have installed plugins from alternative locations, remove them and re-install them from the locations - specified above. - -* 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 %} - -* 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). - -* 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 %} - -* You may need to add the groovy nature (or even java nature) to projects; - with some maven-eclipse plugins this works fine, - but for others (older ones) you may need to handcraft these - (either right-click the project in the Package Explorer and choose Configure, - or edit the ``.project`` manually adding it to the project properties). - The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful. - -If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.url}}/meta/contact.html) 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. - -There have previously been issues where the java 6 compiler incorrectly identified the return type of functions that use -generics. These issues have been refactored away, however may return in future. If so, you can either set the java compiler -level to 1.7, or setup IntelliJ to use the Eclipse compiler as per the instructions provided by JetBeans: - -> The problem seems to be caused by bug in java compiler from JDK 1.6, it is known to sometimes produce compilation -> errors for complicated code involving generic types. Java compiler from JDK 1.7 compiles your code successfully so I would -> recommend you to consider upgrading to JDK 1.7. If it isn't possible you can switch to Eclipse Compiler (Settings | -> Compiler | Java Compiler | "Use Compiler" combobox). - - -## 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/incubator-brooklyn/blob/ba6612ec/docs/dev/build/index.md ---------------------------------------------------------------------- diff --git a/docs/dev/build/index.md b/docs/dev/build/index.md deleted file mode 100644 index 7dd3412..0000000 --- a/docs/dev/build/index.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -layout: guide-normal -title: Maven Build -toc: /toc.json ---- - -## The Basics - -To build the code, you need Maven (v3) installed and Java (1.6). -With that in place, you should be able to build everything with a: - -{% highlight bash %} -brooklyn% 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](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.html)** - (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}`` - -* The **developers catalog** ([developers-catalog.xml](developers-catalog.xml)) uses artifacts from your local `~/.m2/repository/...` (after building from source). This avoids unnecessary web requests to Maven Central or Sonatype, and will allow you to work off-line. - - ``wget {{site.url}}/dev/build/developers-catalog.xml > ~/.brooklyn/catalog.xml`` - -## 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 %} -brooklyn% 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 /Users/aled/.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 -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. -[INFO] Copying files to /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist -[WARNING] Assembly file: /Users/aled/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 -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory. -[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-SNAPSHOT-dist.tar.gz -[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.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/incubator-brooklyn/blob/ba6612ec/docs/dev/build/tests.md ---------------------------------------------------------------------- diff --git a/docs/dev/build/tests.md b/docs/dev/build/tests.md deleted file mode 100644 index 16f6810..0000000 --- a/docs/dev/build/tests.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -layout: guide-normal -title: Tests -toc: /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` -* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true` -* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true` - - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/build/toc.json ---------------------------------------------------------------------- diff --git a/docs/dev/build/toc.json b/docs/dev/build/toc.json deleted file mode 100644 index fca9b70..0000000 --- a/docs/dev/build/toc.json +++ /dev/null @@ -1,8 +0,0 @@ -[ -{ "title": "Maven", - "file": "{{ site.url }}/dev/build/index.html" }, -{ "title": "IDE", - "file": "{{ site.url }}/dev/build/ide.html" }, -{ "title": "Tests", - "file": "{{ site.url }}/dev/build/tests.html" } -] http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/code/entity.md ---------------------------------------------------------------------- diff --git a/docs/dev/code/entity.md b/docs/dev/code/entity.md deleted file mode 100644 index 7001612..0000000 --- a/docs/dev/code/entity.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -layout: guide-normal -title: Writing an Entity -toc: /toc.json ---- - -## Ways to write an entity - -There are several ways to write a new entity: - -* Write pure-java, extending existing base-classes and using utilities such as `HttpTool` and `BashCommands`. -* Write scripts, and configure (e.g. using YAML) a **`VanillaSoftwareProcess`**. -* Use Chef recipes, and wire these into the entity by using `ChefConfig` and `ChefLifecycleEffectorTasks`. -* Use an equivalent of Chef (e.g. Salt or Puppet; support for these is currently less mature than for Chef) - -The rest of this section covers writing an entity in pure-java (or other JVM languages). - - -## Things To Know - -All entities have an interface and an implementation. The methods on the interface -are its effectors; the interface also defines its sensors. - -Entities are created through the management context (rather than calling the -constructor directly). This returns a proxy for the entity rather than the real -instance, which is important in a distributed management plane. - -All entity implementations inherit from `AbstractEntity`, -often through one of the following: - -* **`SoftwareProcessImpl`**: if it's a software process -* **`VanillaJavaAppImpl`**: if it's a plain-old-java app -* **`JavaWebAppSoftwareProcessImpl`**: if it's a JVM-based web-app -* **`DynamicClusterImpl`**, **`DynamicGroupImpl`** or **`AbstractGroupImpl`**: if it's a collection of other entities - -Software-based processes tend to use *drivers* to install and -launch the remote processes onto *locations* which support that driver type. -For example, `AbstractSoftwareProcessSshDriver` is a common driver superclass, -targetting `SshMachineLocation` (a machine to which Brooklyn can ssh). -The various `SoftwareProcess` entities above (and some of the exemplars -listed at the end of this page) have their own dedicated drivers. - -Finally, there are a collection of *traits*, such as `Resizable`, -in the package ``brooklyn.entity.trait``. These provide common -sensors and effectors on entities, supplied as interfaces. -Choose one (or more) as appropriate. - - - -## Key Steps - -So to get started: - -1. Create your entity interface, extending the appropriate selection from above, - to define the effectors and sensors. -2. Include an annotation like `@ImplementedBy(YourEntityImpl.class)` on your interface, - where `YourEntityImpl` will be the class name for your entity implementation. -3. Create your entity class, implementing your entity interface and extending the - classes for your chosen entity super-types. Naming convention is a suffix "Impl" - for the entity class, but this is not essential. -4. Create a driver interface, again extending as appropriate (e.g. `SoftwareProcessDriver`). - The naming convention is to have a suffix "Driver". -5. Create the driver class, implementing your driver interface, and again extending as appropriate. - Naming convention is to have a suffix "SshDriver" for an ssh-based implementation. - The correct driver implementation is found using this naming convention, or via custom - namings provided by the `BasicEntityDriverFactory`. -6. Wire the `public Class getDriverInterface()` method in the entity implementation, to specify - your driver interface. -7. Provide the implementation of missing lifecycle methods in your driver class (details below) -8. Connect the sensors from your entity (e.g. overriding `connectSensors()` of `SoftwareProcessImpl`).. - See the sensor feeds, such as `HttpFeed` and `JmxFeed`. - -Any JVM language can be used to write an entity. However use of pure Java is encouraged for -entities in core brooklyn. - - -## Helpful References - -A few handy pointers will help make it easy to build your own entities. -Check out some of the exemplar existing entities -(note, some of the other entities use deprecated utilities and a deprecated class -hierarchy; it is suggested to avoid these, looking at the ones below instead): - -* `JBoss7Server` -* `MySqlNode` - -You might also find the following helpful: - -* **[Entity Design Tips]({{site.url}}/dev/tips/index.html#EntityDesign)** -* The **[User Guide]({{site.url}}/use/guide/index.html)** -* The **[Mailing List](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)** http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/code/index.include.md ---------------------------------------------------------------------- diff --git a/docs/dev/code/index.include.md b/docs/dev/code/index.include.md deleted file mode 100644 index a213cd6..0000000 --- a/docs/dev/code/index.include.md +++ /dev/null @@ -1,99 +0,0 @@ -## The Basics - -Brooklyn is available at [GitHub brooklyncentral/brooklyn](http://github.com/brooklyncentral/brooklyn). Check it out using: - -{% highlight bash %} -git clone git@github.com:brooklyncentral/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 %} - -Plenty of examples are in the **examples** sub-dir, -described [here]({{site.url}}/use/examples), -and pushed to the [brooklyn-examples](http://github.com/brooklyncentral/brooklyn-examples) -GitHub project when a version is released. - -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.url}}/use/guide/quickstart/index.html). -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 the CAMP REST API and which 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 which lower level utilities - * **common**: Utility classes and methods developed for Brooklyn but not dependendent on Brooklyn - * **groovy**: Groovy extensions and utility classes and methods developed for Brooklyn but not dependendent 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 dependendent on Brooklyn - * **test-support**: Test utility classes and methods developed for Brooklyn but not dependendent 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 a 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, as described [here]({{site.url}}/dev/tips/update-docs.html) -* **``examples``**: some canonical examples, as listed [here]({{site.url}}/use/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](../build/index.html) -* [IDE setup](../build/ide.html) -* [Tests](../build/tests.html) -* [Tips](../tips/index.html) -* [Remote Debugging](../build/debugging-remote-brooklyn.html) - -If you want to start writing your own policies and entities, have a look at: - -* [Writing a Brooklyn Entity](entity.html) -* [Writing a Brooklyn Policy](policy.html) -* Or see the [User Guide]({{ site.url }}/use/guide/index.html) - on [policies]({{ site.url }}/use/guide/policies/index.html) - and [entities]({{ site.url }}/use/guide/entities/index.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/incubator-brooklyn/blob/ba6612ec/docs/dev/code/index.md ---------------------------------------------------------------------- diff --git a/docs/dev/code/index.md b/docs/dev/code/index.md deleted file mode 100644 index ecf9fcf..0000000 --- a/docs/dev/code/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: guide-normal -title: Code Structure -toc: /toc.json ---- - -{% readj index.include.md %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/code/policy.md ---------------------------------------------------------------------- diff --git a/docs/dev/code/policy.md b/docs/dev/code/policy.md deleted file mode 100644 index 7bbbcad..0000000 --- a/docs/dev/code/policy.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: guide-normal -title: Writing a Policy -toc: /toc.json ---- - -Policies perform the active management enabled by Brooklyn. -Each policy instance is associated with an entity, -and at runtime it will typically subscribe to sensors on that entity or children, -performing some computation and optionally actions when a subscribed sensor event occurs. -This action might be invoking an effector or emitting a new sensor, -depending the desired behvaiour is. - -Writing a policy is straightforward. -Simply extend ``AbstractPolicy``, -overriding the ``setEntity`` method to supply any subscriptions desired: - -{% highlight java %} - @Override - public void setEntity(EntityLocal entity) { - super.setEntity(entity) - subscribe(entity, TARGET_SENSOR, this) - } -{% endhighlight %} - -and supply the computation and/or activity desired whenever that event occurs: - -{% highlight java %} - @Override - public void onEvent(SensorEvent event) { - int val = event.getValue() - if (val % 2 == 1) - entity.sayYoureOdd(); - } -{% endhighlight %} - -You'll want to do more complicated things, no doubt, -like access other entities, perform multiple subscriptions, -and emit other sensors -- and you can. -See the source code, and see some commonly used policies -in ``AutoScalerPolicy`` and ``RollingMeanEnricher``. - -One rule of thumb, to close on: -try to keep policies simple, and compose them together at runtime; -for instance, if a complex computation triggers an action, -define one **enricher** policy to aggregate other sensors and emit a new sensor, -then write a second policy to perform that action. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/code/toc.json ---------------------------------------------------------------------- diff --git a/docs/dev/code/toc.json b/docs/dev/code/toc.json deleted file mode 100644 index d599dbe..0000000 --- a/docs/dev/code/toc.json +++ /dev/null @@ -1,10 +0,0 @@ -[ -{ "title": "Structure", - "file": "{{ site.url }}/dev/code/index.html" }, -{ "title": "Writing an Entity", - "file": "{{ site.url }}/dev/code/entity.html" }, -{ "title": "Writing a Policy", - "file": "{{ site.url }}/dev/code/policy.html" }, -{ "title": "brooklyn.git (github)", - "file": "http://github.com/brooklyncentral/brooklyn" } -] http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/how-to-contrib.md ---------------------------------------------------------------------- diff --git a/docs/dev/how-to-contrib.md b/docs/dev/how-to-contrib.md deleted file mode 100644 index b5a8306..0000000 --- a/docs/dev/how-to-contrib.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: guide-normal -title: How to Contribute -toc: /toc.json ---- - -### The Process - -If you've built something which you think others could use, or are interested in doing so -- -whether a new supported entity, or a policy, or an example -- -it's easy to give back to the community. Just: - -1. **Tell [the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)** about your work or interest - -1. **Create your fork** of the project on GitHub - -1. **Clone it** to your local machine and do your work on it - -1. **Push it**, and tell everyone about it - -1. **Sign the relevant Apache contributor agreement(s)** - -1. **Issue a pull request** from your GitHub repo - -The same process holds for contributing to this documentation (web site and user guide), -but see the additional [tips for updating documentation]({{ site.url }}/dev/tips/update-docs.html). - - -### Some Words of Advice - -* Do early-stage work in the ``/sandbox``, which means we can pulled it in to ``master`` more often -- - keeping branches short-lived and making it easier to collaborate! - -* Include javadoc and tests - -* See the [tips here]({{site.url}}/dev/tips/index.html) - -* If you get blocked, **[hollar]({{site.url}}/meta/contact.html)**! http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/index.md ---------------------------------------------------------------------- diff --git a/docs/dev/index.md b/docs/dev/index.md deleted file mode 100644 index 11377d7..0000000 --- a/docs/dev/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: guide-normal -title: Getting to Code -toc: /toc.json ---- - -{% readj code/index.include.md %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/links.md ---------------------------------------------------------------------- diff --git a/docs/dev/links.md b/docs/dev/links.md deleted file mode 100644 index 4be8f30..0000000 --- a/docs/dev/links.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: guide-normal -title: Development Bookmarks -toc: ../toc.json ---- - - -Handy places: - -* **Code** is in Github at [https://github.com/brooklyncentral/brooklyn](https://github.com/brooklyncentral/brooklyn) - -* **Issues** are also on Github at [https://github.com/brooklyncentral/brooklyn/issues](https://github.com/brooklyncentral/brooklyn/issues) - -* **Maven repositories** are at [http://developers.cloudsoftcorp.com/download/maven2/](http://developers.cloudsoftcorp.com/download/maven2/) for releases - and [http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/](http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/) for snapshots - (under ``io/brooklyn``) - -* **CI server** is currently a private server managed by Cloudsoft. There is a proposal to move to CloudBees. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/tips/index.md ---------------------------------------------------------------------- diff --git a/docs/dev/tips/index.md b/docs/dev/tips/index.md deleted file mode 100644 index 664a95e..0000000 --- a/docs/dev/tips/index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -layout: guide-normal -title: Miscellaneous Tips and Tricks -toc: /toc.json ---- - -## 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.url}}/dev/build/ide.html)), - 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. - - - -## 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.url}}/meta/contact.html), -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/incubator-brooklyn/blob/ba6612ec/docs/dev/tips/local-artifact-repo.md ---------------------------------------------------------------------- diff --git a/docs/dev/tips/local-artifact-repo.md b/docs/dev/tips/local-artifact-repo.md deleted file mode 100644 index a96c62f..0000000 --- a/docs/dev/tips/local-artifact-repo.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: guide-normal -title: Prepopulating a Local Artifact Repository -toc: /toc.json ---- - -On occasion it can be useful to have/control/prepopulate a local repository of entity installers [1]. - -The following command (run from `~/`) may be used to sync Cloudsoft's fallback repository to the local `~/.brooklyn/repository/` folder: - - wget --directory-prefix=".brooklyn/repository/" --no-parent --relative --no-host-directories --reject="index.html*" --cut-dirs=2 --recursive -e robots=off --user-agent="Brooklyn Repository Sync" http://downloads.cloudsoftcorp.com/brooklyn/repository/ - -Brooklyn's default search behaviour for installation artifacts is as follows: - -1. The local `~/.brooklyn/repository/` folder. -2. The entity's installer's public download url (or an overridden url if one has been specified). -3. Cloudsoft's fallback repository. - -Cloudsoft's fallback repository [2] contains many of the installation artifacts used by current Brooklyn entities. - -It is intended to prevent problems occurring when the public url for an installer changes (e.g. when several new versions of MySQL have been released). It is provided on an as-is and as-available basis. - -If you use this command to create a local repository, please respect the `--user-agent`. In future this will allow Cloudsoft to easily filter repository syncing behaviour from fallback behaviour, allowing out-of-date entities to be more easily identified and updated. - -
- -
    -
  1. For example, when establishing a local cache or enterprise golden source, or when developing Brooklyn while offline, in planes, trains and automobiles, or other such situations of exemplary derring-do [3].
    2. -
  2. downloads.cloudsoftcorp.com/brooklyn/repository
    3. -
  3. This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.
    4. -
- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/tips/logging.md ---------------------------------------------------------------------- diff --git a/docs/dev/tips/logging.md b/docs/dev/tips/logging.md deleted file mode 100644 index 4e6b001..0000000 --- a/docs/dev/tips/logging.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -layout: guide-normal -title: Logging -toc: /toc.json ---- - -## 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 %} - - - - - - - -{% 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 ````. -* 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 ```` XML tags rather - than ```` 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!).