Commits

Andy Gross  committed 8fc95ab

javadocs and cleanup in the java client

  • Participants
  • Parent commits 7448319

Comments (0)

Files changed (3)

File client_lib/java/src/com/basho/riak/JiakClient.java

 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.  
-*/
-
+ */
 package com.basho.riak;
 
 import java.io.ByteArrayOutputStream;
 
 import sun.net.www.protocol.http.HttpURLConnection;
 
+/**
+ * Client class for accessing the Riak document store via the HTTP/JSON
+ * interface.
+ * 
+ * @author Andy Gross <andy@basho.com>
+ * @version 0.1
+ */
 public class JiakClient {
 
-	private String ip;
-	private String port;
-	private String prefix;
-	
-	public JiakClient(String ip, String port) {
+	private final String ip;
+	private final String port;
+	private final String prefix;
+
+	/**
+	 * Construct a JiakClient with the default server path prefix of /jiak/
+	 * 
+	 * @param ip
+	 *            The IP address of the Riak server
+	 * @param port
+	 *            The Jiak web port to access
+	 */
+	public JiakClient(final String ip, final String port) {
 		this(ip, port, "/jiak/");
 	}
-	
-	public JiakClient(String ip, String port, String prefix) {
+
+	/**
+	 * Construct a JiakClient with a user-specified path prefix
+	 * 
+	 * @param ip
+	 *            The IP address of the Riak server.
+	 * @param port
+	 *            The Jiak web port to access.
+	 * @param prefix
+	 *            The server path prefix.
+	 */
+	public JiakClient(final String ip, final String port, final String prefix) {
 		this.ip = ip;
-		this.port = port;		
+		this.port = port;
 		this.prefix = prefix;
 	}
-	
-	public void setBucketSchema(String bucket, 
-								List<String> allowedFields, 
-								List<String> writeMask, 
-								List<String> readMask, 
-								List<String> requiredFields) 
-		throws JSONException, IOException, JiakException {
-		
-		if (requiredFields == null) requiredFields = new ArrayList<String>();
-		if (writeMask == null) writeMask = new ArrayList<String>(allowedFields);
-		if (readMask == null) readMask = new ArrayList<String>(allowedFields);
-		
-		JSONObject schema = new JSONObject();
+
+	/**
+	 * Set the schema describing the structure and per-field permissions for a
+	 * Riak bucket.
+	 * 
+	 * @param bucket
+	 *            The bucket name.
+	 * @param allowedFields
+	 *            The complete list of field names allowed in a document.
+	 * @param writeMask
+	 *            The list of writable fields, or null. If null, the write mask
+	 *            is set to the value of <code>allowedFields</code>.
+	 * @param readMask
+	 *            The list of readable fields, or null. If null, the read mask
+	 *            is set to the value of <code>allowedFields</code>.
+	 * @param requiredFields
+	 *            The list of fields that must be present when creating or
+	 *            updating a document. If null, <code>requiredFields</code> is
+	 *            set to an empty list.
+	 * 
+	 * @throws JSONException
+	 *             If an error occurs assembling the JSON request body.
+	 * @throws IOException
+	 *             If an error occurs during communication with the Riak server.
+	 * @throws JiakException
+	 *             If the Riak server returns an error or or an unexpected
+	 *             response code.
+	 */
+	public void setBucketSchema(final String bucket,
+			final List<String> allowedFields, List<String> writeMask,
+			List<String> readMask, List<String> requiredFields)
+			throws JSONException, IOException, JiakException {
+
+		if (requiredFields == null)
+			requiredFields = new ArrayList<String>();
+		if (writeMask == null)
+			writeMask = new ArrayList<String>(allowedFields);
+		if (readMask == null)
+			readMask = new ArrayList<String>(allowedFields);
+
+		final JSONObject schema = new JSONObject();
 		schema.put("allowed_fields", allowedFields);
 		schema.put("required_fields", requiredFields);
 		schema.put("read_mask", readMask);
 		schema.put("write_mask", writeMask);
-		JSONObject schemaReqBody = new JSONObject();
+		final JSONObject schemaReqBody = new JSONObject();
 		schemaReqBody.put("schema", schema);
-		HashMap<String, String> reqHeaders = new HashMap<String, String>();
+		final HashMap<String, String> reqHeaders = new HashMap<String, String>();
 		reqHeaders.put("Content-Type", "application/json");
 		reqHeaders.put("Accept", "application/json");
-		String reqURI = makeURI(bucket);
-		HttpURLConnection requestConn = doRequest("PUT", 
-				reqURI, schemaReqBody, reqHeaders);
-		if (requestConn.getResponseCode() != 204) {
+		final String reqURI = makeURI(bucket);
+		final HttpURLConnection requestConn = doRequest("PUT", reqURI,
+				schemaReqBody, reqHeaders);
+		if (requestConn.getResponseCode() != 204)
 			throw new JiakException(requestConn.getResponseMessage());
-		}
 	}
-	
-	public JSONObject listBucket(String bucket) 
-		throws IOException, JSONException, JiakException {
-		HashMap<String, String> reqHeaders = new HashMap<String, String>();
+
+	/**
+	 * Return the schema and keys for a Riak bucket.
+	 * 
+	 * @param bucket
+	 *            The bucket to list.
+	 * @return A <code>JSONObject</code> with keys <code>schema</code> and
+	 *         <code>keys</code>.
+	 * @throws JSONException
+	 *             If an error occurs assembling the JSON request body.
+	 * @throws IOException
+	 *             If an error occurs during communication with the Riak server.
+	 * @throws JiakException
+	 *             If the Riak server returns an error or or an unexpected
+	 *             response code.
+	 */
+	public JSONObject listBucket(final String bucket) throws IOException,
+			JSONException, JiakException {
+		final HashMap<String, String> reqHeaders = new HashMap<String, String>();
 		reqHeaders.put("Content-Type", "application/json");
-		reqHeaders.put("Accept", "application/json");		
-		HttpURLConnection requestConn = doRequest("GET", makeURI(bucket), null, reqHeaders);
+		reqHeaders.put("Accept", "application/json");
+		final HttpURLConnection requestConn = doRequest("GET", makeURI(bucket),
+				null, reqHeaders);
 		return expect(200, requestConn);
 	}
-	
-	public void store(JiakObject object) 
-		throws IOException, JSONException, JiakException {
-		HashMap<String, String> reqHeaders = new HashMap<String, String>();
+
+	/**
+	 * Store a {@link JiakObject}.
+	 * 
+	 * @param object
+	 *            The {@link JiakObject} to store.
+	 * 
+	 * @throws JSONException
+	 *             If an error occurs assembling the JSON request body.
+	 * @throws IOException
+	 *             If an error occurs during communication with the Riak server.
+	 * @throws JiakException
+	 *             If the Riak server returns an error or or an unexpected
+	 *             response code.
+	 */
+	public void store(final JiakObject object) throws IOException,
+			JSONException, JiakException {
+		final HashMap<String, String> reqHeaders = new HashMap<String, String>();
 		reqHeaders.put("Content-Type", "application/json");
 		reqHeaders.put("Accept", "application/json");
-		String reqURI = makeURI(object.getBucket() + "/" + object.getKey() + "?returnbody=true");
-		HttpURLConnection requestConn = doRequest("PUT", reqURI, object.toJSONObject(), reqHeaders);
-		JSONObject updated = expect(200, requestConn);
+		final String reqURI = makeURI(object.getBucket() + "/"
+				+ object.getKey() + "?returnbody=true");
+		final HttpURLConnection requestConn = doRequest("PUT", reqURI, object
+				.toJSONObject(), reqHeaders);
+		final JSONObject updated = expect(200, requestConn);
 		object.update(updated);
 	}
-	
-	public JiakObject fetch(String bucket, String key) 
-		throws IOException, JSONException, JiakException {
-		HashMap<String, String> reqHeaders = new HashMap<String, String>();
+
+	/**
+	 * Fetch the {@link JiakObject} stored at <code>bucket</code> and
+	 * <code>key</code>.
+	 * 
+	 * @param bucket
+	 *            The bucket containing the {@link JiakObject} to fetch.
+	 * @param key
+	 *            The key of the {@link JiakObject} to fetch.
+	 * 
+	 * @return A {@link JiakObject}.
+	 * 
+	 * @throws JSONException
+	 *             If an error occurs assembling the JSON request body.
+	 * @throws IOException
+	 *             If an error occurs during communication with the Riak server.
+	 * @throws JiakException
+	 *             If the Riak server returns an error or or an unexpected
+	 *             response code.
+	 */
+	public JiakObject fetch(final String bucket, final String key)
+			throws IOException, JSONException, JiakException {
+		final HashMap<String, String> reqHeaders = new HashMap<String, String>();
 		reqHeaders.put("Content-Type", "application/json");
 		reqHeaders.put("Accept", "application/json");
-		String reqURI = makeURI(bucket + "/" + key);
-		HttpURLConnection requestConn = doRequest("GET", reqURI, null, reqHeaders);
-		if (requestConn.getResponseCode() == 404) return null;
-		JSONObject objData = expect(200, requestConn);
-		JiakObject object = new JiakObject(bucket, key);
+		final String reqURI = makeURI(bucket + "/" + key);
+		final HttpURLConnection requestConn = doRequest("GET", reqURI, null,
+				reqHeaders);
+		if (requestConn.getResponseCode() == 404)
+			return null;
+		final JSONObject objData = expect(200, requestConn);
+		final JiakObject object = new JiakObject(bucket, key);
 		object.update(objData);
 		return object;
 	}
-	
-	public void delete(String bucket, String key) throws IOException, JiakException {
-		String reqURI = makeURI(bucket + "/" + key);
-		HashMap<String, String> reqHeaders = new HashMap<String, String>();
-		reqHeaders.put("Accept", "*/*");				
-		HttpURLConnection requestConn = doRequest("DELETE", reqURI, null, reqHeaders);
-		int responseCode = requestConn.getResponseCode();
-		if ((responseCode != 404) && (responseCode != 204)) 
+
+	/**
+	 * Delete a {@link JiakObject}.
+	 * 
+	 * @param bucket
+	 *            The bucket containing the object to delete.
+	 * @param key
+	 *            The key of the object to delete.
+	 * 
+	 * @throws JSONException
+	 *             If an error occurs assembling the JSON request body.
+	 * @throws IOException
+	 *             If an error occurs during communication with the Riak server.
+	 * @throws JiakException
+	 *             If the Riak server returns an error or or an unexpected
+	 *             response code.
+	 */
+	public void delete(final String bucket, final String key)
+			throws IOException, JiakException {
+		final String reqURI = makeURI(bucket + "/" + key);
+		final HashMap<String, String> reqHeaders = new HashMap<String, String>();
+		reqHeaders.put("Accept", "*/*");
+		final HttpURLConnection requestConn = doRequest("DELETE", reqURI, null,
+				reqHeaders);
+		final int responseCode = requestConn.getResponseCode();
+		if (responseCode != 404 && responseCode != 204)
 			throw new JiakException(requestConn.getResponseMessage());
 	}
-	
-	protected HttpURLConnection doRequest(String method, 
-							 			  String uri, 
-							 			  JSONObject body, 
-							 			  Map<String, String> headers) 
-		throws IOException {
-		URL requestURL = new URL(uri);
-		HttpURLConnection requestConn = (HttpURLConnection)requestURL.openConnection();
+
+	protected HttpURLConnection doRequest(final String method,
+			final String uri, final JSONObject body,
+			final Map<String, String> headers) throws IOException {
+		final URL requestURL = new URL(uri);
+		final HttpURLConnection requestConn = (HttpURLConnection) requestURL
+				.openConnection();
 		requestConn.setRequestMethod(method);
-		if (headers != null) {
-			for (String k : headers.keySet()) {
+		if (headers != null)
+			for (final String k : headers.keySet())
 				requestConn.setRequestProperty(k, headers.get(k));
-			}
-		}
 		if (body != null) {
 			requestConn.setDoOutput(true);
 			writeRequestBody(requestConn, body);
 		return requestConn;
 	}
 
-	protected JSONObject expect(int responseCode, HttpURLConnection connection) 
-		throws JSONException, JiakException, IOException {
+	protected JSONObject expect(final int responseCode,
+			final HttpURLConnection connection) throws JSONException,
+			JiakException, IOException {
 		if (connection.getResponseCode() == responseCode) {
-			String responseBody = readResponseBody(connection);
+			final String responseBody = readResponseBody(connection);
 			return new JSONObject(responseBody);
 		}
 		throw new JiakException(connection.getResponseMessage());
 	}
-	
-	protected String makeURI(String path) {
-		return "http://" + this.ip + ":" + this.port + this.prefix + path;
+
+	protected String makeURI(final String path) {
+		return "http://" + ip + ":" + port + prefix + path;
 	}
-	
-	protected static void writeRequestBody(URLConnection connection, 
-										   JSONObject body) {
+
+	protected static void writeRequestBody(final URLConnection connection,
+			final JSONObject body) {
 		OutputStream outputStream;
 		try {
 			outputStream = connection.getOutputStream();
-		} catch (IOException e1) {
+		} catch (final IOException e1) {
 			e1.printStackTrace();
 			return;
 		}
-		OutputStreamWriter outputStreamWriter = new OutputStreamWriter(outputStream);
+		final OutputStreamWriter outputStreamWriter = new OutputStreamWriter(
+				outputStream);
 		try {
 			outputStreamWriter.write(body.toString());
 			outputStreamWriter.flush();
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			e.printStackTrace();
-		}
-		finally {
+		} finally {
 			try {
 				outputStream.close();
-			} catch (IOException e) {
+			} catch (final IOException e) {
 				e.printStackTrace();
 			}
 		}
 	}
 
-	protected static String readResponseBody(HttpURLConnection connection)  {
+	protected static String readResponseBody(final HttpURLConnection connection) {
 		String urlContent = null;
 		InputStream inputStream;
 		try {
 			inputStream = connection.getInputStream();
-		} catch (IOException e) {
+		} catch (final IOException e) {
 			e.printStackTrace();
 			return urlContent;
 		}
 		try {
 			urlContent = downloadStream(inputStream);
-		} 
-		catch (IOException e) {
+		} catch (final IOException e) {
 			e.printStackTrace();
-		}
-		finally {
+		} finally {
 			try {
 				inputStream.close();
-			} catch (IOException e) {
+			} catch (final IOException e) {
 				e.printStackTrace();
 			}
 		}
 		return urlContent;
 	}
 
-	public static String downloadStream(InputStream in) 
-		throws IOException {
+	protected static String downloadStream(final InputStream in)
+			throws IOException {
 
-		OutputStream out = new ByteArrayOutputStream();
-	    try {
-	    	copy(in, out);
-	    } finally {
-	    	in.close();
-	    	out.close();
-	    }
-	    return out.toString();
-	     
+		final OutputStream out = new ByteArrayOutputStream();
+		try {
+			copy(in, out);
+		} finally {
+			in.close();
+			out.close();
+		}
+		return out.toString();
+
 	}
-	
-	private static void copy(InputStream in, OutputStream out) 
-		throws IOException {
-		
-		byte[] buffer = new byte[1024];
-	    while (true) {
-	    	int readCount = in.read(buffer);
-	    	if (readCount == -1) {
-	    		break;
-	    	}
-	    	out.write(buffer, 0, readCount);
-	    }
+
+	protected static void copy(final InputStream in, final OutputStream out)
+			throws IOException {
+
+		final byte[] buffer = new byte[1024];
+		while (true) {
+			final int readCount = in.read(buffer);
+			if (readCount == -1)
+				break;
+			out.write(buffer, 0, readCount);
+		}
 	}
 }

File client_lib/java/src/com/basho/riak/JiakException.java

 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.  
-*/
-
+ */
 package com.basho.riak;
 
+/**
+ * Default Jiak exception.
+ * 
+ * 
+ */
 public class JiakException extends Exception {
 
 	private static final long serialVersionUID = -4739928528628198267L;
 
-	public JiakException() {}
+	public JiakException() {
+	}
 
-	public JiakException(String message) {
+	public JiakException(final String message) {
 		super(message);
 	}
 
-	public JiakException(Throwable cause) {
+	public JiakException(final Throwable cause) {
 		super(cause);
 	}
 
-	public JiakException(String message, Throwable cause) {
+	public JiakException(final String message, final Throwable cause) {
 		super(message, cause);
 	}
 

File client_lib/java/src/com/basho/riak/JiakObject.java

 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.  
-*/
+ */
 
 package com.basho.riak;
 
 import org.json.JSONException;
 import org.json.JSONObject;
 
+/**
+ * Container class for Riak/Jiak data. The actual user data in a JiakObject is
+ * contained in the <code>.object</code> field of a JiakObject. The other
+ * top-level fields are metadata that must be carried along with the object in
+ * order to properly modify the object in subsequent requests.
+ * 
+ * @author Andy Gross <andy@basho.com>
+ * @version 0.1
+ */
+
 public class JiakObject {
 
-	private String bucket;
-	private String key;
+	private final String bucket;
+	private final String key;
 	private JSONArray links;
 	private JSONObject object;
 	private String vclock;
 	private String lastmod;
 	private String vtag;
 
-	public JiakObject(String bucket, String key) {
+	/**
+	 * Construct an empty Jiak object.
+	 * 
+	 * @param bucket
+	 *            The containing bucket for this JiakObject.
+	 * @param key
+	 *            The key of this JiakObject.
+	 */
+	public JiakObject(final String bucket, final String key) {
 		this(bucket, key, new JSONArray());
 	}
-	
-	public JiakObject(String bucket, String key, JSONArray links) {
+
+	/**
+	 * Construct a Jiak object and define a starting set of links.
+	 * 
+	 * @param bucket
+	 *            The containing bucket for this JiakObject.
+	 * @param key
+	 *            The key of this JiakObject.
+	 * @param links
+	 *            The links for this JiakObject. The links field is a JSONArray
+	 *            of JSONArrays of the form:
+	 *            <code>["bucket", "key", "tag"]</code>.
+	 */
+	public JiakObject(final String bucket, final String key,
+			final JSONArray links) {
 		this(bucket, key, links, new JSONObject());
 	}
-	
-	public JiakObject(String bucket, String key, JSONArray links, JSONObject object) {
+
+	/**
+	 * Construct a Jiak object and define a starting set of links and object
+	 * values.
+	 * 
+	 * @param bucket
+	 *            The containing bucket for this JiakObject.
+	 * @param key
+	 *            The key of this JiakObject.
+	 * @param links
+	 *            The links for this JiakObject. The links field is a JSONArray
+	 *            of JSONArrays of the form:
+	 *            <code>["bucket", "key", "tag"]</code>.
+	 * @param object
+	 *            A JSONObject representing the initial value of this object.
+	 */
+	public JiakObject(final String bucket, final String key,
+			final JSONArray links, final JSONObject object) {
 		this.bucket = bucket;
 		this.key = key;
 		this.links = links;
 		this.object = object;
-		this.vclock = null;
-		this.lastmod = null;
-		this.vtag = null;
+		vclock = null;
+		lastmod = null;
+		vtag = null;
 	}
 
+	/**
+	 * Get the bucket for this JiakObject.
+	 * 
+	 * @return The bucket for this object.
+	 */
 	public String getBucket() {
 		return bucket;
 	}
 
-	public void setBucket(String bucket) {
-		this.bucket = bucket;
-	}
-
+	/**
+	 * Get the key for this JiakObject.
+	 * 
+	 * @return The key for this object.
+	 */
 	public String getKey() {
 		return key;
 	}
 
-	public void setKey(String key) {
-		this.key = key;
-	}
-
+	/**
+	 * Get the links for this JiakObject.
+	 * 
+	 * @return A JSONArray of links for this object.
+	 */
 	public JSONArray getLinks() {
 		return links;
 	}
 
-	public void setLinks(JSONArray links) {
+	/**
+	 * Set the links for this JiakObject.
+	 * 
+	 * @param links
+	 *            The links to set for this object.
+	 */
+	public void setLinks(final JSONArray links) {
 		this.links = links;
 	}
 
+	/**
+	 * Get the object data for this JiakObject.
+	 * 
+	 * @return The actual object data for this JiakObject.
+	 */
 	public JSONObject getObject() {
 		return object;
 	}
 
-	public void setObject(JSONObject object) {
+	/**
+	 * Set the object data for this JiakObject.
+	 * 
+	 * @param object
+	 *            A JSONObject representing the actual object data for this
+	 *            JiakObject.
+	 */
+	public void setObject(final JSONObject object) {
 		this.object = object;
 	}
 
+	/**
+	 * Get a string representation of the vector clock for this object.
+	 * 
+	 * @return The Vector Clock for this object.
+	 */
 	public String getVclock() {
 		return vclock;
 	}
 
-	public void setVclock(String vclock) {
-		this.vclock = vclock;
-	}
-
+	/**
+	 * Get the last-modified timestamp for this object.
+	 * 
+	 * @return The last modified timestamp of this object.
+	 */
 	public String getLastmod() {
 		return lastmod;
 	}
 
-	public void setLastmod(String lastmod) {
-		this.lastmod = lastmod;
-	}
-
+	/**
+	 * Return the "VTag" for this JiakObject. A VTag is a hashed representation
+	 * of the vector clock of an object, suitable for quick comparison of two
+	 * object values, or for use as an HTTP Entity Tag.
+	 * 
+	 * @return The VTag for this JiakObject
+	 */
 	public String getVtag() {
 		return vtag;
 	}
 
-	public void setVtag(String vtag) {
-		this.vtag = vtag;
+	/**
+	 * Update this object with new data from a Riak server. This method is
+	 * mainly intended for internal use an should be used with care.
+	 * 
+	 * @param data
+	 *            A JSONObject returned from calling an HTTP method on a Riak
+	 *            server.
+	 * @throws JSONException
+	 *             If an error occurs unparsing the JSONObject.
+	 */
+	public void update(final JSONObject data) throws JSONException {
+		vclock = data.getString("vclock");
+		lastmod = data.getString("lastmod");
+		vtag = data.getString("vtag");
+		object = data.getJSONObject("object");
+		links = data.getJSONArray("links");
 	}
 
-	public void update(JSONObject data) throws JSONException {
-		this.vclock = data.getString("vclock");
-		this.lastmod = data.getString("lastmod");
-		this.vtag = data.getString("vtag");
-		this.object = data.getJSONObject("object");
-		this.links = data.getJSONArray("links");
+	/**
+	 * Accessor for values in the underlying object data.
+	 * 
+	 * @param key
+	 *            The field name in the object to return.
+	 * @return The value associated with the key in the object data.
+	 * @throws JSONException
+	 */
+	public Object get(final String key) throws JSONException {
+		return object.get(key);
 	}
 
-	public Object get(String key) throws JSONException {
-		return this.object.get(key);
+	/**
+	 * Setter for values in the underlying object data.
+	 * 
+	 * @param key
+	 *            The field name to set.
+	 * @param value
+	 *            The value to set.
+	 * @throws JSONException
+	 *             If the key-value are invalid JSON.
+	 */
+	public void set(final String key, final Object value) throws JSONException {
+		object.put(key, value);
 	}
-	
-	public void set(String key, Object value) throws JSONException {
-		this.object.put(key, value);
-	}
-	
-	public JSONObject toJSONObject() throws JSONException { 
-		JSONObject o = new JSONObject();
+
+	/**
+	 * Return a JSONObject representing the JiakObject (metadata and object
+	 * state).
+	 * 
+	 * @return A JSONObject.
+	 * @throws JSONException
+	 *             If a failure occurs converting the object to JSON.
+	 */
+	public JSONObject toJSONObject() throws JSONException {
+		final JSONObject o = new JSONObject();
 		o.put("vclock", vclock);
 		o.put("lastmod", lastmod);
 		o.put("vtag", vtag);
 		o.put("object", object);
 		return o;
 	}
-	
-	public String toJSONString() throws JSONException { 
+
+	/**
+	 * Return a JSON string representing this JiakObject. This is equivalent to
+	 * calling <code>.toJSONObject.toString()</code>.
+	 * 
+	 * @return A JSON string.
+	 * @throws JSONException
+	 *             If a failure occurs converting the object to JSON.
+	 */
+	public String toJSONString() throws JSONException {
 		return toJSONObject().toString();
 	}
 }