params.json

{"name":"SQP","tagline":"Simple Query Protocol - A WebSocket and JSON based protocol to access relational databases","body":"SQP - Simple Query Protocol\r\n===========================\r\nA simple protocol to query databases based on JSON and WebSocket. It's implemented as a Java client\r\nlibrary and a proxy server that can be used to easily access SQL databases in a standardized manner.\r\nThe proxy server is currently able to communicate with Transbase and PostgreSQL databases.\r\n\r\nThe project started as a master thesis by Stefan Burnicki (@sburnicki) in 2015. Therefore it might not be stable\r\nor complete, yet.\r\n\r\nStructure\r\n---------\r\nThe project uses gradle as build system. Consequently, the project's file structure is a typical\r\ngradle structure:\r\n\r\nJava code can be found in `src/main/java`, while test code can be found in `src/test/java`.\r\nResources are in `src/main/resources` and test resources in `src/test/resources`.\r\nThe folder libs/ contains non-maven dependencies.\r\n\r\nThis project consists of several main modules, namely:\r\n  - The core (io.sqp.core), which contains definitions for the SQP data types and messages in Java\r\n  - The SQP proxy server (io.sqp.proxy) that is able to understand the SQP, talk to a database\r\n    and answer the client\r\n  - The backend module (io.sqp.backend) contains interfaces and some utilities to write a database\r\n    backend for the server\r\n  - The PostgreSQL SQP proxy server backend (org.postgres.sqp) which enables the proxy to talk to\r\n    PostgreSQL databases\r\n  - The Transbase SQP proxy server backend (io.sqp.transbase) which enables the proxy to talk to\r\n    Transbase databases\r\n  - The SchemaMatcher (io.sqp.schemamatcher) which is used by the proxy to match custom JSON\r\n    schemas to existing ones\r\n  - The client library (io.sqp.client) can be used to communicate with an SQP server, as the proxy\r\n    server.\r\n\r\n\r\nInvolved Technologies & Dependencies\r\n------------------------------------\r\nTo understand this project, you probably need to get an overview of some technologies involved in\r\nthis project first.\r\n\r\nIn general:\r\n  - `git` as the version control system\r\n  - `gradle` as the build system in use\r\n  - `Java 8` as main programming language\r\n  - unit testing\r\n\r\nFor unit testing with mocks:\r\n  - `TestNG` as unit test framework\r\n  - `Mockito` as framework for mock objects\r\n  - `Hamcrest` for matchers used in test assertions\r\n\r\nFor the protocol/core:\r\n  - `WebSocket` as the underlying protocol\r\n  - `JSON` as the standard serialization/message format\r\n  - `MsgPack` as the binary equivalent for serialization/messages\r\n  - `Jackson` as the serialization framework for both JSON and MsgPack used in the Java\r\n    implementation\r\n  - `JSON Schema` for data type descriptions\r\n\r\nFor the proxy:\r\n  - Event-loop/callback based, asynchronous (non-blocking) programming\r\n  - `Vert.x 3.0` as the event-loop and netty based server platform\r\n  - `JSON Schema Validator` as a validator input against a custom JSON Schema\r\n\r\nFor the client:\r\n  - `JSR 356` specification for Java WebSocket support\r\n  - `Tyrus` as a glassfish-based reference implementation of JSR 356\r\n  - Java 8's `CompletableFuture`s for non-blocking, but not event-loop/callback based programming\r\n\r\nIf you run the gradle build for the first time you will notice that quite a bunch of dependency\r\npackages are downloaded.\r\nSome packages are dependencies of others that get downloaded, like Netty as the basis of Vert.x.\r\nOther package are needed for tests only, like hamcrest, mockito, and TestNG.\r\nThe \"JSON Schema Validator\" project pulls pretty much dependencies. So it's probably a good idea\r\nto replace this package in the future if the amount of dependencies packages need to be reduced.\r\n\r\nAnother dependency is the \"tbjdbc.jar\" that is not available in a maven repository and thus does\r\nnot get downloaded automatically. However, this package is needed for the Transbase SQP proxy\r\nbackend.\r\n\r\nBuilding\r\n--------\r\nMake sure you have Java 8 installed and a working internet connection so dependencies can get\r\ndownloaded. Then just execute the gradle wrapper with the build task:\r\n\r\n    ./gradlew build\r\n\r\nTransbase Backend\r\n-----------------\r\nThe Transbase backend is only built optionally. You can either install the eligible Transbase JDBC\r\ndriver to `libs/tbjdbc.jar` or define its location on the cmdline:\r\n\r\n    ./gradlew -Ptbjdbc=/path/to/tbjdbc.jar\r\n\r\n\r\nIDE integration\r\n---------------\r\nThe gradle plugins \"eclipse\" and \"idea\" are used to generate project files for the Eclipse or\r\nIntelliJ IDEA IDEs. Just run\r\n\r\n    ./gradlew idea\r\n\r\nor\r\n\r\n    ./gradlew eclipse\r\n\r\nCheck out the plugin documentation for more details on this.\r\n\r\nConfiguration of the server\r\n---------------------------\r\nIn order for the proxy to work, you need to provide a configuration. See the\r\n[config.json](config.json) file for an example.\r\nThe proxy server itself needs to be configured in a number of ways:\r\n  - The `port` to listen on for WebSocket connections. It's optional and the default is `8080`.\r\n  - The `path` to match for incoming connections. It's optional  and the default is `/`.\r\n  - The `connectionPoolSize`, i.e. the maximum number of concurrently open connections.\r\n    It's optional and the default is `30`.\r\n  - The `backends` array which contains backend configurations.\r\n    Currently only the first is used and the rest is ignored. This is mandatory as there are no\r\n    defaults.\r\n\r\nA backend configuration needs to include two fields:\r\n  - The `type` is the full class name of the Backend implementation. E.g.\r\n    `io.sqp.postgresql.PostgreSQLBackend`.\r\n  - The `config` needs to be an object whose values depend on the concrete backend.\r\n    Common fields are server credentials of the DBMS.\r\n\r\n\r\nRun the Server from IDE\r\n-----------------------\r\nYou can run it directly in your IDE by creating a run configuration that uses the main class\r\n`io.vertx.core.Starter` and passes in the arguments `-config <conffile>.json run\r\nio.sqp.proxy.ServerVerticle`. \"<conffile>.json\" should be the path to the proxy's configuration\r\nfile, which is mandatory to connect to a database. For details on the configuration file, see the\r\nsection \"Proxy Configuration\" below.\r\n\r\nTo use a specific Transbase JDBC driver, you might define it just like stated for the building process.\r\n\r\nCreating and using a fat jar\r\n----------------------------\r\nThe build.gradle uses the Gradle shadowJar plugin to assemble the application and all it's\r\ndependencies into a single \"fat\" jar.\r\nTo build the \"fat jar\", run\r\n\r\n    ./gradlew shadowJar\r\n\r\nTo run the fat jar, run\r\n\r\n    java -jar build/libs/sqp-1.0-fat.jar -conf config.json\r\n\r\n(You can take that jar and run it anywhere there is a Java 8+ JDK. It contains *all* the\r\ndependencies it needs so you don't need to install Vert.x or any other libraries on the target\r\nmachine).\r\n\r\nScaling the server\r\n------------------\r\nThe server is implemented as a Vert.x verticle, which allows easy scaling of the server.\r\nE.g. let's say you have 8 cores on your server and you want to utilise them all, you can deploy 8\r\ninstances as follows:\r\n\r\n    java -jar build/libs/sqp-1.0-fat.jar -conf config.json -instances 8\r\n\r\nYou can also enable clustering and ha at the command line, e.g.\r\n\r\n    java -jar build/libs/sqp-1.0-fat.jar -conf config.json -cluster\r\n    java -jar build/libs/sqp-1.0-fat.jar -conf config.json -ha\r\n\r\nPlease see the Vert.x docs for a full list of Vert.x command line options.\r\n\r\nRunning the tests\r\n-----------------\r\nTo run the tests you need to care about some prerequisites:\r\n  1. Install and start a PostgreSQL server.\r\n  2. Set up a PostgreSQL user called `proxyuser` with password `proxypw`.\r\n    If you want to use another user, you need to modify the\r\n    [test configuration](src/test/resources/backendConfiguration.json) and the\r\n    [run configuration](config.json) accordingly.\r\n  3. Create a `proxytest` PostgreSQL database.\r\n  4. Install and start a Transbase server.\r\n  5. Create a `proxytest` Transbase database.\r\n  6. For both Transbase and PostgreSQL: Create tables with statements that can be found in\r\n    `src/test/resources/*Table.sql`.\r\n  7. Run the tests by executing\r\n            ./gradlew test\r\n    The test results can be seen on the console or as a HTML summary at\r\n    `build/reports/tests/index.html`.\r\n\r\nIf you want to exclude a backend from the tests, you need to comment out the backend related\r\nsections in the [common test configuration](src/test/resources/testng-common.xml) and exclude the\r\nbackend-falvored tests from being run in the [build.gradle](build.gradle) file.\r\nIn the console output you might see backtraces and logs. This does not mean that tests failed, as\r\nsome of them tests correct behavior on failure.\r\n\r\nRunning the Server with Transbase Free\r\n--------------------------------------\r\nTransbase has a free edition that can be used with SQP. To do so, install it at a specific location\r\nand copy the eligible Transbase JDBC driver to that location.\r\nYou need to then build and run the server by explicitly defining the location of the `tbjdbc.jar` in the\r\ninstallation location of Transbase Free.\r\nYou can also try to define the location of the Transbase Free installation by setting the Java property\r\n`LINKED_IN_PATH`. Then you don't need to explicitly copy and define the location of `tbjdbc.jar`.\r\n\r\nThe backend configuration must then set `\"pipe\": true` instead of a host and port.\r\nThe integration tests currently do not work with Transbase Free.\r\n\r\nDue to some limitations of Transbase Free, the integration tests currently fail with it.\r\n\r\nFurther Documentation\r\n---------------------\r\nYou can build and read the Javadoc documentation by executing the `javadoc` gradle task:\r\n\r\n    ./gradlew javadoc\r\n\r\nThe documentation can then be found in `build/docs`.\r\n\r\nLicense\r\n-------\r\nSQP uses \"dual licensing\". Under this model, developers can freely choose to use SQP under the free\r\nsoftware/Open Source GNU Affero General Public License Version 3 (commonly known as the \"AGPLv3\")\r\nor under a commercial license.\r\n\r\nA copy of AGPLv3 can be found in the [license file](LICENSE).\r\nFor a commercial license, please contact Rothmeyer Consulting (see below).\r\n\r\nContact\r\n-------\r\nCopyright Holder: [Rothmeyer Consulting](http://www.rothmeyer.com/)\r\n\r\nAuthor: Stefan Burnicki <stefan.burnicki@burnicki.net> (@sburnicki)\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}