diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueConfiguration.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueConfiguration.java index 165df11b234b..1fad44dfe643 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueConfiguration.java +++ b/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. + *

+ * 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"; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueContract.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueContract.java index 62a6e2b5fb80..aa86eaf4ffcd 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueContract.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueContract.java @@ -2,20 +2,21 @@ * 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 java.util.HashMap; +import com.microsoft.windowsazure.services.core.Configuration; import com.microsoft.windowsazure.services.core.FilterableService; import com.microsoft.windowsazure.services.core.ServiceException; import com.microsoft.windowsazure.services.queue.models.CreateMessageOptions; @@ -32,61 +33,399 @@ import com.microsoft.windowsazure.services.queue.models.ServiceProperties; import com.microsoft.windowsazure.services.queue.models.UpdateMessageResult; +/** + * Defines the methods available on the Windows Azure storage queue service. Construct an object instance implementing + * QueueContract with one of the static create methods on {@link QueueService}. These methods + * associate a {@link Configuration} with the implementation, so the methods on the instance of + * QueueContract all work with a particular storage account. + */ public interface QueueContract extends FilterableService { + /** + * Gets the service properties of the queue. + * + * @return + * A {@link GetServicePropertiesResult} reference to the queue service properties. + * + * @throws ServiceException + * if an error occurs accessing the storage service. + */ GetServicePropertiesResult getServiceProperties() throws ServiceException; + /** + * Gets the service properties of the queue, using the specified options. Use the {@link QueueServiceOptions + * options} parameter to specify the server timeout for the operation. + * + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @return + * A {@link GetServicePropertiesResult} reference to the queue service properties. + * + * @throws ServiceException + * if an error occurs accessing the storage service. + */ GetServicePropertiesResult getServiceProperties(QueueServiceOptions options) throws ServiceException; + /** + * Sets the service properties of the queue. + * + * @param serviceProperties + * A {@link ServiceProperties} instance containing the queue service properties to set. + * + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void setServiceProperties(ServiceProperties serviceProperties) throws ServiceException; + /** + * Sets the service properties of the queue, using the specified options. Use the {@link QueueServiceOptions + * options} parameter to specify the server timeout for the operation. + * + * @param serviceProperties + * A {@link ServiceProperties} instance containing the queue service properties to set. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void setServiceProperties(ServiceProperties serviceProperties, QueueServiceOptions options) throws ServiceException; + /** + * Creates a queue in the storage account with the specified queue name. + * + * @param queue + * A {@link String} containing the name of the queue to create. + * + * @throws ServiceException + * if an error occurs in the storage service. + */ void createQueue(String queue) throws ServiceException; + /** + * Creates a queue in the storage account with the specified queue name, using the specified options. Use the + * {@link QueueServiceOptions options} parameter to specify the server timeout for the operation. + * + * @param queue + * A {@link String} containing the name of the queue to create. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs in the storage service. + */ void createQueue(String queue, CreateQueueOptions options) throws ServiceException; + /** + * Deletes the queue in the storage account with the specified queue name. + * + * @param queue + * A {@link String} containing the name of the queue to delete. + * + * @throws ServiceException + * if an error occurs in the storage service. + */ void deleteQueue(String queue) throws ServiceException; + /** + * Deletes the queue in the storage account with the specified queue name, using the specified options. Use the + * {@link QueueServiceOptions options} parameter to specify the server timeout for the operation. + * + * @param queue + * A {@link String} containing the name of the queue to delete. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs in the storage service. + */ void deleteQueue(String queue, QueueServiceOptions options) throws ServiceException; + /** + * Gets a list of the queues in the storage account. + * + * @return + * A {@link ListQueuesResult} reference to the queues returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ ListQueuesResult listQueues() throws ServiceException; + /** + * Gets a list of the queues in the storage account, using the specified options. Use the {@link ListQueuesOptions + * options} parameter to specify the server timeout for the operation, the prefix for queue names to match, the + * marker for the beginning of the queues to list, the maximum number of results to return, and whether to include + * queue metadata with the results. + * + * @param options + * A {@link ListQueuesOptions} instance containing options for the request. + * @return + * A {@link ListQueuesResult} reference to the queues returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ ListQueuesResult listQueues(ListQueuesOptions options) throws ServiceException; + /** + * Gets the metadata for the named queue in the storage account. Queue metadata is a user-defined collection of + * key-value {@link String} pairs that is opaque to the server. + * + * @param queue + * A {@link String} containing the name of the queue to get the metadata for. + * @return + * A {@link GetQueueMetadataResult} reference to the metadata for the queue. + * @throws ServiceException + * if an error occurs in the storage service. + */ GetQueueMetadataResult getQueueMetadata(String queue) throws ServiceException; + /** + * Gets the metadata for the named queue in the storage account, using the specified options. Use the + * {@link QueueServiceOptions options} parameter to specify the server timeout for the operation. Queue metadata is + * a user-defined collection of key-value {@link String} pairs that is opaque to the server. + * + * @param queue + * A {@link String} containing the name of the queue to get the metadata for. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @return + * A {@link ListQueuesResult} reference to the queues returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ GetQueueMetadataResult getQueueMetadata(String queue, QueueServiceOptions options) throws ServiceException; + /** + * Sets the specified metadata on the named queue in the storage account. Queue metadata is a user-defined + * collection of key-value {@link String} pairs that is opaque to the server. + * + * @param queue + * A {@link String} containing the name of the queue to set the metadata on. + * @param metadata + * A {@link java.util.HashMap} of metadata key-value {@link String} pairs to set on the queue. + * @throws ServiceException + * if an error occurs in the storage service. + */ void setQueueMetadata(String queue, HashMap metadata) throws ServiceException; + /** + * Sets the specified metadata on the named queue in the storage account, using the specified options. Use the + * {@link QueueServiceOptions options} parameter to specify the server timeout for the operation. Queue metadata is + * a user-defined collection of key-value {@link String} pairs that is opaque to the server. + * + * @param queue + * A {@link String} containing the name of the queue to set the metadata on. + * @param metadata + * A {@link java.util.HashMap} of metadata key-value {@link String} pairs to set on the queue. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs in the storage service. + */ void setQueueMetadata(String queue, HashMap metadata, QueueServiceOptions options) throws ServiceException; + /** + * Appends a message with the specified text to the tail of the named queue in the storage account. + * + * @param queue + * A {@link String} containing the name of the queue to append the message to. + * @param messageText + * A {@link String} containing the text of the message to append to the queue. + * @throws ServiceException + * if an error occurs in the storage service. + */ void createMessage(String queue, String messageText) throws ServiceException; + /** + * Appends a message with the specified text to the tail of the named queue in the storage account, using the + * specified options. Use the {@link CreateMessageOptions options} parameter to specify the server timeout for the + * operation, the message visibility timeout, and the message time to live in the queue. + * + * @param queue + * A {@link String} containing the name of the queue to append the message to. + * @param messageText + * A {@link String} containing the text of the message to append to the queue. + * @param options + * A {@link CreateMessageOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs in the storage service. + */ void createMessage(String queue, String messageText, CreateMessageOptions options) throws ServiceException; + /** + * Updates the message in the named queue with the specified message ID and pop receipt value to have the specified + * message text and visibility timeout value. + * + * @param queue + * A {@link String} containing the name of the queue with the message to update. + * @param messageId + * A {@link String} containing the ID of the message to update. + * @param popReceipt + * A {@link String} containing the pop receipt for the message returned by a call to updateMessage or + * listMessages. + * @param messageText + * A {@link String} containing the updated text to set for the message. + * @param visibilityTimeoutInSeconds + * The new visibility timeout to set on the message, in seconds. + * @return + * An {@link UpdateMessageResult} reference to the updated message result returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ UpdateMessageResult updateMessage(String queue, String messageId, String popReceipt, String messageText, int visibilityTimeoutInSeconds) throws ServiceException; + /** + * Updates the message in the named queue with the specified message ID and pop receipt value to have the specified + * message text and visibility timeout value, using the specified options. Use the {@link QueueServiceOptions + * options} parameter to specify the server timeout for the operation. + * + * @param queue + * A {@link String} containing the name of the queue with the message to update. + * @param messageId + * A {@link String} containing the ID of the message to update. + * @param popReceipt + * A {@link String} containing the pop receipt for the message returned by a call to updateMessage or + * listMessages. + * @param messageText + * A {@link String} containing the updated text to set for the message. + * @param visibilityTimeoutInSeconds + * The new visibility timeout to set on the message, in seconds. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @return + * An {@link UpdateMessageResult} reference to the updated message result returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ UpdateMessageResult updateMessage(String queue, String messageId, String popReceipt, String messageText, int visibilityTimeoutInSeconds, QueueServiceOptions options) throws ServiceException; + /** + * Deletes the message in the named queue with the specified message ID and pop receipt value. + * + * @param queue + * A {@link String} containing the name of the queue with the message to delete. + * @param messageId + * A {@link String} containing the ID of the message to delete. + * @param popReceipt + * A {@link String} containing the pop receipt for the message returned by a call to updateMessage or + * listMessages. + * @throws ServiceException + * if an error occurs in the storage service. + */ void deleteMessage(String queue, String messageId, String popReceipt) throws ServiceException; + /** + * Deletes the message in the named queue with the specified message ID and popReceipt value, using the specified + * options. Use the {@link QueueServiceOptions options} parameter to specify the server timeout for the operation. + * + * @param queue + * A {@link String} containing the name of the queue with the message to delete. + * @param messageId + * A {@link String} containing the ID of the message to delete. + * @param popReceipt + * A {@link String} containing the pop receipt for the message returned by a call to updateMessage or + * listMessages. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs in the storage service. + */ void deleteMessage(String queue, String messageId, String popReceipt, QueueServiceOptions options) throws ServiceException; + /** + * Retrieves the first message from head of the named queue in the storage account. This marks the message as + * invisible for the default visibility timeout period. When message processing is complete, the message must be + * deleted with a call to {@link QueueContract#deleteMessage(String, String, String, QueueServiceOptions) + * deleteMessage}. If message processing will take longer than the visibility timeout period, + * use the {@link QueueContract#updateMessage(String, String, String, String, int, QueueServiceOptions) + * updateMessage} method to extend the visibility timeout. The message will become visible in the queue again + * when the timeout completes if it is not deleted. + *

+ * To get a list of multiple messages from the head of the queue, call the + * {@link QueueContract#listMessages(String, ListMessagesOptions)} method with options set specifying the number of + * messages to return. + * + * @param queue + * A {@link String} containing the name of the queue to get the message from. + * @return + * A {@link ListMessagesResult} reference to the message result returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ ListMessagesResult listMessages(String queue) throws ServiceException; + /** + * Retrieves up to 32 messages from the head of the named queue in the storage account, using the specified options. + * Use the {@link ListMessagesOptions options} parameter to specify the server timeout for the operation, the number + * of messages to retrieve, and the visibility timeout to set on the retrieved messages. When message processing is + * complete, each message must be deleted with a call to + * {@link QueueContract#deleteMessage(String, String, String, QueueServiceOptions) deleteMessage}. If message + * processing takes longer than the default timeout period, use the + * {@link QueueContract#updateMessage(String, String, String, String, int, QueueServiceOptions) updateMessage} + * method to extend the visibility timeout. Each message will become + * visible in the queue again when the timeout completes if it is not deleted. + * + * @param queue + * A {@link String} containing the name of the queue to get the messages from. + * @param options + * A {@link ListMessagesOptions} instance containing options for the request. + * @return + * A {@link ListMessagesResult} reference to the message result returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ ListMessagesResult listMessages(String queue, ListMessagesOptions options) throws ServiceException; + /** + * Peeks a message from the named queue. A peek request retrieves a message from the head of the queue without + * changing its visibility. + * + * @param queue + * A {@link String} containing the name of the queue to peek the message from. + * @return + * A {@link PeekMessagesResult} reference to the message result returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ PeekMessagesResult peekMessages(String queue) throws ServiceException; + /** + * Peeks messages from the named queue, using the specified options. A peek request retrieves messages from the + * head of the queue without changing their visibility. Use the {@link PeekMessagesOptions options} parameter to + * specify the server timeout for the operation and the number of messages to retrieve. + * + * @param queue + * A {@link String} containing the name of the queue to peek the message from. + * @param options + * A {@link PeekMessagesOptions} instance containing options for the request. + * @return + * A {@link PeekMessagesResult} reference to the message result returned. + * @throws ServiceException + * if an error occurs in the storage service. + */ PeekMessagesResult peekMessages(String queue, PeekMessagesOptions options) throws ServiceException; + /** + * Deletes all messages in the named queue. + * + * @param queue + * A {@link String} containing the name of the queue to delete all messages from. + * @throws ServiceException + * if an error occurs in the storage service. + */ void clearMessages(String queue) throws ServiceException; + /** + * Deletes all messages in the named queue, using the specified options. Use the {@link QueueServiceOptions options} + * parameter to specify the server timeout for the operation. + * + * @param queue + * A {@link String} containing the name of the queue to delete all messages from. + * @param options + * A {@link QueueServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs in the storage service. + */ void clearMessages(String queue, QueueServiceOptions options) throws ServiceException; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueService.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueService.java index c457b6b34d39..a610b7500706 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/QueueService.java +++ b/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); } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateMessageOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateMessageOptions.java index f227771970f4..1ce3ba2a191b 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateMessageOptions.java +++ b/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. + *

+ * The timeout 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. + *

+ * The visibilityTimeoutInSeconds 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 timeToLiveInSeconds values range from 0 to 604800 seconds (0 to 7 days), with the default value + * set to seven days. + *

+ * The timeToLiveInSeconds 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; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateQueueOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateQueueOptions.java index cb7987657124..81ff8debedf3 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/CreateQueueOptions.java +++ b/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 metadata = new HashMap(); + /** + * Sets the server request timeout value associated with this {@link CreateQueueOptions} instance. + *

+ * The timeout 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 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. + *

+ * The metadata 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 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. + *

+ * 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; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetQueueMetadataResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetQueueMetadataResult.java index e412e00ece63..b522a7c589e9 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetQueueMetadataResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetQueueMetadataResult.java @@ -2,36 +2,75 @@ * 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; + +/** + * A wrapper class for the result returned from a Queue Service REST API operation to get queue metadata. This is + * returned by calls to implementations of {@link QueueContract#getQueueMetadata(String)} and + * {@link QueueContract#getQueueMetadata(String, QueueServiceOptions)}. + *

+ * See the Get Queue Metadata + * documentation on MSDN for details of the underlying Queue Service REST API operation. + */ public class GetQueueMetadataResult { private long approximateMessageCount; private HashMap metadata; + /** + * Gets the queue's approximate message count, as reported by the server. + * + * @return + * The queue's approximate message count. + */ public long getApproximateMessageCount() { return approximateMessageCount; } + /** + * Reserved for internal use. This method is invoked by the API as part of the response generation from the + * Queue Service REST API operation to set the value for the approximate message count returned by the server. + * + * @param approximateMessageCount + * The queue's approximate message count to set. + */ public void setApproximateMessageCount(long approximateMessageCount) { this.approximateMessageCount = approximateMessageCount; } + /** + * Gets the metadata collection of key-value {@link String} pairs currently set on a queue. Queue metadata is a + * user-defined collection of key-value pairs that is opaque to the server. + * + * @return + * A {@link java.util.HashMap} of key-value {@link String} pairs containing the metadata set on the + * queue. + */ public HashMap getMetadata() { return metadata; } + /** + * Reserved for internal use. This method is invoked by the API as part of the response generation from the + * Queue Service REST API operation to set the value from the queue metadata returned by the server. + * + * @param metadata + * A {@link java.util.HashMap} of key-value {@link String} pairs containing the metadata set on the + * queue. + */ public void setMetadata(HashMap metadata) { this.metadata = metadata; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetServicePropertiesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetServicePropertiesResult.java index 2a7e78820565..4dff09479acf 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetServicePropertiesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/GetServicePropertiesResult.java @@ -2,25 +2,56 @@ * 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; + +/** + * A wrapper class for the service properties returned in response to Queue Service REST API operations. This is + * returned by calls to implementations of {@link QueueContract#getServiceProperties()} and + * {@link QueueContract#getServiceProperties(QueueServiceOptions)}. + *

+ * See the Get Queue Service Properties + * documentation on MSDN for details of the underlying Queue Service REST API operation. + */ public class GetServicePropertiesResult { private ServiceProperties value; + /** + * Gets a {@link ServiceProperties} instance containing the service property values associated with the storage + * account. + *

+ * Modifying the values in the {@link ServiceProperties} instance returned does not affect the values associated + * with the storage account. To change the values in the storage account, call the + * {@link QueueContract#setServiceProperties} method and pass the modified {@link ServiceProperties} instance as a + * parameter. + * + * @return + * A {@link ServiceProperties} instance containing the property values associated with the storage account. + */ public ServiceProperties getValue() { return value; } + /** + * Reserved for internal use. Sets the value of the {@link ServiceProperties} instance associated with a + * storage service call result. This method is invoked by the API to store service properties returned by + * a call to a REST operation and is not intended for public use. + * + * @param value + * A {@link ServiceProperties} instance containing the property values associated with the storage + * account. + */ public void setValue(ServiceProperties value) { this.value = value; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesOptions.java index 2aa19b640944..0fb34021981c 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesOptions.java @@ -2,41 +2,96 @@ * 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 a {@link QueueContract#listMessages(String, ListMessagesOptions) + * listMessages} request. These options include a server response timeout for the request, the number of messages to + * retrieve from the queue, and the visibility timeout to set on the retrieved messages. + */ public class ListMessagesOptions extends QueueServiceOptions { private Integer numberOfMessages; private Integer visibilityTimeoutInSeconds; + /** + * Sets the server request timeout value associated with this {@link ListMessagesOptions} instance. + *

+ * The timeout value only affects calls made on methods where this {@link ListMessagesOptions} instance is + * passed as a parameter. + * + * @param timeout + * The server request timeout value to set in milliseconds. + * @return + * A reference to this {@link ListMessagesOptions} instance. + */ @Override public ListMessagesOptions setTimeout(Integer timeout) { super.setTimeout(timeout); return this; } + /** + * Gets the number of messages to request from the queue with this {@link ListMessagesOptions} instance. + * + * @return + * The number of messages requested. + */ public Integer getNumberOfMessages() { return numberOfMessages; } + /** + * Sets the number of messages to request from the queue with this {@link ListMessagesOptions} instance. + *

+ * The numberOfMessages value is only used for requests where this {@link ListMessagesOptions} instance is + * passed as a parameter. + * + * @param numberOfMessages + * The number of messages to request. The valid range of values is 0 to 32. + * @return + * A reference to this {@link ListMessagesOptions} instance. + */ public ListMessagesOptions setNumberOfMessages(Integer numberOfMessages) { this.numberOfMessages = numberOfMessages; return this; } + /** + * Gets the visibility timeout to set on the messages requested from the queue with this {@link ListMessagesOptions} + * instance. + * + * @return + * The visibility timeout to set on the messages requested from the queue. + */ public Integer getVisibilityTimeoutInSeconds() { return visibilityTimeoutInSeconds; } + /** + * Sets the visibility timeout value to set on the messages requested from the queue with this + * {@link ListMessagesOptions} instance. + *

+ * The visibilityTimeoutInSeconds value is only used for requests where this {@link ListMessagesOptions} + * instance is passed as a parameter. + * + * @param visibilityTimeoutInSeconds + * The visibility timeout to set on the messages requested from the queue. The valid range of values is 0 + * to 604800 seconds. + * @return + * A reference to this {@link ListMessagesOptions} instance. + */ public ListMessagesOptions setVisibilityTimeoutInSeconds(Integer visibilityTimeoutInSeconds) { this.visibilityTimeoutInSeconds = visibilityTimeoutInSeconds; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesResult.java index af7c53f87ff1..facfb7328344 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListMessagesResult.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.queue.models; @@ -23,20 +23,50 @@ import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter; import com.microsoft.windowsazure.services.blob.implementation.RFC1123DateAdapter; +import com.microsoft.windowsazure.services.queue.QueueContract; +/** + * A wrapper class for the result returned from a Queue Service REST API operation to get a list of messages. This is + * returned by calls to implementations of {@link QueueContract#listMessages(String)} and + * {@link QueueContract#listMessages(String, ListMessagesOptions)}. + *

+ * See the Get Messages documentation + * on MSDN for details of the underlying Queue Service REST API operation. + */ @XmlRootElement(name = "QueueMessagesList") public class ListMessagesResult { private List queueMessages = new ArrayList(); + /** + * Gets the list of queue messages returned by a {@link QueueContract}.listMessages request. The queue + * messages returned have their visibility timeout set to allow for processing by the client. The client must + * delete the messages once processing is complete, or they will become visible in the queue when the visibility + * timeout period is over. + * + * @return + * A {@link List} of {@link QueueMessage} instances representing the messages returned by the request. + */ @XmlElement(name = "QueueMessage") public List getQueueMessages() { return queueMessages; } + /** + * Reserved for internal use. Sets the list of queue messages returned by a {@link QueueContract} + * .listMessages request. This method is invoked by the API as part of the response generation from the + * Queue Service REST API operation to set the value from the queue message list returned by the server. + * + * @param queueMessages + * A {@link List} of {@link QueueMessage} instances representing the messages returned by the request. + */ public void setQueueMessages(List queueMessages) { this.queueMessages = queueMessages; } + /** + * Represents a message in the queue returned by the server. A {@link QueueMessage} instance contains a copy of the + * queue message data in the storage service as of the time the message was requested. + */ public static class QueueMessage { private String messageId; private Date insertionDate; @@ -46,68 +76,168 @@ public static class QueueMessage { private int dequeueCount; private String messageText; + /** + * Gets the message ID for the message in the queue. The message ID is a value that is opaque to the client + * that must be used along with the pop receipt to validate an update message or delete message operation. + * + * @return + * A {@link String} containing the message ID. + */ @XmlElement(name = "MessageId") public String getMessageId() { return messageId; } + /** + * Reserved for internal use. Sets the value of the message ID for the queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the message ID returned by the server. + * + * @param messageId + * A {@link String} containing the message ID. + */ public void setMessageId(String messageId) { this.messageId = messageId; } + /** + * Gets the {@link Date} when this message was added to the queue. + * + * @return + * The {@link Date} when this message was added to the queue. + */ @XmlElement(name = "InsertionTime") @XmlJavaTypeAdapter(RFC1123DateAdapter.class) public Date getInsertionDate() { return insertionDate; } + /** + * Reserved for internal use. Sets the value of the insertion time for the queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the insertion time returned by the server. + * + * @param insertionDate + * The {@link Date} when this message was added to the queue. + */ public void setInsertionDate(Date insertionDate) { this.insertionDate = insertionDate; } + /** + * Gets the {@link Date} when this message will expire and be automatically removed from the queue. + * + * @return + * The {@link Date} when this message will expire. + */ @XmlElement(name = "ExpirationTime") @XmlJavaTypeAdapter(RFC1123DateAdapter.class) public Date getExpirationDate() { return expirationDate; } + /** + * Reserved for internal use. Sets the value of the expiration time for the queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the expiration time returned by the server. + * + * @param expirationDate + * The {@link Date} when this message will expire. + */ public void setExpirationDate(Date expirationDate) { this.expirationDate = expirationDate; } + /** + * Gets the pop receipt value for the queue message. The pop receipt is a value that is opaque to the client + * that must be used along with the message ID to validate an update message or delete message operation. + * + * @return + * A {@link String} containing the pop receipt value for the queue message. + */ @XmlElement(name = "PopReceipt") public String getPopReceipt() { return popReceipt; } + /** + * Reserved for internal use. Sets the value of the pop receipt for the queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the pop receipt returned by the server. + * + * @param popReceipt + * A {@link String} containing the pop receipt value for the queue message. + */ public void setPopReceipt(String popReceipt) { this.popReceipt = popReceipt; } + /** + * Gets the {@link Date} when this message will become visible in the queue. + * + * @return + * The {@link Date} when this message will become visible in the queue. + */ @XmlElement(name = "TimeNextVisible") @XmlJavaTypeAdapter(RFC1123DateAdapter.class) public Date getTimeNextVisible() { return timeNextVisible; } + /** + * Reserved for internal use. Sets the value of the time the message will become visible. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the time next visible returned by the server. + * + * @param timeNextVisible + * The {@link Date} when this message will become visible in the queue. + */ public void setTimeNextVisible(Date timeNextVisible) { this.timeNextVisible = timeNextVisible; } + /** + * Gets the number of times this queue message has been retrieved with a list messages operation. + * + * @return + * The number of times this queue message has been retrieved. + */ @XmlElement(name = "DequeueCount") public int getDequeueCount() { return dequeueCount; } + /** + * Reserved for internal use. Sets the value of the dequeue count of the message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the queue message dequeue count returned by the server. + * + * @param dequeueCount + * The number of times this queue message has been retrieved. + */ public void setDequeueCount(int dequeueCount) { this.dequeueCount = dequeueCount; } + /** + * Gets the {@link String} containing the content of the queue message. + * + * @return + * A {@link String} containing the content of the queue message. + */ @XmlElement(name = "MessageText") public String getMessageText() { return messageText; } + /** + * Reserved for internal use. Sets the {@link String} containing the content of the message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the queue message content returned by the server. + * + * @param messageText + * A {@link String} containing the content of the message. + */ public void setMessageText(String messageText) { this.messageText = messageText; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesOptions.java index 6b62c7cacd2a..7d4d346570b8 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesOptions.java @@ -2,61 +2,166 @@ * 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#listQueues(ListQueuesOptions)} + * requests. These options include a server response timeout for the request, a prefix to match queue names to return, a + * marker to specify where to resume a list queues query, the maximum number of queues to return in a single response, + * and whether to include queue metadata with the response. + */ public class ListQueuesOptions extends QueueServiceOptions { private String prefix; private String marker; private int maxResults; private boolean includeMetadata; + /** + * Sets the server request timeout value associated with this {@link ListQueuesOptions} instance. + *

+ * The timeout value only affects calls made on methods where this {@link ListQueuesOptions} instance is passed as a + * parameter. + * + * @param timeout + * The server request timeout value to set in milliseconds. + * @return + * A reference to this {@link ListQueuesOptions} instance. + */ @Override public ListQueuesOptions setTimeout(Integer timeout) { super.setTimeout(timeout); return this; } + /** + * Gets the prefix {@link String} used to match queue names to return in a + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. + * + * @return + * The prefix {@link String} used to match queue names to return in a + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. + */ public String getPrefix() { return prefix; } + /** + * Sets the prefix {@link String} to use to match queue names to return in a + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. + *

+ * The prefix value only affects calls made on methods where this {@link ListQueuesOptions} instance is passed as a + * parameter. + * + * @param prefix + * The prefix {@link String} to use to match queue names to return in a + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. + * @return + * A reference to this {@link ListQueuesOptions} instance. + */ public ListQueuesOptions setPrefix(String prefix) { this.prefix = prefix; return this; } + /** + * Gets a {@link String} value that identifies the beginning of the list of queues to be returned with a + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. + *

+ * The {@link QueueContract#listQueues(ListQueuesOptions) listQueues} method returns a NextMarker + * element within the response if the list returned was not complete, which can be accessed with the + * {@link ListQueuesResult#getNextMarker()} method. This opaque value may then be set on a {@link ListQueuesOptions} + * instance with a call to {@link ListQueuesOptions#setMarker(String) setMarker} to be used in a subsequent + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} call to request the next portion of the list of + * queues. + * + * @return + * The marker value that identifies the beginning of the list of queues to be returned. + */ public String getMarker() { return marker; } + /** + * Sets a {@link String} marker value that identifies the beginning of the list of queues to be returned with a + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. + *

+ * The {@link QueueContract#listQueues(ListQueuesOptions) listQueues} method returns a NextMarker + * element within the response if the list returned was not complete, which can be accessed with the + * {@link ListQueuesResult#getNextMarker()} method. This opaque value may then be set on a {@link ListQueuesOptions} + * instance with a call to {@link ListQueuesOptions#setMarker(String) setMarker} to be used in a subsequent + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} call to request the next portion of the list of + * queues. + * + * @param marker + * The {@link String} marker value to set. + * @return + * A reference to this {@link ListQueuesOptions} instance. + */ public ListQueuesOptions setMarker(String marker) { this.marker = marker; return this; } + /** + * Gets the maximum number of queues to return with a {@link QueueContract#listQueues(ListQueuesOptions) listQueues} + * request. If the value is not specified, the server will return up to 5,000 items. + * + * @return + * The maximum number of queues to return. + */ public int getMaxResults() { return maxResults; } + /** + * Sets the maximum number of queues to return with a {@link QueueContract#listQueues(ListQueuesOptions) listQueues} + * request. If the value is not specified, by default the server will return up to 5,000 items. + *

+ * The maxResults value only affects calls made on methods where this {@link ListQueuesOptions} instance is passed + * as a parameter. + * + * @param maxResults + * The maximum number of queues to return. + * @return + * A reference to this {@link ListQueuesOptions} instance. + */ public ListQueuesOptions setMaxResults(int maxResults) { this.maxResults = maxResults; return this; } + /** + * Gets a flag indicating whether to return metadata with a {@link QueueContract#listQueues(ListQueuesOptions) + * listQueues} request. + * + * @return + * true to return metadata. + */ public boolean isIncludeMetadata() { return includeMetadata; } + /** + * Sets a flag indicating whether to return metadata with a {@link QueueContract#listQueues(ListQueuesOptions) + * listQueues} request. + * + * @param includeMetadata + * true to return metadata. + * @return + * A reference to this {@link ListQueuesOptions} instance. + */ public ListQueuesOptions setIncludeMetadata(boolean includeMetadata) { this.includeMetadata = includeMetadata; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesResult.java index 6dc3a704a930..144dddada23c 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ListQueuesResult.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.queue.models; @@ -25,7 +25,16 @@ import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter; import com.microsoft.windowsazure.services.blob.implementation.MetadataAdapter; +import com.microsoft.windowsazure.services.queue.QueueContract; +/** + * A wrapper class for the results returned in response to Queue service REST API operations to list queues. This + * is returned by calls to implementations of {@link QueueContract#listQueues()} and + * {@link QueueContract#listQueues(ListQueuesOptions)}. + *

+ * See the List Queues documentation on + * MSDN for details of the underlying Queue service REST API operation. + */ @XmlRootElement(name = "EnumerationResults") public class ListQueuesResult { private List queues = new ArrayList(); @@ -35,90 +44,248 @@ public class ListQueuesResult { private String nextMarker; private int maxResults; + /** + * Gets the list of queues returned by a {@link QueueContract}.listQueues request. + * + * @return + * A {@link List} of {@link Queue} instances representing the queues returned by the request. + */ @XmlElementWrapper(name = "Queues") @XmlElement(name = "Queue") public List getQueues() { return queues; } + /** + * Reserved for internal use. Sets the list of queues returned by a {@link QueueContract}.listQueues + * request. This method is invoked by the API as part of the response generation from the Queue service REST API + * operation to set the value from the queue list returned by the server. + * + * @param value + * A {@link List} of {@link Queue} instances representing the queues returned by the request. + */ public void setQueues(List value) { this.queues = value; } + /** + * Gets the base URI for Queue service REST API operations on the storage account. The URI consists of the protocol + * along with the DNS prefix name for the account followed by ".queue.core.windows.net". For example, if the DNS + * prefix name for the storage account is "myaccount" then the value returned by this method is + * "http://myaccount.queue.core.windows.net". + * + * @return + * A {@link String} containing the base URI for Queue service REST API operations on the storage account. + */ @XmlAttribute(name = "AccountName") public String getAccountName() { return accountName; } + /** + * Reserved for internal use. Sets the base URI for Queue service REST API operations on the storage account. This + * method is invoked by the API as part of the response generation from the Queue service REST API operation to set + * the value from the response returned by the server. + * + * @param accountName + * A {@link String} containing the base URI for Queue service REST API operations on the storage account. + */ public void setAccountName(String accountName) { this.accountName = accountName; } + /** + * Gets the prefix {@link String} used to qualify the results returned by the + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. Only queues with names that start with + * the prefix are returned by the request. By default, the prefix is empty and all queues are returned. + * + * @return + * The {@link String} prefix used to qualify the names of the queues returned. + */ @XmlElement(name = "Prefix") public String getPrefix() { return prefix; } + /** + * Reserved for internal use. Sets the prefix {@link String} used to qualify the results returned by the Queue + * service REST API list queues operation invoked with a call to {@link QueueContract#listQueues(ListQueuesOptions) + * listQueues}. This method is invoked by the API as part of the response generation from the Queue service REST API + * operation to set the value from the Prefix element returned by the server. + * + * @param prefix + * The {@link String} prefix used to qualify the names of the queues returned. + */ public void setPrefix(String prefix) { this.prefix = prefix; } + /** + * Gets the marker value for the beginning of the queue results returned by the + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. The marker is used by the server to + * specify the place to resume a query for queues. The marker value is a {@link String} opaque to the client. A + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request response may include a + * NextMarker value if there are more queue results than can be returned in a single response. Call + * the {@link ListQueuesResult#getNextMarker() getNextMarker} method to get this value. The + * client can request the next set of queue results by setting the marker to this value in the + * {@link ListQueuesOptions} parameter. By default, this value is empty and the server responds with the first + * queues that match the request. + * + * @return + * A {@link String} containing the marker value used for the response. + */ @XmlElement(name = "Marker") public String getMarker() { return marker; } + /** + * Reserved for internal use. Sets the marker value specifying the beginning of the results returned by the Queue + * service REST API list queues operation invoked with a call to {@link QueueContract#listQueues(ListQueuesOptions) + * listQueues}. This method is invoked by the API as part of the response generation from the Queue service REST API + * operation to set the value from the Marker element returned by the server. + * + * @param marker + * A {@link String} containing the marker value used for the response. + */ public void setMarker(String marker) { this.marker = marker; } + /** + * Gets the next marker value needed to retrieve additional queues. If more queues are available that satisfy a + * listQueues request than can be returned in the response, the server generates a marker value to specify + * the beginning of the queues to return in a subsequent request. The client can request the next set of queue + * results by setting the marker to this value in the {@link ListQueuesOptions} parameter. This value is + * empty if there are no more queues that satisfy the request than are included in the response. + * + * @return + * A {@link String} containing the marker value to use to resume the list queues request. + */ @XmlElement(name = "NextMarker") public String getNextMarker() { return nextMarker; } + /** + * Reserved for internal use. Sets the next marker value specifying the place to resume a list queues query if more + * results are available than have been returned by the Queue service REST API list queues operation response. This + * method is invoked by the API as part of the response generation from the Queue service REST API operation to set + * the value from the NextMarker element returned by the server. + * + * @param nextMarker + * A {@link String} containing the marker value to use to resume the list queues request. + */ public void setNextMarker(String nextMarker) { this.nextMarker = nextMarker; } + /** + * Gets the value specified for the number of queue results to return for the + * {@link QueueContract#listQueues(ListQueuesOptions) listQueues} request. The server will not return more than this + * number of queues in the response. If the value is not specified, the server will return up to 5,000 items. + *

+ * If there are more queues available that match the request than the number returned, the response will include a + * next marker value to specify the beginning of the queues to return in a subsequent request. Call the + * {@link ListQueuesResult#getNextMarker() getNextMarker} method to get this value. The client can request the next + * set of queue results by setting the marker to this value in the {@link ListQueuesOptions} parameter. + * + * @return + * The maximum number of results to return specified by the request. + */ @XmlElement(name = "MaxResults") public int getMaxResults() { return maxResults; } + /** + * Reserved for internal use. Sets the value returned by the Queue service REST API list queues operation response + * for the maximum number of queues to return. This method is invoked by the API as part of the response generation + * from the Queue service REST API operation to set the value from the MaxResults element returned + * by the server. + * + * @param maxResults + * The maximum number of results to return specified by the request. + */ public void setMaxResults(int maxResults) { this.maxResults = maxResults; } + /** + * Represents a queue in the storage account returned by the server. A {@link Queue} instance contains a copy of the + * queue name, URI, and metadata in the storage service as of the time the queue was requested. + */ public static class Queue { private String name; private String url; private HashMap metadata = new HashMap(); + /** + * Gets the name of this queue. + * + * @return + * A {@link String} containing the name of this queue. + */ @XmlElement(name = "Name") public String getName() { return name; } + /** + * Reserved for internal use. Sets the name of this queue. This method is invoked by the API as part of the + * response generation from the Queue service REST API operation to set the value from the + * Name element returned by the server. + * + * @param name + * A {@link String} containing the name of this queue. + */ public void setName(String name) { this.name = name; } + /** + * Gets the URI for Queue service REST API operations on this queue. + * + * @return + * A {@link String} containing the URI for Queue service REST API operations on this queue. + */ @XmlElement(name = "Url") public String getUrl() { return url; } + /** + * Reserved for internal use. Sets the URI of this queue. This method is invoked by the API as part of the + * response generation from the Queue service REST API operation to set the value from the + * Url element returned by the server. + * + * @param url + * A {@link String} containing the URI for Queue service REST API operations on this queue. + */ public void setUrl(String url) { this.url = url; } + /** + * Gets the metadata collection of key-value {@link String} pairs associated with this queue. + * + * @return + * A {@link java.util.HashMap} of key-value {@link String} pairs containing the queue metadata. + */ @XmlElement(name = "Metadata") @XmlJavaTypeAdapter(MetadataAdapter.class) public HashMap getMetadata() { return metadata; } + /** + * Reserved for internal use. Sets the metadata of this queue. This method is invoked by the API as part of the + * response generation from the Queue service REST API operation to set the value from the + * Metadata element returned by the server. + * + * @param metadata + * A {@link java.util.HashMap} of key-value {@link String} pairs containing the queue metadata. + */ public void setMetadata(HashMap metadata) { this.metadata = metadata; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesOptions.java index 9339f83eb958..eff229bf1657 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesOptions.java @@ -2,31 +2,69 @@ * 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 a {@link QueueContract#peekMessages(String, PeekMessagesOptions) + * peekMessages} request. These options include a server response timeout for the request and the number of messages to + * peek from the queue. + */ public class PeekMessagesOptions extends QueueServiceOptions { private Integer numberOfMessages; + /** + * Sets the server request timeout value associated with this {@link PeekMessagesOptions} instance. + *

+ * The timeout value only affects calls made on methods where this {@link PeekMessagesOptions} instance is passed as + * a parameter. + * + * @param timeout + * The server request timeout value to set in milliseconds. + * @return + * A reference to this {@link PeekMessagesOptions} instance. + */ @Override public PeekMessagesOptions setTimeout(Integer timeout) { super.setTimeout(timeout); return this; } + /** + * Gets the number of messages to return in the response to a + * {@link QueueContract#peekMessages(String, PeekMessagesOptions) peekMessages} request specified in this instance. + * + * @return + * The number of messages to return in the response. + */ public Integer getNumberOfMessages() { return numberOfMessages; } + /** + * Sets the number of messages to return in the response to a + * {@link QueueContract#peekMessages(String, PeekMessagesOptions) peekMessages} request. + *

+ * The numberOfMessages value only affects calls made on methods where this {@link PeekMessagesOptions} + * instance is passed as a parameter. + * + * + * @param numberOfMessages + * The number of messages to return in the response. This value must be in the range from 0 to 32. + * @return + * A reference to this {@link PeekMessagesOptions} instance. + */ public PeekMessagesOptions setNumberOfMessages(Integer numberOfMessages) { this.numberOfMessages = numberOfMessages; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesResult.java index 79990e4391d6..602f2bee8e8c 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/PeekMessagesResult.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.queue.models; @@ -23,20 +23,49 @@ import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter; import com.microsoft.windowsazure.services.blob.implementation.RFC1123DateAdapter; +import com.microsoft.windowsazure.services.queue.QueueContract; +/** + * A wrapper class for the results returned in response to Queue Service REST API operations to peek messages. This + * is returned by calls to implementations of {@link QueueContract#peekMessages(String)} and + * {@link QueueContract#peekMessages(String, PeekMessagesOptions)}. + *

+ * See the Peek Messages documentation + * on MSDN for details of the underlying Queue Service REST API operation. + */ @XmlRootElement(name = "QueueMessagesList") public class PeekMessagesResult { private List queueMessages = new ArrayList(); + /** + * Gets the list of queue messages returned by a {@link QueueContract}.peekMessages request. The queue + * messages returned do not have a visibility timeout set, and they can be retrieved by other clients for + * processing. + * + * @return + * A {@link List} of {@link QueueMessage} instances representing the messages returned by the request. + */ @XmlElement(name = "QueueMessage") public List getQueueMessages() { return queueMessages; } + /** + * Reserved for internal use. Sets the list of queue messages returned by a {@link QueueContract} + * .peekMessages request. This method is invoked by the API as part of the response generation from the + * Queue Service REST API operation to set the value from the queue message list returned by the server. + * + * @param queueMessages + * A {@link List} of {@link QueueMessage} instances representing the messages returned by the request. + */ public void setQueueMessages(List queueMessages) { this.queueMessages = queueMessages; } + /** + * Represents a message in the queue returned by the server. A {@link QueueMessage} instance contains a copy of the + * queue message data in the storage service as of the time the message was requested. + */ public static class QueueMessage { private String messageId; private Date insertionDate; @@ -44,49 +73,119 @@ public static class QueueMessage { private int dequeueCount; private String messageText; + /** + * Gets the message ID for the message in the queue. * + * + * @return + * A {@link String} containing the message ID. + */ @XmlElement(name = "MessageId") public String getMessageId() { return messageId; } + /** + * Reserved for internal use. Sets the value of the message ID for the queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the message ID returned by the server. + * + * @param messageId + * A {@link String} containing the message ID. + */ public void setMessageId(String messageId) { this.messageId = messageId; } + /** + * Gets the {@link Date} when this message was added to the queue. + * + * @return + * The {@link Date} when this message was added to the queue. + */ @XmlElement(name = "InsertionTime") @XmlJavaTypeAdapter(RFC1123DateAdapter.class) public Date getInsertionDate() { return insertionDate; } + /** + * Reserved for internal use. Sets the value of the insertion time for the queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the insertion time returned by the server. + * + * @param insertionDate + * The {@link Date} when this message was added to the queue. + */ public void setInsertionDate(Date insertionDate) { this.insertionDate = insertionDate; } + /** + * Gets the {@link Date} when this message will expire and be automatically removed from the queue. + * + * @return + * The {@link Date} when this message will expire. + */ @XmlElement(name = "ExpirationTime") @XmlJavaTypeAdapter(RFC1123DateAdapter.class) public Date getExpirationDate() { return expirationDate; } + /** + * Reserved for internal use. Sets the value of the expiration time for the queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the expiration time returned by the server. + * + * @param expirationDate + * The {@link Date} when this message will expire. + */ public void setExpirationDate(Date expirationDate) { this.expirationDate = expirationDate; } + /** + * Gets the number of times this queue message has been retrieved with a list messages operation. + * + * @return + * The number of times this queue message has been retrieved. + */ @XmlElement(name = "DequeueCount") public int getDequeueCount() { return dequeueCount; } + /** + * Reserved for internal use. Sets the value of the dequeue count of the message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the queue message dequeue count returned by the server. + * + * @param dequeueCount + * The number of times this queue message has been retrieved. + */ public void setDequeueCount(int dequeueCount) { this.dequeueCount = dequeueCount; } + /** + * Gets the {@link String} containing the content of the queue message. + * + * @return + * A {@link String} containing the content of the queue message. + */ @XmlElement(name = "MessageText") public String getMessageText() { return messageText; } + /** + * Reserved for internal use. Sets the {@link String} containing the content of the message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the queue message content returned by the server. + * + * @param messageText + * A {@link String} containing the content of the message. + */ public void setMessageText(String messageText) { this.messageText = messageText; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/QueueServiceOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/QueueServiceOptions.java index ff574f82e179..9f22a1f5fa1b 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/QueueServiceOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/QueueServiceOptions.java @@ -2,26 +2,52 @@ * 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 base class for options that may be set on Queue Service REST API operations invoked through the + * {@link QueueContract} interface. This class defines a server request timeout, which can be applied to all operations. + */ public class QueueServiceOptions { // Nullable because it is optional private Integer timeout; + /** + * Gets the current server request timeout value associated with this {@link QueueServiceOptions} instance. + *

+ * The timeout value only affects calls made on methods where this {@link QueueServiceOptions} instance is passed as + * a parameter. + * + * @return + * The server request timeout value in milliseconds. + */ public Integer getTimeout() { return timeout; } + /** + * Sets the server request timeout value associated with this {@link QueueServiceOptions} instance. + *

+ * The timeout value only affects calls made on methods where this {@link QueueServiceOptions} instance is passed as + * a parameter. + * + * @param timeout + * The server request timeout value to set in milliseconds. + * @return + * A reference to this {@link QueueServiceOptions} instance. + */ public QueueServiceOptions setTimeout(Integer timeout) { this.timeout = timeout; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ServiceProperties.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ServiceProperties.java index f676d600b63b..9f2715a7fe0d 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ServiceProperties.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/ServiceProperties.java @@ -2,44 +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 javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; +import com.microsoft.windowsazure.services.queue.QueueContract; + +/** + * A wrapper class for the Queue service properties set or retrieved with Queue Service REST API operations. This + * is returned by calls to implementations of {@link QueueContract#getServiceProperties()} and + * {@link QueueContract#getServiceProperties(QueueServiceOptions)} and passed to the server with calls to + * {@link QueueContract#setServiceProperties(ServiceProperties)} and + * {@link QueueContract#setServiceProperties(ServiceProperties, QueueServiceOptions)}. + *

+ * See the Get Queue Service Properties + * and Set Queue Service Properties + * documentation on MSDN for details of the underlying Queue Service REST API operations. See the Storage Analytics Overview + * documentation on MSDN for more information about logging and metrics. + */ @XmlRootElement(name = "StorageServiceProperties") public class ServiceProperties { private Logging logging = new Logging(); private Metrics metrics = new Metrics(); + /** + * Gets a reference to the {@link Logging} instance in this {@link ServiceProperties} instance. + *

+ * This {@link ServiceProperties} instance holds a local copy of the Queue service properties when returned by a + * call to {@link QueueContract}.getServiceProperties. + *

+ * Note that changes to this value are not reflected in the Queue service properties until they have been set on the + * storage account with a call to {@link QueueContract}.setServiceProperties. + * + * @return + * A reference to the {@link Logging} instance in this {@link ServiceProperties} instance. + */ @XmlElement(name = "Logging") public Logging getLogging() { return logging; } + /** + * Sets the {@link Logging} instance in this {@link ServiceProperties} instance. + *

+ * Note that changes to this value are not reflected in the Queue service properties until they have been set on the + * storage account with a call to {@link QueueContract}.setServiceProperties. + * + * @param logging + * The {@link Logging} instance to set in this {@link ServiceProperties} instance. + */ public void setLogging(Logging logging) { this.logging = logging; } + /** + * Gets a reference to the {@link Metrics} instance in this {@link ServiceProperties} instance. + *

+ * This {@link ServiceProperties} instance holds a local copy of the Queue service properties when returned by a + * call to {@link QueueContract}.getServiceProperties. + *

+ * Note that changes to this value are not reflected in the Queue service properties until they have been set on the + * storage account with a call to {@link QueueContract}.setServiceProperties. + * + * @return + * A reference to the {@link Metrics} instance in this {@link ServiceProperties} instance. + */ @XmlElement(name = "Metrics") public Metrics getMetrics() { return metrics; } + /** + * Sets the {@link Metrics} instance in this {@link ServiceProperties} instance. + *

+ * Note that changes to this value are not reflected in the Queue service properties until they have been set on the + * storage account with a call to {@link QueueContract}.setServiceProperties. + * + * @param metrics + * The {@link Metrics} instance to set in this {@link ServiceProperties} instance. + */ public void setMetrics(Metrics metrics) { this.metrics = metrics; } + /** + * This inner class represents the settings for logging on the Queue service of the storage account. These settings + * include the Storage Analytics version, whether to log delete requests, read requests, or write requests, and a + * {@link RetentionPolicy} instance for retention policy settings. + */ public static class Logging { private String version; private Boolean delete; @@ -47,113 +109,283 @@ public static class Logging { private Boolean write; private RetentionPolicy retentionPolicy; + /** + * Gets a reference to the {@link RetentionPolicy} instance in this {@link Logging} instance. + * + * @return + * A reference to the {@link RetentionPolicy} instance in this {@link Logging} instance. + */ @XmlElement(name = "RetentionPolicy") public RetentionPolicy getRetentionPolicy() { return retentionPolicy; } + /** + * Sets the {@link RetentionPolicy} instance in this {@link Logging} instance. + * + * @param retentionPolicy + * The {@link RetentionPolicy} instance to set in this {@link Logging} instance. + */ public void setRetentionPolicy(RetentionPolicy retentionPolicy) { this.retentionPolicy = retentionPolicy; } + /** + * Gets a flag indicating whether queue write operations are logged. If this value is true then all + * requests that write to the Queue service will be logged. These requests include adding a message, updating a + * message, setting queue metadata, and creating a queue. + * + * @return + * true if queue write operations are logged, otherwise false. + */ @XmlElement(name = "Write") public boolean isWrite() { return write; } + /** + * Sets a flag indicating whether queue write operations are logged. If this value is true then all + * requests that write to the Queue service will be logged. These requests include adding a message, updating a + * message, setting queue metadata, and creating a queue. + * + * @param write + * true to enable logging of queue write operations, otherwise false. + */ public void setWrite(boolean write) { this.write = write; } + /** + * Gets a flag indicating whether queue read operations are logged. If this value is true then all + * requests that read from the Queue service will be logged. These requests include listing queues, getting + * queue metadata, listing messages, and peeking messages. + * + * @return + * true if queue read operations are logged, otherwise false. + */ @XmlElement(name = "Read") public boolean isRead() { return read; } + /** + * Sets a flag indicating whether queue read operations are logged. If this value is true then all + * requests that read from the Queue service will be logged. These requests include listing queues, getting + * queue metadata, listing messages, and peeking messages. + * + * @param read + * true to enable logging of queue read operations, otherwise false. + */ public void setRead(boolean read) { this.read = read; } + /** + * Gets a flag indicating whether queue delete operations are logged. If this value is true then + * all requests that delete from the Queue service will be logged. These requests include deleting queues, + * deleting messages, and clearing messages. + * + * @return + * true if queue delete operations are logged, otherwise false. + */ @XmlElement(name = "Delete") public boolean isDelete() { return delete; } + /** + * Sets a flag indicating whether queue delete operations are logged. If this value is true then + * all requests that delete from the Queue service will be logged. These requests include deleting queues, + * deleting messages, and clearing messages. + * + * @param delete + * true to enable logging of queue delete operations, otherwise false. + */ public void setDelete(boolean delete) { this.delete = delete; } + /** + * Gets the Storage Analytics version number associated with this {@link Logging} instance. + * + * @return + * A {@link String} containing the Storage Analytics version number. + */ @XmlElement(name = "Version") public String getVersion() { return version; } + /** + * Sets the Storage Analytics version number to associate with this {@link Logging} instance. The current + * supported + * version number is "1.0". + *

+ * See the Storage Analytics + * Overview documentation on MSDN for more information. + * + * @param version + * A {@link String} containing the Storage Analytics version number to set. + */ public void setVersion(String version) { this.version = version; } } + /** + * This inner class represents the settings for metrics on the Queue service of the storage account. These settings + * include the Storage Analytics version, whether metrics are enabled, whether to include API operation summary + * statistics, and a {@link RetentionPolicy} instance for retention policy settings. + */ public static class Metrics { private String version; private boolean enabled; private Boolean includeAPIs; private RetentionPolicy retentionPolicy; + /** + * Gets a reference to the {@link RetentionPolicy} instance in this {@link Metrics} instance. + * + * @return + * A reference to the {@link RetentionPolicy} instance in this {@link Metrics} instance. + */ @XmlElement(name = "RetentionPolicy") public RetentionPolicy getRetentionPolicy() { return retentionPolicy; } + /** + * Sets the {@link RetentionPolicy} instance in this {@link Metrics} instance. + * + * @param retentionPolicy + * The {@link RetentionPolicy} instance to set in this {@link Metrics} instance. + */ public void setRetentionPolicy(RetentionPolicy retentionPolicy) { this.retentionPolicy = retentionPolicy; } + /** + * Gets a flag indicating whether metrics should generate summary statistics for called API operations. If this + * value is true then all Queue service REST API operations will be included in the metrics. + * + * @return + * true if Queue service REST API operations are included in metrics, otherwise + * false. + */ @XmlElement(name = "IncludeAPIs") public Boolean isIncludeAPIs() { return includeAPIs; } + /** + * Sets a flag indicating whether metrics should generate summary statistics for called API operations. If this + * value is true then all Queue service REST API operations will be included in the metrics. + * + * @param includeAPIs + * true to include Queue service REST API operations in metrics, otherwise + * false. + */ public void setIncludeAPIs(Boolean includeAPIs) { this.includeAPIs = includeAPIs; } + /** + * Gets a flag indicating whether metrics is enabled for the Queue storage service. + * + * @return + * A flag indicating whether metrics is enabled for the Queue storage service. + */ @XmlElement(name = "Enabled") public boolean isEnabled() { return enabled; } + /** + * Sets a flag indicating whether to enable metrics for the Queue storage service. + * + * @param enabled + * true to enable metrics for the Queue storage service, otherwise false. + */ public void setEnabled(boolean enabled) { this.enabled = enabled; } + /** + * Gets the Storage Analytics version number associated with this {@link Metrics} instance. + * + * @return + * A {@link String} containing the Storage Analytics version number. + */ @XmlElement(name = "Version") public String getVersion() { return version; } + /** + * Sets the Storage Analytics version number to associate with this {@link Metrics} instance. The current + * supported version number is "1.0". + *

+ * See the Storage Analytics + * Overview documentation on MSDN for more information. + * + * @param version + * A {@link String} containing the Storage Analytics version number to set. + */ public void setVersion(String version) { this.version = version; } } + /** + * This inner class represents the retention policy settings for logging or metrics on the Queue service of the + * storage account. These settings include whether a retention policy is enabled for the data, and the number of + * days that metrics or logging data should be retained. + */ public static class RetentionPolicy { private boolean enabled; private Integer days; // nullable, because optional if "enabled" is false + /** + * Gets the number of days that metrics or logging data should be retained. All data older than this value will + * be deleted. The value may be null if a retention policy is not enabled. + * + * @return + * The number of days that metrics or logging data should be retained. + */ @XmlElement(name = "Days") public Integer getDays() { return days; } + /** + * Sets the number of days that metrics or logging data should be retained. All data older than this value will + * be deleted. The value must be in the range from 1 to 365. This value must be set if a retention policy is + * enabled, but is not required if a retention policy is not enabled. + * + * @param days + * The number of days that metrics or logging data should be retained. + */ public void setDays(Integer days) { this.days = days; } + /** + * Gets a flag indicating whether a retention policy is enabled for the storage service. + * + * @return + * true if data retention is enabled, otherwise false. + */ @XmlElement(name = "Enabled") public boolean isEnabled() { return enabled; } + /** + * Sets a flag indicating whether a retention policy is enabled for the storage service. + * + * @param enabled + * Set true to enable data retention. + */ public void setEnabled(boolean enabled) { this.enabled = enabled; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/UpdateMessageResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/UpdateMessageResult.java index a57f8be013ff..7c81179931e4 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/UpdateMessageResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/UpdateMessageResult.java @@ -2,36 +2,75 @@ * 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.Date; +import com.microsoft.windowsazure.services.queue.QueueContract; + +/** + * A wrapper class for the results returned in response to Queue Service REST API operations to update a message. This + * is returned by calls to implementations of {@link QueueContract#updateMessage(String, String, String, String, int)} + * and {@link QueueContract#updateMessage(String, String, String, String, int, QueueServiceOptions)}. + *

+ * See the Update Message documentation + * on MSDN for details of the underlying Queue Service REST API operation. + */ public class UpdateMessageResult { private String popReceipt; private Date timeNextVisible; + /** + * Gets the pop receipt value for the updated queue message. The pop receipt is a value that is opaque to the client + * that must be used along with the message ID to validate an update message or delete message operation. + * + * @return + * A {@link String} containing the pop receipt value for the queue message. + */ public String getPopReceipt() { return popReceipt; } + /** + * Reserved for internal use. Sets the value of the pop receipt for the updated queue message. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the pop receipt returned by the server. + * + * @param popReceipt + * A {@link String} containing the pop receipt value for the queue message. + */ public void setPopReceipt(String popReceipt) { this.popReceipt = popReceipt; } + /** + * Gets the {@link Date} when the updated message will become visible in the queue. + * + * @return + * The {@link Date} when the updated message will become visible in the queue. + */ public Date getTimeNextVisible() { return timeNextVisible; } + /** + * Reserved for internal use. Sets the value of the time the updated message will become visible. This method is + * invoked by the API as part of the response generation from the Queue Service REST API operation to set the + * value with the time next visible returned by the server. + * + * @param timeNextVisible + * The {@link Date} when the updated message will become visible in the queue. + */ public void setTimeNextVisible(Date timeNextVisible) { this.timeNextVisible = timeNextVisible; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/package.html new file mode 100644 index 000000000000..6d2f45a3fae7 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/models/package.html @@ -0,0 +1,5 @@ + + +This package contains the queue data transfer object classes. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/package.html new file mode 100644 index 000000000000..4847f5461cb6 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/package.html @@ -0,0 +1,5 @@ + + +This package contains the queue service class, interface, and associated configuration and utility classes. + +