Merge pull request torodb#42 from ahachete/master

Release v0.40-alpha1

Author: ahachete

.mailmap

@@ -0,0 +1,5 @@
+Álvaro Hernández Tortosa <aht@8kdata.com> Álvaro Hernández Tortosa <aht@nosys.es>
+Matteo Melli <matteom@8kdata.com> matteom <matteom@8kdata.com>
+Gonzalo Ortiz Jaureguizar <gortiz@8kdata.com> Gonzalo Ortiz Jaureguizar <gortiz@users.noreply.github.com>
+Gonzalo Ortiz Jaureguizar <gortiz@8kdata.com> Gonzalo Ortiz Jaureguizar <gortiz@nosys.es>
+Gonzalo Ortiz Jaureguizar <gortiz@8kdata.com> golthiryus <golthiryus@golthi-linux-chrono>

.travis.yml

@@ -0,0 +1,41 @@
+language: java
+script: mvn -Psafer -Passembler -B -e -T 1C verify
+jdk:
+- oraclejdk8
+- oraclejdk7
+
+before_script:
+- export GIT_BRANCH=$TRAVIS_BRANCH
+
+sudo: false
+
+before_deploy:
+  - echo "<settings><servers><server><id>ossrh-snapshot</id><username>\${env.MAVEN_DEPLOY_USER}</username><password>\${env.MAVEN_DEPLOY_PASS}</password></server><server><id>ossrh-release</id><username>\${env.MAVEN_DEPLOY_USER}</username><password>\${env.MAVEN_DEPLOY_PASS}</password></server></servers></settings>" > ~/settings.xml
+
+deploy:
+- provider: releases
+  api_key:
+    secure: g2kUTryp5anBi6xzkHT4CfTFJz3K1q1nYYwjtNfreCoEGrjTA6A4ZgU/utVTOJxeNWmKZ1QO4suegKfsRCpiSqNvp85lM49qeXAp/xxuI0ac+J7JJALeGEn0AyLmhuHu/BBm3dIG+6oi+cXRsTKAX8uTqrT9P1tkfaUhEEV1XmA4tU3uEqzHiazPUKXysxAOacqeUfvZh+MoZaqA54p0UjmOilTMGnQvpv2uR7tBnXNGVXkqyonH6HsxAOwKdyZAYwsg2hvCNREJUCgl/OVkQI/H8+SmOfZ4btHxZqX3U5iVLZ9CugsUbqflvVzVd7KIPn4DPXalkSDLsJ2SxBio7Y1t50omDIlb7NsClR4JDAzME5XKw8XR9glmC0uDTMxMuhgXYWLq2JgQUlnD8vWh1SGsdUCNa+aQMlcYdIIMQZG50LgY5s+E2YVEzJ7NrWm66UCqeuxjqWetrGin1eFOY0+y2/+Pe4tr2ZhrbGhlqS11GKWy+tKLM9v7+L2w1gjKJaqcmbtVfja1kehaP7JLhq2S2S7jmcTggy4bx5B9U4rVwWq1cv5sXXXNEsvB/PzifXHV3z38O/ed8ddJpCTkhfubAr6zOKkyGdkPvXbdAmDOVWw5JPbP1fWDojaRgqxumf7MUhAlOGxmj//hgpwh/Q8/QVKCJ+lQRq89H5bT0q4=
+  skip_cleanup: true
+  file:
+  - torodb/target/dist/torodb.tar.bz2
+  - torodb/target/dist/torodb.zip
+  on:
+    repo: torodb/torodb
+    tags: true
+    jdk: oraclejdk8
+- provider: script
+  script: mvn -B -e -T 1C -Pdeploy -DskipTests=true deploy --settings ~/settings.xml
+  skip_cleanup: true
+  on:
+    repo: torodb/torodb
+    tags: true
+    jdk: oraclejdk8
+- provider: script
+  script: mvn -B -e -T 1C -Pdeploy -DskipTests=true deploy --settings ~/settings.xml
+  skip_cleanup: true
+  on:
+    repo: torodb/torodb
+    branch: devel
+    jdk: oraclejdk8
+  

README.md

@@ -1,92 +1,140 @@
 # ToroDB
 
-ToroDB is an open source, document-oriented, JSON database that runs on top of PostgreSQL. JSON documents are stored relationally, not as a blob/jsonb. This leads to significant storage and I/O savings. It speaks natively the MongoDB protocol, meaning that it can be used with any mongo-compatible client.
+ToroDB is an open source project that turns your RDBMS into a
+MongoDB-compatible server, supporting the MongoDB query API and
+MongoDB's replication, but storing your data into a reliable and trusted
+ACID database. ToroDB currently supports PostgreSQL as a backend, but
+others will be added in the future.
 
-ToroDB follows a RERO (Release Early, Release Often) policy. Current version is considered a "developer preview" and hence is not suitable for production use. However, any feedback, contributions, help and/or patches are very welcome. Please join the [torodb-dev][8] mailing list for further discussion.
+ToroDB natively implements the MongoDB protocol, so you can use it with
+MongoDB tools and drivers, and features a document-to-relational mapping
+algorithm that transforms the JSON documents into relational tables.
+ToroDB also offers a native SQL layer and automatic data normalization
+and partitioning based on JSON documents' implicit schema.
 
-For more information, please see [ToroDB's website][1], this [latest presentation][7] or this [video recording of a presentation][11] about ToroDB. There's also a great [ToroDB introductory video][12] made by [Ernst-Georg Schmid][13], which explains how to start using ToroDB.
+ToroDB follows a RERO (Release Early, Release Often) policy. Current version is
+considered a "developer preview" and hence is not suitable for
+production use. Use at your own risk. However, any feedback,
+contributions, help and/or patches are very welcome. Please join the
+[torodb-dev][8] mailing list for further discussion.
+
+For more information, please see [ToroDB's website][1], this 
+[latest presentation][7] or this [video recording of a presentation][11] about 
+ToroDB.
+
+
+## Code QA
+ * Master branch build status: [![Master branch build status](https://travis-ci.org/torodb/torodb.svg?branch=master)](https://travis-ci.org/torodb/torodb)
+ * Devel branch build status :  [![Devel branch build status](https://travis-ci.org/torodb/torodb.svg?branch=devel)](https://travis-ci.org/torodb/torodb)
 
 
 ## Requisites
 
 ToroDB is written in Java and requires:
 
-* A suitable JRE, version 6 or higher. It has been mainly tested with Oracle JRE 8.
+* A suitable JRE, version 7 or higher. It has been mainly tested with Oracle JRE 8.
 * A [PostgreSQL][2] database, version 9.4 or higher. [Download][9].
 
 
 ## Download/Installation
 
-### Download the compiled jar file
+### Download the compiled file
 
-You may download the [latest version][3] (v. 0.23) of ToroDB from ToroDB's maven repository. See below for instructions on how to run it.
+You may download the latest version (v. 0.40-alpha1) of ToroDB from 
+[the release page](https://github.com/torodb/torodb/releases/latest) on the 
+following packaging formats:
+ * [tar.gz](https://github.com/torodb/torodb/archive/v0.40-alpha1.tar.gz)
+ * [zip](https://github.com/torodb/torodb/archive/v0.40-alpha1.zip)
+
+See below for instructions on how to run it.
+
+You can also find binary files on [ToroDB's maven repository][3].
 
 
 ### Compile and install from sources
 
-You may compile ToroDB yourself. All the project is written in Java and managed with Maven, so you need a javac and maven.
+To get the latest version, you may compile ToroDB yourself. All the project is written in Java and managed with Maven, so you need a javac and maven.
 
 ToroDB is based on the [Mongo Wire Protocol library][5] (mongowp), which is another library built by [8Kdata][6] to help construct programs that speak the MongoDB protocol. You may also compile this library yourself, or let maven download it from the repository automatically.
 
-Just run `mvn package` on the root directory and find the executable jar file in `torodb/target/torodb-0.23-jar-with-dependencies.jar`.
+Just run `mvn package -Passembler` on the root directory and execute it from 
+`torodb/target/appassembler/bin` or choose your prefered packaging format from
+`torodb/target/dist/`.
 
 
 ## Running ToroDB
 
-Execute with `java -jar <path>/torodb.jar <arguments>`. If you run with `--help`, you will see the required and optional arguments to run ToroDB:
-
-    --ask-for-password
-       Force input of PostgreSQL's database user password.
-       Default: false
-    -c, --connections
-       Number of connections to establish to the PostgreSQL database
-       Default: 10
-    -d, --dbname
-       PostgreSQL's database name to connect to (must exist)
-       Default: torod
-    -p, --dbport
-       PostgreSQL's server port
-       Default: 5432
-    --debug
-       Change log level to DEBUG
-       Default: false
-    -h, --host
-       PostgreSQL's server host (hostname or IP address)
-       Default: localhost
-    -P, --mongoport
-       Port to listen on for Mongo wire protocol connections
-       Default: 27017
-    --help, --usage
-       Print this usage guide
-       Default: false
-    -u, --username
-       PostgreSQL's database user name. Must be a superuser
-       Default: postgres
-    --verbose
-       Change log level to INFO
-       Default: false
-
-The database must exist, and the username must have superuser privileges. This will be changed in the future.
-
-Alternatively to the command line options, you may create a `~/.toropass` file, which follows the syntax of [PostgreSQL's pgpass][4] files.
+ToroDB needs either a configuration file or some command-line parameters
+to run. But it can also run without any of them if you follow some
+conventions.
+
+Before running ToroDB it is necessary to configure the RDBMS with the
+ToroDB user that will be responsible to create namespaces, required data
+types, tables and indexes. 
+
+Create user torodb (this is default user name, see ToroDB configuration
+to use a different name):
+
+    =# CREATE USER torodb WITH  SUPERUSER PASSWORD '<your-password>';
+
+Create the database torod (this is default database name, see ToroDB
+configuration to use a different name):
+
+    =# CREATE DATABASE torod OWNER torodb;
+
+The script $TOROHOME/bin/torodb (or torodb.bat) will run ToroDB. ToroDB can be
+configured by a configuration file written in YAML or XML formats by
+passing arguments -c or -x, respectively, to the script
+$TOROHOME/bin/torodb. For example, to run ToroDB with configuration file
+torodb.yml, run:
+
+    $ $TOROHOME/bin/torodb -c torodb.yml
+
+To print default configuration script in YAML or XML format use the
+arguments -l an -lx respectively. For example to generate default YAML
+configuration file:
+
+    $ $TOROHOME/bin/torodb -l > torodb.yml
+
+ToroDB connects to the backend database using user torodb (that has been
+created in previous step). By default ToroDB reads the file
+$HOME/.toropass (file path can be configured in the configuration), if
+it exists, that stores the password in PostgreSQL's [.pgpass][4] syntax. The
+password can also be specified in clear text in the configuration file or
+will be asked at the prompt if the argument -W is issued.
+
+To get general help, pass --help argument:
+
+    $ $TOROHOME/bin/torodb --help
+
+Use --help-param to get help on all available parameters of the
+configuration file:
+
+    $ $TOROHOME/bin/torodb --help-param
+
+If you setup a .toropass, use torodb as the user and torod as the
+database, ToroDB will run without a configuration file (with the rest of
+the configuration values with their respective defaults).
+
+Once ToroDB is running, connect to it with a normal MongoDB client,
+like:
+
+    $ mongo localhost:27018/torod
 
 
 ## Are you a developer? Want to contribute? Questions about the source code?
 
 Please see [CONTRIBUTING][10].
 
 
-
 [1]: http://www.torodb.com
 [2]: http://www.postgresql.org
-[3]: http://maven.torodb.com/jar/com/torodb/torodb/0.23/torodb.jar
-[4]: http://www.postgresql.org/docs/9.3/static/libpq-pgpass.html
+[3]: https://oss.sonatype.org/content/groups/public/com/torodb/torodb/
+[4]: http://www.postgresql.org/docs/9.4/static/libpq-pgpass.html
 [5]: https://github.com/8kdata/mongowp
 [6]: http://www.8kdata.com
-[7]: http://www.slideshare.net/8kdata/big-dataspain2014-torodbbridgebetweennosqlandrelational
+[7]: http://www.slideshare.net/8kdata/torodb-internals-how-to-create-a-nosql-database-on-top-of-sql-55275036
 [8]: https://groups.google.com/forum/#!forum/torodb-dev
 [9]: http://www.postgresql.org/download/
 [10]: https://github.com/torodb/torodb/blob/master/CONTRIBUTING.md
-[11]: http://www.bigdataspain.org/2014/conference/new-open-source-database-a-bridge-between-the-nosql-and-relational-worlds
-[12]: https://youtu.be/kgge0ZZ_lUM
-[13]: https://twitter.com/e_g_schmid
+[11]: https://www.youtube.com/watch?v=C2XuOhLrblo