Mangle Developers’ Guide

Sub Modules

Mangle is a spring-boot application with implementation of web services to invoke Fault injection on Supported Endpoints.

The mangle Code is organised is as below sub modules using Maven build tool. 

  1. ├──  assets/files
  2. ├──  checkstyle
  3. ├──  docker
  4. ├──  docs
  5. ├──  formatter
  6. ├──  mangle-byteman-root
  7. ├──  mangle-default-plugin
  8. ├──  mangle-metric-reporter
  9. ├──  mangle-models
  10. ├──  mangle-services
  11. ├──  mangle-support
  12. ├──  mangle-task-framework
  13. ├──  mangle-test-plugin
  14. ├──  mangle-ui
  15. ├──  mangle-utils
  16. ├──  mangle-vcenter-adapter
  17. │    .gitbook.yaml
  18. │    .gitignore
  19. │    CONTRIBUTING.md
  20. │    LICENSE
  21. │    NOTICE
  22. │    pom.xml

mangle-byteman-root:

Module for the Mangle java Agent, which is used to support application level fault injection against apps running on JVM.

mangle-models:

Module for the complete data model of Mangle Web Application.

mangle–utils:

Module for all the core logic shared across Mangle Application.

mangle-task-framework:

Module for command execution orchestration in Mangle. Every fault execution or request processing in Mangle is handled as an asynchronous task. This module also contains the code responsible for managing scheduler functionality of Mangle.

mangle-test-plugin:

Module for the test utilities required for testing the mangle–task-framework.

mangle-default-plugin:

Module for all the out of the box faults supported by Mangle as a plugin. This is developed using the pf4j-spring framework. Mangle can support fault execution only if this module is available as plugin.

mangle-ui

Module for the presentation layer of mangle.

mangle –services

Module for core web services exposed to user, corresponding persistence layer and business logic.

mangle-vcenter-adapter:

Module for the spring-boot application that has to be deployed as a container or hosted as an application reachable by Mangle for executing faults against VMware vCenter Server.

The order of execution of sub modules is: 

  1. mangle-byteman-root
  2. mangle-models
  3. mangle-utils
  4. mangle-task-framework
  5. mangle-test-plugin
  6. mangle-default-plugin
  7. mangle-ui
  8. mangle-services
  9. mangle-vcenter-adapter

Build Profiles

Different build profiles available in Mangle pom are:

default

This profile builds mangle with last known good configuration of mangle-byteman-agent and does not take latest changes to mangle-byteman-root module into consideration.

To build:

  1. mvn clean install

build-all

This profile builds mangle with latest changes of mangle-byteman-agent and is recommended for use if the Mangle java agent jar has to be updated.

To build using this profile:

  1. mvn clean install –P build-all
  2. OR
  3. mvn clean install --activate-profiles build-all

byteman

This profile builds only the mangle-byteman-root module with the latest changes.

To build using profile byteman

  1. mvn clean install –P byteman
  2. OR
  3. mvn clean install --activate-profiles byteman

vcenter-adapter

This profile builds only mangle-vcenter-adapter with the latest changes.

  1. mvn clean install –P vcenter-adapter
  2. OR
  3. mvn clean install --activate-profiles vcenter-adapter

Building the code

Prerequisites

Java

  • Java 8 JDK installed on your OS of choice (Mac OSX, Linux variants, Windows are all supported hosts)
  • Eclipse Luna or a modern IDE of your choice. Make sure to apply the same formatting profile for code.
  • Git for source code management.

Maven

Maven is used to build and test the project. Install maven 3.5.X to your local system.

  • (Optional) Install Maven with your system’s package manager (e.g. apt on Ubuntu/Debian, homebrew on OSX, …).
  • Set your JAVA_HOME environment variable to be the home of the Java 8 JDK. On OSX, this lands in /Library/Java/JavaVirtualMachines/jdk1.8.0_65.jdk/Contents/Home/.
  • Run mvn clean install to compile the code, run checkstyle and run unit tests.

Packaging a fat jar

Resulting JAR goes to mangle-services/target/mangle-services.jar.

./mvnw clean package -DskipTests (packages without running tests)

Please refer to Mangle Administrator Guide for starting the jar by providing the Supported DB_OPTIONS and supported CLUSTER_OPTIONS as inputs to jar execution command.

  1. java –jar mangle-services-.x.x.x-jar –D...... (Db parameters are mandatory)

Code Style

License

Each source file has to specify the license at the very top of the file:

  1. /*
  2.  * Copyright (c) 2016-2019 VMware, Inc. All Rights Reserved.
  3.  *
  4.  * This product is licensed to you under the Apache License, Version 2.0 (the "License").
  5.  * You may not use this product except in compliance with the License.
  6.  *
  7.  * This product may include a number of subcomponents with separate copyright notices
  8.  * and license terms. Your use of these subcomponents is subject to the terms and
  9.  * conditions of the subcomponent's license, as noted in the LICENSE file.
  10.  */

Line length

Set to 100

Import statements

The order of import statements is:

  • import static java.*
  • import static javax.*
  • blank line
  • import static all other imports
  • blank line
  • import static com.vmware.*
  • blank line
  • import java.*
  • import javax.*
  • blank line
  • import all other imports
  • blank line
  • import com.vmware.*

Comments

Comments are always placed at independent line.
Do not append the comment at the end of the line.

Wrong

  1.   host.setLoggingLevel(Level.OFF);  // setting log level OFF

Correct

  1.   // setting log level OFF
  2.   host.setLoggingLevel(Level.OFF);

Commit message

Follow the widely used format:

Sample:

  1. Short (50 chars or less) summary of changes
  3. More detailed explanatory text, if necessary.  Wrap it to
  4. about 72 characters or so.  In some contexts, the first
  5. line is treated as the subject of an email and the rest of
  6. the text as the body.  The blank line separating the
  7. summary from the body is critical (unless you omit the body
  8. entirely); tools like rebase can get confused if you run
  9. the two together.
  11. Further paragraphs come after blank lines.
  13.   - Bullet points are okay, too
  15.   - Typically a hyphen or asterisk is used for the bullet,
  16.     preceded by a single space, with blank lines in
  17.     between, but conventions vary here
  • 50 char in title
  • Wrap the body at 72 char or less

Checkstyle

Checkstyle runs as part of maven validate lifecycle.

You can call it manually like ./mvnw validate or ./mvnw checkstyle:checkstyle.

checkstyle file: checkstyle.xml

IDE Settings

Formatter

For both Eclipse and IntellJ, import contrib/eclipse-java-style.xml

IntelliJ

IntelliJ can import eclipse formatter file.

Preference - Editor - Code Style - Manage - Import

Import contrib/eclipse-java-style.xml.

IntelliJ Specific

Setting java package import order

  1. Update .idea/codeStyleSettings.xml with contrib/idea-java-style.xml
  2. Restart IntelliJ

Building Mangle Docker Images

Prerequisites

Install docker on the developer machine following docker installation manual. Change the working directory to the root of mangle code repository.

To build a docker image for Mangle

  1. #!/bin/bash
  2. #stop the existing container if it is already running
  3. docker rm -f $(docker ps -a | grep mangle-app | awk '{print$1}')
  4. IMAGE=`docker images | grep "^mangle-app"| awk '{print $1}'`
  5. $CONTAINER_NAME= mangle-app
  6. if [ $IMAGE = $CONTAINER_NAME ]
  7. then
  8.                echo 'removing '$CONTAINER_NAME' image ...'
  9.                docker rmi -f $CONTAINER_NAME
  10. fi
  12. #Build Image
  13. docker build –f docker/Dockerfile -t $CONTAINER_NAME .
  14. IP=`ifconfig eth0 | grep "inet addr" | cut -d ':' -f 2 | cut -d ' ' -f 1`

To build a docker image for Mangle vCenter Adapter

  1. #!/bin/bash
  2. #stop the existing container if it is already running
  3. docker rm -f $(docker ps -a | grep mangle-app | awk '{print$1}')
  4. IMAGE=`docker images | grep "^mangle-app"| awk '{print $1}'`
  5. $CONTAINER_NAME= mangle-app
  6. if [ $IMAGE = $CONTAINER_NAME ]
  7. then
  8.                echo 'removing '$CONTAINER_NAME' image ...'
  9.                docker rmi -f $CONTAINER_NAME
  10. fi
  12. #Build Image
  13. docker build –f docker/Dockerfile -t $CONTAINER_NAME .
  14. IP=`ifconfig eth0 | grep "inet addr" | cut -d ':' -f 2 | cut -d ' ' -f 1`