You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by wo...@apache.org on 2010/09/23 18:00:28 UTC
svn commit: r1000512 - in /incubator/libcloud/sandbox/java/trunk/src: base/
base/connection/ base/interfaces/ base/types/ libcloud/data/
libcloud/exceptions/ libcloud/interfaces/ simplecloud/storage/
simplecloud/storage/exceptions/ simplecloud/storage/...
Author: woodser
Date: Thu Sep 23 16:00:27 2010
New Revision: 1000512
URL: http://svn.apache.org/viewvc?rev=1000512&view=rev
Log:
Commented core base classes for documentation.
Modified:
incubator/libcloud/sandbox/java/trunk/src/base/Driver.java
incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionKey.java
incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionUserAndKey.java
incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnection.java
incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnectionUserAndKey.java
incubator/libcloud/sandbox/java/trunk/src/base/connection/Response.java
incubator/libcloud/sandbox/java/trunk/src/base/connection/ResponseHandler.java
incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IConnection.java
incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IItem.java
incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IResponse.java
incubator/libcloud/sandbox/java/trunk/src/base/types/Item.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/data/Node.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeAuth.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeImage.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeLocation.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeSize.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeState.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/exceptions/InvalidCredsException.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INode.java
incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INodeDriver.java
incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/Example.java
incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/exceptions/StorageException.java
incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/interfaces/IStorageAdapter.java
Modified: incubator/libcloud/sandbox/java/trunk/src/base/Driver.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/Driver.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/Driver.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/Driver.java Thu Sep 23 16:00:27 2010
@@ -2,6 +2,12 @@ package base;
import base.interfaces.IConnection;
+/**
+ * Base class which represents a "Driver" or "Adapter" and conforms to
+ * libcloud's APIs. Includes a single connection for server requests. Extend
+ * this class to write a Driver/Adapter which plugs into the libcloud
+ * infrastructure.
+ */
public class Driver {
protected IConnection connection;
Modified: incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionKey.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionKey.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionKey.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionKey.java Thu Sep 23 16:00:27 2010
@@ -11,7 +11,6 @@ import java.util.Map;
import java.util.TreeSet;
import org.apache.http.HttpEntityEnclosingRequest;
-import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.ClientProtocolException;
@@ -31,31 +30,46 @@ import base.Driver;
import base.interfaces.IConnection;
import base.interfaces.IItem;
-/*
+/**
* Manages a connection with a secret access key.
*/
public class ConnectionKey implements IConnection {
+ /** The host server. */
protected String host;
+ /** The server's port. */
protected int port;
+ /** Identifies the user's account. */
protected String accessId;
+ /** The account user's secret key/password. */
protected String accessKey;
+ /** Indicates if the connection is secure. Defaults to true. */
protected boolean secure;
+ /** References the driver that owns this connection. */
protected Driver driver;
+ /** HTTP operation (i.e. GET, DELETE, PUT, POST). */
protected String method;
+ /** Path to the resource being accessed (e.g. /john.doe/images/1) */
protected String path;
- protected DefaultHttpClient httpClient;
-
- protected HttpHost httpHost;
+ /** Client used to make requests to the server. */
+ public DefaultHttpClient httpClient;
+ /**
+ * Constructs this connection with the default port.
+ *
+ * @param accessKey is the user's secret key used for authentication
+ * @param secure indicates if this connection is secure or not
+ * @param host is the host to connect to
+ * @param driver references the driver that owns this connection
+ */
public ConnectionKey(String accessKey, boolean secure, String host, Driver driver) {
this.accessKey = accessKey;
this.secure = secure;
@@ -66,6 +80,15 @@ public class ConnectionKey implements IC
this.path = null;
}
+ /**
+ * Constructs this connection.
+ *
+ * @param accessKey is the user's secret key used for authentication
+ * @param secure indicates if this connection is secure
+ * @param host is the host to connect to
+ * @param port is the host's port to connect to
+ * @param driver references the driver that owns this connection
+ */
public ConnectionKey(String accessKey, boolean secure, String host, int port,
Driver driver) {
this.accessKey = accessKey;
@@ -74,7 +97,6 @@ public class ConnectionKey implements IC
this.port = port;
this.driver = driver;
this.httpClient = null;
- this.httpHost = null;
this.accessId = null; // subclass may initialize
this.path = null;
}
@@ -111,6 +133,8 @@ public class ConnectionKey implements IC
* inputstream body content (use Item?)
* multipart form posts
* change to encodeData(Object data) for generic processing
+ *
+ * TODO: use List<KeyValuePair> for headers/params? Map does not support one-many mapping
*/
public Response request(String method, String path,
Map<String, String> headers, Map<String, String> params, Object data) {
@@ -198,7 +222,7 @@ public class ConnectionKey implements IC
return null; // Error
}
- /*
+ /**
* Utility that performs UTF-8 encoding of a map of Strings. Returns a
* String that is suitable for use as an application/x-www-form-urlencoded
* list of parameters in an HTTP PUT or HTTP POST.
@@ -238,6 +262,6 @@ public class ConnectionKey implements IC
* @return String is the user agent for making requests
*/
private String getUserAgent() {
- return "libcloud-java"; // TODO: generate version like python?
+ return "libcloud-java";
}
}
Modified: incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionUserAndKey.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionUserAndKey.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionUserAndKey.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/connection/ConnectionUserAndKey.java Thu Sep 23 16:00:27 2010
@@ -2,14 +2,36 @@ package base.connection;
import base.Driver;
+/**
+ * Manages a connection with an access ID and secret key.
+ */
public class ConnectionUserAndKey extends ConnectionKey {
+ /**
+ * Constructs this ConnectionUserAndKey.
+ *
+ * @param accessId identifies the user with the server
+ * @param accessKey is the user's secret key for server authentication
+ * @param secure indicates if this connection is secure
+ * @param host is the host to connect to
+ * @param port is the host's port to connect to
+ * @param driver references the driver that owns this connection
+ */
public ConnectionUserAndKey(String accessId, String accessKey, boolean secure,
String host, int port, Driver driver) {
super(accessKey, secure, host, port, driver);
this.accessId = accessId;
}
+ /**
+ * Constructs this ConnectionUserAndKey with a default port.
+ *
+ * @param accessId identifies the user with the server
+ * @param accessKey is the user's secret key for server authentication
+ * @param secure indicates if this connection is secure
+ * @param host is the host to connect to
+ * @param driver references the driver that owns this connection
+ */
public ConnectionUserAndKey(String accessId, String accessKey, boolean secure,
String host, Driver driver) {
super(accessKey, secure, host, driver);
Modified: incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnection.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnection.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnection.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnection.java Thu Sep 23 16:00:27 2010
@@ -4,6 +4,10 @@ import java.util.Map;
import base.Driver;
+/**
+ * Manages a connection with an access key and logs server requests and
+ * responses.
+ */
public class LoggingConnection extends ConnectionKey {
protected StringBuffer log;
Modified: incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnectionUserAndKey.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnectionUserAndKey.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnectionUserAndKey.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/connection/LoggingConnectionUserAndKey.java Thu Sep 23 16:00:27 2010
@@ -2,6 +2,10 @@ package base.connection;
import base.Driver;
+/**
+ * Manages a connection with an access ID and key and logs server requests
+ * and responses.
+ */
public class LoggingConnectionUserAndKey extends LoggingConnection {
public LoggingConnectionUserAndKey(String accessId, String accessKey, boolean secure,
Modified: incubator/libcloud/sandbox/java/trunk/src/base/connection/Response.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/connection/Response.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/connection/Response.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/connection/Response.java Thu Sep 23 16:00:27 2010
@@ -12,7 +12,6 @@ import base.interfaces.IItem;
import base.interfaces.IResponse;
import base.types.Item;
-
public class Response implements IResponse {
protected int status;
@@ -25,6 +24,12 @@ public class Response implements IRespon
protected Map<String, String> headers;
+ /**
+ * Constructs the Response from an HttpResponse, which is used by
+ * HttpClient.
+ *
+ * @param response is the HttpResponse object returned from HttpClient.
+ */
public Response(HttpResponse response) {
// Retrieve HTTP version from response
Modified: incubator/libcloud/sandbox/java/trunk/src/base/connection/ResponseHandler.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/connection/ResponseHandler.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/connection/ResponseHandler.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/connection/ResponseHandler.java Thu Sep 23 16:00:27 2010
@@ -1,10 +1,12 @@
package base.connection;
+import libcloud.providers.ibm.IBMDriver;
+import libcloud.providers.ibm.IBMHandler;
import base.interfaces.IResponse;
-/*
- * Default handler for request responses. Subclasses should extend for custom
- * processing.
+/**
+ * Default handler for request responses. Subclasses should override
+ * these methods for custom handling.
*/
public class ResponseHandler {
@@ -12,7 +14,7 @@ public class ResponseHandler {
protected Object object;
- /*
+ /**
* Constructs the handler with the given response.
*
* @param response is the request's response
@@ -27,7 +29,7 @@ public class ResponseHandler {
}
}
- /*
+ /**
* Returns the response's processed representation.
*
* @return Object is the response's parsed object for additional processing
@@ -36,7 +38,7 @@ public class ResponseHandler {
return object;
}
- /*
+ /**
* Returns the original response.
*
* @return IResponse is the request's original response
@@ -45,15 +47,19 @@ public class ResponseHandler {
return response;
}
- /*
+ /**
* Parses the response's body. The parsed response is stored in 'object'.
+ * This object is then used within the Driver to custom parse the response.
* Subclasses should override for custom processing.
+ *
+ * @see IBMHandler
+ * @see IBMDriver
*/
protected void parseBody() {
object = response.getBody();
}
- /*
+ /**
* Returns a String expressing the error that occurred. Subclasses should
* override for custom processing.
*
@@ -63,7 +69,7 @@ public class ResponseHandler {
return response.getStatus() + " " + response.getPhrase();
}
- /*
+ /**
* Indicates if the request was successful or not. Subclasses should
* override for custom processing.
*
Modified: incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IConnection.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IConnection.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IConnection.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IConnection.java Thu Sep 23 16:00:27 2010
@@ -4,14 +4,42 @@ import java.util.Map;
import base.connection.Response;
+/**
+ * Manages connections & requests with a server.
+ */
public interface IConnection {
+ /**
+ * Connects to the host with the already-defined host & port.
+ */
public void connect();
+ /**
+ * Connects to the given host with the default port.
+ *
+ * @param host is the host to connect to
+ */
public void connect(String host);
+ /**
+ * Connects to the given host at the given port.
+ *
+ * @param host is the host to connect to
+ * @param port is the host's port to connect to
+ */
public void connect(String host, int port);
- public Response request(String method, String action,
+ /**
+ * Makes a request to this connection.
+ *
+ * @param method defines the operation to perform (i.e. GET, DELETE, PUT, POST)
+ * @param path is the path to the resource (e.g. /john.doe/images/1)
+ * @param headers are the headers to include with the request
+ * @param params are the parameters to include with the request
+ * @param data is the body data to include with the request
+ *
+ * @return Response represents the server's response to this request
+ */
+ public Response request(String method, String path,
Map<String, String> headers, Map<String, String> params, Object data);
}
Modified: incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IItem.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IItem.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IItem.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IItem.java Thu Sep 23 16:00:27 2010
@@ -2,12 +2,12 @@ package base.interfaces;
import java.io.InputStream;
-/*
+/**
* Defines the base unit of generic "data" for sending and receiving.
*/
public interface IItem {
- /*
+ /**
* Represents the content's stream as a String.
*
* NOTE: The data's InputStream may not be consumable after this
@@ -16,63 +16,63 @@ public interface IItem {
*/
public String getContentString();
- /*
+ /**
* Sets the String that represents this data.
*
* @param data is the String that represents this data
*/
public void setContentString(String data);
- /*
+ /**
* Returns the raw InputStream of the data.
*
* @return InputStream is the data's InputStream
*/
public InputStream getContent();
- /*
+ /**
* Sets the InputStream which defines this data.
*
* @param stream is the InputStream to define the data
*/
public void setContent(InputStream stream);
- /*
+ /**
* Indicates this data's Content-Type.
*
* @return String defines this data's Content-Type.
*/
public String getContentType();
- /*
+ /**
* Sets the Content-Type of this data.
*
* @param type is this data's Content-Type
*/
public void setContentType(String type);
- /*
+ /**
* Indicates this data's Content-Encoding.
*
* @return String defines this data's Content-Encoding.
*/
public String getContentEncoding();
- /*
+ /**
* Sets the Content-Encoding of this data.
*
* @param encoding indicates the data's encoding
*/
public void setContentEncoding(String encoding);
- /*
+ /**
* Indicates the length of the data.
*
* @return long indicates the length of the data
*/
public long getContentLength();
- /*
+ /**
* Sets the Content-Length of this data.
*
* @param length is the data's length
Modified: incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IResponse.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IResponse.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IResponse.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/interfaces/IResponse.java Thu Sep 23 16:00:27 2010
@@ -3,45 +3,45 @@ package base.interfaces;
import java.io.InputStream;
import java.util.Map;
-/*
+/**
* Defines a request's response.
*/
public interface IResponse {
- /*
+ /**
* Indicates the status of the request (e.g. 200)
*/
public int getStatus();
- /*
+ /**
* Returns the content of the response as a String.
*
* @return String is the body of the response interpreted as a String
*/
public String getBody();
- /*
+ /**
* Returns the raw InputStream of the response.
*
* @return InputStream is a stream of bytes composing the response content
*/
public InputStream getBodyStream();
- /*
+ /**
* Returns the response's content as an Item.
*
* @return IItem is the response's content as an Item
*/
public IItem getItem();
- /*
+ /**
* Indicates the phrase of the response status.
*
* @return String is the phrase corresponding with the status
*/
public String getPhrase();
- /*
+ /**
* Returns the headers included in the request's response.
*
* @return Map<String, String> are the respone's headers
Modified: incubator/libcloud/sandbox/java/trunk/src/base/types/Item.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/base/types/Item.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/base/types/Item.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/base/types/Item.java Thu Sep 23 16:00:27 2010
@@ -9,6 +9,9 @@ import org.apache.http.HttpEntity;
import base.interfaces.IItem;
+/**
+ * Concrete class which represents a base unit of data.
+ */
public class Item implements IItem {
private String string;
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/data/Node.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/data/Node.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/data/Node.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/data/Node.java Thu Sep 23 16:00:27 2010
@@ -6,6 +6,9 @@ import java.util.UUID;
import libcloud.interfaces.INode;
import libcloud.interfaces.INodeDriver;
+/**
+ * Represents a node in IaaS Cloud Computing. Commonly called an instance.
+ */
public class Node implements INode {
private String id;
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeAuth.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeAuth.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeAuth.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeAuth.java Thu Sep 23 16:00:27 2010
@@ -1,5 +1,8 @@
package libcloud.data;
+/**
+ * Encapsulates authentication credentials for a cloud provider.
+ */
public class NodeAuth {
public String secret;
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeImage.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeImage.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeImage.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeImage.java Thu Sep 23 16:00:27 2010
@@ -4,6 +4,9 @@ import java.util.Map;
import libcloud.interfaces.INodeDriver;
+/**
+ * Represents an Image from which Nodes may be derived.
+ */
public class NodeImage {
public String id;
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeLocation.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeLocation.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeLocation.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeLocation.java Thu Sep 23 16:00:27 2010
@@ -2,6 +2,9 @@ package libcloud.data;
import libcloud.interfaces.INodeDriver;
+/**
+ * Represents a Node's location.
+ */
public class NodeLocation {
public String id;
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeSize.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeSize.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeSize.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeSize.java Thu Sep 23 16:00:27 2010
@@ -2,6 +2,9 @@ package libcloud.data;
import libcloud.interfaces.INodeDriver;
+/**
+ * Represents a Node configuration.
+ */
public class NodeSize {
public String id;
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeState.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeState.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeState.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/data/NodeState.java Thu Sep 23 16:00:27 2010
@@ -1,5 +1,8 @@
package libcloud.data;
+/**
+ * Represents the current of a Node.
+ */
public enum NodeState {
RUNNING,
REBOOTING,
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/exceptions/InvalidCredsException.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/exceptions/InvalidCredsException.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/exceptions/InvalidCredsException.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/exceptions/InvalidCredsException.java Thu Sep 23 16:00:27 2010
@@ -1,5 +1,8 @@
package libcloud.exceptions;
+/**
+ * Represents an authentication exception caused by invalid credentials.
+ */
public class InvalidCredsException extends RuntimeException {
private static final long serialVersionUID = 1L;
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INode.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INode.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INode.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INode.java Thu Sep 23 16:00:27 2010
@@ -4,6 +4,9 @@ import java.util.Map;
import libcloud.data.NodeState;
+/**
+ * Represents a node in IaaS Cloud Computing. Commonly called an instance.
+ */
public interface INode {
public boolean reboot();
Modified: incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INodeDriver.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INodeDriver.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INodeDriver.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/libcloud/interfaces/INodeDriver.java Thu Sep 23 16:00:27 2010
@@ -8,6 +8,9 @@ import libcloud.data.NodeImage;
import libcloud.data.NodeLocation;
import libcloud.data.NodeSize;
+/**
+ * The standard libcloud API for communicating with cloud providers.
+ */
public interface INodeDriver {
public INode createNode(String name, NodeSize size,
Modified: incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/Example.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/Example.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/Example.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/Example.java Thu Sep 23 16:00:27 2010
@@ -24,7 +24,7 @@ public class Example {
File file = new File(localPath);
InputStream stream = new BufferedInputStream(new FileInputStream(file));
Item item = new Item(stream, contentType, null, file.length());
- if (nirvanix.storeItem("/toby.jpg", item, options)) {
+ if (nirvanix.storeItem("/toby.jpg", item, new HashMap<String, String>(), options)) {
System.out.println("Upload succeeded");
} else {
System.out.println("Upload failed");
@@ -49,7 +49,7 @@ public class Example {
InputStream stream = new BufferedInputStream(new FileInputStream(file));
Item item = new Item(stream, contentType, null, file.length());
options.put(S3Adapter.Type.SRC_BUCKET, "ericlibcloud");
- if (amazon.storeItem("/toby.jpg", item, options)) {
+ if (amazon.storeItem("/toby.jpg", item, new HashMap<String, String>(), options)) {
System.out.println("Upload succeeded");
} else {
System.out.println("Upload failed");
Modified: incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/exceptions/StorageException.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/exceptions/StorageException.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/exceptions/StorageException.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/exceptions/StorageException.java Thu Sep 23 16:00:27 2010
@@ -1,6 +1,6 @@
package simplecloud.storage.exceptions;
-/*
+/**
* Represents an exception when interacting with SimpleCloud's storage service.
*/
public class StorageException extends Exception {
Modified: incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/interfaces/IStorageAdapter.java
URL: http://svn.apache.org/viewvc/incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/interfaces/IStorageAdapter.java?rev=1000512&r1=1000511&r2=1000512&view=diff
==============================================================================
--- incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/interfaces/IStorageAdapter.java (original)
+++ incubator/libcloud/sandbox/java/trunk/src/simplecloud/storage/interfaces/IStorageAdapter.java Thu Sep 23 16:00:27 2010
@@ -5,32 +5,98 @@ import java.util.Map;
import base.interfaces.IItem;
-/*
- * Common interface for unstructured cloud storage.
- *
- * TODO: Comments
- * TODO: For every return void, why not return status? PHP doesn't.
- * TODO: listItems() return List<Map<String, Object>> for attributes instead of names?
+/**
+ * Common interface to all Storage providers.
*/
public interface IStorageAdapter {
+ /**
+ * Fetches an item from the storage provider.
+ *
+ * @param path is the path to the item to fetch
+ * @param options are provider-specific options for fetching the item
+ * @return IItem is the item fetched from the server
+ */
public IItem fetchItem(String path, Map<Object, Object> options);
+ /**
+ * Stores an item with the storage provider.
+ *
+ * @param destinationPath is the path to store the item at
+ * @param item is the content to store on the provider
+ * @param metadata is metadata to associate with the item
+ * @param options are provider-specific options for storing the item
+ * @return true if the item was stored successfully, false otherwise
+ */
public boolean storeItem(String destinationPath, IItem item, Map<String, String> metadata, Map<Object, Object> options);
+ /**
+ * Deletes an item from the storage provider.
+ *
+ * @param path is the path to the item to delete
+ * @param options are provider-specific options for deleting the item
+ */
public void deleteItem(String path, Map<Object, Object> options);
+ /**
+ * Copies an item from one location to another location.
+ *
+ * @param sourcePath is the path to the item to copy
+ * @param destinationPath is the destination path for the item's copy
+ * @param options are provider-specific options for copying the item
+ */
public void copyItem(String sourcePath, String destinationPath, Map<Object, Object> options);
+ /**
+ * Moves an item from one location to another location.
+ *
+ * @param sourcePath is the path to the item to move
+ * @param destinationPath is the item's new destination
+ * @param options are provider specific-options for moving the item
+ */
public void moveItem(String sourcePath, String destinationPath, Map<Object, Object> options);
+ /**
+ * Renames an item.
+ *
+ * @param path is the path to the item to rename
+ * @param name is the new name of the item
+ * @param options are provider-specific options for renaming the item
+ */
public void renameItem(String path, String name, Map<Object, Object> options);
+ /**
+ * Lists the items at the given path.
+ *
+ * @param path identifies the directory to list the contents of
+ * @param options are provider-specific options for listing the contents
+ * @return List<String> is a list of the items at the given path
+ */
public List<String> listItems(String path, Map<Object, Object> options);
+ /**
+ * Fetches the metadata of an item.
+ *
+ * @param path identifies the item to fetch the metadata for
+ * @param options are provider-specific options for fetching the metadata
+ * @return Map<String, String> are key/value pairs composing the item's metadata
+ */
public Map<String, String> fetchMetadata(String path, Map<Object, Object> options);
+ /**
+ * Stores metadata for an item.
+ *
+ * @param destinationPath identifies the item to associate with the metadata
+ * @param metadata are the key/value pairs composing the item's metadata
+ * @param options are provider-specific options for storing the metadata
+ */
public void storeMetadata(String destinationPath, Map<String, String> metadata, Map<Object, Object> options);
+ /**
+ * Deletes metadata associated with an item.
+ *
+ * @param path identifies the item to delete the metadata from
+ * @param options are provider-specific options for deleting the metadata
+ */
public void deleteMetadata(String path, Map<Object, Object> options);
}