From 821a6c24bfa6a303d72188b5a7f8caf96348cb9a Mon Sep 17 00:00:00 2001 From: Victor Romero Date: Mon, 14 Jul 2014 17:45:09 -0300 Subject: [PATCH] MULE-7747 Add root project files to better Gnits standards compiance --- BUILD.md | 97 ++++++++++ CONTRIBUTE.md | 315 ++++++++++++++++++++++++++++++++ I18N.md | 29 +++ LICENSE.txt | 492 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- STYLE.md | 262 +++++++++++++++++++++++++++ 6 files changed, 1196 insertions(+), 1 deletion(-) create mode 100644 BUILD.md create mode 100644 CONTRIBUTE.md create mode 100644 I18N.md create mode 100644 LICENSE.txt create mode 100644 STYLE.md diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 000000000000..c253cacc227d --- /dev/null +++ b/BUILD.md @@ -0,0 +1,97 @@ +# Building Mule + +[Maven](http://maven.apache.org/) is the build automation tool used in Mule ESB. To modify or add to Mule source code, it's specially relevant to understand the hierarchy of maven projects that represent the Mule source code. + +To be able to build Mule you will need Maven among others. Refer to the [CONTRIBUTE.md](CONTRIBUTE.md) file to find the installation instructions prerequisites necessary to build Mule. + +In the following sections we will learn how Mule is organized, how to build Mule and how to troubleshoot problems we might find. + +### Mule Source Code Sub-projects + +The Mule source code project is neatly organized into a hierarchy of sub-projects. (Sub-projects are sometimes referred to as "modules," but to avoid confusion with Mule modules, we use "sub-projects".) Each sub-project generally produces one Maven artifact, usually a JAR file. The Mule build is structured using intermediate project object models (POMs) to group common sub-projects together. These intermediate sub-projects are sub-folders of the source code's mule folder, and are described in the table below. + +| Sub-project | Description | +|-------------------|--------------| +| `buildtools` | tools to build Mule, scripts, and checkstyle configuration | +| `core` | Mule's core API and functionality that is required by all transports distributions | +| `builds` | the various distributions (refer to the Distributions section below for further details) | +| `examples` | examples that come with the full Mule distribution | +| `modules` | non-transport extensions to Mule, such as XML processing, Spring extras, or scripting support +| `tests` | tests that can be run as part of the Mule build | +| `tools` | tools for Mule, such as the transport and project Maven archetypes | +| `transports` | Mule transports such as the JMS, VM, and TCP transports | + + +### Building Mule + +The following table lists common goals to execute for building Mule. These goals are standard Maven goals, refer to [Maven's documentation](http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html#Running_Maven_Tools) for more info on them. + +|Command | Description | +|:----------|:-------------| +| `mvn clean` | purges any built artifacts or intermediate files (such as .class) from the target directory | +| `mvn install` | installs the artifact to your local repository.| +| `mvn test` | runs any unit tests for this sub-project | +| `mvn -DskipTests install` | By default, Maven runs all unit tests for each project for each build which, depending on the project, can take a long time to complete. If you wish, you can skip the tests using this command.| + +#### Build properties + +In addition to the standard properties, the following ones can change the behaviour of the Mule build: + +| Property | Default | Description | +|:--------------------------|:-------------|:-------------| +| `skipIntegrationTests` | `false` | Skip flag for integration tests | +| `skipSystemTests` | `true` | Skip flag for container level tests | +| `skipPerformanceTests` | `true` | Skip flag for performance tests | +| `skipArchetypeTests` | `true` | Skip flag for the archetype tests| +| `skipVerifications` | `false` | Skip flag for the license check, version enforce, style checks, etc.| +| `skipInstalls` | `false` | Disable installation of artifacts in the local maven repository| +| `skipGpg` | `true` | Skip artifact signing, as it does require special setup| +| `skipDistributions` | `true` | Skip flag for the distribution files creation | + +To set these properties, it's necessary to pass them in the maven command line as `-DPropertyName=value` where value is optional for `true`. Therefore, to disable the distribution creation skip we could use `-DskipDistributions=false` while to skip the integration tests we can `-DskipIntegrationTests`. + +It is important to remember that the rest of the maven plugins flags are still applicable, for instance to disable tests in the surefire plugin we could do: `-DskipTests`. + +#### Build profiles + +Along with the [Build properties](#build-properties) the Mule build has a number of Maven profiles (see Maven's guide on profiles [here](http://maven.apache.org/guides/introduction/introduction-to-profiles.html)). These profiles can activate build properties or configure other build behaviors. + +The following list shows the Mule's build profiles: + +| Property | Description | +|:--------------------------|:------------------------------------------------------------------| +| `unit` | Only tests annotated with `org.mule.tck.size.SmallTest` will run.| +| `functional ` | Will just run functional tests, located in [/tests/functional](mule/tree/3.x/tests/functional). | +| `integration` | Will just run integration tests, located in [/tests/integration](mule/tree/3.x/tests/integration). | +| `system` | Will just run system tests. | +| `release` | Won't execute any tests and will create the distributable files.| + +To set these profiles, we should pass them in the maven command line as `-PprofileName`. Therefore, to disable the distribution creation skip we could use `-DskipDistributions=false` while to skip the integration tests we can `-DskipIntegrationTests`. + +#### Distributions + +When you package Mule for distribution, all distributions and related resources are located in the distributions sub-project. + +For performance's sake, the distributions are *not* built from the project's top-level directory by default. You may either build a distribution from its own directory, or disable the `distributions` skip flag by adding `-DskipDistributions=false` to your Maven command line. + +The table below offers a brief description of each type distribution. + +|Type | Sub-project |Description | +|:------------------------------|:-------------------------------|:-----------------| +| Full Standalone Server | `/distributions/standalone` | Packages Mule as a stand-alone server application. Includes all transports, extras and all dependencies. Includes the [Java Service Wrapper](http://wrapper.tanukisoftware.org/) for starting/stopping/restarting Mule from the native OS. | +| Custom Standalone Server | `/distributions/standalone-light` | Packages Mule as a standalone server application without any source or javadoc files | +| Embedded (Composite) JAR File | `/distribution/embedded` | Packages Mule as a single JAR file containing all Mule classes, including all transports and extras). This distribution is useful when embedding Mule into another application, or when using Mule with a non-Maven-based build. Note that when you use this approach, you are responsible for providing any needed Mule dependencies, as described in the next section. | + + +### Troubleshooting Maven + +This section describes some problems you might experience using Maven and how to resolve or work around them. + +| Problem | Description | Solution | +|:------------------------------------|:-------------|:------------| +| Files could not be retrieved | You are behind a firewall and get an error stating that repository metadata for org.mule.tools could not be retrieved from the central repository.|Check the proxy settings in your Maven settings.xml file to confirm that they are configured correctly.| +|OutOfMemory Error | You encounter OutOfMemoryError exceptions when attempting a full build of Mule.| Increasing the max heap and the PermGen space sizes. To do so, either export a MAVEN_OPTS variable in your shell, or add the variable to the original mvn script. Use the following: `MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=256m` | +|Slow build | - |If you know your downloads are up-to-date, you can use the offline option using the following command: `mvn -o` | +| Conflicting transitive dependencies | Transitive dependencies in m2 are both powerful and problematic at times. For example, you many have conflicting library versions or when unwanted libraries are in your classpath.| Use the debug option to display the effective classpath in a tree format, making it easy to see where each library is coming from: `mvn -x` | +| Running a goal for a specific project| By default, Maven execute a goal for a project and all sub-projects in its hierarchy. | If you want to run the goal for a specific project only (and not its children), you can use the non-recursive option: `mvn -N` | +| Debugging test failures | Surefire, the default Maven test runner, outputs all reports as a set of XML and text files. Any test failure details and stack traces are written to those files instead of the console, so it can be time consuming to open files to find problems. | You can redirect the output to the console temporarily by adding the following option: `mvn -Dsurefire.useFile=false`. This option skips creation ofthe text report, but still makes the XML report available for transformation by tools. | diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 000000000000..7aa3e6384b6b --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,315 @@ + +# Thank you! + +Really, thank you. Thank you for taking some of your precious time helping the Mule ESB project move forward. + +This guide will help you get started with Mule ESB's development environment. You'll also find the set of rules you're expected to follow in order to submit improvements and fixes to Mule ESB. + +In this guide you will find: + +- [Before you begin](#before-you-begin) + - [Getting to know better Mule](#getting-to-know-better-mule) + - [Visiting the community meeting points](#visiting-the-community-meeting-points) + - [Understanding the extension mechanisms](#understanding-the-extension-mechanisms) +- [Setting up the development environment](#setting-up-the-development-environment) + - [Installing Prerequisites](#installing-prerequisites) + - [Getting the Source Code](#getting-the-source-code) +- [Configuring the IDE](#configuring-the-ide) + - [Working with Eclipse](#working-with-eclipse) + - [Working with IntelliJ IDEA](#working-with-intellij-idea) +- [Developing your contribution](#developing-your-contribution) + - [Creating your topic branch](#creating-your-topic-branch) + - [Updating Your topic Branch](#updating-your-topic-branch) + - [Submitting a Pull Request](#submitting-a-pull-request) +- [Summary](#summary) + +----------------------------------------------------------------------------- + + +# Before you begin +Mule is a powerful and complex project. Before contributing to the Mule source code, it's important to understand the domain of the enterprose integration, Mule ESB from the user point of view and the different mechanisms to extend Mule. + +## Getting to know better Mule +There are a number of sources you can use to understand better Mule and its forthcoming features: + +- MuleSoft's [blog](http://blogs.mulesoft.org/). The fastest way of knowing about new features in mule. +- [@MuleSoft](https://twitter.com/MuleSoft)'s twitter account. You might also want to check the [#MuleESB](https://twitter.com/hashtag/MuleESB) hashtag. +- [Mule User Guide](http://www.mulesoft.org/documentation/display/current/Mule+User+Guide), the official documentation around usage of Mule ESB. +- The books [Mule in Action 2ed](http://www.manning.com/dossot2/) and [Getting Started with Mule Cloud Connect](http://shop.oreilly.com/product/0636920025726.do). Both are excelent resources to understand how to use and extend Mule. + + +## Visiting the community meeting points + +If you are here reading this document, you probably have already in mind a new feature or a bug fix to work on. This is great, however there could be other members of the communiry with the same idea. + +Before you begin, please take a few minutes to review community meeting points to make sure someone else hasn't already taken on your challenge: + +1. Review [existing JIRAs](http://www.mulesoft.org/jira/browse/MULE) to see if a bug has already been logged. +2. Follow the [Mule forum](http://forum.mulesoft.org/mulesoft) chatter to see if anyone else has begun to resolve the problem or initiate the improvement. +3. Scan [StackOverflow](http://stackoverflow.com/questions/tagged/mule) to see if there is already a proposed solution for your problem. +If, in the above-listed resources, no-one else has initiated your improvement or fix, log the issue by creating a [Mule JIRA](http://www.mulesoft.org/jira/browse/MULE). JIRA issues a identifier for your issue; keep this handy as you will use it to create a branch later if you decide to fix it yourself. + +## Understanding the extension mechanisms + +Mule ESB has two different extension mechanisms for writting modules and connectors. Avoiding to add functionality to this project and rather use one of those mechanisms to extend Mule is probably the more favorable option. + +It is therefor important to understand those two extension mechanisms. The first and more intuitive mechanism for extensions is the [Anypoint Connector DevKit](http://www.mulesoft.org/documentation/display/current/Anypoint+Connector+DevKit), an annotation based framework for easy construction of extesions. The second choice is to extend mule through the [Extensions](http://www.mulesoft.org/documentation/display/current/Extending) mechanism. + +Now we should undestand Mule and the enterprise integration domain. At the same time we should know the different extension mechanisms of Mule. + + +# Setting up the development environment + +While getting ready to contribute to any piece of software we will need to install number of prerequisites, we will need also to obtain the preexisting source code there could be. In this section we will follow some installation steps for the prerequisites and also we will download the source code. + +## Installing Prerequisites + +Before you get started, you need to set yourself up with an environment in which to develop Mule. Your dev environment needs three things: a Java SDK, a recent version of Maven, an integration development environment (IDE), and new branch of code to work on. + +### JDK + +1. If you are working with **Windows** or **Linux**, install one of the following [Java Development Kits](http://www.oracle.com/technetwork/java/javase/downloads/index.html) on your local drive. If you are working on a **Mac**, simply confirm that the JDK shipped with your Mac OS X the following is *Java SE Development Kit 7 (also known as Java SE 7u13)* or newer using the command `java -version`, then skip to step 4 below: +2. Create an environment variable called `JAVA_HOME`, setting it to the directory in which you installed the JDK. +3. Update the PATH environment variable so that it includes the path to JDK binaries. Add the following line to the PATH variable: + - Windows: `%JAVA_HOME%/bin` + - Linux or Mac OS X: `$JAVA_HOME/bin` +4. If you are using a Mac OS X, examine the contents of the `$JAVA_HOME/jre/lib/` security directory to confirm that the following two files are present: + - local_policy.jar + - US_export_policy.jar +These two files prevent any problems regarding cryptology. If not present, download the [Java Cryptology Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6.0](http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html), then copy the files into the security directory identified above. + +### Maven + +1. Download the Maven distribution from the [Maven web site](http://maven.apache.org/download.cgi), then unpack it to a convenient folder on your local drive. +2. Create an environment variable called `M2_HOME`, then set it to the folder into which you unpacked Maven. +3. Update the `PATH` environment variable to include the path to Maven binaries. + - Windows: add the following line to the `PATH` variable: `%M2_HOME%/bin` + - Mac or Linux: add the following line to the `PATH` variable: `$M2_HOME/bin` + + + +## Getting the Source Code + +Mule source code lives on Github. Complete the following procedure to locate the code and get it onto your local drive. + + +If you're new to Git, consider reading [Pro Git](http://git-scm.com/book) to absorb the basics. + Just want a Read-Only version of Mule source code? + +1. [Create](https://help.github.com/articles/signing-up-for-a-new-github-account) or log in to your github account. +2. If you haven't already done so, [set up git](https://help.github.com/articles/set-up-git) on your local drive. +3. Navigate to Mule's github page at: [https://github.com/mulesoft/mule.git](https://github.com/mulesoft/mule.git) +4. Click the Fork button at the top right corner of the page, then select your own git repository into which github inserts a copy of the repository. +5. Prepare to clone your forked Mule ESB repository from your github account to your local drive via a secure file transfer connection. As per git's recommendation, we advise using HTTPS to transfer the source code files to your local drive. However, if you prefer to establish a secure connection for transferring the files via SSH, follow git's procedure to [generate SSH keys](https://help.github.com/articles/generating-ssh-keys). +6. In the command line, create or navigate to an existing folder on your local drive into which you wish to store your forked clone of Mule source code. +7. From the command line, execute one of the following: + - For **HTTPS**: `git clone https://github.com//mule` + - For **SSH**: `git clone git@github.com:/.git` +8. Add the upstream repository so that you can pull changes and stay updated with changes to the mule-3.x (i.e. master) branch. From the command line, execute one of the following: + - For **HTTPS**: `git remote add upstream https://github.com/mulesoft/mule.git` + - For **SSH**: `git remote add upstream git@github.com:mulesoft/mule.git` + +## Understanding the build +This is an excelent moment to read the guide to [build Mule](BUILD.md). A correct understanding of how the Mule project is organized and build is key for a productive development. + +We are ready to develop our improvements. However, instead of doing it manually we may want to configure an IDE for better productivity. We will do it in the next section. + +# Configuring the IDE + +This section offers tips for importing and working on Mule source code in **Eclipse** or **IntelliJ IDEA**. There are no restrictions on the type of integration development environment you use to develop Mule, we simply chose to discuss the above-listed three as common IDEs. + +### Working with Eclipse + +An open-source integration development platform, use Eclipse to modify or add to your cloned version of Mule source code. + +#### Importing + +1. Download and install [Eclipse](http://www.eclipse.org/downloads/) on your local drive. +2. From the command line, in the directory into which you downloaded the Mule source code, enter the following command to generate the classpath and project files for each sub-project: `mvn eclipse:eclipse`. +3. Before launching Eclipse, make the Maven repository known in Eclipse using the following command: `mvn -Declipse.workspace=/path/to/eclipse/workspace eclipse:configure-workspace`. +4. Launch Eclipse, selecting the workspace you just "mavenized". +5. Select **File > Import**. +6. In the **Import** wizard, click to expand the **General** folder, then select **Existing Projects into Workspace**, then click **Next**. +7. In the **Select root directory** field, use the **Browse** button to navigate to the directory into which you downloaded the cloned fork of Mule source code from your Github account. +8. Ensure all **Projects** are checked, then click **Finish**. Eclipse imports the mule source code. +9. Open source code files as you need to edit or add content. +10. Click the **Save icon to save locally. + +#### Debugging + +You can debug following these steps. There is also a more in-depth guide avaiable in the [Mule documentation site](http://www.mulesoft.org/documentation/display/current/Step+Debugging). + +1. In Eclipse, select **Window > Open Perspective > Other...**, then select **Java** to open the Java Perspective. +2. Select **File > New > Java Project**. You are creating a new project just for launching Mule. +3. In the **New Java Project wizard**, select a **Name** for your project, such as Mule Launcher, then click **Next**. +4. In the **Java Settings** panel of the wizard, select the **Projects** tab, then click **Add**. +5. Click **Select All**, then click **OK**, then **Finish**. +6. In the Package Explorer, right click your launcher project's name, then select **Debug As > Debug Configurations...** +7. In the **Debug Configurations** wizard, double-click **Java Application**. +8. In the **Main class** field, enter the following content: `org.mule.MuleServer` +9. Click the **Arguments** tab. In the **Program Arguments** field, enter the following content: `-config ` +10. Click **Apply**, then click **Debug**. +11. Eclipse requests permission to switch to the **Debug Perspective**; click **Yes** to accept and open. + +You can now set breakpoints anywhere in any of the Java files in any of the Mule projects in the workspace. When you change java files and rebuild, the debugger hot swaps the rebuilt Java class file to the running Mule server. Note that you only need to follow the procedure above to set your Debug configurations once; thereafter, simply right-click the project name, then select **Debug As > Java Application** for subsequent debugging. + +#### Debugging Remotely + +1. From the command line, edit the `JPDA_OPTS` variable in the Mule startup script and specify the debugger port. +2. Start the Mule server with the `-debug` switch. The server waits until a debugger attaches. +3. In the Package Explorer in studio, right-click your Mule source code project's name, then select ***Debug > Debug Configurations...*** +4. Double-click ***Remote Java Application***. +5. Under ***Connection Properties***, enter a value for ***Host*** and ***Port***, then click ***Apply***. +6. Click Debug. Eclipse requests permission to switch to the ***Debug Perspective***; click ***Yes*** to accept and open. + +#### Testing + +Use Maven to run unit test on your project using the following command: `mvn test`. + +In addition to the unit tests for each sub-project, the Mule parent project has a separate sub-project containing integration tests. These tests verify "macroscopic" functionality that could not be tested by any single sub-project alone. + +#### Setting Eclipse Startup Parameters + +The table below lists a number of command-line parameters you can use to alter Eclipse's startup behavior, if you wish. + +| Parameter | Action | +|:------------------|:---------------------------------------------------| +| `-clean` | enables clean registration of plug-in (some plug-ins do not always register themselves properly after a restart) | +| `-nosplash` | does not show Eclipse or plug-in splash screens | +| `-showLocation` | allows you to explicitly set which JDK to use | +| `-vm` | examples that come with the full Mule distribution | +| `-vmargs` | allows you to pass in standard VM arguments | + + +### Working with IntelliJ IDEA + +Use IntelliJ's IDEA integration platform to modify or add to your cloned Mule source code. + +#### Importing + +1. [Download](http://www.jetbrains.com/idea/download/) and install IntelliJ IDEA. +2. Open IDEA, then select ***File > Open...*** +3. Browse to the directory into which you downloaded the Mule source code, then select the `pom.xml` file. +4. Click ***OK***. IDEA takes awhile to process all the pom.xml files. +5. Set the correct source for the JDK on your local drive. Right click the ***mule-transport-jdbc*** directory, then select **Module Settings > Sources > src > main > jdk6** or **jdk7**. Repeat this step for test sources, as tests. + +##### Troubleshooting + +If you IDEA presents any compilation errors in test classes from the CXF module when you create the project, it is safe to ignore them. Those classes depend on some test classes generated by the Maven build during execution. Right click the error message, then select **Exclude from compile**. Alternatively, you can run `mvn install` from the command line to fix the errors. + +#### Debugging Remotely + +You can debug following these steps. There is also a more in-depth guide avaiable in the [Mule documentation site](http://www.mulesoft.org/documentation/display/current/Step+Debugging). + +1. Start the Mule server with the `-debug` switch. The server waits until a debugger attaches. +2. In IDEA, select **Run > Edit Configurations...** to open the **Run/Debug Configurations** window. +3. Click **Add New Configuration** (plus sign), then select **Remote**. +4. Enter a **name** for the configuration, then update the **host** and **port** values if required (You can use the default values, localhost:5005, for debugging a local mule instance). +5. Click **OK** to start the debugging session. + +#### Testing + +Use Maven to run unit tests on your project using the following command: `mvn test`. + +In addition to the unit tests for each sub-project, the Mule parent project has a separate sub-project containing integration tests. These tests verify "macroscopic" functionality that could not be tested by any single sub-project alone. + +We finally have everything ready to start writting code. Lets start with the code and also learn how to commit it in the next section. + + +# Developing your contribution + +Working directly on the master version of Mule source code would likely result in merge conflicts with the original master. Instead, as a best practice for contributing to source code, work on your project in a feature branch. + +## Creating your feature branch + +In order to create our feature branch we should follow these steps: + +1. From your local drive, create a new branch in which you can work on your bug fix or improvement using the following command: +`git branch yourJIRAissuenumber`. +2. Switch to the new branch using the followcing ommand: +`git checkout yourJIRAissuenumber`. + +Now we should be able to make our very first compilation of the Mule ESB source code. We just need to instruct Maven to download all the dependent libraries and compile the project, you can do so execution the following command Within the directory into which you cloned the Mule source code: `mvn -DskipTests install`. + +Note that if this is your first time using Maven, the download make take several minutes to complete. + +> ** Windows and the local Maven repository ** +> In Windows, Maven stores the libraries in the .m2 repository in your home directory. For example, `C:\Documents and Settings\\.m2\repository`. Because Java RMI tests fail where a directory name includes spaces, you must move the Maven local repository to a directory with a name that does not include spaces, such as `%M2_HOME%/conf` or `%USERPROFILE%/.m2` + +Now that you're all set with a local development environment and your own branch of Mule source code, you're ready get kicking! The following steps briefly outline the development lifecycle to follow to develop and commit your changes in preparation for submission. + +1. If you are using an IDE, make sure you read the previous section about [IDE configuration](#configuring-the-ide). +2. Review the [Mule Coding Style](STYLE.md) documentation to ensure you adhere to source code standards, thus increasing the likelihood that your changes will be merged with the `mule-3.x` (i.e. master) source code. +3. Import the Mule source code project into your IDE (if you are using one), then work on your changes, fixes or improvements. +4. Debug and test your local version, resolving any issues that arise. +5. Save your changes locally. +6. Prepare your changes for a Pull Request by first squashing your changes into a single commit on your branch using the following command: +`git rebase -i mule3.x`. +7. Push your squashed commit to your branch on your github repository. Refer to [Git's documentation](http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository) for details on how to commit your changes. +8. Regularly update your branch with any changes or fixes applied to the mule-3.x branch. Refer to details below. + +## Updating Your feature Branch + +To ensure that your cloned version of Mule source code remains up-to-date with any changes to the mule-3.x (i.e. master) branch, regularly update your branch to rebase off the latest version of the master. + +1. Pull the latest changes from the "upstream" master mule-3.x branch using the following commands: + +```shell +git fetch upstream +git fetch upstream --tags +``` +2. Ensure you are working with the master branch using the following command: + +```shell +git checkout mule-3.x +``` +3. Merge the latest changes and updates from the master branch to your feature branch using the following command: + +```shell +git merge upstream/mule-3.x +``` +4. Push any changes to the master to your forked clone using the following commands: + +```shell +git push origin mule-3.x +git push origin --tags +``` +5. Access your feature branch once again (to continue coding) using the following command: + +```shell +git checkout dev/yourreponame/bug/yourJIRAissuenumber +``` +6. Rebase your branch from the latest version of the master branch using the following command: + +```shell +git rebase mule-3.x +``` +7. Resolve any conflicts on your feature branch that may appear as a result of the changes to mule-3.x (i.e. master). +8. Push the newly-rebased branch back to your fork on your git repository using the following command: + +```shell +git push origin dev/yourreponame/bug/yourJIRAissuenumber -f +``` + +## Submitting a Pull Request + +Ready to submit your patch for review and merging? Initiate a pull request in github! + +1. Review the [MuleSoft Contributors' Agreement](http://www.mulesoft.org/legal/contributor-agreement.html). +2. From the repo of your branch, click the Pull Request button. +3. In the Pull Request Preview dialog, enter a title and optional description of your changes, review the commits that form part of your pull request, then click Send Pull Request (Refer to github's [detailed instructions](https://help.github.com/articles/using-pull-requests) for submitting a pull request). +4. Mule's core dev team reviews the pull request and may initiate discussion or ask questions about your changes in a Pull Request Discussion. The team can then merge your commits with the master where appropriate. +5. If you have made changes or corrections to your commit after having submitted the pull request, go back to the Pull Request page and update the Commit Range (via the Commits tab), rather than submitting a new pull request. + +# Summary + +This guide started with pointing to different [sources of information](#getting-to-know-better-mule) around Mule and the Mule's [community meeting points](#visiting-the-community-meeting-points) on the net. These were useful to understand were Mule is moving to and to have contact mechanisms with the rest of the community for help or discussion. + +In order to set up our [development environment](#setting-up-the-development-environment) we got to [install some prerequisites](#installing-prerequisites). Once we had them ready, we downloaded the [source code](#getting-the-source-code). + +At that point we were almost ready to develop improvements, we just needed to [configured our favourite IDE](#configuring-the-ide) to develop or debug Mule code. + +Then we were finally ready to [develop our contribution](#developing-your-contribution). We created our very own [feature branch](#creating-your-topic-branch) were we'll develop our improvement, then we learnt how to [keep it updated](#updating-your-topic-branch) in order to be able to submit a [pull request](#submitting-a-pull-request) to the main Mule ESB repository + +Thank you one more time for taking some time understanding how to contribute to Mule ESB. + diff --git a/I18N.md b/I18N.md new file mode 100644 index 000000000000..5e1538f0532a --- /dev/null +++ b/I18N.md @@ -0,0 +1,29 @@ +# Internationalization Guidelines + +There are two levels of internationalization functionality in Mule. + +- **Level 1** Core Internationalization Support +Java provides basic internationalization functions in the language and bundled libraries. Mule supports message conversion by the specified encoding in metadata and configuration files. +- **Level 2** Message Catalog +Mule supports a locale-based message catalog. + +## Encoding Priority + +When writing code, respect the following priority order: + +1. encoding in metadata (HTTP headers, Mail headers, etc.) +2. encoding in the configuration file +3. hard-coded default encoding or platform default encoding + +## Byte Stream Conversion + +Conversion between string and byte stream is locale-sensitive. If you write code for byte stream conversion, carefully consider the encoding you use. + +The following lists typically misused APIs. + +- **Incorrect**: `String#getBytes()`. **Correct**: Use `String#getBytes(String charsetName)` if you handle non-ASCII strings. +- **Incorrect**: `String#String(byte[] bytes)`. **Correct**: Use `String(byte[] bytes, String charsetName)` if you handle non-ASCII byte stream. The following constructors are not friendly to internationalization and should be avoided. + - `String(byte ascii[], int hibyte, int offset, int count);` + - `String(byte ascii[], int hibyte);` + - `String(byte bytes[], int offset, int length);` +- **Incorrect**: InputStreamReader#InputStreamReader(InputStream in) and Friends. **Correct**: Use `InputStreamReader(InputStream in, String charsetName)` if you handle non-ASCII byte stream. If you use subclasses of Reader and Writer, use a constructor with charsetName (we consider charsetName as encoding name in this context). diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 000000000000..a24a93a12114 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,492 @@ +Mule ESB is distributed under the terms of the Common Public Attribution +License (CPAL), whose definition follows below. For information on the license +type for each third-party software product used by Mule, refer to +http://www.mulesoft.org/documentation/display/MULE3INTRO/Third-party+Software+in+Mule + + +Common Public Attribution License Version 1.0 (CPAL) + + +1. "Definitions" + +1.0.1 "Commercial Use" means distribution or otherwise making the Covered +Code available to a third party. + +1.1 "Contributor" means each entity that creates or contributes to the creation +of Modifications. + +1.2 "Contributor Version" means the combination of the Original Code, prior +Modifications used by a Contributor, and the Modifications made by that +particular Contributor. + +1.3 "Covered Code" means the Original Code or Modifications or the combination +of the Original Code and Modifications, in each case including portions +thereof. + +1.4 "Electronic Distribution Mechanism" means a mechanism generally accepted in +the software development community for the electronic transfer of data. + +1.5 "Executable" means Covered Code in any form other than Source Code. + +1.6 "Initial Developer" means the individual or entity identified as the Initial +Developer in the Source Code notice required by Exhibit A. + +1.7 "Larger Work" means a work which combines Covered Code or portions thereof +with code not governed by the terms of this License. + +1.8 "License" means this document. + +1.8.1 "Licensable" means having the right to grant, to the maximum extent +possible, whether at the time of the initial grant or subsequently acquired, any +and all of the rights conveyed herein. + +1.9 "Modifications" means any addition to or deletion from the substance or +structure of either the Original Code or any previous Modifications. When +Covered Code is released as a series of files, a Modification is: + +A. Any addition to or deletion from the contents of a file containing Original +Code or previous Modifications. + +B. Any new file that contains any part of the Original Code or previous +Modifications. + +1.10 "Original Code" means Source Code of computer software code which is +described in the Source Code notice required by Exhibit A as Original Code, and +which, at the time of its release under this License is not already Covered Code +governed by this License. + +1.10.1 "Patent Claims" means any patent claim(s), now owned or hereafter +acquired, including without limitation, method, process, and apparatus claims, +in any patent Licensable by grantor. + +1.11 "Source Code" means the preferred form of the Covered Code for making +modifications to it, including all modules it contains, plus any associated +interface definition files, scripts used to control compilation and installation +of an Executable, or source code differential comparisons against either the +Original Code or another well known, available Covered Code of the Contributor's +choice. The Source Code can be in a compressed or archival form, provided the +appropriate decompression or de-archiving software is widely available for no +charge. + +1.12 "You" (or "Your") means an individual or a legal entity exercising +rights under, and complying with all of the terms of, this License or a future +version of this License issued under Section 6.1. For legal entities, "You" +includes any entity which controls, is controlled by, or is under common control +with You. For purposes of this definition, "control" means (a) the power, direct +or indirect, to cause the direction or management of such entity, whether by +contract or otherwise, or (b) ownership of more than fifty percent (50%) of the +outstanding shares or beneficial ownership of such entity. + +2. Source Code License. + +2.1 The Initial Developer Grant. +The Initial Developer hereby grants You a world-wide, royalty-free, +non-exclusive license, subject to third party intellectual property claims: + +(a) under intellectual property rights (other than patent or trademark) +Licensable by Initial Developer to use, reproduce, modify, display, perform, +sublicense and distribute the Original Code (or portions thereof) with or +without Modifications, and/or as part of a Larger Work; and + +(b) under Patents Claims infringed by the making, using or selling of +Original Code, to make, have made, use, practice, sell, and offer for sale, +and/or otherwise dispose of the Original Code (or portions thereof). + +(c) the licenses granted in this Section 2.1(a) and (b) are effective on the +date Initial Developer first distributes Original Code under the terms of this +License. + +(d) Notwithstanding Section 2.1(b) above, no patent license is granted: 1) +for code that You delete from the Original Code; 2) separate from the Original +Code; or 3) for infringements caused by: i) the modification of the Original +Code or ii) the combination of the Original Code with other software or +devices. + +2.2 Contributor Grant. + +Subject to third party intellectual property claims, each Contributor hereby +grants You a world-wide, royalty-free, non-exclusive license + +(a) under intellectual property rights (other than patent or trademark) +Licensable by Contributor, to use, reproduce, modify, display, perform, +sublicense and distribute the Modifications created by such Contributor (or +portions thereof) either on an unmodified basis, with other Modifications, as +Covered Code and/or as part of a Larger Work; and + +(b) under Patent Claims infringed by the making, using, or selling of +Modifications made by that Contributor either alone and/or in combination with +its Contributor Version (or portions of such combination), to make, use, sell, +offer for sale, have made, and/or otherwise dispose of: 1) Modifications made +by that Contributor (or portions thereof); and 2) the combination of +Modifications made by that Contributor with its Contributor Version (or portions +of such combination). + +(c) the licenses granted in Sections 2.2(a) and 2.2(b) are effective on the +date Contributor first makes Commercial Use of the Covered Code. + +(d) Notwithstanding Section 2.2(b) above, no patent license is granted: 1) +for any code that Contributor has deleted from the Contributor Version; 2) +separate from the Contributor Version; 3) for infringements caused by: i) third +party modifications of Contributor Version or ii) the combination of +Modifications made by that Contributor with other software (except as part of +the Contributor Version) or other devices; or 4) under Patent Claims infringed +by Covered Code in the absence of Modifications made by that Contributor. + +3. Distribution Obligations. + +3.1 Application of License. +The Modifications which You create or to which You contribute are governed by +the terms of this License, including without limitation Section 2.2. The Source +Code version of Covered Code may be distributed only under the terms of this +License or a future version of this License released under Section 6.1, and You +must include a copy of this License with every copy of the Source Code You +distribute. You may not offer or impose any terms on any Source Code version +that alters or restricts the applicable version of this License or the +recipients' rights hereunder. However, You may include an additional document +offering the additional rights described in Section 3.5. + +3.2 Availability of Source Code. +Any Modification which You create or to which You contribute must be made +available in Source Code form under the terms of this License either on the same +media as an Executable version or via an accepted Electronic Distribution +Mechanism to anyone to whom you made an Executable version available; and if +made available via Electronic Distribution Mechanism, must remain available for +at least twelve (12) months after the date it initially became available, or at +least six (6) months after a subsequent version of that particular Modification +has been made available to such recipients. You are responsible for ensuring +that the Source Code version remains available even if the Electronic +Distribution Mechanism is maintained by a third party. + +3.3 Description of Modifications. +You must cause all Covered Code to which You contribute to contain a file +documenting the changes You made to create that Covered Code and the date of any +change. You must include a prominent statement that the Modification is +derived, directly or indirectly, from Original Code provided by the Initial +Developer and including the name of the Initial Developer in (a) the Source +Code, and (b) in any notice in an Executable version or related documentation in +which You describe the origin or ownership of the Covered Code. + +3.4 Intellectual Property Matters + +(a) Third Party Claims. +If Contributor has knowledge that a license under a third party's intellectual +property rights is required to exercise the rights granted by such Contributor +under Sections 2.1 or 2.2, Contributor must include a text file with the Source +Code distribution titled "LEGAL" which describes the claim and the party making +the claim in sufficient detail that a recipient will know whom to contact. If +Contributor obtains such knowledge after the Modification is made available as +described in Section 3.2, Contributor shall promptly modify the LEGAL file in +all copies Contributor makes available thereafter and shall take other steps +(such as notifying appropriate mailing lists or newsgroups) reasonably +calculated to inform those who received the Covered Code that new knowledge has +been obtained. + +(b) Contributor APIs. +If Contributor's Modifications include an application programming interface and +Contributor has knowledge of patent licenses which are reasonably necessary to +implement that API, Contributor must also include this information in the LEGAL +file. + +(c) Representations. +Contributor represents that, except as disclosed pursuant to Section 3.4(a) +above, Contributor believes that Contributor's Modifications are Contributor's +original creation(s) and/or Contributor has sufficient rights to grant the +rights conveyed by this License. + +3.5 Required Notices. +You must duplicate the notice in Exhibit A in each file of the Source Code. If +it is not possible to put such notice in a particular Source Code file due to +its structure, then You must include such notice in a location (such as a +relevant directory) where a user would be likely to look for such a notice. If +You created one or more Modification(s) You may add your name as a Contributor +to the notice described in Exhibit A. You must also duplicate this License in +any documentation for the Source Code where You describe recipients' rights or +ownership rights relating to Covered Code. You may choose to offer, and to +charge a fee for, warranty, support, indemnity or liability obligations to one +or more recipients of Covered Code. However, You may do so only on Your own +behalf, and not on behalf of the Initial Developer or any Contributor. You must +make it absolutely clear than any such warranty, support, indemnity or liability +obligation is offered by You alone, and You hereby agree to indemnify the +Initial Developer and every Contributor for any liability incurred by the +Initial Developer or such Contributor as a result of warranty, support, +indemnity or liability terms You offer. + +3.6 Distribution of Executable Versions. +You may distribute Covered Code in Executable form only if the requirements of +Section 3.1-3.5 have been met for that Covered Code, and if You include a notice +stating that the Source Code version of the Covered Code is available under the +terms of this License, including a description of how and where You have +fulfilled the obligations of Section 3.2. The notice must be conspicuously +included in any notice in an Executable version, related documentation or +collateral in which You describe recipients' rights relating to the Covered +Code. You may distribute the Executable version of Covered Code or ownership +rights under a license of Your choice, which may contain terms different from +this License, provided that You are in compliance with the terms of this License +and that the license for the Executable version does not attempt to limit or +alter the recipient's rights in the Source Code version from the rights set +forth in this License. If You distribute the Executable version under a +different license You must make it absolutely clear that any terms which differ +from this License are offered by You alone, not by the Initial Developer, +Original Developer or any Contributor. You hereby agree to indemnify the +Initial Developer, Original Developer and every Contributor for any liability +incurred by the Initial Developer, Original Developer or such Contributor as a +result of any such terms You offer. + +3.7 Larger Works. +You may create a Larger Work by combining Covered Code with other code not +governed by the terms of this License and distribute the Larger Work as a single +product. In such a case, You must make sure the requirements of this License are +fulfilled for the Covered Code. + +4. Inability to Comply Due to Statute or Regulation. +If it is impossible for You to comply with any of the terms of this License with +respect to some or all of the Covered Code due to statute, judicial order, or +regulation then You must: (a) comply with the terms of this License to the +maximum extent possible; and (b) describe the limitations and the code they +affect. Such description must be included in the LEGAL file described in +Section 3.4 and must be included with all distributions of the Source Code. +Except to the extent prohibited by statute or regulation, such description must +be sufficiently detailed for a recipient of ordinary skill to be able to +understand it. + +5. Application of this License. +This License applies to code to which the Initial Developer has attached the +notice in Exhibit A and to related Covered Code. + +6. Versions of the License. + +6.1 New Versions. +MuleSoft, Inc. ("MuleSoft") may publish revised and/or new versions of the +License from time to time. Each version will be given a distinguishing version +number. + +6.2 Effect of New Versions. +Once Covered Code has been published under a particular version of the License, +You may always continue to use it under the terms of that version. You may also +choose to use such Covered Code under the terms of any subsequent version of the +License published by MuleSoft. No one other than MuleSoft has the right to +modify the terms applicable to Covered Code created under this License. + +6.3 Derivative Works. +If You create or use a modified version of this License (which you may only do +in order to apply it to code which is not already Covered Code governed by this +License), You must (a) rename Your license so that the phrases "MuleSoft", +"CPAL" or any confusingly similar phrase do not appear in your license (except +to note that your license differs from this License) and (b) otherwise make it +clear that Your version of the license contains terms which differ from the +CPAL. (Filling in the name of the Initial Developer, Original Developer, +Original Code or Contributor in the notice described in Exhibit A shall not of +themselves be deemed to be modifications of this License.) + +7. DISCLAIMER OF WARRANTY. +COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS" BASIS, WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT +LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS, MERCHANTABLE, +FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE +QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED CODE +PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL DEVELOPER, ORIGINAL +DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, +REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART +OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER +THIS DISCLAIMER. + +8. TERMINATION. + +8.1 This License and the rights granted hereunder will terminate automatically +if You fail to comply with terms herein and fail to cure such breach within 30 +days of becoming aware of the breach. All sublicenses to the Covered Code which +are properly granted shall survive any termination of this License. Provisions +which, by their nature, must remain in effect beyond the termination of this +License shall survive. + +8.2 If You initiate litigation by asserting a patent infringement claim +(excluding declatory judgment actions) against Initial Developer, Original +Developer or a Contributor (the Initial Developer, Original Developer or +Contributor against whom You file such action is referred to as "Participant") +alleging that: + +(a) such Participant's Contributor Version directly or indirectly infringes +any patent, then any and all rights granted by such Participant to You under +Sections 2.1 and/or 2.2 of this License shall, upon 60 days notice from +Participant terminate prospectively, unless if within 60 days after receipt of +notice You either: (i) agree in writing to pay Participant a mutually agreeable +reasonable royalty for Your past and future use of Modifications made by such +Participant, or (ii) withdraw Your litigation claim with respect to the +Contributor Version against such Participant. If within 60 days of notice, a +reasonable royalty and payment arrangement are not mutually agreed upon in +writing by the parties or the litigation claim is not withdrawn, the rights +granted by Participant to You under Sections 2.1 and/or 2.2 automatically +terminate at the expiration of the 60 day notice period specified above. + +(b) any software, hardware, or device, other than such Participant's +Contributor Version, directly or indirectly infringes any patent, then any +rights granted to You by such Participant under Sections 2.1(b) and 2.2(b) are +revoked effective as of the date You first made, used, sold, distributed, or had +made, Modifications made by that Participant. + +8.3 If You assert a patent infringement claim against Participant alleging that +such Participant's Contributor Version directly or indirectly infringes any +patent where such claim is resolved (such as by license or settlement) prior to +the initiation of patent infringement litigation, then the reasonable value of +the licenses granted by such Participant under Sections 2.1 or 2.2 shall be +taken into account in determining the amount or value of any payment or +license. + +8.4 In the event of termination under Sections 8.1 or 8.2 above, all end user +license agreements (excluding distributors and resellers) which have been +validly granted by You or any distributor hereunder prior to termination shall +survive termination. + +9. LIMITATION OF LIABILITY. +UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING +NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ORIGINAL +DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR ANY +SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY INDIRECT, +SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, +WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER +FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN +IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS +LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL +INJURY RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE LAW +PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR +LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION AND +LIMITATION MAY NOT APPLY TO YOU. + +10. U.S. GOVERNMENT END USERS. +The Covered Code is a "commercial item," as that term is defined in 48 C.F.R. +2.101 (Oct. 1995), consisting of "commercial computer software" and "commercial +computer software documentation," as such terms are used in 48 C.F.R. 12.212 +(Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through +227.7202-4 (June 1995), all U.S. Government End Users acquire Covered Code with +only those rights set forth herein. + +11. MISCELLANEOUS. +This License represents the complete agreement concerning subject matter hereof. +If any provision of this License is held to be unenforceable, such provision +shall be reformed only to the extent necessary to make it enforceable. This +License shall be governed by California law provisions (except to the extent +applicable law, if any, provides otherwise), excluding its conflict-of-law +provisions. With respect to disputes in which at least one party is a citizen +of, or an entity chartered or registered to do business in the United States of +America, any litigation relating to this License shall be subject to the +jurisdiction of the Federal Courts of the Northern District of California, with +venue lying in Santa Clara County, California, with the losing party responsible +for costs, including without limitation, court costs and reasonable attorneys' +fees and expenses. The application of the United Nations Convention on Contracts +for the International Sale of Goods is expressly excluded. Any law or +regulation which provides that the language of a contract shall be construed +against the drafter shall not apply to this License. + +12. RESPONSIBILITY FOR CLAIMS. +As between Initial Developer, Original Developer and the Contributors, each +party is responsible for claims and damages arising, directly or indirectly, out +of its utilization of rights under this License and You agree to work with +Initial Developer, Original Developer and Contributors to distribute such +responsibility on an equitable basis. Nothing herein is intended or shall be +deemed to constitute any admission of liability. + +13. MULTIPLE-LICENSED CODE. +Initial Developer may designate portions of the Covered Code as +Multiple-Licensed. Multiple-Licensed means that the Initial Developer permits +you to utilize portions of the Covered Code under Your choice of the CPAL or the +alternative licenses, if any, specified by the Initial Developer in the file +described in Exhibit A. + +14. ADDITIONAL TERM: ATTRIBUTION + +(a) As a modest attribution to the organizer of the development of the +Original Code ("Original Developer"), in the hope that its promotional value may +help justify the time, money and effort invested in writing the Original Code, +the Original Developer may include in Exhibit B ("Attribution Information") a +requirement that each time an Executable and Source Code or a Larger Work is +launched or initially run (which includes initiating a session), a prominent +display of the Original Developer's Attribution Information (as defined below) +must occur on the graphic user interface employed by the end user to access such +Covered Code (which may include display on a splash screen), if any. The size +of the graphic image should be consistent with the size of the other elements of +the Attribution Information. If the access by the end user to the Executable and +Source Code does not create a graphic user interface for access to the Covered +Code, this obligation shall not apply. If the Original Code displays such +Attribution Information in a particular form (such as in the form of a splash +screen, notice at login, an "about" display, or dedicated attribution area on +user interface screens), continued use of such form for that Attribution +Information is one way of meeting this requirement for notice. + +(b) Attribution information may only include a copyright notice, a brief +phrase, graphic image and a URL ("Attribution Information") and is subject to +the Attribution Limits as defined below. For these purposes, prominent shall +mean display for sufficient duration to give reasonable notice to the user of +the identity of the Original Developer and that if You include Attribution +Information or similar information for other parties, You must ensure that the +Attribution Information for the Original Developer shall be no less prominent +than such Attribution Information or similar information for the other party. +For greater certainty, the Original Developer may choose to specify in Exhibit B +below that the above attribution requirement only applies to an Executable and +Source Code resulting from the Original Code or any Modification, but not a +Larger Work. The intent is to provide for reasonably modest attribution, +therefore the Original Developer cannot require that You display, at any time, +more than the following information as Attribution Information: (a) a copyright +notice including the name of the Original Developer; (b) a word or one phrase +(not exceeding 10 words); (c) one graphic image provided by the Original +Developer; and (d) a URL (collectively, the "Attribution Limits"). + +(c) If Exhibit B does not include any Attribution Information, then there +are no requirements for You to display any Attribution Information of the +Original Developer. + +(d) You acknowledge that all trademarks, service marks and/or trade names +contained within the Attribution Information distributed with the Covered Code +are the exclusive property of their owners and may only be used with the +permission of their owners, or under circumstances otherwise permitted by law or +as expressly set out in this License. + +15. ADDITIONAL TERM: NETWORK USE. +The term "External Deployment" means the use, distribution, or communication of +the Original Code or Modifications in any way such that the Original Code or +Modifications may be used by anyone other than You, whether those works are +distributed or communicated to those persons or made available as an application +intended for use over a network. As an express condition for the grants of +license hereunder, You must treat any External Deployment by You of the Original +Code or Modifications as a distribution under section 3.1 and make Source Code +available under Section 3.2. + + +EXHIBIT A. Common Public Attribution License Version 1.0. +"The contents of this file are subject to the Common Public Attribution License +Version 1.0 (the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at +http://www.MuleSoft.com/CPAL/. The License is based on the Mozilla Public +License Version 1.1 but Sections 14 and 15 have been added to cover use of +software over a computer network and provide for limited attribution for the +Original Developer. In addition, Exhibit A has been modified to be consistent +with Exhibit B. +Software distributed under the License is distributed on an "AS IS" basis, +WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the +specific language governing rights and limitations under the License. +The Original Code is MuleSoft Mule +The Initial Developer of the Original Code is MuleSoft Inc. All portions of +the code are Copyright (c) 2003-2009 MuleSoft Inc. All Rights Reserved. + +EXHIBIT B. Attribution Information +Subject to the limitations and other requirements in Section 14 of the License, +the Original Developer requires You to display the following Attribution +Information: + +Attribution Copyright Notice: Copyright (c) 2003-2009 MuleSoft Inc. +Attribution Phrase (not exceeding 10 words): Powered by Mule. MuleSoft is Open +for Integration. +Attribution URL: http://www.MuleSoft.com +Graphic Image provided in the Covered Code as file: +http://www.MuleSoft.com/images/mulesoft-logo.gif + + +Redistributions of the Covered Code in binary form or source code form, must +ensure that the first time the resulting executable program is launched, a user +interface, if any, shall include the attribution information set forth below +prominently. If the executable program does not launch a user interface, the +Company name and URL shall be included in the notice section of each file of the +Covered Code. : + +Display of Attribution Information is required in Larger Works which are defined +in the CPAL as a work which combines Covered Code or portions thereof with code +not governed by the terms of the CPAL. \ No newline at end of file diff --git a/README.md b/README.md index 1bfea10c7d0c..4cd744b14a0f 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Contribute ========== Mule is open source and we love contributions! If you have an idea for a great improvement or spy an issue you’re keen to fix, you can fork us on [github](https://github.com/mulesoft/mule). -No contribution is too small– providing feedback, [reporting issues](http://www.mulesoft.org/jira/browse/MULE) and participating in the [community forums](http://forum.mulesoft.org/mulesoft) is invaluable and extremely helpful for all our users. Please refer to our [contribution guidelines](http://www.mulesoft.org/documentation/display/current/Mule+Contributors+Guide) for details. +No contribution is too small– providing feedback, [reporting issues](http://www.mulesoft.org/jira/browse/MULE) and participating in the [community forums](http://forum.mulesoft.org/mulesoft) is invaluable and extremely helpful for all our users. Please refer to our [contribution guidelines](CONTRIBUTE.md) for details. diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 000000000000..68baf7fad311 --- /dev/null +++ b/STYLE.md @@ -0,0 +1,262 @@ +# Mule Java Coding Conventions + +As best practice for team development, Mule uses coding conventions to ensure that code is clean and consistent, and that developers are able to maintain efficient productivity. + +## Coding Conventions + +In general, Mule follows [Checkstyle](http://checkstyle.sourceforge.net/) conventions. Refer to this sample [checkstyle.xml](http://www.mulesoft.org/docs/checkstyle.xml) config file for further detail. + + +### JavaDoc Comments + +As per the example below, include the `JavadocType` and `JavadocMethod` accompained by `JavadocStyle`. We highly recommend including `PackageHtml`. + +```xml + + + + +``` + +### Naming Classes + +As per the example below, include all standard naming conventions. `AbstractClassName` (which enforces Abstract prefix or Factory suffix) and `ConstantName` (which enforces all CAPS) may be excluded. + +```xml + + + + + + + + + + +``` + +### Importing Clases + +As per the example below, include `AvoidStarImport`. Though it makes Java files long, it provides clear information about classes and their use. Further, include `IllegalImport`, `RedundantImport` and `UnusedImports`. + +```xml + + + + + +``` + +### File Size + +Include a methodLength check to ensure that files contain no more than 2000 lines and methods contain no more then 7 parameters. + +```xml + + + +``` + +### Whitespace + +As per the example below, set the `tabWidth` property to 4. + +```xml + + + + + + + + +``` + +### Modifier order + +To avoid redundant modifiers on interfaces and annotations, follow the order of the Java Language specification, as per the following example. + +```xml + + + +``` + +### Block checks + +As per the following example, ensure block checks are applied so that there are no empty blocks, and all blocks are contained within braces. + +```xml +<\!-\- [http://checkstyle.sf.net/config_blocks.html] \--> + + + + + + + + + +``` + +### Coding + +As per the following example, ensure your project meets these general coding conventions. + +```xml +<\!-\- [http://checkstyle.sf.net/config_coding.html] \--> + + + + + + + + + + + + +``` + +### Design + +As per the the following example, ensure your project enforces encapsulation and adheres to standard coding design. + +```xml +<\!-\- [http://checkstyle.sf.net/config_design.html] \--> + + + + + +``` + +### Miscellaneous +As per the following example below, ensure your project meets these miscellaneous coding conventions. + +```xml +<\!-\- [http://checkstyle.sf.net/config_misc.html] \--> + + + <\!-\- to the Checker \--> +``` + +## Source File Headers + +Ensure that all source files contain the following header. + +```java +/* + * Copyright (c) MuleSoft, Inc. All rights reserved. http://www.mulesoft.com + * The software in this package is published under the terms of the CPAL v1.0 + * license, a copy of which has been included with this distribution in the + * LICENSE.txt file. + */ +``` + +## Packages + +| Convention | Example | Notes | +|:--------------------------|:-------------|:-------------| +| Names representing packages should be in all lower case. | `org.mule.application` | Package naming convention used by Sun for the Java core packages. The initial package name representing the domain name must be in lower case. | +| Package names should be singular rather than plural. | `org.mule.transformer`, `org.mule.transport` | | +| The 'org.mule.api' package tree should be used for all interfaces that make up the API/SPI. | `org.mule.api.lifecycle.Callable` | | + + +## Interfaces/Classes + +| Convention | Example | Notes | +|:--------------------------|:-------------|:-------------| +| Names representing types must be nouns and written in mixed case starting with upper case. | `EsbMessage`, `OrderService` | Common practice in the Java development community and also the type naming convention used by Sun for the Java core packages. | +| Interface and class names should avoid abbreviations, be descriptive and be camel-cased. | `interface OrderService` +NOT: `interface OrderServ` | | +| Abstact classes should be prefixed with 'Abstract'. | `class AbstractOrderService implements OrderService` +NOT `class OrderServiceAbs implements OrderService` | | +| Exception class names should be suffixed with 'Exception' | `EngineFailureException extends Exception` +NOT: `EngineFailure extends Exception` | | +| Interface implementations should ideally be prefixed with something meaningful in the context. e.g. 'Simple', 'Generic' is possible. | `GenericLifeCycleManager`, `SingletonObjectFactory` | | +| Default interface implementations can be prefixed by 'Default'. | `class DefaultOrderService implements OrderService` +NOT: `class OrderServiceImpl implements OrderService` | It is not uncommon to create a simplistic class implementation of an interface providing default behaviour to the interface methods. The convention of prefixing these classes by Default has been adopted by Sun for the Java library. | +| Test classes should be suffixed with 'TestCase' | `LoanBrokerESBTestCase` | | + +## Methods/Variables + +| Convention | Example | Notes | +|:--------------------------|:-------------|:-------------| +| Variable names must be in mixed case starting with lower case. | `message`, `newOrder` | Common practice in the Java development community and also the naming convention for variables used by Sun for the Java core packages. Makes variables easy to distinguish from types, and effectively resolves potential naming collision as in the declaration Line line; | +| Names representing constants (final variables) must be all uppercase using underscore to separate words. | `MAX_ITERATIONS`, `COLOR_RED` | Common practice in the Java development community and also the naming convention used by Sun for the Java core packages. | +| Names representing methods must be verbs and written in mixed case starting with lower case. | `getName()`, `computeTotalWidth()` | Common practice in the Java development community and also the naming convention used by Sun for the Java core packages and the JavaBean specification. This is identical to variable names, but methods in Java are already distinguishable from variables by their specific form. | +| Abbreviations and acronyms should not be uppercase when used as name. | `exportHtmlSource();` NOT: `exportHTMLSource();` +`openDvdPlayer(); ` NOT: `openDVDPlayer();` | Using all uppercase for the base name will give conflicts with the naming conventions given above. A variable of this type whould have to be named dVD, hTML etc. which obviously is not very readable. Another problem is illustrated in the examples above; When the name is connected to another, the readability is seriously reduced; The word following the acronym does not stand out as it should. | +| Underscores and other special characters should NOT be used in variable names, method names or class names | `private String name;` NOT `private String name_;` | Often private member variables are given an underscore '_' prefix to denote it's private member status. Mule does not use this convention as Java Editors make the status of variables know through color coding. | +| Generic variables should have the same name as their type. | `void setTopic(Topic topic)` NOT: `void setTopic(Topic value)` NOT: `void setTopic(Topic aTopic)` NOT: `void setTopic(Topic t)` `void connect(Database database)` NOT: `void connect(Database db)` NOT: `void connect(Database oracleDB)` | Reduce complexity by reducing the number of terms and names used. Also makes it easy to deduce the type given a variable name only. If for some reason this convention doesn't seem to fit it is a strong indication that the type name is badly chosen. Non-generic variables have a role. These variables can often be named by combining role and type: Point startingPoint, centerPoint; Name loginName;| +|All names should be written in English.| | English is the preferred language for Mule development.| +| The terms get/set must be used where an attribute is accessed directly. | `employee.getName(); employee.setName(name); matrix.getElement(2, 4); matrix.setElement(2, 4, value);` | Common practice in the Java community and the convention used by Sun for the Java core packages and the JavaBean Specification. | +| `is` prefix should be used for boolean variables and methods.| `isSet`, `isVisible`, `isFinished`, `isFound`, `isOpen` | This is the naming convention for boolean methods and variables used by Sun for the Java core packages and the JavaBean specification. Using the is prefix solves a common problem of choosing bad boolean names like status or flag. isStatus or isFlag simply doesn't fit, and the programmer is forced to chose more meaningful names. | +| Negated boolean variable names must be avoided. | `boolean isError;` NOT: `boolean isNoError` boolean `isFound;` NOT: `isNotFound` | The problem arise when the logical not operator is used and double negative arises. It is not immediately apparent what !isNotError means.| +| Associated constants (final variables) should be prefixed by a common type name. | `final int COLOR_RED = 1; final int COLOR_GREEN = 2; final int COLOR_BLUE = 3;` | This indicates that the constants belong together, and what concept the constants represents. | + +## Imports + +In general, do not include star imports, and ensure that you sort all imports alphabetically, in ascending order in each group. + +```java +org.mule + +com + +java + +javax + + +``` + + +# Mule XML Coding Conventions + +## XML Formatting + +| Concept | Rule | +|:-----------|:-----------------------------------------------------------------------------------| +| Wrapping | Wrap lines at 120 characters. Wrap attributes only if they exceed 120 characters. | +| Indenting | Use four spaces for indenting, rather that tabs. | +| Whitespace | Empty tags should not contain whitespace. Incorrect: `` Correct: `` | +| Aligning | Align wrapped attributes with the first attribute on the previous line. | + +## XML Schema Conventions + +| Schema Item | Convention | +|:-------------------------------|:-----------------------------------------------------------------------------------| +| Simple Types and Complex Types | Use nouns for the names of simple and complex types. Use mixed case names, starting with lowercase. Always apply a `Type` suffix. | `inboundRouterType` | +| Attributes | Use mixed case names for attributes, starting with lowercase. | `address` `name` `synchronous` | +| Element | Use lowercase for element names. Use a "-" separator between words, when necessary. | `inbound-router` `custom-transformer` | +| Groups | Use mixed case names for groups, starting with lowercase. Always apply a Group suffix. | `inboundRouterGroup` `exceptionStrategiesGroup` | +| Namespaces | see example | http://www.mulesoft.org/schema/mule/${module}/${version} | +| Namespace prefixes | see example | ${module} | +| Occurrence constraint | Use occurrence constraints only when non-default values are required. | Note: For clarity's sake, include either all values, or just the non-default values. Given the number of places where minOccurs/maxOccurs attributes exists, it is tedious to complete all values. | + + +## XML Schema Best Practices + +- Avoid restricting complex types; restricting simple types is acceptable. +- Use elements rather than attributes in the following circumstances: + - you require complex types + - you do not have a requirement to specify valid combinations (for example, with choice) + - you must accommodate future extensibility +- Keep schema restrictive but extensible +- Do not use unbound choice model groups, as per the example below. + +```xml + + ... + +``` + +Always order elements using ``. +Specify occurrence constraints only on references to groups, rather than groups. + +## Resources + +Access [xFront Best Practices](http://www.xfront.com/BestPracticesHomepage.html) for more details.