http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/blueprints/yaml-reference.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/yaml-reference.md b/guide/blueprints/yaml-reference.md deleted file mode 100644 index 7a46970..0000000 --- a/guide/blueprints/yaml-reference.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -title: YAML Blueprint Reference -layout: website-normal ---- - -## Root Elements - -* `name`: human readable names -* `services`: a list of `ServiceSpecification` elements -* `location` (or `locations` taking a list): a `LocationSpecification` element as a string or a map - - -## Service Specification Elements - -Within the `services` block, a list of maps should be supplied, with each map -defining a `ServiceSpecification`. Each `ServiceSpecification` should declare the -service `type` (synonyms `serviceType` and `service_type`), indicating what type of -service is being specified there. The following formats are supported for -defining types: - -* `com.acme.brooklyn.package.JavaEntityClass` -* `java:com.acme.brooklyn.package.JavaEntityClass` -* `java-entity-class` (where this has been added to the [catalog]({{ site.path.guide }}/blueprints/catalog/)) - -A reference of some of the common service `type` instances used is included in a section below. - -Within the `ServiceSpecification`, other key-value pairs can be supplied to customize -the entity being defined, with these being the most common: - -* `id`: an ID string, used to refer to this service - -* `location` (or `locations`): as defined in the root element - -* `brooklyn.config`: configuration key-value pairs passed to the service entity being created - -* `brooklyn.children`: a list of `ServiceSpecifications` which will be configured as children of this entity - -* `brooklyn.policies`: a list of policies, each as a map described with their `type` and their `brooklyn.config` as keys - -* `brooklyn.enrichers`: a list of enrichers, each as a map described with their `type` and their `brooklyn.config` as keys; - see the keys declared on individual enrichers; - also see [this enricher example](example_yaml/test-app-with-enrichers-slightly-simpler.yaml) for a detailed and commented illustration - <!-- TODO assert that this yaml maches the yaml we test against --> - -* `brooklyn.initializers`: a list of `EntityInitializer` instances to be constructed and run against the entity, - each as a map described with their `type` and their `brooklyn.config` as keys. - An `EntityInitiailzer` can perform arbitrary customization to an entity whilst it is being constructed, - such as adding dynamic sensors and effectors. These classes must expose a public constructor taking - a single `Map` where the `brooklyn.config` is passed in. - Some common initializers are: - - * `org.apache.brooklyn.core.effector.ssh.SshCommandEffector`: takes a `name` and `command`, - and optionally a map of named `parameters` to their `description` and `defaultValue`, - to define an effector with the given name implemented by the given SSH command - (on an entity which as an ssh-able machine) - - * `org.apache.brooklyn.core.sensor.ssh.SshCommandSensor`: takes a `name` and `command`, - and optionally a `period`, to create a sensor feed which populates the sensor with - the given name by running the given command (on an entity which as an ssh-able machine) - - * `org.apache.brooklyn.core.sensor.windows.WinRmCommandSensor`: For a command supplied via WinRm. Takes a `name`, `command`, - and optionally a `period` and `executionDir`, to create a sensor feed which populates the sensor with - the given name by running the given command (on an entity which as an winrm-able machine).<br/> - _`"~"` will use the default execution directory for the WinRm session which is usually `%USERPROFILE%`_ - -* `brooklyn.parameters`: documents a list of typed parameters the entity accepts. If none - are specified the config keys declared in the entity's class are used (including the - information from the `@CatalogConfig` annotation). The items have the following properties: - * `name` (required): identifier by which to reference the parameter when setting - or retrieving its value - * `label`: a value to present to the user, same as `name` if empty - * `description`: short text describing the parameter behaviour/usage, presented - to the user - * `type`: the type of the parameter, one of `string`, `integer`, `long`, `float`, - `double`, `timestamp`, `duration`, `port`, or a fully qualified Java type name; - the default is `string`; - obvious coercion is supported so - `timestamp` accepts most common ISO date formats, `duration` accepts `5m`, and port accepts `8080+` - * `default`: a default value; this will be coerced to the declared `type` - * `pinned`: mark the parameter as pinned (always displayed) for the UI. The default is `true` - * `constraints`: a list of constraints the parameter should meet; - for details, see [Entity Configuration]({{ site.path.guide }}/blueprints/entity-configuration.html#config-key-constraints). - - A shorthand notation is also supported where just the name of the parameter is supplied - as an item in the list, with the other values being unset or the default. - See `displayName` in the following example for an illustration of this: - - ~~~ yaml - brooklyn.parameters: - # user.age parameter is required, pinned and fully specified - - name: user.age - type: integer - label: Age - description: the age of the user - pinned: true - constraints: - - required - # user.name is optional, is not pinned and has a default - - name: user.name - default: You - pinned: false - # shorthand notation: displayName will be an optional config of type string with no default - - displayName - ~~~ - - Entities, policies, and initializers may accept additional key-value pairs, - usually documented in their documentation (e.g. javadoc), or in the case of Java - often as static fields in the underlying Java class. - Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class; - these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`. - (Undeclared config is only accepted in the `brooklyn.config` map.) - Referencing the parameters from within java classes is identical to using config keys. In yaml it's - usually referenced using `$brooklyn:scopeRoot().config("displayName")`. See below for more details on scopes. - -* `brooklyn.tags`: documents a list of tag objects which should be assigned to the entity. - - -## Location Specification Elements - -<!-- TODO - expand this, currently it's concise notes --> - -In brief, location specs are supplied as follows, either for the entire application (at the root) -or for a specific `ServiceSpecification`: - - location: - jclouds:aws-ec2: - region: us-east-1 - identity: AKA_YOUR_ACCESS_KEY_ID - credential: <access-key-hex-digits> - -Or in many cases it can be in-lined: - - location: localhost - location: named:my_openstack - location: aws-ec2:us-west-1 - -For the first immediately, you'll need password-less ssh access to localhost. -For the second, you'll need to define a named location in `brooklyn.properties`, -using `brooklyn.location.named.my_openstack....` properties. -For the third, you'll need to have the identity and credentials defined in -`brooklyn.properties`, using `brooklyn.location.jclouds.aws-ec2....` properties. - -If specifying multiple locations, e.g. for a fabric: - - locations: - - localhost - - named:my_openstack - - aws-ec2:us-east-2 # if credentials defined in `brooklyn.properties - - jclouds:aws-ec2: - region: us-east-1 - identity: AKA_YOUR_ACCESS_KEY_ID - credential: <access-key-hex-digits> - -If you have pre-existing nodes, you can use the `byon` provider, either in this format: - - location: - byon: - user: root - privateKeyFile: ~/.ssh/key.pem - hosts: - - 81.95.144.58 - - 81.95.144.59 - - brooklyn@159.253.144.139 - - brooklyn@159.253.144.140 - -or: - - location: - byon: - user: root - privateKeyFile: ~/.ssh/key.pem - hosts: "{81.95.144.{58,59},brooklyn@159.253.144.{139-140}" - -You cannot use glob expansions with the list notation, nor can you specify per-host -information apart from user within a single `byon` declaration. -However you can combine locations using `multi`: - - location: - multi: - targets: - - byon: - user: root - privateKeyFile: ~/.ssh/key.pem - hosts: - - 81.95.144.58 - - 81.95.144.59 - - byon: - privateKeyFile: ~/.ssh/brooklyn_key.pem - hosts: brooklyn@159.253.144{139-140} - - -## DSL Commands - -Dependency injection other powerful references and types can be built up within the YAML using the -concise DSL defined here: - -* `$brooklyn:attributeWhenReady("sensor")` will store a future which will be blocked when it is accessed, - until the given `sensor` from this entity "truthy" (i.e. non-trivial, non-empty, non-zero) value - (see below on `component` for looking up values on other sensors) -* `$brooklyn:config("key")` will insert the value set against the given key at this entity (or nearest ancestor); - can be used to supply config at the root which is used in multiple places in the plan -* `$brooklyn:sensor("sensor.name")` returns the given sensor on the current entity if found, or an untyped (Object) sensor; - `$brooklyn:sensor("com.acme.brooklyn.ContainingEntityClass", "sensor.name")` returns the strongly typed sensor defined in the given class -* `$brooklyn:entity("ID")` refers to a Brooklyn entity with the given ID; you can then access the following subfields, - using the same syntax as defined above but with a different reference entity, - e.g. `$brooklyn:entity("ID").attributeWhenReady("sensor")`: - * `.attributeWhenReady("sensor")` - * `.config("key")` - * `.sensor("sensor.name")` -* `$brooklyn:component("scope", "ID")` is also supported, to limit scope to any of - * `global`: looks for the `ID` anywhere in the plan - * `child`: looks for the `ID` anywhere in the child only - * `descendant`: looks for the `ID` anywhere in children or their descendants - * `sibling`: looks for the `ID` anywhere among children of the parent entity - * `parent`: returns the parent entity (ignores the `ID`) - * `this`: returns this entity (ignores the `ID`) -* `$brooklyn:root()` will return the topmost entity (the application) -* `$broopklyn:scopeRoot()` will return the root entity in the current plan scope. - For catalog items it's the topmost entity in the plan, for application plans it is the same as - `$brooklyn:root()`. -* `$brooklyn:formatString("pattern e.g. %s %s", "field 1", "field 2")` returns a future which creates the formatted string - with the given parameters, where parameters may be strings *or* other tasks such as `attributeWhenReady` -* `$brooklyn:urlEncode("val")` returns a future which creates a string with the characters escaped - so it is a valid part of a URL. The parameter can be a string *or* another task. For example, - `$brooklyn:urlEncode($brooklyn:config(\"mykey\"))`. It uses "www-form-urlencoded" for the encoding, - which is appropriate for query parameters but not for some other parts of the URL (e.g. space is encoded as '+'). -* `$brooklyn:literal("string")` returns the given string as a literal (suppressing any `$brooklyn:` expansion) -* `$brooklyn:object(Map)` creates an object, using keys `type` to define the java type, - and either `object.fields` or `brooklyn.config` to supply bean/constructor/flags to create an instance -* `$brooklyn:entitySpec(Map)` returns a new `ServiceSpecification` as defined by the given `Map`, - but as an `EntitySpec` suitable for setting as the value of `ConfigKey<EntitySpec>` config items - (such as `dynamiccluster.memberspec` in `DynamicCluster`) - -<!-- TODO examples for object and entitySpec --> - -Parameters above can be supplied either as strings or as lists and maps in YAML, -and the `$brooklyn:` syntax can be used within those parameters. - - -## Some Powerful YAML Entities - -All entities support configuration via YAML, but these entities in particular -have been designed for general purpose use from YAML. Consult the Javadoc for these -elements for more information: - -* **Vanilla Software** in `VanillaSoftwareProcess`: makes it very easy to build entities - which use `bash` commands to install and the PID to stop and restart -* **Chef** in `ChefSoftwareProcess`: makes it easy to use Chef cookbooks to build entities, - either with recipes following conventions or with configuration in the `ServiceSpecification` - to use artibitrary recipes -* `DynamicCluster`: provides resizable clusters given a `dynamiccluster.memberspec` set with `$brooklyn.entitySpec(Map)` as described above -* `DynamicFabric`: provides a set of homogeneous instances started in different locations, - with an effector to `addLocation`, i.e. add a new instance in a given location, at runtime
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/application-parent-membership.md ---------------------------------------------------------------------- diff --git a/guide/concepts/application-parent-membership.md b/guide/concepts/application-parent-membership.md deleted file mode 100644 index c2d0ac3..0000000 --- a/guide/concepts/application-parent-membership.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Application, Parent and Membership -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -All entities have a ***parent*** entity, which creates and manages it, with one important exception: *applications*. -Application entities are the top-level entities created and managed externally, manually or programmatically. - -Applications are typically defined in Brooklyn as an ***application descriptor***. -This is a Java class specifying the entities which make up the application, -by extending the class ``AbstractApplication``, and specifying how these entities should be configured and managed. - -All entities, including applications, can be the parent of other entities. -This means that the "child" is typically started, configured, and managed by the parent. -For example, an application may be the parent of a web cluster; that cluster in turn is the parent of web server processes. -In the management console, this is represented hierarchically in a tree view. - -A parallel concept is that of ***membership***: in addition to one fixed parent, -and entity may be a ***member*** of any number of special entities called ***groups***. -Membership of a group can be used for whatever purpose is required; -for example, it can be used to manage a collection of entities together for one purpose -(e.g. wide-area load-balancing between locations) even though they may have been -created by different parents (e.g. a multi-tier stack within a location). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png ---------------------------------------------------------------------- diff --git a/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png b/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png deleted file mode 100644 index c2b48ba..0000000 Binary files a/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/brooklyn-flow-websequencediagrams.com.png ---------------------------------------------------------------------- diff --git a/guide/concepts/brooklyn-flow-websequencediagrams.com.png b/guide/concepts/brooklyn-flow-websequencediagrams.com.png deleted file mode 100644 index 78eb5c8..0000000 Binary files a/guide/concepts/brooklyn-flow-websequencediagrams.com.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/configuration-sensor-effectors.md ---------------------------------------------------------------------- diff --git a/guide/concepts/configuration-sensor-effectors.md b/guide/concepts/configuration-sensor-effectors.md deleted file mode 100644 index 3575337..0000000 --- a/guide/concepts/configuration-sensor-effectors.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Configuration, Sensors and Effectors -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -### Configuration - -All entities contain a map of config information. This can contain arbitrary values, typically keyed under static `ConfigKey` fields on the `Entity` sub-class. These values are inherited, so setting a configuration value at the -application level will make it available in all entities underneath unless it is overridden. - -Configuration is propagated when an application "goes live" (i.e. it becomes "managed", either explicitly or when its `start()` method is invoked), so config values must be set before this occurs. - -Configuration values can be specified in a configuration file (`brooklyn.cfg`) -to apply universally, and/or programmatically to a specific entity and its descendants -by calling `.configure(KEY, VALUE)` in the entity spec when creating it. -There is also an `entity.config().set(KEY, VALUE)` method. - -Additionally, many common configuration parameters are available as "flags" which can be supplied as Strings when constructing -then entity, in the form -`EntitySpec.createË(MyEntity.class).configure("config1", "value1").configure("config2", "value2")`. - -Documentation of the flags available for individual entities can normally be found in the javadocs. -The `@SetFromFlag` annotations on `ConfigKey` static field definitions -in the entity's interface is the recommended mechanism for exposing configuration options. - - -### Sensors and Effectors - -***Sensors*** (activity information and notifications) and ***effectors*** (operations that can be invoked on the entity) are defined by entities as static fields on the `Entity` subclass. - -Sensors can be updated by the entity or associated tasks, and sensors from an entity can be subscribed to by its parent or other entities to track changes in an entity's activity. - -Effectors can be invoked by an entity's parent remotely, and the invoker is able to track the execution of that effector. Effectors can be invoked by other entities, but use this functionality with care to prevent too many managers! - -An entity consists of a Java interface (used when interacting with the entity) and a Java class. For resilience. it is recommended to store -the entity's state in attributes (see `getAttribute(AttributeKey)`). If internal fields can be used then the data will be lost on brooklyn -restart, and may cause problems if the entity is to be moved to a different brooklyn management node. - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/dependent-configuration.md ---------------------------------------------------------------------- diff --git a/guide/concepts/dependent-configuration.md b/guide/concepts/dependent-configuration.md deleted file mode 100644 index 1d08e1a..0000000 --- a/guide/concepts/dependent-configuration.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Dependent Configuration -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -Under the covers Brooklyn has a sophisticated sensor event and subscription model, but conveniences around this model make it very simple to express cross-entity dependencies. Consider the example where Tomcat instances need to know the URL of a database (or a set of URLs to connect to a Monterey processing fabric, or other entities) - -{% highlight java %} -setConfiguration(UsesJava.JAVA_OPTIONS, ImmutableMap.of("mysql.url", - attributeWhenReady(mysql, MySqlNode.MY_SQL_URL) )) -{% endhighlight %} - -The ``attributeWhenReady(Entity, Sensor)`` call (a static method on the class ``DependentConfiguration``) -causes the configuration value to be set when that given entity's attribue is ready. -In the example, ``attributeWhenReady()`` causes the JVM system property ``mysql.url`` to be set to the value of the ``MySqlNode.MY_SQL_URL`` sensor from ``mysql`` when that value is ready. As soon as the database URL is announced by the MySql entity, the configuration value will be available to the Tomcat cluster. - -By default "ready" means being *set* (non-null) and, if appropriate, *non-empty* (for collections and strings) or *non-zero* (for numbers). Formally the interpretation of ready is that of "Groovy truth" defined by an ``asBoolean()`` method on the class and in the Groovy language extensions. - -You can customize "readiness" by supplying a ``Predicate`` (Google common) or ``Closure`` (Groovy) in a third parameter. -This evaluates candidate values reported by the sensor until one is found to be ``true``. -For example, passing ``{ it.size()>=3 }`` as the readiness argument would require at least three management plane URLs. - -More information on this can be found in the javadoc for ``DependentConfiguration``, -along with a few other methods such as ``valueWhenAttributeReady`` which allow post-processing of an attribute value. - -Note that if the value of ``CONFIG_KEY`` passed to ``Entity.getConfig`` is a Closure or Task (such as returned by ``attributeWhenReady``), -the first access of ``Entity.getConfig(CONFIG_KEY)`` will block until the task completes. -Typically this does the right thing, blocking when necessary to generate the right start-up sequence -without the developer having to think through the order, but it can take some getting used to. -Be careful not to request config information until really necessary (or to use non-blocking "raw" mechanisms), -and in complicated situations be ready to attend to circular dependencies. -The management console gives useful information for understanding what is happening and resolving the cycle. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/entities.md ---------------------------------------------------------------------- diff --git a/guide/concepts/entities.md b/guide/concepts/entities.md deleted file mode 100644 index 0afeb50..0000000 --- a/guide/concepts/entities.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Entities -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -The central concept in a Brooklyn deployment is that of an ***entity***. -An entity represents a resource under management, either *base* entities (individual machines or software processes) -or logical collections of these entities. - -Fundamental to the processing model is the capability of entities to be the *parent* of other entities (the mechanism by which collections are formed), -with every entity having a single parent entity, up to the privileged top-level ***application*** entity. - -Entities are code, so they can be extended, overridden, and modified. Entities can have events, operations, and processing logic associated with them, and it is through this mechanism that the active management is delivered. - -The main responsibilities of an entity are: - -- Provisioning the entity in the given location or locations -- Holding configuration and state (attributes) for the entity -- Reporting monitoring data (sensors) about the status of the entity -- Exposing operations (effectors) that can be performed on the entity -- Hosting management policies and tasks related to the entity http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/execution.md ---------------------------------------------------------------------- diff --git a/guide/concepts/execution.md b/guide/concepts/execution.md deleted file mode 100644 index 9762005..0000000 --- a/guide/concepts/execution.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Execution -layout: website-normal ---- - -All processing, whether an effector invocation or a policy cycle, are tracked as ***tasks***. This allows several important capabilities: - -* active and historic processing can be observed by operators -* the invocation context is available in the thread, to check entitlement (permissions) and maintain a -hierarchical causal chain even when operations are run in parallel -* processing can be managed across multiple management nodes - -Some executions create new entities, which can then have tasks associated with them, and the system will record, for example, that a start effector on the new entity is a task associated with that entity, with that task -created by a task associated with a different entity. - -The execution of a typical overall start-up sequence is shown below: - -[](brooklyn-flow-websequencediagrams.com.png) - - -## Integration - -One vital aspect of Brooklyn is its ability to communicate with the systems it starts. This is abstracted using a ***driver*** facility in Brooklyn, where a -driver describes how a process or service can be installed and managed using a particular technology. - -For example, a ``TomcatServer`` may implement start and other effectors using a ``TomcatSshDriver`` which inherits from ``JavaSoftwareProcessSshDriver`` (for JVM and JMX start confguration), inheriting from ``AbstractSoftwareProcessSshDriver`` -(for SSH scripting support). - -Particularly for sensors, some technologies are used so frequently that they are -packaged as ***feeds*** which can discover their configuration (including from drivers). These include JMX and HTTP (see ``JmxFeed`` and ``HttpFeed``). - -Brooklyn comes with entity implementations for a growing number of commonly used systems, including various web application servers, databases and NoSQL data stores, and messaging systems. - - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/index.md ---------------------------------------------------------------------- diff --git a/guide/concepts/index.md b/guide/concepts/index.md deleted file mode 100644 index b27ea8c..0000000 --- a/guide/concepts/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Brooklyn Concepts -title_in_menu: Brooklyn Concepts -layout: website-normal -children: -- entities.md -- application-parent-membership.md -- configuration-sensor-effectors.md -- lifecycle-managementcontext.md -- dependent-configuration.md -- location.md -- policies.md -- execution.md -- stop-start-restart-behaviour.md ---- - -This introduces brooklyn and describes how it simplifies the deployment and management of big applications. It is -intended for people who are using brooklyn-supported application components (such as web/app servers, data stores) -to be able to use brooklyn to easily start their application in multiple locations with off-the-shelf management -policies. - -{% include list-children.html %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/lifecycle-managementcontext.md ---------------------------------------------------------------------- diff --git a/guide/concepts/lifecycle-managementcontext.md b/guide/concepts/lifecycle-managementcontext.md deleted file mode 100644 index 90cedcf..0000000 --- a/guide/concepts/lifecycle-managementcontext.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Lifecycle and ManagementContext -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -Under-the-covers, at heart of the brooklyn management plane is the ``ManagementContext``. -This is started automatically when using launching an application using the brooklyn CLI. For programmatic use, see -``BrooklynLauncher.newLauncher().launch()``. - -A Brooklyn deployment consists of many entities in a hierarchical tree, with the privileged *application* entity at the top level. - -An application entity (``Application`` class) is responsible for starting the deployment of all its child entities (i.e. the entire entity tree under its ownership). - -An ``Application``'s ``start()`` method begins provisioning the child entities of the application (and their entities, recursively). - -Provisioning of entities typically happens in parallel automatically, -although this can be customized. This is implemented as ***tasks*** which are tracked by the management plane and is accessible in the web-based management console and REST API. - -Customized provisioning can be useful where two starting entities depend on each other. For example, it is often necessary to delay start of one entity until another entity reaches a certain state, and to supply run-time information about the latter to the former. - -<!-- TODO ambiguous language; need a better description of the "manage" lifecycle --> -When new entities are created, the entity is wired up to an application by giving it a parent. The entity is then explicitly "managed", which allows other entities to discover it. - -Typically a Brooklyn deployment has a single management context which records: - -* all entities under management that are reachable by the application(s) via the parent-child relationships, -* the state associated with each entity, -* subscribers (listeners) to sensor events arising from the entities, -* active tasks (jobs) associated with any the entity, -* which Brooklyn management node is mastering (managing) each entity. - -<!-- TODO Distributed brooklyn not yet supported; needs clarification in docs --> - -In a multi-location deployment, management operates in all regions, with brooklyn entity instances being mastered in the relevant region. - -When management is distributed a Brooklyn deployment may consist of multiple Brooklyn management nodes each with a ``ManagementContext`` instance. - -<!-- TODO - Clarify the following statements. -The management context entity forms part of the management plane. -The management plane is responsible for the distribution of the ``Entity`` instances across multiple machines and multiple locations, -tracking the transfer of events (subscriptions) between ``Entity`` instances, and the execution of tasks (often initiated by management policies). ---> http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/location.md ---------------------------------------------------------------------- diff --git a/guide/concepts/location.md b/guide/concepts/location.md deleted file mode 100644 index 417d0a7..0000000 --- a/guide/concepts/location.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Location -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -<!-- TODO, Clarify is how geographical location works. ---> - -Entities can be provisioned/started in the location of your choice. Brooklyn transparently uses [jclouds](http://www.jclouds.org) to support different cloud providers and to support BYON (Bring Your Own Nodes). - -The implementation of an entity (e.g. Tomcat) is agnostic about where it will be installed/started. When writing the application definition specify the location or list of possible locations (``Location`` instances) for hosting the entity. - -``Location`` instances represent where they run and indicate how that location (resource or service) can be accessed. - -For example, a ``JBoss7Server`` will usually be running in an ``SshMachineLocation``, which contains the credentials and address for sshing to the machine. A cluster of such servers may be running in a ``MachineProvisioningLocation``, capable of creating new ``SshMachineLocation`` instances as required. - -<!-- TODO, incorporate the following. - -The idea is that you could specify the location as AWS and also supply an image id. You could configure the Tomcat entity accordingly: specify the path if the image already has Tomcat installed, or specify that Tomcat must be downloaded/installed. Entities typically use _drivers_ (such as SSH-based) to install, start, and interact with their corresponding real-world instance. ---> http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/concepts/policies.md ---------------------------------------------------------------------- diff --git a/guide/concepts/policies.md b/guide/concepts/policies.md deleted file mode 100644 index 495e57f..0000000 --- a/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/58bb3aa0/guide/concepts/stop-start-restart-behaviour.md ---------------------------------------------------------------------- diff --git a/guide/concepts/stop-start-restart-behaviour.md b/guide/concepts/stop-start-restart-behaviour.md deleted file mode 100644 index d862cb3..0000000 --- a/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/58bb3aa0/guide/dev/code/licensing.md ---------------------------------------------------------------------- diff --git a/guide/dev/code/licensing.md b/guide/dev/code/licensing.md deleted file mode 100644 index 8f031e0..0000000 --- a/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/58bb3aa0/guide/dev/code/structure.md ---------------------------------------------------------------------- diff --git a/guide/dev/code/structure.md b/guide/dev/code/structure.md deleted file mode 100644 index bf1139b..0000000 --- a/guide/dev/code/structure.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Code Structure -layout: website-normal ---- - -Brooklyn is split into the following subprojects: - -* **brooklyn-server**: - * **api**: the pure-Java interfaces for interacting with the system - * **camp**: the components for a server which speaks with the CAMP REST API and understands the CAMP YAML plan language - * **core**: the base class implementations for entities and applications, entity traits, locations, policies, sensor and effector support, tasks, and more - * **karaf**: OSGi support - * **launcher**: for launching brooklyn, either using a main method or invoked from the cli project - * **locations**: specific location integrations - * **jclouds**: integration with many cloud APIs and providers via Apache jclouds - * **logging**: how we enable configurable logging - * **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 - * **parent**: a meta-project parent to collect dependencies and other maven configuration for re-use - * **policy**: collection of useful policies for automating entity activity - * **rest**: supporting the REST API - * **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 - * **server-cli**: implementation of the Brooklyn *server* command line interface; not to be confused with the client CLI - * **software**: support frameworks for creating entities which mainly launch software processes on machines - * **base**: software process lifecycle abstract classes and drivers (e.g. SSH) - * **winrm**: support for connecting to Windows machines - * **test-framework**: provides Brooklyn entities for building YAML tests for other entities - * **test-support**: provides Brooklyn-specific support for Java TestNG tests, used by nearly all projects in scope ``test``, building on `utils/test-support` - * **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 - -* **brooklyn-ui**: Javascript web-app for the brooklyn management web console (builds a WAR) - -* **brooklyn-library**: a library of useful blueprints - * **examples**: some canonical examples - * **qa**: longevity and stress tests - * **sandbox**: experimental items - * **software**: blueprints for software processes - * **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 - -* **brooklyn-docs**: the markdown source code for this documentation - -* **brooklyn-dist**: projects for packaging Brooklyn and making it easier to consume - * **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 - * **dist**: builds brooklyn as a downloadable .zip and .tar.gz - * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/dev/code/tests.md ---------------------------------------------------------------------- diff --git a/guide/dev/code/tests.md b/guide/dev/code/tests.md deleted file mode 100644 index a19f814..0000000 --- a/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/58bb3aa0/guide/dev/env/ide/eclipse.include.md ---------------------------------------------------------------------- diff --git a/guide/dev/env/ide/eclipse.include.md b/guide/dev/env/ide/eclipse.include.md deleted file mode 100644 index c3a7a06..0000000 --- a/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/58bb3aa0/guide/dev/env/ide/index.md ---------------------------------------------------------------------- diff --git a/guide/dev/env/ide/index.md b/guide/dev/env/ide/index.md deleted file mode 100644 index 94bbfba..0000000 --- a/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`` and/or ``-Dno-go-client``) -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 -Dno-go-client`) 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/58bb3aa0/guide/dev/env/maven-build.md ---------------------------------------------------------------------- diff --git a/guide/dev/env/maven-build.md b/guide/dev/env/maven-build.md deleted file mode 100644 index bc5a79b..0000000 --- a/guide/dev/env/maven-build.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -layout: website-normal -title: Maven Build -toc: /guide/toc.json ---- - -## The Basics - -The full build requires the following software to be installed: - -* Maven (v3.1+) -* Java (v1.7+, 1.8 recommended) -* Go (v1.6+) [if building the CLI client] -* rpm tools [if building the dist packages for those platforms] - -With these in place, you should be able to build everything with a: - -{% highlight bash %} -% mvn clean install -{% endhighlight %} - -Alternatively you can build most things with just Java and Maven installed using: - -{% highlight bash %} -mvn clean install -Dno-go-client -Dno-rpm` -{% endhighlight %} - -Other tips: - -* Add ``-DskipTests`` to skip tests (builds much faster, but not as safe) - -* You may need more JVM memory, e.g. at the command-line (or in `.profile`): - - ``export MAVEN_OPTS="-Xmx1024m -Xms512m"`` - -* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests - ([tests described here](../code/tests.html)) - -* You may need to install ``rpm`` package to build RPM packages: ``brew install rpm`` for Mac OS, ``apt-get install rpm`` for Ubuntu, ``yum install rpm`` for Centos/RHEL. - On Mac OS you may also need to set `%_tmppath /tmp` in `~/.rpmmacros`. - -* If you're looking at the maven internals, note that many of the settings are inherited from parent projects (see for instance `brooklyn-server/parent/pom.xml`) - -* For tips on building within various IDEs, look [here](ide/). - - -## 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 REST JavaScript Web GUI -[INFO] Brooklyn Server Root -[INFO] Brooklyn Parent Project -[INFO] Brooklyn Test Support Utilities -[INFO] Brooklyn Logback Includable Configuration -[INFO] Brooklyn Common Utilities - -... - -[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:1.0.0-SNAPSHOT; it doesn't have an associated file or directory. -[INFO] Copying files to ~/repos/apache/brooklyn/usage/dist/target/brooklyn-dist -[WARNING] Assembly file: ~/repos/apache/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:1.0.0-SNAPSHOT; it doesn't have an associated file or directory. -{% comment %}BROOKLYN_VERSION{% endcomment %}[INFO] Building tar: /Users/aled/repos/apache/brooklyn/usage/dist/target/brooklyn-1.0.0-SNAPSHOT-dist.tar.gz -{% comment %}BROOKLYN_VERSION{% endcomment %}[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:1.0.0-SNAPSHOT; it doesn't have an associated file or directory. - -... - -[WARNING] Don't override file /Users/aled/repos/apache/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/58bb3aa0/guide/dev/index.md ---------------------------------------------------------------------- diff --git a/guide/dev/index.md b/guide/dev/index.md deleted file mode 100644 index f0cf45e..0000000 --- a/guide/dev/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Developer Guide -started-pdf-exclude: true -layout: website-normal -menu_parent: /website/documentation/ -breadcrumbs: -- /website/documentation/index.md -- /guide/dev/index.md -children: -- { link: "{{ site.path.website }}/developers/code/", title: "Get the Code" } -- env/maven-build.md -- env/ide/ -- code/structure.md -- code/tests.md -- code/licensing.md -- tips/ -- tips/logging.md -- tips/debugging-remote-brooklyn.md -- { link: "http://github.com/apache/brooklyn";, title: "GitHub" } -- { 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/58bb3aa0/guide/dev/tips/debugging-remote-brooklyn.md ---------------------------------------------------------------------- diff --git a/guide/dev/tips/debugging-remote-brooklyn.md b/guide/dev/tips/debugging-remote-brooklyn.md deleted file mode 100644 index 5056fd8..0000000 --- a/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": "1.0.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 -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"`, 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/58bb3aa0/guide/dev/tips/index.md ---------------------------------------------------------------------- diff --git a/guide/dev/tips/index.md b/guide/dev/tips/index.md deleted file mode 100644 index 417a42f..0000000 --- a/guide/dev/tips/index.md +++ /dev/null @@ -1,70 +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! - -## YAML Blueprint Debugging - -* Brooklyn will reject any YAML blueprint that contains syntax errors and will alert the user of such errors. - -* However, it is possible to create a blueprint that is syntactically legal but results in runtime problems - for Brooklyn (for example, if an enricher's `enricher.producer` value is not immediately resolvable). - -* If Brooklyn appears to freeze after deploying a blueprint, run the `jstack <brooklyn-pid>` command to view - the state of all running threads. By examining this output, it may become obvious which thread(s) are causing - the problem, and the details of the stack trace will provide insight into which part of the blueprint is - incorrectly written. - -## 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!) -
