Dev

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/BlobConfiguration.java

@@ -2,20 +2,41 @@
  * Copyright 2011 Microsoft Corporation
  * 
  * 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
+ * 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.
+ * 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.microsoft.windowsazure.services.blob;
 
+/**
+ * This class contains static strings used to identify parts of a service configuration instance associated with the
+ * Windows Azure Blob service.
+ * <p>
+ * These values must not be altered.
+ */
 public class BlobConfiguration {
+    /**
+     * The Blob configuration account name constant. This <code>String</code> value is used as a key in the
+     * configuration file, to identify the value for the DNS prefix name for the storage account.
+     */
     public final static String ACCOUNT_NAME = "blob.accountName";
+
+    /**
+     * The Blob configuration account key constant. This <code>String</code> value is used as a key in the
+     * configuration file, to identify the value for the storage service account key.
+     */
     public final static String ACCOUNT_KEY = "blob.accountKey";
+
+    /**
+     * The Blob configuration URI constant. This <code>String</code> value is used as a key in the
+     * configuration file, to identify the URI value for the Blob storage service REST API address for the
+     * storage account.
+     */
     public final static String URI = "blob.uri";
 }

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/BlobService.java

@@ -2,36 +2,83 @@
  * Copyright 2011 Microsoft Corporation
  * 
  * 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
+ * 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.
+ * 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.microsoft.windowsazure.services.blob;
 
 import com.microsoft.windowsazure.services.core.Configuration;
 
+/**
+ * A class for static factory methods that return instances implementing {@link BlobContract}.
+ */
 public class BlobService {
     private BlobService() {
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link BlobContract} using default values for
+     * initializing a {@link Configuration} instance. Note that the returned interface will not work unless storage
+     * account credentials have been added to the "META-INF/com.microsoft.windowsazure.properties" resource file.
+     * 
+     * @return
+     *         An instance implementing {@link BlobContract} for interacting with the blob service.
+     */
     public static BlobContract create() {
         return create(null, Configuration.getInstance());
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link BlobContract} using the specified
+     * {@link Configuration} instance. The {@link Configuration} instance must have storage account information and
+     * credentials set before this method is called for the returned interface to work.
+     * 
+     * @param config
+     *            A {@link Configuration} instance configured with storage account information and credentials.
+     * 
+     * @return
+     *         An instance implementing {@link BlobContract} for interacting with the blob service.
+     */
     public static BlobContract create(Configuration config) {
         return create(null, config);
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link BlobContract} using default values for
+     * initializing a {@link Configuration} instance, and using the specified profile prefix for service settings. Note
+     * that the returned interface will not work unless storage account settings and credentials have been added to the
+     * "META-INF/com.microsoft.windowsazure.properties" resource file with the specified profile prefix.
+     * 
+     * @param profile
+     *            A string prefix for the account name and credentials settings in the {@link Configuration} instance.
+     * @return
+     *         An instance implementing {@link BlobContract} for interacting with the blob service.
+     */
     public static BlobContract create(String profile) {
         return create(profile, Configuration.getInstance());
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link BlobContract} using the specified
+     * {@link Configuration} instance and profile prefix for service settings. The {@link Configuration} instance must
+     * have storage account information and credentials set with the specified profile prefix before this method is
+     * called for the returned interface to work.
+     * 
+     * @param profile
+     *            A string prefix for the account name and credentials settings in the {@link Configuration} instance.
+     * @param config
+     *            A {@link Configuration} instance configured with storage account information and credentials.
+     * 
+     * @return
+     *         An instance implementing {@link BlobContract} for interacting with the blob service.
+     */
     public static BlobContract create(String profile, Configuration config) {
         return config.create(profile, BlobContract.class);
     }

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/AccessCondition.java

@@ -2,15 +2,15 @@
  * Copyright 2011 Microsoft Corporation
  * 
  * 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
+ * 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.
+ * 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.microsoft.windowsazure.services.blob.models;
 
@@ -19,18 +19,18 @@
 import com.microsoft.windowsazure.services.blob.implementation.RFC1123DateConverter;
 
 /**
- * Represents a set of access conditions to be used for operations against the storage services.
+ * Represents a set of access conditions for operations that use storage services.
  */
 public final class AccessCondition {
 
     /**
-     * Specifies that no access condition is set.
+     * Specifies an access condition with no conditions set.
      */
     public static final AccessCondition NONE = new AccessCondition(AccessConditionHeaderType.NONE, null);
 
     /**
-     * Returns an access condition such that an operation will be performed only if the resource's ETag value matches
-     * the specified ETag value.
+     * Creates an access condition that only allows an operation if the resource's ETag value matches the specified ETag
+     * value.
      * <p>
      * Setting this access condition modifies the request to include the HTTP <i>If-Match</i> conditional header. If
      * this access condition is set, the operation is performed only if the ETag of the resource matches the specified
@@ -49,8 +49,8 @@ public static AccessCondition ifMatch(String etag) {
     }
 
     /**
-     * Returns an access condition such that an operation will be performed only if the resource has been modified since
-     * the specified time.
+     * Creates an access condition that only allows an operation if the resource has been modified since the specified
+     * time.
      * <p>
      * Setting this access condition modifies the request to include the HTTP <i>If-Modified-Since</i> conditional
      * header. If this access condition is set, the operation is performed only if the resource has been modified since
@@ -70,8 +70,8 @@ public static AccessCondition ifModifiedSince(Date lastMotified) {
     }
 
     /**
-     * Returns an access condition such that an operation will be performed only if the resource's ETag value does not
-     * match the specified ETag value.
+     * Creates an access condition that only allows an operation if the resource's ETag value does not match the
+     * specified ETag value.
      * <p>
      * Setting this access condition modifies the request to include the HTTP <i>If-None-Match</i> conditional header.
      * If this access condition is set, the operation is performed only if the ETag of the resource does not match the
@@ -90,8 +90,8 @@ public static AccessCondition ifNoneMatch(String etag) {
     }
 
     /**
-     * Returns an access condition such that an operation will be performed only if the resource has not been modified
-     * since the specified time.
+     * Creates an access condition that only allows an operation if the resource has not been modified since the
+     * specified time.
      * <p>
      * Setting this access condition modifies the request to include the HTTP <i>If-Unmodified-Since</i> conditional
      * header. If this access condition is set, the operation is performed only if the resource has not been modified
@@ -111,12 +111,12 @@ public static AccessCondition ifNotModifiedSince(Date lastMotified) {
     }
 
     /**
-     * Represents the header type.
+     * Represents the access condition header type.
      */
     private AccessConditionHeaderType header = AccessConditionHeaderType.NONE;
 
     /**
-     * Represents the header value.
+     * Represents the access condition header value.
      */
     private String value;
 
@@ -140,18 +140,43 @@ protected AccessCondition(AccessConditionHeaderType headerType, String value) {
         this.setValue(value);
     }
 
+    /**
+     * Gets the access condition header type set in this <code>AccessCondition</code> instance.
+     * 
+     * @return
+     *         The {@link AccessConditionHeaderType} set in this <code>AccessCondition</code> instance.
+     */
     public AccessConditionHeaderType getHeader() {
         return header;
     }
 
+    /**
+     * Sets the access condition header type in this <code>AccessCondition</code> instance.
+     * 
+     * @param header
+     *            The {@link AccessConditionHeaderType} to set in this <code>AccessCondition</code> instance.
+     */
     public void setHeader(AccessConditionHeaderType header) {
         this.header = header;
     }
 
+    /**
+     * Gets the access condition value set in this <code>AccessCondition</code> instance.
+     * 
+     * @return
+     *         A {@link String} containing the access condition value set in this <code>AccessCondition</code> instance.
+     */
     public String getValue() {
         return value;
     }
 
+    /**
+     * Sets the access condition value in this <code>AccessCondition</code> instance.
+     * 
+     * @param value
+     *            A {@link String} containing the access condition value to set in this <code>AccessCondition</code>
+     *            instance.
+     */
     public void setValue(String value) {
         this.value = value;
     }

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/AcquireLeaseOptions.java

@@ -2,32 +2,68 @@
  * Copyright 2011 Microsoft Corporation
  * 
  * 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
+ * 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.
+ * 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.microsoft.windowsazure.services.blob.models;
 
+import com.microsoft.windowsazure.services.blob.BlobContract;
 
+/**
+ * Represents the options that may be set on an {@link BlobContract#acquireLease(String, String, AcquireLeaseOptions)
+ * acquireLease} request.
+ * These options include an optional server timeout for the operation and any access conditions for the operation.
+ */
 public class AcquireLeaseOptions extends BlobServiceOptions {
     private AccessCondition accessCondition;
 
+    /**
+     * Sets the optional server request timeout value associated with this {@link AcquireLeaseOptions} instance.
+     * <p>
+     * The <em>timeout</em> value only affects calls made on methods where this {@link AcquireLeaseOptions} instance is
+     * passed as a parameter.
+     * 
+     * @param timeout
+     *            The server request timeout value to set in milliseconds.
+     * @return
+     *         A reference to this {@link AcquireLeaseOptions} instance.
+     */
     @Override
     public AcquireLeaseOptions setTimeout(Integer timeout) {
         super.setTimeout(timeout);
         return this;
     }
 
+    /**
+     * Gets the access conditions set in this {@link AcquireLeaseOptions} instance.
+     * 
+     * @return
+     *         An {@link AccessCondition} containing the access conditions set, if any.
+     */
     public AccessCondition getAccessCondition() {
         return accessCondition;
     }
 
+    /**
+     * Sets the access conditions for acquiring a lease on a blob. By default, the operation will acquire the lease
+     * unconditionally. Use this method to specify conditions on the ETag or last modified time value for performing the
+     * operation.
+     * <p>
+     * The <em>accessCondition</em> value only affects calls made on methods where this {@link AcquireLeaseOptions}
+     * instance is passed as a parameter.
+     * 
+     * @param accessCondition
+     *            An {@link AccessCondition} containing the access conditions to set.
+     * @return
+     *         A reference to this {@link AcquireLeaseOptions} instance.
+     */
     public AcquireLeaseOptions setAccessCondition(AccessCondition accessCondition) {
         this.accessCondition = accessCondition;
         return this;