Skip to content
This repository was archived by the owner on Mar 11, 2022. It is now read-only.

Commit d01581d

Browse files
mojito317emlaverricellis
authored
Add migration guide (#518)
Co-authored-by: Esteban Laver <emlaver@us.ibm.com> Co-authored-by: Rich Ellis <ricellis@users.noreply.github.com>
1 parent b970b22 commit d01581d

File tree

2 files changed

+257
-0
lines changed

2 files changed

+257
-0
lines changed

‎MIGRATION.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# Migrating to the `cloudant-java-sdk` library
2+
This document is to assist in migrating from the `java-cloudant` (coordinates: `com.cloudant:cloudant-client`) to the newly supported [`cloudant-java-sdk`](https://github.com/IBM/cloudant-java-sdk) (coordinates: `com.ibm.cloud:cloudant`).
3+
4+
## Initializing the client connection
5+
There are several ways to create a client connection in `cloudant-java-sdk`:
6+
1. [Environment variables](https://github.com/IBM/cloudant-java-sdk#authentication-with-environment-variables)
7+
2. [External configuration file](https://github.com/IBM/cloudant-java-sdk#authentication-with-external-configuration)
8+
3. [Programmatically](https://github.com/IBM/cloudant-java-sdk#programmatic-authentication)
9+
10+
[See the README](https://github.com/IBM/cloudant-java-sdk#code-examples) for code examples on using environment variables.
11+
12+
## Other differences
13+
1. In `cloudant-java-sdk` all operations are performed from the scope of the client instance and
14+
not associated with any sub-scope like `Database`. There is no need to instantiate
15+
a `Database` object to interact with documents - the database name is included as part of
16+
document operations. For example, in the case of updating a document you would first call
17+
`getDocument` to fetch and then `putDocument` to update, there is no need to `getDatabase`.
18+
1. In `cloudant-java-sdk` a user-supplied POJO is not required to represent a document.
19+
The default document representation is the `Document` model class. It is still possible
20+
to use POJOs in preference instead of the `Document` model, see examples in the section
21+
[POJO usage in the `cloudant-java-sdk` library](#pojo-usage-in-the-new-library).
22+
1. Sending and receiving byte responses is available for operations that accept user-defined documents or return user-defined documents, document projections or map/reduce data. See [the Raw IO section](https://github.com/IBM/cloudant-java-sdk#raw-io) of `cloudant-java-sdk` README or the [Bypass the document model and use the `asStream` methods section](#3-bypass-the-document-model-and-use-the-asstream-methods) for more details.
23+
1. There is no built-in pagination support for views. Examples coming soon.
24+
25+
### POJO usage in the new library
26+
27+
Since the new library supports models, this guide will demonstrate three ways to migrate your POJOs from `java-cloudant`.
28+
29+
Let's start with a simple POJO:
30+
31+
```java
32+
public class Pojo {
33+
private String name;
34+
35+
public String getName() {
36+
return name;
37+
}
38+
39+
public void setName(String name) {
40+
this.name = name;
41+
}
42+
43+
@Override
44+
public String toString() {
45+
return name;
46+
}
47+
}
48+
```
49+
The code block below uses the POJO in a simple update implementation - reading the
50+
document into an object, performing an update and then writing the updated document in
51+
the database.
52+
53+
```java
54+
//... set up the service client and the database
55+
Pojo p = db.find(Pojo.class, "example_id");
56+
System.out.println(p); // the value of the Pojo's toString method
57+
58+
p.setName("new_name");
59+
System.out.println(p.getName()); // will be new_name
60+
61+
Response response = db.update(p); // the same object is used for the update, it will set the name parameter to new_name
62+
```
63+
64+
#### 1. Use the `Document` model class, storing user properties in the `Map`
65+
66+
```java
67+
//set up the service client
68+
GetDocumentOptions documentOptions =
69+
new GetDocumentOptions.Builder()
70+
.db("example_db")
71+
.docId("example_id")
72+
.build();
73+
74+
Document doc = service.getDocument(documentOptions)
75+
.execute()
76+
.getResult();
77+
78+
System.out.println(doc); // will be a JSON
79+
80+
// Set the JSON properties to the Pojo
81+
Pojo p = new Pojo();
82+
p.setName((String) doc.getProperties().get("name"));
83+
System.out.println(p); // will be a Pojo with the same name as the JSON
84+
85+
p.setName("new_name");
86+
System.out.println(p.getName()); // new_name
87+
88+
doc.put("name", p.getName()); // add your modifications to the Document object
89+
90+
PutDocumentOptions putDocumentOptions =
91+
new PutDocumentOptions.Builder()
92+
.db("example_db")
93+
.docId("example_id")
94+
.document(doc)
95+
.build();
96+
97+
DocumentResult response =
98+
service.putDocument(putDocumentOptions)
99+
.execute()
100+
.getResult();
101+
```
102+
103+
#### 2. Convert the `Document` model into a POJO (and vice versa)
104+
105+
```java
106+
//set up the service client
107+
GetDocumentOptions documentOptions =
108+
new GetDocumentOptions.Builder()
109+
.db("example_db")
110+
.docId("example_id")
111+
.build();
112+
113+
Document doc = service.getDocument(documentOptions)
114+
.execute()
115+
.getResult();
116+
117+
System.out.println(doc); // will be a JSON
118+
119+
// Serialize the JSON to Pojo
120+
Pojo p = YourJsonSerializer.fromJson(doc.toString(), Pojo.class);
121+
System.out.println(p); // the value of the Pojo's toString method
122+
123+
p.setName("new_name");
124+
System.out.println(p.getName()); // will be new_name
125+
126+
// Deserialize the Pojo back to the Document model
127+
doc.setProperties(YourJsonSerializer.fromJson(YourJsonSerializer.toJson(p), Map.class));
128+
129+
PutDocumentOptions putDocumentOptions =
130+
new PutDocumentOptions.Builder()
131+
.db("example_db")
132+
.docId("example_id")
133+
.document(doc)
134+
.build();
135+
136+
DocumentResult response =
137+
service.putDocument(putDocumentOptions)
138+
.execute()
139+
.getResult();
140+
```
141+
142+
#### 3. Bypass the `Document` model and use the `AsStream` methods
143+
144+
```java
145+
//set up the service client
146+
GetDocumentOptions documentOptions =
147+
new GetDocumentOptions.Builder()
148+
.db("example_db")
149+
.docId("example_id")
150+
.build();
151+
152+
Pojo p = new Pojo()
153+
try(InputStream is = service.getDocumentAsStream(documentOptions).execute().getResult()){
154+
p = YourSeriliazer.fromJson(is, Old.Pojo.class);
155+
System.out.println(p); // the value of the Pojo's toString method
156+
} catch (RuntimeException re){
157+
// ...
158+
}
159+
p.setName("new_name");
160+
System.out.println(p.getName()); // will be new_name
161+
162+
try (InputStream is = new ByteArrayInputStream(YourSeriliazer.toJson(p).getBytes())) {
163+
PutDocumentOptions putDocumentOptions =
164+
new PutDocumentOptions.Builder()
165+
.db("example_db")
166+
.docId("example_id")
167+
.body(is)
168+
.build();
169+
170+
DocumentResult response =
171+
service.putDocument(putDocumentOptions)
172+
.execute()
173+
.getResult();
174+
} catch (IOException e) {
175+
// ...
176+
}
177+
```
178+
179+
## Request mapping
180+
Here's a list of the top 5 most frequently used `java-cloudant` operations and the `cloudant-java-sdk` equivalent API operation documentation link:
181+
182+
| `java-cloudant` method | `cloudant-java-sdk` API method documentation link |
183+
|-----------------------------|---------------------------------|
184+
|`db.find()`|[`getDocument`](https://cloud.ibm.com/apidocs/cloudant?code=java#getdocument), `getDocumentAsStream`|
185+
|`db.getViewRequestBuilder().newRequest().build()`|[`postView`](https://cloud.ibm.com/apidocs/cloudant?code=java#postview), `postViewAsStream`|
186+
|`db.query()`|[`postFind`](https://cloud.ibm.com/apidocs/cloudant?code=java#postfind), `postFindAsStream`|
187+
|`db.contains()`|[`headDocument`](https://cloud.ibm.com/apidocs/cloudant?code=java#headdocument)|
188+
|`db.update()`|[`putDocument`](https://cloud.ibm.com/apidocs/cloudant?code=java#putdocument)|
189+
190+
[A table](#reference-table) with the whole list of operations is provided at the end of this guide.
191+
192+
The `cloudant-java-sdk` library is generated from a more complete API spec and provides a significant number of operations that do not exist in `java-cloudant`. See [the IBM Cloud API Documentation](https://cloud.ibm.com/apidocs/cloudant) to review request parameter and body options, code examples, and additional details for every endpoint.
193+
194+
## Known Issues
195+
There's an [outline of known issues](https://github.com/IBM/cloudant-java-sdk/blob/master/KNOWN_ISSUES.md) in the `cloudant-java-sdk` repository.
196+
197+
## Reference table
198+
The table below contains a list of `java-cloudant` functions and the `cloudant-java-sdk` equivalent API operation documentation link. The `cloudant-java-sdk` operation documentation link will contain the new function in a code sample e.g. `getServerInformation` link will contain a code example with `getServerInformation()`.
199+
200+
**Note:** There are many API operations included in the new `cloudant-java-sdk` that are not available in the `java-cloudant` library. The [API documentation](https://cloud.ibm.com/apidocs/cloudant?code=java) contains the full list of operations.
201+
202+
|java-cloudant operation | cloudant-java-sdk method reference |
203+
|-------------------------|--------------------------------------|
204+
|`metaInformation()`|[getServerInformation](https://cloud.ibm.com/apidocs/cloudant?code=java#getserverinformation)|
205+
|`getActiveTasks()`|[getActiveTasks](https://cloud.ibm.com/apidocs/cloudant?code=java#getactivetasks)|
206+
|`getAllDbs()`|[getAllDbs](https://cloud.ibm.com/apidocs/cloudant?code=java#getalldbs)|
207+
|`getMembership()`|[getMembershipInformation](https://cloud.ibm.com/apidocs/cloudant?code=java#getmembershipinformation)|
208+
|`replication().trigger()`|[postReplicate](https://cloud.ibm.com/apidocs/cloudant?code=java#postreplicate)|
209+
|`replicator().remove()`|[deleteReplicationDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#deletereplicationdocument)|
210+
|`replicator().find()`|[getReplicationDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#getreplicationdocument)|
211+
|`replicator().save()`|[putReplicationDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#putreplicationdocument)|
212+
|`schedulerDocs()`|[getSchedulerDocs](https://cloud.ibm.com/apidocs/cloudant?code=java#getschedulerdocs)|
213+
|`schedulerDoc()`|[getSchedulerDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#getschedulerdocument)|
214+
|`schedulerJobs()`|[getSchedulerJobs](https://cloud.ibm.com/apidocs/cloudant?code=java#getschedulerjobs)|
215+
|`uuids()`|[getUUids](https://cloud.ibm.com/apidocs/cloudant?code=java#getuuids)|
216+
|`deleteDB()`|[deleteDatabase](https://cloud.ibm.com/apidocs/cloudant?code=java#deletedatabase)|
217+
|`db.info()`|[getDatabaseInformation](https://cloud.ibm.com/apidocs/cloudant?code=java#getdatabaseinformation)|
218+
|`db.save()/db.post()`|[postDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#postdocument)|
219+
|`createDB()/database() with create=true/createPartitionedDb(dbName)`|[putDatabase](https://cloud.ibm.com/apidocs/cloudant?code=java#putdatabase)|
220+
|`db.getAllDocsRequestBuilder().build()`|[postAllDocs, postAllDocsAsStream](https://cloud.ibm.com/apidocs/cloudant?code=java#postalldocs)|
221+
|`db.bulk()`|[postBulkDocs](https://cloud.ibm.com/apidocs/cloudant?code=java#postbulkdocs)|
222+
|`db.changes()`|[postChanges, postChangesAsStream](https://cloud.ibm.com/apidocs/cloudant?code=java#postchanges)|
223+
|`db.getDesignDocumentManager().remove()`|[deleteDesignDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#deletedesigndocument)|
224+
|`db.getDesignDocumentManager().get()`|[getDesignDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#getdesigndocument)|
225+
|`db.getDesignDocumentManager().put()`|[putDesignDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#putdesigndocument)|
226+
|`db.search()`|[postSearch](https://cloud.ibm.com/apidocs/cloudant?code=java#postsearch), postSearchAsStream|
227+
|`db.getViewRequestBuilder().newRequest().build()`|[postView](https://cloud.ibm.com/apidocs/cloudant?code=java#postview), postViewAsStream|
228+
|`db.getDesignDocumentManager().list() with a filter`|[postDesignDocs](https://cloud.ibm.com/apidocs/cloudant?code=java#postdesigndocs)|
229+
|`db.query()`|[postFind](https://cloud.ibm.com/apidocs/cloudant?code=java#postfind), postFindAsStream|
230+
|`db.listIndexes()`|[getIndexesInformation](https://cloud.ibm.com/apidocs/cloudant?code=java#getindexesinformation)|
231+
|`db.createIndex()`|[postIndex](https://cloud.ibm.com/apidocs/cloudant?code=java#postindex)|
232+
|`db.deleteIndex()`|[deleteIndex](https://cloud.ibm.com/apidocs/cloudant?code=java#deleteindex)|
233+
|`db.remove() with an _id with _local path`|[deleteLocalDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#deletelocaldocument)|
234+
|`db.find() with _local path`|[getLocalDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#getlocaldocument)|
235+
|`db.save() with _local path`|[putLocalDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#putlocaldocument)|
236+
|`db.partitionInfo()`|[getPartitionInformation](https://cloud.ibm.com/apidocs/cloudant?code=java#getpartitioninformation)|
237+
|`db.getAllDocsRequestBuilder().partition().build()`|[postPartitionAllDocs](https://cloud.ibm.com/apidocs/cloudant?code=java#postpartitionalldocs), postPartitionAllDocsAsStream|
238+
|`db.search()`|[postPartitionSearch](https://cloud.ibm.com/apidocs/cloudant?code=java#postpartitionsearch), postPartitionSearchAsStream|
239+
|`db.getViewRequestBuilder().newRequest().partition().build()`|[postPartitionView](https://cloud.ibm.com/apidocs/cloudant?code=java#postpartitionview), postPartitionViewAsStream|
240+
|`db.query() using partitionKey method arg`|[postPartitionFind](https://cloud.ibm.com/apidocs/cloudant?code=java#postpartitionfind), postPartitionFindAsStream|
241+
|`db.getPermissions()`|[getSecurity](https://cloud.ibm.com/apidocs/cloudant?code=java#getsecurity)|
242+
|`db.setPermissions(userNameorApikey, permissions)`|[putSecurity](https://cloud.ibm.com/apidocs/cloudant?code=java#putsecurity)|
243+
|`db.getShards()`|[getShardsInformation](https://cloud.ibm.com/apidocs/cloudant?code=java#getshardsinformation)|
244+
|`db.getShard()`|[getDocumentShardsInfo](https://cloud.ibm.com/apidocs/cloudant?code=java#getdocumentshardsinfo)|
245+
|`db.remove()`|[deleteDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#deletedocument)|
246+
|`db.find()`|[getDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#getdocument), getDocumentAsStream|
247+
|`db.contains()`|[headDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#headdocument)|
248+
|`db.update()`|[putDocument](https://cloud.ibm.com/apidocs/cloudant?code=java#putdocument)|
249+
|`db.removeAttachment()`|[deleteAttachment](https://cloud.ibm.com/apidocs/cloudant?code=java#deleteattachment)|
250+
|`db.getAttachment()`|[getAttachment](https://cloud.ibm.com/apidocs/cloudant?code=java#getattachment)|
251+
|`db.saveAttachment()`|[putAttachment](https://cloud.ibm.com/apidocs/cloudant?code=java#putattachment)|
252+
|`generateApiKey()`|[postApiKeys](https://cloud.ibm.com/apidocs/cloudant?code=java#postapikeys)|
253+
|`db.setPermissions()`|[putCloudantSecurityConfiguration](https://cloud.ibm.com/apidocs/cloudant?code=java#putcloudantsecurity)|

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,10 @@ For information about contributing, building, and running tests see the [CONTRIB
179179

180180
The preferred approach for using java-cloudant in other projects is to use the Gradle or Maven dependency as described above.
181181

182+
## Migrating to `cloudant-java-sdk` library
183+
We have a newly supported Cloudant Java SDK named [cloudant-java-sdk](https://github.com/IBM/cloudant-java-sdk).
184+
For advice on migrating from this module see [MIGRATION.md](MIGRATION.md).
185+
182186
### License
183187

184188
Copyright © 2014, 2016 IBM Corp. All rights reserved.

0 commit comments

Comments
 (0)