Class CouchDbClientBase

java.lang.Object
org.lightcouch.CouchDbClientBase
Direct Known Subclasses:
CouchDbClient, CouchDbClientAndroid

public abstract class CouchDbClientBase extends Object
Contains a client Public API implementation.
See Also:
  • Field Details

    • log

      static final org.apache.commons.logging.Log log
    • baseURI

      private URI baseURI
    • dbURI

      private URI dbURI
    • gson

      private com.google.gson.Gson gson
    • context

      private CouchDbContext context
    • design

      private CouchDbDesign design
    • httpClient

      final org.apache.http.client.HttpClient httpClient
    • host

      final org.apache.http.HttpHost host
  • Constructor Details

    • CouchDbClientBase

      CouchDbClientBase()
    • CouchDbClientBase

      CouchDbClientBase(CouchDbConfig config)
  • Method Details

    • createHttpClient

      abstract org.apache.http.client.HttpClient createHttpClient(CouchDbProperties properties)
      Returns:
      HttpClient instance for HTTP request execution.
    • createContext

      abstract org.apache.http.protocol.HttpContext createContext()
      Returns:
      HttpContext instance for HTTP request execution.
    • shutdown

      abstract void shutdown()
      Shuts down the connection manager used by this client instance.
    • context

      public CouchDbContext context()
      Provides access to DB server APIs.
      Returns:
      CouchDbContext
    • design

      public CouchDbDesign design()
      Provides access to CouchDB Design Documents.
      Returns:
      CouchDbDesign
    • view

      public View view(String viewId)
      Provides access to CouchDB View APIs.
      Parameters:
      viewId - The view id.
      Returns:
      View
    • replication

      public Replication replication()
      Provides access to CouchDB replication APIs.
      Returns:
      Replication
    • replicator

      public Replicator replicator()
      Provides access to the replicator database.
      Returns:
      Replicator
    • changes

      public Changes changes()
      Provides access to Change Notifications API.
      Returns:
      Changes
    • find

      public <T> T find(Class<T> classType, String id)
      Finds an Object of the specified type.
      Type Parameters:
      T - Object type.
      Parameters:
      classType - The class of type T.
      id - The document id.
      Returns:
      An object of type T.
      Throws:
      NoDocumentException - If the document is not found in the database.
    • find

      public <T> T find(Class<T> classType, String id, Params params)
      Finds an Object of the specified type.
      Type Parameters:
      T - Object type.
      Parameters:
      classType - The class of type T.
      id - The document id.
      params - Extra parameters to append.
      Returns:
      An object of type T.
      Throws:
      NoDocumentException - If the document is not found in the database.
    • find

      public <T> T find(Class<T> classType, String id, String rev)
      Finds an Object of the specified type.
      Type Parameters:
      T - Object type.
      Parameters:
      classType - The class of type T.
      id - The document _id field.
      rev - The document _rev field.
      Returns:
      An object of type T.
      Throws:
      NoDocumentException - If the document is not found in the database.
    • findAny

      public <T> T findAny(Class<T> classType, String uri)
      This method finds any document given a URI.

      The URI must be URI-encoded.

      Type Parameters:
      T - The class type.
      Parameters:
      classType - The class of type T.
      uri - The URI as string.
      Returns:
      An object of type T.
    • find

      public InputStream find(String id)
      Finds a document and return the result as InputStream.

      Note: The stream must be closed after use to release the connection.

      Parameters:
      id - The document _id field.
      Returns:
      The result as InputStream
      Throws:
      NoDocumentException - If the document is not found in the database.
      See Also:
    • find

      public InputStream find(String id, String rev)
      Finds a document given id and revision and returns the result as InputStream.

      Note: The stream must be closed after use to release the connection.

      Parameters:
      id - The document _id field.
      rev - The document _rev field.
      Returns:
      The result as InputStream
      Throws:
      NoDocumentException - If the document is not found in the database.
    • findDocs

      public <T> List<T> findDocs(String jsonQuery, Class<T> classOfT)
      Find documents using a declarative JSON querying syntax.
      Type Parameters:
      T - The class type.
      Parameters:
      jsonQuery - The JSON query string.
      classOfT - The class of type T.
      Returns:
      The result of the query as a List<T>
      Throws:
      CouchDbException - If the query failed to execute or the request is invalid.
    • contains

      public boolean contains(String id)
      Checks if a document exist in the database.
      Parameters:
      id - The document _id field.
      Returns:
      true If the document is found, false otherwise.
    • save

      public Response save(Object object)
      Saves an object in the database, using HTTP PUT request.

      If the object doesn't have an _id value, the code will assign a UUID as the document id.

      Parameters:
      object - The object to save
      Returns:
      Response
      Throws:
      DocumentConflictException - If a conflict is detected during the save.
    • post

      public Response post(Object object)
      Saves an object in the database using HTTP POST request.

      The database will be responsible for generating the document id.

      Parameters:
      object - The object to save
      Returns:
      Response
    • batch

      public void batch(Object object)
      Saves a document with batch=ok query param.
      Parameters:
      object - The object to save.
    • update

      public Response update(Object object)
      Updates an object in the database, the object must have the correct _id and _rev values.
      Parameters:
      object - The object to update
      Returns:
      Response
      Throws:
      DocumentConflictException - If a conflict is detected during the update.
    • remove

      public Response remove(Object object)
      Removes a document from the database.

      The object must have the correct _id and _rev values.

      Parameters:
      object - The document to remove as object.
      Returns:
      Response
      Throws:
      NoDocumentException - If the document is not found in the database.
    • remove

      public Response remove(String id, String rev)
      Removes a document from the database given both a document _id and _rev values.
      Parameters:
      id - The document _id field.
      rev - The document _rev field.
      Returns:
      Response
      Throws:
      NoDocumentException - If the document is not found in the database.
    • bulk

      public List<Response> bulk(List<?> objects, boolean newEdits)
      Performs bulk documents create and update request.
      Parameters:
      objects - The List of documents objects.
      newEdits - If false, prevents the database from assigning documents new revision IDs.
      Returns:
      List<Response> Containing the resulted entries.
    • saveAttachment

      public Response saveAttachment(InputStream in, String name, String contentType)
      Saves an attachment to a new document with a generated UUID as the document id.

      To retrieve an attachment, see find(String).

      Parameters:
      in - The InputStream holding the binary data.
      name - The attachment name.
      contentType - The attachment "Content-Type".
      Returns:
      Response
    • saveAttachment

      public Response saveAttachment(InputStream in, String name, String contentType, String docId, String docRev)
      Saves an attachment to an existing document given both a document id and revision, or save to a new document given only the id, and rev as null.

      To retrieve an attachment, see find(String).

      Parameters:
      in - The InputStream holding the binary data.
      name - The attachment name.
      contentType - The attachment "Content-Type".
      docId - The document id to save the attachment under, or null to save under a new document.
      docRev - The document revision to save the attachment under, or null when saving to a new document.
      Returns:
      Response
    • invokeUpdateHandler

      public String invokeUpdateHandler(String updateHandlerUri, String docId, Params params)
      Invokes an Update Handler.
       Params params = new Params()
              .addParam("field", "foo")
              .addParam("value", "bar"); 
       String output = dbClient.invokeUpdateHandler("designDoc/update1", "docId", params);
       
      Parameters:
      updateHandlerUri - The Update Handler URI, in the format: designDoc/update1
      docId - The document id to update.
      params - The query parameters as Params.
      Returns:
      The output of the request.
    • executeRequest

      public org.apache.http.HttpResponse executeRequest(org.apache.http.client.methods.HttpRequestBase request)
      Executes a HTTP request.

      Note: The response must be closed after use to release the connection.

      Parameters:
      request - The HTTP request to execute.
      Returns:
      HttpResponse
    • syncDesignDocsWithDb

      public void syncDesignDocsWithDb()
      Synchronize all design documents with the database.
    • setGsonBuilder

      public void setGsonBuilder(com.google.gson.GsonBuilder gsonBuilder)
      Sets a GsonBuilder to create Gson instance.

      Useful for registering custom serializers/deserializers, such as JodaTime classes.

      Parameters:
      gsonBuilder - The GsonBuilder
    • getBaseUri

      public URI getBaseUri()
      Returns:
      The base URI.
    • getDBUri

      public URI getDBUri()
      Returns:
      The database URI.
    • getGson

      public com.google.gson.Gson getGson()
      Returns:
      The Gson instance.
    • get

      InputStream get(org.apache.http.client.methods.HttpGet httpGet)
      Performs a HTTP GET request.
      Returns:
      InputStream
    • get

      InputStream get(URI uri)
      Performs a HTTP GET request.
      Returns:
      InputStream
    • get

      <T> T get(URI uri, Class<T> classType)
      Performs a HTTP GET request.
      Returns:
      An object of type T
    • head

      org.apache.http.HttpResponse head(URI uri)
      Performs a HTTP HEAD request.
      Returns:
      HttpResponse
    • put

      Response put(URI uri, Object object, boolean newEntity)
      Performs a HTTP PUT request, saves or updates a document.
      Returns:
      Response
    • put

      Response put(URI uri, InputStream instream, String contentType)
      Performs a HTTP PUT request, saves an attachment.
      Returns:
      Response
    • post

      org.apache.http.HttpResponse post(URI uri, String json)
      Performs a HTTP POST request.
      Returns:
      HttpResponse
    • delete

      Response delete(URI uri)
      Performs a HTTP DELETE request.
      Returns:
      Response
    • validate

      void validate(org.apache.http.HttpResponse response) throws IOException
      Validates a HTTP response; on error cases logs status and throws relevant exceptions.
      Parameters:
      response - The HTTP response.
      Throws:
      IOException
    • getResponse

      private Response getResponse(org.apache.http.HttpResponse response) throws CouchDbException
      Parameters:
      response - The HttpResponse
      Returns:
      Response
      Throws:
      CouchDbException
    • getResponseList

      private List<Response> getResponseList(org.apache.http.HttpResponse response) throws CouchDbException
      Parameters:
      response - The HttpResponse
      Returns:
      Response
      Throws:
      CouchDbException
    • setEntity

      private void setEntity(org.apache.http.client.methods.HttpEntityEnclosingRequestBase httpRequest, String json)
      Sets a JSON String as a request entity.
      Parameters:
      httpRequest - The request to set entity.
      json - The JSON String to set.
    • initGson

      private com.google.gson.Gson initGson(com.google.gson.GsonBuilder gsonBuilder)
      Builds Gson and registers any required serializer/deserializer.
      Returns:
      Gson instance