Merge pull request #25 from adashcolinr/dev

Queue Javadocs

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueConfiguration.java

@@ -2,18 +2,24 @@
  * 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.queue;
 
+/**
+ * A class that contains static strings used to identify parts of a service configuration instance associated with the
+ * Windows Azure Queue service.
+ * <p>
+ * These values must not be altered.
+ */
 public class QueueConfiguration {
     public final static String ACCOUNT_NAME = "queue.accountName";
     public final static String ACCOUNT_KEY = "queue.accountKey";

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueService.java

@@ -2,36 +2,86 @@
  * 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.queue;
 
 import com.microsoft.windowsazure.services.core.Configuration;
 
+/**
+ * A class for static factory methods that return instances implementing {@link QueueContract}.
+ */
 public class QueueService {
+    /**
+     * Private default constructor.
+     */
     private QueueService() {
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link QueueContract} 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 QueueContract} for interacting with the queue service.
+     */
     public static QueueContract create() {
         return create(null, Configuration.getInstance());
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link QueueContract} 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 QueueContract} for interacting with the queue service.
+     */
     public static QueueContract create(Configuration config) {
         return create(null, config);
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link QueueContract} 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 QueueContract} for interacting with the queue service.
+     */
     public static QueueContract create(String profile) {
         return create(profile, Configuration.getInstance());
     }
 
+    /**
+     * A static factory method that returns an instance implementing {@link QueueContract} 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 QueueContract} for interacting with the queue service.
+     */
     public static QueueContract create(String profile, Configuration config) {
         return config.create(profile, QueueContract.class);
     }

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateMessageOptions.java

@@ -2,41 +2,106 @@
  * 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.queue.models;
 
+import com.microsoft.windowsazure.services.queue.QueueContract;
+
+/**
+ * Represents the options that may be set on the Queue service for
+ * {@link QueueContract#createMessage(String, String, CreateMessageOptions) createMessage} requests. These options
+ * include a server response timeout for the request, the visibility timeout to set on the created message, and the
+ * time-to-live value to set on the message.
+ */
 public class CreateMessageOptions extends QueueServiceOptions {
     private Integer visibilityTimeoutInSeconds;
     private Integer timeToLiveInSeconds;
 
+    /**
+     * Sets the server request timeout value associated with this {@link CreateMessageOptions} instance.
+     * <p>
+     * The <em>timeout</em> value only affects calls made on methods where this {@link CreateMessageOptions} instance is
+     * passed as a parameter.
+     * 
+     * @param timeout
+     *            The server request timeout value to set in milliseconds.
+     * @return
+     *         A reference to this {@link CreateMessageOptions} instance.
+     */
     @Override
     public CreateMessageOptions setTimeout(Integer timeout) {
         super.setTimeout(timeout);
         return this;
     }
 
+    /**
+     * Gets the message visibility timeout in seconds value in this {@link CreateMessageOptions} instance.
+     * to set on messages when making a {@link QueueContract#createMessage(String, String, CreateMessageOptions)
+     * createMessage} request.
+     * 
+     * @return
+     *         The message visibility timeout in seconds.
+     */
     public Integer getVisibilityTimeoutInSeconds() {
         return visibilityTimeoutInSeconds;
     }
 
+    /**
+     * Sets the message visibility timeout in seconds value to set on messages when making a
+     * {@link QueueContract#createMessage(String, String, CreateMessageOptions) createMessage} request. This allows
+     * messages to be loaded into the queue but not become visible until the visibility timeout has passed.
+     * Valid visibility timeout values range from 0 to 604800 seconds (0 to 7 days), and must be less than the
+     * time-to-live value.
+     * <p>
+     * The <em>visibilityTimeoutInSeconds</em> value only affects calls made on methods where this
+     * {@link CreateMessageOptions} instance is passed as a parameter.
+     * 
+     * @param visibilityTimeoutInSeconds
+     *            The length of time during which the message will be invisible, starting when it is added to the queue,
+     *            or 0 to make the message visible immediately. This value must be greater than or equal to zero and
+     *            less than or equal to the time-to-live value.
+     * @return
+     *         A reference to this {@link CreateMessageOptions} instance.
+     */
     public CreateMessageOptions setVisibilityTimeoutInSeconds(Integer visibilityTimeoutInSeconds) {
         this.visibilityTimeoutInSeconds = visibilityTimeoutInSeconds;
         return this;
     }
 
+    /**
+     * Gets the message time-to-live in seconds value associated with this {@link CreateMessageOptions} instance.
+     * 
+     * @return
+     *         The message time-to-live value in seconds.
+     */
     public Integer getTimeToLiveInSeconds() {
         return timeToLiveInSeconds;
     }
 
+    /**
+     * Sets the message time-to-live timeout value to set on messages when making a
+     * {@link QueueContract#createMessage(String, String, CreateMessageOptions) createMessage} request. This is the
+     * maximum duration in seconds for the message to remain in the queue after it is created.
+     * Valid <em>timeToLiveInSeconds</em> values range from 0 to 604800 seconds (0 to 7 days), with the default value
+     * set to seven days.
+     * <p>
+     * The <em>timeToLiveInSeconds</em> value only affects calls made on methods where this {@link CreateMessageOptions}
+     * instance is passed as a parameter.
+     * 
+     * @param timeToLiveInSeconds
+     *            The maximum time to allow the message to be in the queue, in seconds.
+     * @return
+     *         A reference to this {@link CreateMessageOptions} instance.
+     */
     public CreateMessageOptions setTimeToLiveInSeconds(Integer timeToLiveInSeconds) {
         this.timeToLiveInSeconds = timeToLiveInSeconds;
         return this;

microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateQueueOptions.java

@@ -2,38 +2,92 @@
  * 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.queue.models;
 
 import java.util.HashMap;
 
+import com.microsoft.windowsazure.services.queue.QueueContract;
+
+/**
+ * Represents the options that may be set on a queue when created in the storage service with a
+ * {@link QueueContract#createQueue(String, CreateQueueOptions) createQueue} request. These options include a server
+ * response timeout for the request and the metadata to associate with the created queue.
+ */
 public class CreateQueueOptions extends QueueServiceOptions {
     private HashMap<String, String> metadata = new HashMap<String, String>();
 
+    /**
+     * Sets the server request timeout value associated with this {@link CreateQueueOptions} instance.
+     * <p>
+     * The <em>timeout</em> value only affects calls made on methods where this {@link CreateQueueOptions} instance is
+     * passed as a parameter.
+     * 
+     * @param timeout
+     *            The server request timeout value to set in milliseconds.
+     * @return
+     *         A reference to this {@link CreateQueueOptions} instance.
+     */
     @Override
     public CreateQueueOptions setTimeout(Integer timeout) {
         super.setTimeout(timeout);
         return this;
     }
 
+    /**
+     * Gets the metadata collection of key-value {@link String} pairs to set on a queue when the queue is created.
+     * 
+     * @return
+     *         A {@link java.util.HashMap} of key-value {@link String} pairs containing the metadata to set on the
+     *         queue.
+     */
     public HashMap<String, String> getMetadata() {
         return metadata;
     }
 
+    /**
+     * Sets the metadata collection of key-value {@link String} pairs to set on a queue when the queue is created. Queue
+     * metadata is a user-defined collection of key-value pairs that is opaque to the server.
+     * <p>
+     * The <em>metadata</em> value is only added to a newly created queue where this {@link CreateQueueOptions} instance
+     * is passed as a parameter.
+     * 
+     * @param metadata
+     *            The {@link java.util.HashMap} of key-value {@link String} pairs containing the metadata to set on the
+     *            queue.
+     * @return
+     *         A reference to this {@link CreateQueueOptions} instance.
+     */
     public CreateQueueOptions setMetadata(HashMap<String, String> metadata) {
         this.metadata = metadata;
         return this;
     }
 
+    /**
+     * Adds a key-value pair of {@link String} to the metadata collection to set on a queue when the queue is created.
+     * Queue metadata is a user-defined collection of key-value pairs that is opaque to the server. If the key already
+     * exists in the metadata collection, the value parameter will overwrite the existing value paired with that key
+     * without notification.
+     * <p>
+     * The updated metadata is only added to a newly created queue where this {@link CreateQueueOptions} instance is
+     * passed as a parameter.
+     * 
+     * @param key
+     *            A {@link String} containing the key part of the key-value pair to add to the metadata.
+     * @param value
+     *            A {@link String} containing the value part of the key-value pair to add to the metadata.
+     * @return
+     *         A reference to this {@link CreateQueueOptions} instance.
+     */
     public CreateQueueOptions addMetadata(String key, String value) {
         this.metadata.put(key, value);
         return this;