Initial multipart/related implementation:

* Reader/writer
* Interaction with blob store
* Interaction with _attachments dictionary
Start integrating multipart code with replication:

* Large push attachments working

Deal with gzip encoding:

* Pull down attachments gzipped
* Unzip attachment data inline in SavedAttachments

Improve attachments handling:

* Don't copy over attachments to new rev unnecessarily when pulling in new revisions
* Send atts_since to determine when new attachments need to be pulled

Handle stub attachments on pull replications

Run both inline/out-of-band attachments code paths

Attachment push:

* Correctly work out when to send attachments separately as multipart
  using push_attachments_inline property:

  false = always push multipart;
  small = push small attachments inline;
  true = always push inline

* Fix bug in 1-byte read() with 2s complement bytes
* Update MultipartAttachmentWriterTests to use a jpeg image and differing chunk sizes

* Fix some javadoc comments
Cleanup:

* Remove unused variables
* Add licence headers
Address some of Mike's review comments:

* Refactor the whole safeAddAttachment thing
* Add some doc comments
* Remove multipart reader
* MultipartAttachmentWriter.java tweaks
* Better constructors in Attachment type hierarchy
* Refactor the attachment Encoding enum
* addMultiparts -> createMultipartWriter
* Refactor copying attachments forward to a new revision.
  (This also fixes the potential bug of not escaping filenames)
* Fix limit logic in getPossibleAncestorRevisionIDs()
* Fix Javadoc
* Re-instate 1-arg version of revisionHistoryToJson
* Fix formatting/documentation
* Remove some unused imports
* Change insertRevision to take Options object instead of a ton of arguments
Move attachments pull/push preferences out of system properties
Some documentation fixes
Download attachments before adding them.

This means we can add attachments transactionally but without holding the transaction open whilst
performing the download
Initial multipart/related implementation:

* Reader/writer
* Interaction with blob store
* Interaction with _attachments dictionary
Start integrating multipart code with replication:

* Large push attachments working

Deal with gzip encoding:

* Pull down attachments gzipped
* Unzip attachment data inline in SavedAttachments

Improve attachments handling:

* Don't copy over attachments to new rev unnecessarily when pulling in new revisions
* Send atts_since to determine when new attachments need to be pulled

Handle stub attachments on pull replications

Run both inline/out-of-band attachments code paths

Attachment push:

* Correctly work out when to send attachments separately as multipart
  using push_attachments_inline property:

  false = always push multipart;
  small = push small attachments inline;
  true = always push inline

* Fix bug in 1-byte read() with 2s complement bytes
* Update MultipartAttachmentWriterTests to use a jpeg image and differing chunk sizes

* Fix some javadoc comments
Cleanup:

* Remove unused variables
* Add licence headers
Address some of Mike's review comments:

* Refactor the whole safeAddAttachment thing
* Add some doc comments
* Remove multipart reader
* MultipartAttachmentWriter.java tweaks
* Better constructors in Attachment type hierarchy
* Refactor the attachment Encoding enum
* addMultiparts -> createMultipartWriter
* Refactor copying attachments forward to a new revision.
  (This also fixes the potential bug of not escaping filenames)
* Fix limit logic in getPossibleAncestorRevisionIDs()
* Fix Javadoc
* Re-instate 1-arg version of revisionHistoryToJson
* Fix formatting/documentation
* Remove some unused imports
* Change insertRevision to take Options object instead of a ton of arguments
Move attachments pull/push preferences out of system properties
Some documentation fixes
Download attachments before adding them.

This means we can add attachments transactionally but without holding the transaction open whilst
performing the download
Merge after rebase
Merge pull request #10 from cloudant/26684-multipart-related

This PR addresses the following:

- Push large attachments as MIME Multipart/Related parts
- Pull attachments as binary HTTP streams separately from document bodies
- Fix some of the interactions between the AttachmentManager and replications, ensuring correct handling of stub attachments revpos such that already known attachments are not needlessly transferred.

Extra PushConfiguration/PullConfiguration properties are introduced:

`PushConfiguration.pushAttachmentsInline`: (default small)
* false = always push multipart
* small = push small attachments inline
* true = always push inline

Currently "small" attachments are defined as being < 65536 bytes.

`PullConfiguration.pullAttachmentsInline`: (default false)
* false = always pull attachments as separate HTTP streams
* true = always pull attachments inline, as base64 data inlined in document body

It may be more efficient to pull attachments inline if it is known in advance that they will be small.