/**
* Constructs a web request to add a message to the back of the queue. Write the encoded message
* request body generated with a call to
* QueueMessageSerializer#generateMessageRequestBody(String)} to the output stream of the request.
* Sign the web request with the length of the encoded message request body.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the queue.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param visibilityTimeoutInSeconds Specifies the length of time for the message to be invisible
* in seconds, starting when it is added to the queue. A value of 0 will make the message
* visible immediately. The value must be greater than or equal to 0, and cannot be larger
* than 7 days. The visibility timeout of a message cannot be set to a value greater than the
* time-to-live time.
* @param timeToLiveInSeconds Specifies the time-to-live interval for the message, in seconds. The
* maximum time-to-live allowed is 7 days. If this parameter is 0, the default time-to-live of
* 7 days is used.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws IOException
* @throws URISyntaxException If the URI is not valid.
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection putMessage(
final URI uri,
final int timeout,
final int visibilityTimeoutInSeconds,
final int timeToLiveInSeconds,
final OperationContext opContext)
throws IOException, URISyntaxException, StorageException {
final UriQueryBuilder builder = new UriQueryBuilder();
if (visibilityTimeoutInSeconds != 0) {
builder.add(VISIBILITY_TIMEOUT, Integer.toString(visibilityTimeoutInSeconds));
}
if (timeToLiveInSeconds != 0) {
builder.add(MESSAGE_TTL, Integer.toString(timeToLiveInSeconds));
}
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, builder, opContext);
request.setDoOutput(true);
request.setRequestMethod(Constants.HTTP_POST);
return request;
}
/**
* Constructs a web request to clear all the messages in the queue. Sign the web request with a
* length of -1L.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the queue.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws IOException
* @throws URISyntaxException If the URI is not valid.
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection clearMessages(
final URI uri, final int timeout, final OperationContext opContext)
throws URISyntaxException, IOException, StorageException {
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, null, opContext);
request.setRequestMethod(Constants.HTTP_DELETE);
return request;
}
/**
* Constructs a web request to return the ACL for this queue. Sign with no length specified.
*
* @param uri The absolute URI to the container.
* @param timeout The server timeout interval.
* @return a HttpURLConnection configured for the operation.
* @throws StorageException
*/
public static HttpURLConnection getAcl(
final URI uri, final int timeout, final OperationContext opContext)
throws IOException, URISyntaxException, StorageException {
final UriQueryBuilder builder = new UriQueryBuilder();
builder.add(Constants.QueryConstants.COMPONENT, Constants.QueryConstants.ACL);
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, builder, opContext);
request.setRequestMethod(Constants.HTTP_GET);
return request;
}
/**
* Constructs a web request to delete a message from the queue. Sign the web request with a length
* of -1L.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the queue.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param popReceipt A <code>String</code> that contains the pop receipt value returned from an
* earlier call to {@link CloudQueueMessage#getPopReceipt} for the message to delete.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws URISyntaxException If the URI is not valid.
* @throws IOException
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection deleteMessage(
final URI uri, final int timeout, final String popReceipt, final OperationContext opContext)
throws URISyntaxException, IOException, StorageException {
final UriQueryBuilder builder = new UriQueryBuilder();
builder.add(POP_RECEIPT, popReceipt);
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, builder, opContext);
request.setRequestMethod(Constants.HTTP_DELETE);
return request;
}
/**
* Constructs a web request to retrieve a specified number of messages from the front of the queue
* without changing their visibility. Sign the web request with a length of -1L.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the queue.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param numberOfMessages A nonzero value that specifies the number of messages to retrieve from
* the queue, up to a maximum of 32.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws IOException
* @throws URISyntaxException If the URI is not valid.
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection peekMessages(
final URI uri,
final int timeout,
final int numberOfMessages,
final OperationContext opContext)
throws URISyntaxException, IOException, StorageException {
final UriQueryBuilder builder = new UriQueryBuilder();
builder.add(PEEK_ONLY, "true");
if (numberOfMessages != 0) {
builder.add(NUMBER_OF_MESSAGES, Integer.toString(numberOfMessages));
}
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, builder, opContext);
request.setRequestMethod(Constants.HTTP_GET);
return request;
}
/**
* Constructs a web request to update the visibility timeout of a message in the queue. Optionally
* updates the message content if a message request body is written to the output stream of the
* web request. The web request should be signed with the length of the encoded message request
* body if one is included, or a length of 0 if no message request body is included.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the queue.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param popReceipt A <code>String</code> that contains the pop receipt value returned from an
* earlier call to {@link CloudQueueMessage#getPopReceipt} for the message to update.
* @param visibilityTimeoutInSeconds Specifies the new visibility timeout value in seconds,
* relative to server time, to make the retrieved messages invisible until the visibility
* timeout expires. The value must be larger than or equal to 0, and cannot be larger than 7
* days. The visibility timeout of a message can be set to a value later than the expiry time,
* which will prevent the message from being retrieved again whether it is processed or not.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws IOException
* @throws URISyntaxException If the URI is not valid.
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection updateMessage(
final URI uri,
final int timeout,
final String popReceipt,
final int visibilityTimeoutInSeconds,
final OperationContext opContext)
throws URISyntaxException, IOException, StorageException {
final UriQueryBuilder builder = new UriQueryBuilder();
builder.add(POP_RECEIPT, popReceipt);
builder.add(VISIBILITY_TIMEOUT, Integer.toString(visibilityTimeoutInSeconds));
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, builder, opContext);
request.setDoOutput(true);
request.setRequestMethod(Constants.HTTP_PUT);
return request;
}
/**
* Constructs a web request to return a listing of all queues in this storage account. Sign the
* web request with a length of -1L.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the storage account.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param listingContext A {@link ListingContext} object that specifies parameters for the listing
* operation, if any. May be <code>null</code>.
* @param detailsIncluded A {@link QueueListingDetails} object that specifies additional details
* to return with the listing, if any. May be <code>null</code>.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws IOException
* @throws URISyntaxException If the URI is not valid.
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection list(
final URI uri,
final int timeout,
final ListingContext listingContext,
final QueueListingDetails detailsIncluded,
final OperationContext opContext)
throws URISyntaxException, IOException, StorageException {
final UriQueryBuilder builder = new UriQueryBuilder();
builder.add(Constants.QueryConstants.COMPONENT, Constants.QueryConstants.LIST);
if (listingContext != null) {
if (!Utility.isNullOrEmpty(listingContext.getPrefix())) {
builder.add(Constants.QueryConstants.PREFIX, listingContext.getPrefix());
}
if (!Utility.isNullOrEmpty(listingContext.getMarker())) {
builder.add(Constants.QueryConstants.MARKER, listingContext.getMarker());
}
if (listingContext.getMaxResults() != null && listingContext.getMaxResults() > 0) {
builder.add(
Constants.QueryConstants.MAX_RESULTS, listingContext.getMaxResults().toString());
}
}
if (detailsIncluded == QueueListingDetails.ALL
|| detailsIncluded == QueueListingDetails.METADATA) {
builder.add(Constants.QueryConstants.INCLUDE, Constants.QueryConstants.METADATA);
}
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, builder, opContext);
request.setRequestMethod(Constants.HTTP_GET);
return request;
}
/**
* Constructs a web request to retrieve messages from the front of the queue. Sign the web request
* with a length of -1L.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the queue.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param numberOfMessages A nonzero value that specifies the number of messages to retrieve from
* the queue, up to a maximum of 32.
* @param visibilityTimeoutInSeconds Specifies the visibility timeout value in seconds, relative
* to server time, to make the retrieved messages invisible until the visibility timeout
* expires. The value must be larger than or equal to 0, and cannot be larger than 7 days. The
* visibility timeout of a message can be set to a value later than the expiry time, which
* will prevent the message from being retrieved again whether it is processed or not.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws IOException
* @throws URISyntaxException If the URI is not valid.
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection retrieveMessages(
final URI uri,
final int timeout,
final int numberOfMessages,
final int visibilityTimeoutInSeconds,
final OperationContext opContext)
throws URISyntaxException, IOException, StorageException {
final UriQueryBuilder builder = new UriQueryBuilder();
if (numberOfMessages != 0) {
builder.add(NUMBER_OF_MESSAGES, Integer.toString(numberOfMessages));
}
builder.add(VISIBILITY_TIMEOUT, Integer.toString(visibilityTimeoutInSeconds));
final HttpURLConnection request =
BaseRequest.createURLConnection(uri, timeout, builder, opContext);
request.setRequestMethod("GET");
return request;
}
/**
* Adds user-defined metadata to the web request as one or more name-value pairs.
*
* @param request The <code>HttpURLConnection</code> web request to add the metadata to.
* @param metadata A <code>HashMap</code> containing the user-defined metadata to add.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
*/
public static void addMetadata(
final HttpURLConnection request,
final HashMap<String, String> metadata,
final OperationContext opContext) {
BaseRequest.addMetadata(request, metadata, opContext);
}
/**
* Constructs a web request to set user-defined metadata for the queue. Each call to this
* operation replaces all existing metadata attached to the queue. Use the {@link #addMetadata}
* method to specify the metadata to set on the queue. To remove all metadata from the queue, call
* this web request with no metadata added. Sign the web request with a length of 0.
*
* @param uri A <code>URI</code> object that specifies the absolute URI to the queue.
* @param timeout The server response timeout interval in milliseconds. If the operation does not
* complete within the specified timeout interval, a timeout error is returned by the server.
* If the timeout value is 0, the maximum timeout of 30 seconds is used.
* @param opContext An {@link OperationContext} object that represents the context for the current
* operation. This object is used to track requests to the storage service, and to provide
* additional runtime information about the operation.
* @return An <code>HttpURLConnection</code> configured for the specified operation.
* @throws IOException
* @throws URISyntaxException If the URI is not valid.
* @throws StorageException If a storage service error occurred during the operation.
*/
public static HttpURLConnection setMetadata(
final URI uri, final int timeout, final OperationContext opContext)
throws IOException, URISyntaxException, StorageException {
return BaseRequest.setMetadata(uri, timeout, null, opContext);
}