{"action":"created","comment":{"url":"https://api.github.com/repos/cloudant/java-cloudant/pulls/comments/52440642","id":52440642,"diff_hunk":"@@ -219,6 +220,44 @@ <h3 id=\"Bulk document CRU\">Bulk document CRU</h3>\n     </LI>\n </UL>\n \n+<h3 id=\"Document revisions\">Document revisions</h3>\n+<P>\n+    This library does not modify the Java objects passed to the\n+    {@link com.cloudant.client.api.Database#save(Object)},\n+    {@link com.cloudant.client.api.Database#post(Object)},\n+    {@link com.cloudant.client.api.Database#update(Object)},\n+    or {@link com.cloudant.client.api.Database#bulk(List)} methods. As such once the server write\n+    completes the Java object(s) will be out of sync with the database server regarding the\n+    document revision. For any of these methods the new document revision can be obtained from\n+    the server's {@link com.cloudant.client.api.model.Response} as shown here.\n+</P>\n+<pre>\n+    {@code\n+    Foo foo = new Foo();\n+    Response response = db.save(foo);\n+    foo.setRevision(response.getRevision());\n+    }\n+</pre>\n+<P>\n+    Note that storing the revision from a server response after saving a document may be\n+    insufficient for the Java object to have the latest revision if the server document is\n+    subsequently updated.\n+</P>\n+<P>\n+    Documents retrieved from the server, for example using the\n+    {@link com.cloudant.client.api.Database#find(Class, String)} method, are deserialized into\n+    objects that will contain the revision as long as the type being deserialized into has a\n+    {@code _rev} field or an appropriate custom serializer to ensure that the {@code _rev} is mapped\n+    to another field.\n+</P>\n+<P>\n+    Using the correct revision is essential for the\n+    {@link com.cloudant.client.api.Database#update(Object)} and\n+    {@link com.cloudant.client.api.Database#remove(Object)} methods, as well as when performing bulk\n+    updates or deletions via the {@link com.cloudant.client.api.Database#bulk(List)} method. If the\n+    latest revision is not used then a conflict will result.","path":"overview.html","position":47,"original_position":47,"commit_id":"ffb9bf2e4a884d6611605e42783000c22f3bc30d","original_commit_id":"ffb9bf2e4a884d6611605e42783000c22f3bc30d","user":{"login":"mikerhodes","id":453210,"avatar_url":"https://avatars.githubusercontent.com/u/453210?v=3","gravatar_id":"","url":"https://api.github.com/users/mikerhodes","html_url":"https://github.com/mikerhodes","followers_url":"https://api.github.com/users/mikerhodes/followers","following_url":"https://api.github.com/users/mikerhodes/following{/other_user}","gists_url":"https://api.github.com/users/mikerhodes/gists{/gist_id}","starred_url":"https://api.github.com/users/mikerhodes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mikerhodes/subscriptions","organizations_url":"https://api.github.com/users/mikerhodes/orgs","repos_url":"https://api.github.com/users/mikerhodes/repos","events_url":"https://api.github.com/users/mikerhodes/events{/privacy}","received_events_url":"https://api.github.com/users/mikerhodes/received_events","type":"User","site_admin":false},"body":"This is ambiguous -- a conflict _response_ will be sent but a conflict isn't created.","created_at":"2016-02-10T10:38:46Z","updated_at":"2016-02-10T10:38:46Z","html_url":"https://github.com/cloudant/java-cloudant/pull/203#discussion_r52440642","pull_request_url":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203","_links":{"self":{"href":"https://api.github.com/repos/cloudant/java-cloudant/pulls/comments/52440642"},"html":{"href":"https://github.com/cloudant/java-cloudant/pull/203#discussion_r52440642"},"pull_request":{"href":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203"}}},"pull_request":{"url":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203","id":58733178,"html_url":"https://github.com/cloudant/java-cloudant/pull/203","diff_url":"https://github.com/cloudant/java-cloudant/pull/203.diff","patch_url":"https://github.com/cloudant/java-cloudant/pull/203.patch","issue_url":"https://api.github.com/repos/cloudant/java-cloudant/issues/203","number":203,"state":"open","locked":false,"title":"199 doc updates","user":{"login":"ricellis","id":10698320,"avatar_url":"https://avatars.githubusercontent.com/u/10698320?v=3","gravatar_id":"","url":"https://api.github.com/users/ricellis","html_url":"https://github.com/ricellis","followers_url":"https://api.github.com/users/ricellis/followers","following_url":"https://api.github.com/users/ricellis/following{/other_user}","gists_url":"https://api.github.com/users/ricellis/gists{/gist_id}","starred_url":"https://api.github.com/users/ricellis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ricellis/subscriptions","organizations_url":"https://api.github.com/users/ricellis/orgs","repos_url":"https://api.github.com/users/ricellis/repos","events_url":"https://api.github.com/users/ricellis/events{/privacy}","received_events_url":"https://api.github.com/users/ricellis/received_events","type":"User","site_admin":false},"body":"*What*\r\nUpdate documentation with respect to document revisions on the server and in objects, fixes #199.\r\nIt may be worth reviewing the `Database` changes in the commit b036725 rather than at the PR diff level to avoid them being clouded by the whitespace changes which needed to be made because all the javadocs were incorrectly indented.\r\n\r\n*How*\r\nUpdate javadoc on `Database` `save` `post` and `update` methods.\r\nAdded section \"Document revisions\" to javadoc overview.\r\n\r\n*Testing*\r\nNone, documentation changes.\r\n\r\nreviewer @mikerhodes \r\nreviewer @rhyshort \r\n","created_at":"2016-02-09T11:11:51Z","updated_at":"2016-02-10T10:38:47Z","closed_at":null,"merged_at":null,"merge_commit_sha":"e7cd9b0590d74051c1f28b26da00b05919a9bc50","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203/commits","review_comments_url":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203/comments","review_comment_url":"https://api.github.com/repos/cloudant/java-cloudant/pulls/comments{/number}","comments_url":"https://api.github.com/repos/cloudant/java-cloudant/issues/203/comments","statuses_url":"https://api.github.com/repos/cloudant/java-cloudant/statuses/ffb9bf2e4a884d6611605e42783000c22f3bc30d","head":{"label":"cloudant:199-doc-updates","ref":"199-doc-updates","sha":"ffb9bf2e4a884d6611605e42783000c22f3bc30d","user":{"login":"cloudant","id":44642,"avatar_url":"https://avatars.githubusercontent.com/u/44642?v=3","gravatar_id":"","url":"https://api.github.com/users/cloudant","html_url":"https://github.com/cloudant","followers_url":"https://api.github.com/users/cloudant/followers","following_url":"https://api.github.com/users/cloudant/following{/other_user}","gists_url":"https://api.github.com/users/cloudant/gists{/gist_id}","starred_url":"https://api.github.com/users/cloudant/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cloudant/subscriptions","organizations_url":"https://api.github.com/users/cloudant/orgs","repos_url":"https://api.github.com/users/cloudant/repos","events_url":"https://api.github.com/users/cloudant/events{/privacy}","received_events_url":"https://api.github.com/users/cloudant/received_events","type":"Organization","site_admin":false},"repo":{"id":22873328,"name":"java-cloudant","full_name":"cloudant/java-cloudant","owner":{"login":"cloudant","id":44642,"avatar_url":"https://avatars.githubusercontent.com/u/44642?v=3","gravatar_id":"","url":"https://api.github.com/users/cloudant","html_url":"https://github.com/cloudant","followers_url":"https://api.github.com/users/cloudant/followers","following_url":"https://api.github.com/users/cloudant/following{/other_user}","gists_url":"https://api.github.com/users/cloudant/gists{/gist_id}","starred_url":"https://api.github.com/users/cloudant/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cloudant/subscriptions","organizations_url":"https://api.github.com/users/cloudant/orgs","repos_url":"https://api.github.com/users/cloudant/repos","events_url":"https://api.github.com/users/cloudant/events{/privacy}","received_events_url":"https://api.github.com/users/cloudant/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/cloudant/java-cloudant","description":"A Java client for Cloudant","fork":false,"url":"https://api.github.com/repos/cloudant/java-cloudant","forks_url":"https://api.github.com/repos/cloudant/java-cloudant/forks","keys_url":"https://api.github.com/repos/cloudant/java-cloudant/keys{/key_id}","collaborators_url":"https://api.github.com/repos/cloudant/java-cloudant/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/cloudant/java-cloudant/teams","hooks_url":"https://api.github.com/repos/cloudant/java-cloudant/hooks","issue_events_url":"https://api.github.com/repos/cloudant/java-cloudant/issues/events{/number}","events_url":"https://api.github.com/repos/cloudant/java-cloudant/events","assignees_url":"https://api.github.com/repos/cloudant/java-cloudant/assignees{/user}","branches_url":"https://api.github.com/repos/cloudant/java-cloudant/branches{/branch}","tags_url":"https://api.github.com/repos/cloudant/java-cloudant/tags","blobs_url":"https://api.github.com/repos/cloudant/java-cloudant/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/cloudant/java-cloudant/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/cloudant/java-cloudant/git/refs{/sha}","trees_url":"https://api.github.com/repos/cloudant/java-cloudant/git/trees{/sha}","statuses_url":"https://api.github.com/repos/cloudant/java-cloudant/statuses/{sha}","languages_url":"https://api.github.com/repos/cloudant/java-cloudant/languages","stargazers_url":"https://api.github.com/repos/cloudant/java-cloudant/stargazers","contributors_url":"https://api.github.com/repos/cloudant/java-cloudant/contributors","subscribers_url":"https://api.github.com/repos/cloudant/java-cloudant/subscribers","subscription_url":"https://api.github.com/repos/cloudant/java-cloudant/subscription","commits_url":"https://api.github.com/repos/cloudant/java-cloudant/commits{/sha}","git_commits_url":"https://api.github.com/repos/cloudant/java-cloudant/git/commits{/sha}","comments_url":"https://api.github.com/repos/cloudant/java-cloudant/comments{/number}","issue_comment_url":"https://api.github.com/repos/cloudant/java-cloudant/issues/comments{/number}","contents_url":"https://api.github.com/repos/cloudant/java-cloudant/contents/{+path}","compare_url":"https://api.github.com/repos/cloudant/java-cloudant/compare/{base}...{head}","merges_url":"https://api.github.com/repos/cloudant/java-cloudant/merges","archive_url":"https://api.github.com/repos/cloudant/java-cloudant/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/cloudant/java-cloudant/downloads","issues_url":"https://api.github.com/repos/cloudant/java-cloudant/issues{/number}","pulls_url":"https://api.github.com/repos/cloudant/java-cloudant/pulls{/number}","milestones_url":"https://api.github.com/repos/cloudant/java-cloudant/milestones{/number}","notifications_url":"https://api.github.com/repos/cloudant/java-cloudant/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/cloudant/java-cloudant/labels{/name}","releases_url":"https://api.github.com/repos/cloudant/java-cloudant/releases{/id}","deployments_url":"https://api.github.com/repos/cloudant/java-cloudant/deployments","created_at":"2014-08-12T10:19:56Z","updated_at":"2016-01-19T18:59:25Z","pushed_at":"2016-02-09T14:17:18Z","git_url":"git://github.com/cloudant/java-cloudant.git","ssh_url":"git@github.com:cloudant/java-cloudant.git","clone_url":"https://github.com/cloudant/java-cloudant.git","svn_url":"https://github.com/cloudant/java-cloudant","homepage":null,"size":3332,"stargazers_count":21,"watchers_count":21,"language":"Java","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":22,"mirror_url":null,"open_issues_count":19,"forks":22,"open_issues":19,"watchers":21,"default_branch":"master"}},"base":{"label":"cloudant:master","ref":"master","sha":"045eb644156076c7a8297b792fdf5a823dd39905","user":{"login":"cloudant","id":44642,"avatar_url":"https://avatars.githubusercontent.com/u/44642?v=3","gravatar_id":"","url":"https://api.github.com/users/cloudant","html_url":"https://github.com/cloudant","followers_url":"https://api.github.com/users/cloudant/followers","following_url":"https://api.github.com/users/cloudant/following{/other_user}","gists_url":"https://api.github.com/users/cloudant/gists{/gist_id}","starred_url":"https://api.github.com/users/cloudant/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cloudant/subscriptions","organizations_url":"https://api.github.com/users/cloudant/orgs","repos_url":"https://api.github.com/users/cloudant/repos","events_url":"https://api.github.com/users/cloudant/events{/privacy}","received_events_url":"https://api.github.com/users/cloudant/received_events","type":"Organization","site_admin":false},"repo":{"id":22873328,"name":"java-cloudant","full_name":"cloudant/java-cloudant","owner":{"login":"cloudant","id":44642,"avatar_url":"https://avatars.githubusercontent.com/u/44642?v=3","gravatar_id":"","url":"https://api.github.com/users/cloudant","html_url":"https://github.com/cloudant","followers_url":"https://api.github.com/users/cloudant/followers","following_url":"https://api.github.com/users/cloudant/following{/other_user}","gists_url":"https://api.github.com/users/cloudant/gists{/gist_id}","starred_url":"https://api.github.com/users/cloudant/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cloudant/subscriptions","organizations_url":"https://api.github.com/users/cloudant/orgs","repos_url":"https://api.github.com/users/cloudant/repos","events_url":"https://api.github.com/users/cloudant/events{/privacy}","received_events_url":"https://api.github.com/users/cloudant/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/cloudant/java-cloudant","description":"A Java client for Cloudant","fork":false,"url":"https://api.github.com/repos/cloudant/java-cloudant","forks_url":"https://api.github.com/repos/cloudant/java-cloudant/forks","keys_url":"https://api.github.com/repos/cloudant/java-cloudant/keys{/key_id}","collaborators_url":"https://api.github.com/repos/cloudant/java-cloudant/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/cloudant/java-cloudant/teams","hooks_url":"https://api.github.com/repos/cloudant/java-cloudant/hooks","issue_events_url":"https://api.github.com/repos/cloudant/java-cloudant/issues/events{/number}","events_url":"https://api.github.com/repos/cloudant/java-cloudant/events","assignees_url":"https://api.github.com/repos/cloudant/java-cloudant/assignees{/user}","branches_url":"https://api.github.com/repos/cloudant/java-cloudant/branches{/branch}","tags_url":"https://api.github.com/repos/cloudant/java-cloudant/tags","blobs_url":"https://api.github.com/repos/cloudant/java-cloudant/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/cloudant/java-cloudant/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/cloudant/java-cloudant/git/refs{/sha}","trees_url":"https://api.github.com/repos/cloudant/java-cloudant/git/trees{/sha}","statuses_url":"https://api.github.com/repos/cloudant/java-cloudant/statuses/{sha}","languages_url":"https://api.github.com/repos/cloudant/java-cloudant/languages","stargazers_url":"https://api.github.com/repos/cloudant/java-cloudant/stargazers","contributors_url":"https://api.github.com/repos/cloudant/java-cloudant/contributors","subscribers_url":"https://api.github.com/repos/cloudant/java-cloudant/subscribers","subscription_url":"https://api.github.com/repos/cloudant/java-cloudant/subscription","commits_url":"https://api.github.com/repos/cloudant/java-cloudant/commits{/sha}","git_commits_url":"https://api.github.com/repos/cloudant/java-cloudant/git/commits{/sha}","comments_url":"https://api.github.com/repos/cloudant/java-cloudant/comments{/number}","issue_comment_url":"https://api.github.com/repos/cloudant/java-cloudant/issues/comments{/number}","contents_url":"https://api.github.com/repos/cloudant/java-cloudant/contents/{+path}","compare_url":"https://api.github.com/repos/cloudant/java-cloudant/compare/{base}...{head}","merges_url":"https://api.github.com/repos/cloudant/java-cloudant/merges","archive_url":"https://api.github.com/repos/cloudant/java-cloudant/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/cloudant/java-cloudant/downloads","issues_url":"https://api.github.com/repos/cloudant/java-cloudant/issues{/number}","pulls_url":"https://api.github.com/repos/cloudant/java-cloudant/pulls{/number}","milestones_url":"https://api.github.com/repos/cloudant/java-cloudant/milestones{/number}","notifications_url":"https://api.github.com/repos/cloudant/java-cloudant/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/cloudant/java-cloudant/labels{/name}","releases_url":"https://api.github.com/repos/cloudant/java-cloudant/releases{/id}","deployments_url":"https://api.github.com/repos/cloudant/java-cloudant/deployments","created_at":"2014-08-12T10:19:56Z","updated_at":"2016-01-19T18:59:25Z","pushed_at":"2016-02-09T14:17:18Z","git_url":"git://github.com/cloudant/java-cloudant.git","ssh_url":"git@github.com:cloudant/java-cloudant.git","clone_url":"https://github.com/cloudant/java-cloudant.git","svn_url":"https://github.com/cloudant/java-cloudant","homepage":null,"size":3332,"stargazers_count":21,"watchers_count":21,"language":"Java","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":22,"mirror_url":null,"open_issues_count":19,"forks":22,"open_issues":19,"watchers":21,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203"},"html":{"href":"https://github.com/cloudant/java-cloudant/pull/203"},"issue":{"href":"https://api.github.com/repos/cloudant/java-cloudant/issues/203"},"comments":{"href":"https://api.github.com/repos/cloudant/java-cloudant/issues/203/comments"},"review_comments":{"href":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203/comments"},"review_comment":{"href":"https://api.github.com/repos/cloudant/java-cloudant/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/cloudant/java-cloudant/pulls/203/commits"},"statuses":{"href":"https://api.github.com/repos/cloudant/java-cloudant/statuses/ffb9bf2e4a884d6611605e42783000c22f3bc30d"}}}}