main.java.com.cloudant.client.api.CloudantClient Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of cloudant-client Show documentation
Show all versions of cloudant-client Show documentation
Official Cloudant client for Java
/*
* Copyright (c) 2015 IBM Corp. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the
* License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
* either express or implied. See the License for the specific language governing permissions
* and limitations under the License.
*/
package com.cloudant.client.api;
import static com.cloudant.client.org.lightcouch.internal.CouchDbUtil.close;
import static com.cloudant.client.org.lightcouch.internal.CouchDbUtil.getResponse;
import static com.cloudant.client.org.lightcouch.internal.CouchDbUtil.getResponseList;
import com.cloudant.client.api.model.ApiKey;
import com.cloudant.client.api.model.IndexField;
import com.cloudant.client.api.model.Membership;
import com.cloudant.client.api.model.Task;
import com.cloudant.client.internal.URIBase;
import com.cloudant.client.org.lightcouch.Changes;
import com.cloudant.client.org.lightcouch.CouchDbClient;
import com.cloudant.client.org.lightcouch.CouchDbException;
import com.cloudant.client.org.lightcouch.CouchDbProperties;
import com.cloudant.client.org.lightcouch.Replication;
import com.cloudant.client.org.lightcouch.Replicator;
import com.cloudant.http.HttpConnection;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.reflect.TypeToken;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.util.EnumSet;
import java.util.List;
/**
* Exposes the Cloudant client API
*
* This class is the main object to use to gain access to the Cloudant APIs. Instances of
* CloudantClient are created using a ClientBuilder. Once created a CloudantClient is immutable
* and safe to access from multiple threads.
*
*
* Usage Examples:
*
* Create a new Cloudant client instance
*
* CloudantClient client = ClientBuilder.account
*
* CloudantClient("mycloudantaccount","myusername",
* "mypassword");
*
*
* Client use of the API
*
* - Server APIs accessed by the client directly e.g.:
*
* {@link CloudantClient#getAllDbs() client.getAllDbs()}
*
*
* - DB is accessed by getting the {@link Database} from the client e.g.:
*
* Database db = client.database("customers",false);
*
*
* - Document
CRUD APIs accessed from the {@link Database} e.g.:
*
* {@link Database#find(Class, String) db.find(Foo.class, "doc-id")}
*
*
*
*
* Cloudant Query
*
* - Create an index
* {@link Database#createIndex(String, String, String, IndexField[])} e.g.:
*
*
* db.createIndex("Person_name", "Person_name_design_doc", "json", new IndexField[] { new IndexField
* ("Person_name",SortOrder.asc)})
*
*
*
* - Find using an index
* {@link Database#findByIndex(String, Class)} e.g.:
*
*
* db.findByIndex(" \"selector\": {
* \"Person_name\": \"Alec Guinness\" }", Movie.class)}
*
*
*
* - Delete an index
* {@link Database#deleteIndex(String, String)} e.g.:
*
*
* db.deleteIndex("Person_name", "Person_name_design_doc")
*
*
*
*
*
* Cloudant Search
* {@link Search db.search("views101/animals")}
*
* View APIs
* {@link com.cloudant.client.api.views}
*
* Change Notifications
* {@link Changes db.changes()}
*
* Design Documents
* {@link DesignDocumentManager db.getDesignDocumentManager()}
*
* Replication
* Replication {@link Replication account.replication()} and {@link Replicator account.replicator()}
*
* @author Mario Briggs
* @since 0.0.1
*/
public class CloudantClient {
CouchDbClient couchDbClient;
/**
* Constructs a new instance of this class and connects to the cloudant server with the
* specified credentials
*
* @param props Properties file with account path, credentials, and connection options
*/
CloudantClient(CouchDbProperties props, GsonBuilder gsonBuilder) {
this.couchDbClient = new CouchDbClient(props);
// set the gsonbuilder that includes additional cloudant deserializers
couchDbClient.setGsonBuilder(gsonBuilder);
}
/**
* Use the authorization feature to generate new API keys to access your data. An API key is
* similar to a username/password pair for granting others access to your data.
* Example usage:
*
*
* {@code
* ApiKey key = client.generateApiKey();
* System.out.println(key);
* }
*
* Example output:
*
*
* {@code key: isdaingialkyciffestontsk password: XQiDHmwnkUu4tknHIjjs2P64}
*
*
* @return the generated key and password
* @see Database#setPermissions(String, EnumSet)
*/
public ApiKey generateApiKey() {
URI uri = new URIBase(getBaseUri()).path("_api").path("v2").path("api_keys").build();
InputStream response = couchDbClient.post(uri, null);
return getResponse(response, ApiKey.class, getGson());
}
/**
* Get the list of active tasks from the server.
*
* @return List of tasks
* @see Active tasks
*/
public List getActiveTasks() {
InputStream response = null;
URI uri = new URIBase(getBaseUri()).path("_active_tasks").build();
try {
response = couchDbClient.get(uri);
return getResponseList(response, couchDbClient.getGson(),
new TypeToken>() {
}.getType());
} finally {
close(response);
}
}
/**
* Get the list of all nodes and the list of active nodes in the cluster.
*
* @return Membership object encapsulating lists of all nodes and the cluster nodes
* @see _membership
*/
public Membership getMembership() {
URI uri = new URIBase(getBaseUri()).path("_membership").build();
Membership membership = couchDbClient.get(uri,
Membership.class);
return membership;
}
/**
* Get a database reference for the database with the specified name.
*
* @param name name of database to access
* @param create flag indicating whether to create the database if it does not exist
* @return Database object
* @throws com.cloudant.client.org.lightcouch.NoDocumentException if the database does not
* exist and create was false
* @see Databases -
* read
*/
public Database database(String name, boolean create) {
return new Database(this, couchDbClient.database(name, create));
}
/**
* Request to delete the database with the specified name.
*
* @param dbName the database name
* @see Databases - delete
*
*/
public void deleteDB(String dbName) {
couchDbClient.deleteDB(dbName);
}
/**
* Request to create a new database with the specified name.
*
* @param dbName the database name
* @throws com.cloudant.client.org.lightcouch.PreconditionFailedException if a database with
* the same name
* already exists
* @see Databases -
* create
*/
public void createDB(String dbName) {
couchDbClient.createDB(dbName);
}
/**
* @return The base URI.
*/
public URI getBaseUri() {
return couchDbClient.getBaseUri();
}
/**
* List all the databases on the server for the Cloudant account.
*
* @return List of the names of all the databases
* @see
* Databases - get databases
*/
public List getAllDbs() {
return couchDbClient.getAllDbs();
}
/**
* Get the reported server version from the welcome message metadata.
*
* @return Cloudant server version.
* @see Welcome
* message
*/
public String serverVersion() {
return couchDbClient.serverVersion();
}
/**
* Provides access to Cloudant replication APIs.
*
* @return Replication object for configuration and triggering
* @see com.cloudant.client.api.Replication
* @see
* Replication - _replicate
*
*/
public com.cloudant.client.api.Replication replication() {
Replication couchDbReplication = couchDbClient.replication();
com.cloudant.client.api.Replication replication = new com.cloudant.client.api.Replication
(couchDbReplication);
return replication;
}
/**
* Provides access to Cloudant replication APIs.
*
* @return Replicator object for interacting with the _replicator DB
* @see com.cloudant.client.api.Replicator
* @see
* Replication - _replicator
*
*/
public com.cloudant.client.api.Replicator replicator() {
Replicator couchDbReplicator = couchDbClient.replicator();
com.cloudant.client.api.Replicator replicator = new com.cloudant.client.api.Replicator
(couchDbReplicator);
return replicator;
}
/**
* Executes a HTTP request. This method provides a mechanism to perform operations not
* currently available in the client API.
* Note: Streams obtained from the HttpConnection must be closed after use to release
* the connection.
*
*
* {@code
* HttpConnection response = account.executeRequest(Http.GET(new URL(account.getBaseUri() +
* "/aNewAPI")));
* if (response.getConnection().getResponseCode() == HttpURLConnection.HTTP_OK) {
* InputStream stream = response.responseAsInputStream();
* //process stream
* }
* }
*
*
* @param request The HTTP request to execute, obtained from {@link com.cloudant.http.Http}.
* @return {@link HttpConnection} that has been executed
* @throws CouchDbException for error HTTP status codes or if there is an {@link IOException}
*/
public HttpConnection executeRequest(HttpConnection request) {
return couchDbClient.execute(request);
}
/**
* Shuts down the connection manager used by this client instance.
*/
public void shutdown() {
couchDbClient.shutdown();
}
/**
* Request a list of generated UUIDs from the Cloudant server.
*
* @param count the number of UUIDs
* @return a List of UUID Strings
* @see _uuids
*/
public List uuids(long count) {
return couchDbClient.uuids(count);
}
/**
* @return The Gson instance.
*/
public Gson getGson() {
return couchDbClient.getGson();
}
}