2.0.2 release notes

RELEASE_NOTES.md

@@ -5,6 +5,11 @@ to `grnc-bind`, code quality and documentation.
 
 This release is not backwards compatible, refer to the migration guide at the bottom of these notes for more information.
 
+
+## 2.0.x fixes
+
+See the section at the end of this document for fixes made since the initial 2.0.0 release
+
 ## YAML
 
 Granitic now supports YAML for configuration and component definition files. This involves the
@@ -319,4 +324,11 @@ packages.
 ## Default file locations
 
 Move your configuration files from `resource/config` to `config` and your component definition files from `resource/components`
-to `comp-def`
+to `comp-def`
+
+# Post release fixes
+
+## 2.0.2
+
+  * [rdbms.Client missing InsertQIDParam method](https://github.com/graniticio/granitic/issues/35)
+

doc/ref/fac-json-ws.md

@@ -1 +1,130 @@
-#TODO
+# JSON Web Services (JSONWs)
+
+Enabling the JSON web services facility automatically injects components into your [web service handlers](ws-handlers.md)
+such that HTTP request bodies are parsed as JSON documents and HTTP response bodies are formatted as JSON documents.
+
+## Enabling
+
+The JSONWs facility is _disabled_ by default. To enable it, you must set the following in your configuration
+
+```json
+{
+  "Facilities": {
+    "JSONWs": true
+  }
+}
+```
+
+### Prerequisites
+
+In order to use the JSONWs service, you must also enable the [HTTPServer facility](fac-http-server.md)
+
+## Configuration
+
+The default configuration for this facility can be found in the Granitic source under `facility/config/jsonws.json`
+and is:
+
+```json
+{
+  "JSONWs":{
+    "ResponseWriter": {
+      "DefaultHeaders": {
+        "Content-Type": "application/json; charset=utf-8"
+      }
+    },
+    "Marshal": {
+      "PrettyPrint": false,
+      "IndentString": "  ",
+      "PrefixString": ""
+    },
+    "WrapMode": "BODY",
+    "ResponseWrapper": {
+      "ErrorsFieldName": "Errors",
+      "BodyFieldName":   "Response"
+    }
+  }
+}
+```
+
+### Headers
+
+`JSONWs.ResponseWriter.DefaultHeaders` contains HTTP response headers that will automatically added to every HTTP
+response served by your application. The `Content-Type` header is by default set to  `application/json; charset=utf-8`
+which is the most common content type and encoding for JSON.
+
+You may add additional headers to the response by setting them in your configuration, e.g:
+
+```json
+{
+  "JSONWs":{
+    "ResponseWriter": {
+      "DefaultHeaders": {
+        "My-Common-Header": "my value"
+      }
+    }
+  }
+}
+```
+
+### JSON formatting
+
+The value of your [ws.Response.Body](https://godoc.org/github.com/graniticio/granitic/ws#Response) field will be marshalled
+into JSON using Go's standard [json.Marshal](https://golang.org/pkg/encoding/json/#Marshal) function.
+
+If you set `JSONWs.Marshal.PrettyPrint` to `true`, [json.MarshalIndent](https://golang.org/pkg/encoding/json/#MarshalIndent)
+will be used instead and the configuration values for `IndentString` and `PrefixString` will be passed into
+that function.
+
+### Response wrapping
+
+By default, Granitic will use the JSON representation of your [ws.Response.Body](https://godoc.org/github.com/graniticio/granitic/ws#Response)
+field as the entire HTTP response body. If an [error](ws-error.md) is found, the entire HTTP body is replaced with
+the error document structure described below.
+
+Some applications prefer to have a consistent structure regardless of whether the request was successful or not.
+That behaviour can be enabled in Granitic by setting `JSONWs.WrapMode` to `WRAP`. This means all requests will be
+wrapped with:
+
+```json
+{
+  "Response": { },
+  "Errors": {}
+}
+```
+
+`Response` will only be populated if the request was successful and `Errors` will only be populated if a problem was
+found. The labels `Response` and `Errors` can be modified by changing the `JSONWs.ResponseWrapper.ErrorsFieldName` and
+`JSONWs.ResponseWrapper.BodyFieldName` configuration.
+
+## Behaviour
+
+Enabling this facility causes several components to be created and automatically injected into any [handlers](ws-handlers.md)
+that you have defined that are of the type [handler.WsHandler](https://godoc.org/github.com/graniticio/granitic/ws/handler#WsHandler).
+
+### ResponseWriter
+
+Your handler's `ResponseWriter` field will be set to an instance of [ws.MarshallingResponseWriter](https://godoc.org/github.com/graniticio/granitic/ws#MarshallingResponseWriter).
+This type is agnostic of the serialisation format, so it is customised for JSON serialisation using the
+types defined in the [ws/json package](https://godoc.org/github.com/graniticio/granitic/ws/json).
+
+Together these types are responsible for populating the body, headers and status code of the HTTP responses
+to your webservice request.
+
+The ResponseWriter is also injected into the [HTTP server](fac-http-server.md) so that it can handle requests
+than are not matched to a handler (not found, too busy etc).
+
+### Unmarshaller
+
+Your handler's `ResponseWriter` field will be set to an instance of [json.Unmarshaller](https://godoc.org/github.com/graniticio/granitic/ws/json#Unmarshaller),
+which is a simple wrapper over Go's built-in JSON decoding functions.
+
+## Customisation
+
+Granitic will not inject the above components into your handlers if the relevant target field is already populated. 
+So if you explicitly set an `Unmarshaller` or `ResponseWriter` with a reference to one of your own components in 
+your [component definition](ioc-definition-files.md)  (or in a [component template](ioc-templates.md)) the `JSONWs`
+facility will not overwrite it. 
+
+### Advanced customisation
+
+If you want to use Granitic's `Unmarshaller`, but tweak it's behaviour you can make use of the