diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/BlobContract.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/BlobContract.java index c6d2ec0d4433..af7db3065b41 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/BlobContract.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/BlobContract.java @@ -690,11 +690,10 @@ void createBlobBlock(String container, String blob, String blockId, InputStream * You can call this method to update a blob by uploading only those blocks that have changed, then committing the * new and existing blocks together. You can do this with the blockList parameter by specifying whether to * commit a block from the committed block list or from the uncommitted block list, or to commit the most recently - * uploaded version of the block, whichever list it may belong to. Use the - * {@link BlobContract#CommitBlobBlocksOptions options} parameter to optionally specify the server timeout for the - * operation, the MIME content type and content encoding for the blob, the content language, the MD5 hash, a cache - * control value, blob metadata, the lease ID if the blob has an active lease, and any access conditions for the - * operation. + * uploaded version of the block, whichever list it may belong to. Use the {@link CommitBlobBlocksOptions options} + * parameter to optionally specify the server timeout for the operation, the MIME content type and content encoding + * for the blob, the content language, the MD5 hash, a cache control value, blob metadata, the lease ID if the blob + * has an active lease, and any access conditions for the operation. *

* In order to be written as part of a blob, each block in the list must have been successfully written to the * server with a call to {@link BlobContract#createBlobBlock(String, String, String, InputStream)} or diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/client/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/client/package.html new file mode 100644 index 000000000000..cbf5ee75f377 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/client/package.html @@ -0,0 +1,5 @@ + + +This package contains the integrated blob service client classes and implementation. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/implementation/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/implementation/package.html new file mode 100644 index 000000000000..d44ec4f38bce --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/implementation/package.html @@ -0,0 +1,5 @@ + + +This package contains the implementation of the blob service classes and utilities. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/AccessConditionHeaderType.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/AccessConditionHeaderType.java index 30045ee84b98..34966982a9da 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/AccessConditionHeaderType.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/AccessConditionHeaderType.java @@ -2,15 +2,15 @@ * Copyright 2011 Microsoft Corporation * * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * http://www.apache.org/licenses/LICENSE-2.0 + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * http://www.apache.org/licenses/LICENSE-2.0 * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. */ package com.microsoft.windowsazure.services.blob.models; @@ -24,22 +24,22 @@ public enum AccessConditionHeaderType { NONE, /** - * Specifies the If-Unmodified-Since conditional header is set. + * Specifies the If-Unmodified-Since conditional header is set. */ IF_UNMODIFIED_SINCE, /** - * Specifies the If-Match conditional header is set. + * Specifies the If-Match conditional header is set. */ IF_MATCH, /** - * Specifies the If-Modified-Since conditional header is set. + * Specifies the If-Modified-Since conditional header is set. */ IF_MODIFIED_SINCE, /** - * Specifies the If-None-Match conditional header is set. + * Specifies the If-None-Match conditional header is set. */ IF_NONE_MATCH; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/CreateBlobSnapshotResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/CreateBlobSnapshotResult.java index 25daaff571ab..7965e60deedd 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/CreateBlobSnapshotResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/CreateBlobSnapshotResult.java @@ -46,7 +46,7 @@ public String getSnapshot() { } /** - * Reserved for internal use. Sets the snapshot timestamp value from the x-ms-snapshot header + * Reserved for internal use. Sets the snapshot timestamp value from the x-ms-snapshot header * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by @@ -75,7 +75,7 @@ public String getEtag() { } /** - * Reserved for internal use. Sets the ETag of the snapshot from the ETag header returned in the + * Reserved for internal use. Sets the ETag of the snapshot from the ETag header returned in the * response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by @@ -104,8 +104,8 @@ public Date getLastModified() { } /** - * Reserved for internal use. Sets the last modified time of the snapshot from the Last-Modified - * header returned in the response. + * Reserved for internal use. Sets the last modified time of the snapshot from the Last-Modified header + * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobMetadataResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobMetadataResult.java index bba525e3db1e..14aa9fb13e62 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobMetadataResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobMetadataResult.java @@ -46,7 +46,7 @@ public String getEtag() { } /** - * Reserved for internal use. Sets the ETag of the blob from the ETag header returned in the + * Reserved for internal use. Sets the ETag of the blob from the ETag header returned in the * response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by @@ -75,8 +75,8 @@ public Date getLastModified() { } /** - * Reserved for internal use. Sets the last modified time of the blob from the Last-Modified - * header returned in the response. + * Reserved for internal use. Sets the last modified time of the blob from the Last-Modified header + * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. @@ -101,8 +101,8 @@ public HashMap getMetadata() { } /** - * Reserved for internal use. Sets the blob metadata from the x-ms-meta-name:value headers returned in the - * response. + * Reserved for internal use. Sets the blob metadata from the x-ms-meta-name:value headers + * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobPropertiesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobPropertiesResult.java index db77763781ff..725ce6d3c78a 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobPropertiesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobPropertiesResult.java @@ -66,8 +66,8 @@ public HashMap getMetadata() { } /** - * Reserved for internal use. Sets the blob metadata from the x-ms-meta-name:value headers returned in the - * response. + * Reserved for internal use. Sets the blob metadata from the x-ms-meta-name:value headers + * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobResult.java index 98a86f38291e..dcdc580a79ea 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetBlobResult.java @@ -90,8 +90,8 @@ public HashMap getMetadata() { } /** - * Reserved for internal use. Sets the blob metadata from the x-ms-meta-name:value headers returned in the - * response. + * Reserved for internal use. Sets the blob metadata from the x-ms-meta-name:value headers + * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetContainerPropertiesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetContainerPropertiesResult.java index 00ad2de3de55..6a5cf9495ab0 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetContainerPropertiesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/GetContainerPropertiesResult.java @@ -48,7 +48,7 @@ public String getEtag() { } /** - * Reserved for internal use. Sets the Etag of the container from the ETag header returned in + * Reserved for internal use. Sets the Etag of the container from the ETag header returned in * the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by @@ -74,8 +74,8 @@ public Date getLastModified() { } /** - * Reserved for internal use. Sets the last modified time of the container from the - * Last-Modified header returned in the response. + * Reserved for internal use. Sets the last modified time of the container from the Last-Modified + * header returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. @@ -100,7 +100,7 @@ public HashMap getMetadata() { } /** - * Reserved for internal use. Sets the container metadata from the x-ms-meta-name headers + * Reserved for internal use. Sets the container metadata from the x-ms-meta-name headers * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobBlocksResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobBlocksResult.java index 43008a72f44d..216322e4dd21 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobBlocksResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobBlocksResult.java @@ -85,7 +85,7 @@ public String getEtag() { } /** - * Reserved for internal use. Sets the ETag of the blob from the ETag header returned in the + * Reserved for internal use. Sets the ETag of the blob from the ETag header returned in the * response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by @@ -109,8 +109,8 @@ public String getContentType() { } /** - * Reserved for internal use. Sets the MIME content type of the blob from the Content-Type - * header returned in the response. + * Reserved for internal use. Sets the MIME content type of the blob from the Content-Type header + * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. @@ -133,7 +133,7 @@ public long getContentLength() { } /** - * Reserved for internal use. Sets the content length of the blob from the x-ms-blob-content-length + * Reserved for internal use. Sets the content length of the blob from the x-ms-blob-content-length * header returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobRegionsResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobRegionsResult.java index ffec19183345..c18ccb70c38b 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobRegionsResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobRegionsResult.java @@ -51,8 +51,8 @@ public Date getLastModified() { } /** - * Reserved for internal use. Sets the last modified time of the blob from the Last-Modified - * header returned in the response. + * Reserved for internal use. Sets the last modified time of the blob from the Last-Modified header + * returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by * the server. @@ -78,7 +78,7 @@ public String getEtag() { } /** - * Reserved for internal use. Sets the ETag of the blob from the ETag header returned in the + * Reserved for internal use. Sets the ETag of the blob from the ETag header returned in the * response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by @@ -102,7 +102,7 @@ public long getContentLength() { } /** - * Reserved for internal use. Sets the content length of the blob from the x-ms-blob-content-length + * Reserved for internal use. Sets the content length of the blob from the x-ms-blob-content-length * header returned in the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned by diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsOptions.java index c16f54bdb6c1..ed46f9f71772 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsOptions.java @@ -190,7 +190,7 @@ public String getDelimiter() { * each blob does. *

* Note that if a delimiter is set, you cannot include snapshots. A request that includes both returns an - * InvalidQueryParameter error (HTTP status code 400 – Bad Request), which causes a {@link ServiceException} to be + * InvalidQueryParameter error (HTTP status code 400 - Bad Request), which causes a {@link ServiceException} to be * thrown. *

* The delimiter value only affects calls made on methods where this {@link ListBlobsOptions} instance is @@ -246,7 +246,7 @@ public boolean isIncludeSnapshots() { * Sets the value of an optional flag indicating whether to include blob snapshots with a response. *

* Note that if this flag is set, you cannot set a delimiter. A request that includes both returns an - * InvalidQueryParameter error (HTTP status code 400 – Bad Request), which causes a {@link ServiceException} to be + * InvalidQueryParameter error (HTTP status code 400 - Bad Request), which causes a {@link ServiceException} to be * thrown. * * @param includeSnapshots diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsResult.java index feb0bf40944e..5245eea92427 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListBlobsResult.java @@ -30,11 +30,11 @@ import com.microsoft.windowsazure.services.blob.implementation.MetadataAdapter; /** - * A wrapper class for the response returned from a Blob Service REST API Get Blobs operation. This is returned by + * A wrapper class for the response returned from a Blob Service REST API List Blobs operation. This is returned by * calls to implementations of {@link BlobContract#listBlobs(String)} and * {@link BlobContract#listBlobs(String, ListBlobsOptions)}. *

- * See the Get Blobs documentation on + * See the List Blobs documentation on * MSDN for details of the underlying Blob Service REST API operation. */ @XmlRootElement(name = "EnumerationResults") diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersOptions.java index 2d9bdcca3e1d..71a5a868c5ca 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersOptions.java @@ -93,7 +93,7 @@ public String getMarker() { * Use the {@link ListContainersResult#getNextMarker() getNextMarker} method on a {@link ListContainersResult} * instance to get the marker value to set on a {@link ListContainersOptions} instance using a call to this method. * Pass the {@link ListContainersOptions} instance as a parameter to a - * {@link BlobContract#listContainers(listContainersOptions)} call to get the next portion of the container list. + * {@link BlobContract#listContainers(ListContainersOptions)} call to get the next portion of the container list. *

* The marker value only affects calls made on methods where this {@link ListContainersOptions} instance is * passed as a parameter. @@ -130,7 +130,7 @@ public int getMaxResults() { * Use the {@link ListContainersResult#getNextMarker() getNextMarker} method on a {@link ListContainersResult} * instance to get the marker value to set on a {@link ListContainersOptions} instance using a call to * {@link ListContainersOptions#setMarker(String)}. Pass the {@link ListContainersOptions} instance as a parameter - * to a {@link BlobContract#listContainers(listContainersOptions)} call to get the next portion of the container + * to a {@link BlobContract#listContainers(ListContainersOptions)} call to get the next portion of the container * list. *

* The maxResults value only affects calls made on methods where this {@link ListContainersOptions} diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersResult.java index eb47ce77be2b..3b6508eb4a8a 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/ListContainersResult.java @@ -31,7 +31,7 @@ /** * A wrapper class for the response returned from a Blob Service REST API List Containers operation. This is returned by * calls to implementations of {@link BlobContract#listContainers} and - * {@link BlobContract#listContainers(listContainersOptions)}. + * {@link BlobContract#listContainers(ListContainersOptions)}. *

* See the List Containers * documentation on MSDN for details of the underlying Blob Service REST API operation. @@ -135,7 +135,7 @@ public void setPrefix(String prefix) { * Use the {@link ListContainersResult#getNextMarker() getNextMarker} method to get the marker value to set on a * {@link ListContainersOptions} instance using a call to {@link ListContainersOptions#setMarker(String)}. Pass the * {@link ListContainersOptions} instance as a parameter to a - * {@link BlobContract#listContainers(listContainersOptions)} call to get the next portion of the container list. + * {@link BlobContract#listContainers(ListContainersOptions)} call to get the next portion of the container list. * * @return * A {@link String} containing the marker used to specify the beginning of the container list returned, if @@ -207,7 +207,7 @@ public void setNextMarker(String nextMarker) { * Use the {@link ListContainersResult#getNextMarker() getNextMarker} method to get the marker value to set on a * {@link ListContainersOptions} instance using a call to {@link ListContainersOptions#setMarker(String)}. Pass the * {@link ListContainersOptions} instance as a parameter to a - * {@link BlobContract#listContainers(listContainersOptions)} call to get the next portion of the container list. + * {@link BlobContract#listContainers(ListContainersOptions)} call to get the next portion of the container list. * * @return * The maximum number of container list items to return that was specified in the request, if any. @@ -292,7 +292,7 @@ public void setUrl(String url) { } /** - * Gets the container properties. The container properties include the last modified time and an Etag value. + * Gets the container properties. The container properties include the last modified time and an ETag value. * * @return * A {@link ContainerProperties} instance containing the properties associated with the container. @@ -384,12 +384,12 @@ public void setLastModified(Date lastModified) { } /** - * Gets the Etag of the container. This value can be used when updating or deleting a container using an + * Gets the ETag of the container. This value can be used when updating or deleting a container using an * optimistic concurrency model to prevent the client from modifying data that has been changed by another * client. * * @return - * A {@link String} containing the server-assigned Etag value for the container. + * A {@link String} containing the server-assigned ETag value for the container. */ @XmlElement(name = "Etag") public String getEtag() { @@ -397,14 +397,14 @@ public String getEtag() { } /** - * Reserved for internal use. Sets the Etag of the container from the Etag element returned in + * Reserved for internal use. Sets the ETag of the container from the ETag element returned in * the response. *

* This method is invoked by the API to set the value from the Blob Service REST API operation response returned * by the server. * * @param etag - * A {@link String} containing the server-assigned Etag value for the container. + * A {@link String} containing the server-assigned ETag value for the container. */ public void setEtag(String etag) { this.etag = etag; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/PageRange.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/PageRange.java index 1af40b003e05..44a6fe568ca7 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/PageRange.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/PageRange.java @@ -23,7 +23,7 @@ * be up to the value of the blob's full size. *

* Pages are aligned with 512-byte boundaries. When specifying a page range, the start offset must be a modulus of 512 - * and the end offset must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc. + * and the end offset must be a modulus of 512 - 1. Examples of valid byte ranges are 0-511, 512-1023, etc. */ public class PageRange { private long start; @@ -39,7 +39,7 @@ public PageRange() { * Creates a page range from the specified start and end byte offsets, inclusive. *

* Pages are aligned with 512-byte boundaries. When specifying a page range, the start offset must be a modulus of - * 512 and the end offset must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc. + * 512 and the end offset must be a modulus of 512 - 1. Examples of valid byte ranges are 0-511, 512-1023, etc. * * @param start * The beginning offset value in bytes for the page range, inclusive. @@ -66,7 +66,7 @@ public long getStart() { * Sets the byte offset of the start of the page range within the blob, inclusive. *

* Pages are aligned with 512-byte boundaries. When specifying a page range, the start offset must be a modulus of - * 512 and the end offset must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc. + * 512 and the end offset must be a modulus of 512 - 1. Examples of valid byte ranges are 0-511, 512-1023, etc. * * @param start * The beginning offset value in bytes for the page range, inclusive. @@ -93,7 +93,7 @@ public long getEnd() { * Sets the byte offset of the end of the page range within the blob, inclusive. *

* Pages are aligned with 512-byte boundaries. When specifying a page range, the start offset must be a modulus of - * 512 and the end offset must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc. + * 512 and the end offset must be a modulus of 512 - 1. Examples of valid byte ranges are 0-511, 512-1023, etc. * * @param end * The ending offset value in bytes for the page range, inclusive. @@ -121,7 +121,7 @@ public long getLength() { * 512 bytes. *

* Pages are aligned with 512-byte boundaries. When specifying a page range, the start offset must be a modulus of - * 512 and the end offset must be a modulus of 512 – 1. Examples of valid byte ranges are 0-511, 512-1023, etc. + * 512 and the end offset must be a modulus of 512 - 1. Examples of valid byte ranges are 0-511, 512-1023, etc. * * @param value * The ending offset value in bytes for the page range, inclusive. diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/package.html new file mode 100644 index 000000000000..161010acd848 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/blob/models/package.html @@ -0,0 +1,5 @@ + + +This package contains the blob data transfer object classes. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/client/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/client/package.html new file mode 100644 index 000000000000..72c5aac9b9f3 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/client/package.html @@ -0,0 +1,5 @@ + + +This package contains the integrated queue service client classes and implementation. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/implementation/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/implementation/package.html new file mode 100644 index 000000000000..7cfd5ada0c07 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/queue/implementation/package.html @@ -0,0 +1,5 @@ + + +This package contains the implementation of the queue service classes and utilities. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/EdmValueConverter.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/EdmValueConverter.java index 4a6fd5fb37fb..48b0859ba92f 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/EdmValueConverter.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/EdmValueConverter.java @@ -14,8 +14,39 @@ */ package com.microsoft.windowsazure.services.table; +import com.microsoft.windowsazure.services.table.models.EdmType; + +/** + * An interface for EDM type serialization to Windows Azure Storage service and deserialization to native Java + * types. + */ public interface EdmValueConverter { + /** + * Creates a serialized string in EDM type format from the native Java value parameter. + *

+ * Supported edmType parameter values are defined as constants in the {@link EdmType} class. + * + * @param edmType + * A {@link String} containing the EDM data type to serialize the value parameter as. + * @param value + * An {@link Object} reference to the native Java value to serialize. + * @return + * A {@link String} containing the serialized data to send to the Windows Azure Storage service. + */ String serialize(String edmType, Object value); + /** + * Creates an object of the correct native Java type from the serialized data in EDM type format. + *

+ * Supported edmType parameter values are defined as constants in the {@link EdmType} class. + * + * @param edmType + * A {@link String} containing the EDM data type of the value parameter to deserialize. + * @param value + * A {@link String} containing the Windows Azure Storage service data to deserialize. + * @return + * An {@link Object} reference to the deserialized native Java value. This is an object of the + * correct native Java type for the EDM data type, passed as an {@link Object}. + */ Object deserialize(String edmType, String value); } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableConfiguration.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableConfiguration.java index 33391fc9e711..5d0d696061d1 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableConfiguration.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableConfiguration.java @@ -14,8 +14,29 @@ */ package com.microsoft.windowsazure.services.table; +/** + * This class contains static strings used to identify parts of a service configuration instance associated with the + * Windows Azure Table service. + *

+ * These values must not be altered. + */ public class TableConfiguration { + /** + * The Table configuration account name constant. This String value is used as a key in the + * configuration file, to identify the value for the DNS prefix name for the storage account. + */ public final static String ACCOUNT_NAME = "table.accountName"; + + /** + * The Table configuration account key constant. This String value is used as a key in the + * configuration file, to identify the value for the storage service account key. + */ public final static String ACCOUNT_KEY = "table.accountKey"; + + /** + * The Table configuration URI constant. This String value is used as a key in the + * configuration file, to identify the URI value for the Table service REST API address for the + * storage account. + */ public final static String URI = "table.uri"; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableContract.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableContract.java index 2bb4e1a3ac6a..e4a448f0f7ff 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableContract.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableContract.java @@ -32,68 +32,501 @@ import com.microsoft.windowsazure.services.table.models.TableServiceOptions; import com.microsoft.windowsazure.services.table.models.UpdateEntityResult; +/** + * Defines the methods available on the Windows Azure Table storage service. Construct an object instance implementing + * TableContract with one of the static create methods on {@link TableService}. These methods + * associate a Configuration with the implementation, so the methods on the instance of + * TableContract all work with a particular storage account. + */ public interface TableContract extends FilterableService { + /** + * Gets the properties of a storage account’s Table service, including Windows Azure Storage Analytics. + * + * @return + * A {@link GetServicePropertiesResult} reference to the Table service properties. + * + * @throws ServiceException + * if an error occurs accessing the storage service. + */ GetServicePropertiesResult getServiceProperties() throws ServiceException; + /** + * Gets the properties of a storage account’s Table service, including Windows Azure Storage Analytics, using the + * specified options. + *

+ * Use the {@link TableServiceOptions options} parameter to specify options for the request. + * + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * A {@link GetServicePropertiesResult} reference to the Table service properties. + * + * @throws ServiceException + * if an error occurs accessing the storage service. + */ GetServicePropertiesResult getServiceProperties(TableServiceOptions options) throws ServiceException; + /** + * Sets the properties of a storage account’s Table service, including Windows Azure Storage Analytics. + * + * @param serviceProperties + * A {@link ServiceProperties} instance containing the Table service properties to set. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void setServiceProperties(ServiceProperties serviceProperties) throws ServiceException; + /** + * Sets the properties of a storage account’s Table service, including Windows Azure Storage Analytics, using the + * specified options. + *

+ * Use the {@link TableServiceOptions options} parameter to specify options for the request. + * + * @param serviceProperties + * A {@link ServiceProperties} instance containing the Table service properties to set. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void setServiceProperties(ServiceProperties serviceProperties, TableServiceOptions options) throws ServiceException; + /** + * Creates a table with the specified name in the storage account. + *

+ * Table names must be unique within a storage account, and must conform to these rules: + *

+ *

+ * These rules are also described by the regular expression "^[A-Za-z][A-Za-z0-9]{2,62}$". + *

+ * Table names preserve the case with which they were created, but are case-insensitive when used. + * + * @param table + * A {@link String} containing the name of the table to create. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void createTable(String table) throws ServiceException; + /** + * Creates a table with the specified name in the storage account, using the specified options. + *

+ * Use the {@link TableServiceOptions options} parameter to specify options for the request. + *

+ * Table names must be unique within a storage account, and must conform to these rules: + *

+ *

+ * These rules are also described by the regular expression "^[A-Za-z][A-Za-z0-9]{2,62}$". + *

+ * Table names preserve the case with which they were created, but are case-insensitive when used. + * + * @param table + * A {@link String} containing the name of the table to create. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void createTable(String table, TableServiceOptions options) throws ServiceException; + /** + * Deletes the specified table and any data it contains from the storage account. + *

+ * When a table is successfully deleted, it is immediately marked for deletion and is no longer accessible to + * clients. The table is later removed from the Table service during garbage collection. + *

+ * Note that deleting a table is likely to take at least 40 seconds to complete. If an operation is attempted + * against the table while it is being deleted, the service returns status code 409 (Conflict), with additional + * error information indicating that the table is being deleted. This causes a {@link ServiceException} to be thrown + * in the context of the client request. + * + * @param table + * A {@link String} containing the name of the table to delete. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void deleteTable(String table) throws ServiceException; + /** + * Deletes the specified table and any data it contains from the storage account, using the specified options. + *

+ * Use the {@link TableServiceOptions options} parameter to specify options for the request. + *

+ * When a table is successfully deleted, it is immediately marked for deletion and is no longer accessible to + * clients. The table is later removed from the Table service during garbage collection. + *

+ * Note that deleting a table is likely to take at least 40 seconds to complete. If an operation is attempted + * against the table while it is being deleted, the service returns status code 409 (Conflict), with additional + * error information indicating that the table is being deleted. This causes a {@link ServiceException} to be thrown + * in the context of the client request. + * + * @param table + * A {@link String} containing the name of the table to delete. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void deleteTable(String table, TableServiceOptions options) throws ServiceException; + /** + * Gets the specified table entry from the list of tables in the storage account. + * + * @param table + * A {@link String} containing the name of the table to retrieve. + * @return + * A {@link GetTableResult} instance containing the table entry returned. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ GetTableResult getTable(String table) throws ServiceException; + /** + * Gets the specified table entry from the list of tables in the storage account, using the specified options. + *

+ * Use the {@link TableServiceOptions options} parameter to specify options for the request. + * + * @param table + * A {@link String} containing the name of the table to retrieve. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * A {@link GetTableResult} instance containing the table entry returned. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ GetTableResult getTable(String table, TableServiceOptions options) throws ServiceException; + /** + * Gets a list of tables in the storage account. + * + * @return + * A {@link QueryTablesResult} instance containing the list of table entries returned. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ QueryTablesResult queryTables() throws ServiceException; + /** + * Gets a list of tables in the storage account, using the specified options. + *

+ * Use the {@link QueryTablesOptions options} parameter to specify options for the request, such as a filter to + * limit results to tables with certain properties, the next table name continuation token to use to resume the + * query tables request from, and a prefix string to match table names with. + * + * @param options + * A {@link QueryTablesOptions} instance containing options for the request. + * @return + * A {@link QueryTablesResult} instance containing the list of table entries returned. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ QueryTablesResult queryTables(QueryTablesOptions options) throws ServiceException; + /** + * Inserts an entity into a table. + * + * @param table + * A {@link String} containing the name of the table to insert the entity into. + * @param entity + * An {@link Entity} instance containing the entity data to insert in the table. + * @return + * An {@link InsertEntityResult} containing the entity inserted in the table. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ InsertEntityResult insertEntity(String table, Entity entity) throws ServiceException; + /** + * Inserts an entity into a table, using the specified options. + * + * @param table + * A {@link String} containing the name of the table to insert the entity into. + * @param entity + * An {@link Entity} instance containing the entity data to insert in the table. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * An {@link InsertEntityResult} containing the entity inserted in the table. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ InsertEntityResult insertEntity(String table, Entity entity, TableServiceOptions options) throws ServiceException; + /** + * Updates an entity in a table. The entity data is completely replaced with the data in the entity + * parameter. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to update. + * @param entity + * An {@link Entity} instance containing the entity to update in the table. + * @return + * An {@link UpdateEntityResult} containing the ETag of the updated entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult updateEntity(String table, Entity entity) throws ServiceException; + /** + * Updates an entity in a table, using the specified options. The entity data is completely replaced with the data + * in the entity parameter. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to update. + * @param entity + * An {@link Entity} instance containing the entity to update in the table. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * An {@link UpdateEntityResult} containing the ETag of the updated entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult updateEntity(String table, Entity entity, TableServiceOptions options) throws ServiceException; + /** + * Merges entity data into an existing entity in a table. Property values in the existing entity are overwritten + * with matching properties in the entity parameter. Properties in the entity parameter that are + * not present in the existing entity are added to it. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to merge. + * @param entity + * An {@link Entity} instance containing the entity data to merge into the existing entity. + * @return + * An {@link UpdateEntityResult} containing the ETag of the modified entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult mergeEntity(String table, Entity entity) throws ServiceException; + /** + * Merges entity data into an existing entity in a table, using the specified options. Property values in the + * existing entity are overwritten with matching properties in the entity parameter. Properties in the + * entity parameter that are not present in the existing entity are added to it. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to merge. + * @param entity + * An {@link Entity} instance containing the entity data to merge into the existing entity. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * An {@link UpdateEntityResult} containing the ETag of the modified entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult mergeEntity(String table, Entity entity, TableServiceOptions options) throws ServiceException; + /** + * Inserts or replaces an entity in a table. If the table does not contain an entity with a matching primary key, it + * is inserted. Otherwise, the entity data is completely replaced with the data in the entity parameter. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to insert or replace. + * @param entity + * An {@link Entity} instance containing the entity data to insert or replace in the table. + * @return + * An {@link UpdateEntityResult} containing the ETag of the modified entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult insertOrReplaceEntity(String table, Entity entity) throws ServiceException; + /** + * Inserts or replaces an entity in a table, using the specified options. If the table does not contain an entity + * with a matching primary key, it is inserted. Otherwise, the entity data is completely replaced with the data in + * the entity parameter. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to insert or replace. + * @param entity + * An {@link Entity} instance containing the entity data to insert or replace in the table. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * An {@link UpdateEntityResult} containing the ETag of the modified entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult insertOrReplaceEntity(String table, Entity entity, TableServiceOptions options) throws ServiceException; + /** + * Inserts or merges an entity in a table. If the table does not contain an entity with a matching primary key, it + * is inserted. Otherwise, property values in the existing entity are overwritten with matching properties in the + * entity parameter. Properties in the entity parameter that are not present in the existing + * entity are added to it. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to insert or merge. + * @param entity + * An {@link Entity} instance containing the entity data to insert or merge in the table. + * @return + * An {@link UpdateEntityResult} containing the ETag of the modified entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult insertOrMergeEntity(String table, Entity entity) throws ServiceException; + /** + * Inserts or merges an entity in a table, using the specified options. If the table does not contain an entity with + * a matching primary key, it is inserted. Otherwise, property values in the existing entity are overwritten with + * matching properties in the entity parameter. Properties in the entity parameter that are not + * present in the existing entity are added to it. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to insert or merge. + * @param entity + * An {@link Entity} instance containing the entity data to insert or merge in the table. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * An {@link UpdateEntityResult} containing the ETag of the modified entity. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ UpdateEntityResult insertOrMergeEntity(String table, Entity entity, TableServiceOptions options) throws ServiceException; + /** + * Deletes an entity from a table. + * + * @param table + * A {@link String} containing the name of the table to delete the entity from. + * @param partitionKey + * A {@link String} containing the partition key of the entity to delete. + * @param rowKey + * A {@link String} containing the row key of the entity to delete. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void deleteEntity(String table, String partitionKey, String rowKey) throws ServiceException; + /** + * Deletes an entity from a table, using the specified options. + *

+ * Use the {@link DeleteEntityOptions options} parameter to specify an ETag value that must match to delete the + * entity. + * + * @param table + * A {@link String} containing the name of the table to delete the entity from. + * @param partitionKey + * A {@link String} containing the partition key of the entity to delete. + * @param rowKey + * A {@link String} containing the row key of the entity to delete. + * @param options + * A {@link DeleteEntityOptions} instance containing the ETag to match with the entity to delete. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ void deleteEntity(String table, String partitionKey, String rowKey, DeleteEntityOptions options) throws ServiceException; + /** + * Gets the specified entity. + * + * @param table + * A {@link String} containing the name of the table to get the entity from. + * @param partitionKey + * A {@link String} containing the partition key of the entity to get. + * @param rowKey + * A {@link String} containing the row key of the entity to get. + * @return + * A {@link GetEntityResult} instance containing the entity data returned in the server response. + * @throws ServiceException + */ GetEntityResult getEntity(String table, String partitionKey, String rowKey) throws ServiceException; + /** + * Gets the specified entity, using the specified options. + * + * @param table + * A {@link String} containing the name of the table to get the entity from. + * @param partitionKey + * A {@link String} containing the partition key of the entity to get. + * @param rowKey + * A {@link String} containing the row key of the entity to get. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * A {@link GetEntityResult} instance containing the entity data returned in the server response. + * @throws ServiceException + */ GetEntityResult getEntity(String table, String partitionKey, String rowKey, TableServiceOptions options) throws ServiceException; + /** + * Lists the entities in a table. + * + * @param table + * A {@link String} containing the name of the table to retrieve the list of entities from. + * @return + * A {@link QueryEntitiesResult} instance containing the server response to the batch request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ QueryEntitiesResult queryEntities(String table) throws ServiceException; + /** + * Lists the entities in a table that match the specified options. + *

+ * Use the {@link QueryEntitiesOptions options} parameter to specify the next partition key and next row key + * continuation tokens to use to resume the query entities request from, a collection of the property names to + * include in the entities returned in the server response, a filter to limit results to entities with certain + * property values, and a top count to limit the response to that number of the first matching results. + * + * @param table + * A {@link String} containing the name of the table to retrieve the list of entities from. + * @param options + * A {@link QueryEntitiesOptions} instance containing options for the request. + * @return + * A {@link QueryEntitiesResult} instance containing the server response to the batch request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ QueryEntitiesResult queryEntities(String table, QueryEntitiesOptions options) throws ServiceException; + /** + * Submits multiple entity operations in the same table and partition group as a single transaction. Multiple insert + * entity, update entity, merge entity, delete entity, insert or replace entity, and insert or merge entity + * operations are supported within a single transaction. + * + * @param operations + * A {@link BatchOperations} instance containing the list of operations to send as a single transaction. + * @return + * A {@link BatchResult} instance containing the server response to the batch request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ BatchResult batch(BatchOperations operations) throws ServiceException; + /** + * Submits multiple entity operations in the same table and partition group as a single transaction, using the + * specified options. Multiple insert entity, update entity, merge entity, delete entity, insert or replace entity, + * and insert or merge entity operations are supported within a single transaction. + *

+ * Use the {@link TableServiceOptions options} parameter to specify options for the request. + * + * @param operations + * A {@link BatchOperations} instance containing the list of operations to send as a single transaction. + * @param options + * A {@link TableServiceOptions} instance containing options for the request. + * @return + * A {@link BatchResult} instance containing the server response to the batch request. + * @throws ServiceException + * if an error occurs accessing the storage service. + */ BatchResult batch(BatchOperations operations, TableServiceOptions options) throws ServiceException; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableService.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableService.java index c37f20da147f..51bf07c43bd3 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableService.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/TableService.java @@ -16,22 +16,69 @@ import com.microsoft.windowsazure.services.core.Configuration; +/** + * A class for static factory methods that return instances implementing {@link TableContract}. + */ public class TableService { private TableService() { } + /** + * A static factory method that returns an instance implementing {@link TableContract} 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 TableContract} for interacting with the Table service. + */ public static TableContract create() { return create(null, Configuration.getInstance()); } + /** + * A static factory method that returns an instance implementing {@link TableContract} 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 TableContract} for interacting with the Table service. + */ public static TableContract create(Configuration config) { return create(null, config); } + /** + * A static factory method that returns an instance implementing {@link TableContract} 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 TableContract} for interacting with the Table service. + */ public static TableContract create(String profile) { return create(profile, Configuration.getInstance()); } + /** + * A static factory method that returns an instance implementing {@link TableContract} 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 TableContract} for interacting with the Table service. + */ public static TableContract create(String profile, Configuration config) { return config.create(profile, TableContract.class); } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/client/TableServiceEntity.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/client/TableServiceEntity.java index d958bb328444..04f26b84a300 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/client/TableServiceEntity.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/client/TableServiceEntity.java @@ -78,8 +78,8 @@ * * Edm.Byte * {@link EdmType#BYTE} - * boolean, Boolean - * A Boolean value. + * byte, Byte + * An 8-bit integer value. * * * Edm.DateTime diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/client/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/client/package.html new file mode 100644 index 000000000000..6a84c85156b2 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/client/package.html @@ -0,0 +1,5 @@ + + +This package contains the integrated table service client classes and implementation. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/implementation/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/implementation/package.html new file mode 100644 index 000000000000..4032bfee5276 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/implementation/package.html @@ -0,0 +1,5 @@ + + +This package contains the implementation of the table service classes and utilities. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchOperations.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchOperations.java index 5de01c01542a..f59811f33f6f 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchOperations.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchOperations.java @@ -17,203 +17,594 @@ import java.util.ArrayList; import java.util.List; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the collection of table operations that may be sent as a single batch transaction with a + * {@link TableContract#batch(BatchOperations)} or {@link TableContract#batch(BatchOperations, TableServiceOptions)} + * request. A batch transaction is executed by the Storage Service REST API as a single atomic operation, by invoking an + * Entity Group Transaction. + *

+ * A batch operation may contain up to 100 individual table operations, with the requirement that the target entity of + * each operation must have same partition key. A batch with a query operation cannot contain any other operations. Note + * that the total payload of a batch operation is limited to 4MB. + *

+ * The semantics for entity group transactions are defined by the WCF Data Services Batching Operations. The WCF Data + * Services specification defines the following concepts for batch requests: + *

+ *

+ * The Table service supports a subset of the functionality defined by WCF Data Services: + *

+ *

+ * An individual request within the change set is identical to a request made when that operation is being called by + * itself. + *

+ * To specify an update, merge, or delete operation only succeeds when the entity has not changed since it was last seen + * by the client, include the entities' ETag value in the {@link Entity} instance passed to the operation in the change + * set. + */ public class BatchOperations { private List operations = new ArrayList(); + /** + * Gets the collection of table operations in the batch. + * + * @return + * A {@link java.util.List} of {@link Operation} instances representing the table operations in the batch. + */ public List getOperations() { return operations; } + /** + * Sets the collection of table operations in the batch. + * + * @param operations + * A {@link java.util.List} of {@link Operation} instances representing the table operations in the + * batch. + */ public void setOperations(List operations) { this.operations = operations; } + /** + * Adds an insert entity operation to the collection of table operations in the batch. + *

+ * The table parameter must refer to the same table as all other operations in the batch, and the + * entity parameter must have the same partition key as all other entities in the batch. + * + * @param table + * A {@link String} containing the name of the table to insert the entity into. + * @param entity + * The {@link Entity} instance to insert into the table. + * @return + * A reference to this {@link BatchOperations} instance. + */ public BatchOperations addInsertEntity(String table, Entity entity) { this.operations.add(new InsertEntityOperation().setTable(table).setEntity(entity)); return this; } + /** + * Adds an update entity operation to the collection of table operations in the batch. An update operation replaces + * an existing entity with with the same primary key as the entity parameter. + *

+ * The table parameter must refer to the same table as all other operations in the batch, and the + * entity parameter must have the same partition key as all other entities in the batch. + * + * @param table + * A {@link String} containing the name of the table to update the entity in. + * @param entity + * The {@link Entity} instance to update in the table. + * @return + * A reference to this {@link BatchOperations} instance. + */ public BatchOperations addUpdateEntity(String table, Entity entity) { this.operations.add(new UpdateEntityOperation().setTable(table).setEntity(entity)); return this; } + /** + * Adds a merge entity operation to the collection of table operations in the batch. A merge operation replaces + * and inserts properties in an existing entity with with the same primary key as the entity parameter. + *

+ * The table parameter must refer to the same table as all other operations in the batch, and the + * entity parameter must have the same partition key as all other entities in the batch. + * + * @param table + * A {@link String} containing the name of the table to merge the entity in. + * @param entity + * The {@link Entity} instance to merge in the table. + * @return + * A reference to this {@link BatchOperations} instance. + */ public BatchOperations addMergeEntity(String table, Entity entity) { this.operations.add(new MergeEntityOperation().setTable(table).setEntity(entity)); return this; } + /** + * Adds an insert or replace entity operation to the collection of table operations in the batch. An insert or + * replace operation replaces an existing entity with with the same primary key as the entity parameter, or + * inserts the entity if no matching entity exists in the table. + *

+ * The table parameter must refer to the same table as all other operations in the batch, and the + * entity parameter must have the same partition key as all other entities in the batch. + * + * @param table + * A {@link String} containing the name of the table to insert or replace the entity in. + * @param entity + * The {@link Entity} instance to insert or replace in the table. + * @return + * A reference to this {@link BatchOperations} instance. + */ public BatchOperations addInsertOrReplaceEntity(String table, Entity entity) { this.operations.add(new InsertOrReplaceEntityOperation().setTable(table).setEntity(entity)); return this; } + /** + * Adds an insert or merge entity operation to the collection of table operations in the batch. An insert or + * merge operation replaces and inserts properties in an existing entity with with the same primary key as the + * entity parameter, or inserts the entity if no matching entity exists in the table. + *

+ * The table parameter must refer to the same table as all other operations in the batch, and the + * entity parameter must have the same partition key as all other entities in the batch. + * + * @param table + * A {@link String} containing the name of the table to insert or replace the entity in. + * @param entity + * The {@link Entity} instance to insert or replace in the table. + * @return + * A reference to this {@link BatchOperations} instance. + */ public BatchOperations addInsertOrMergeEntity(String table, Entity entity) { this.operations.add(new InsertOrMergeEntityOperation().setTable(table).setEntity(entity)); return this; } + /** + * Adds a delete entity operation to the collection of table operations in the batch. The delete operation removes + * the entity with with the specified partition key, row key, and ETag from the table. + *

+ * The table parameter must refer to the same table as all other operations in the batch, and the + * partitionKey parameter must be the same partition key in all other operations in the batch. + * + * @param table + * A {@link String} containing the name of the table to delete the entity in. + * @param partitionKey + * A {@link String} containing the partition key of the entity to delete. + * @param rowKey + * A {@link String} containing the row key of the entity to delete. + * @param etag + * A {@link String} containing the ETag value of the entity to delete. + * @return + * A reference to this {@link BatchOperations} instance. + */ public BatchOperations addDeleteEntity(String table, String partitionKey, String rowKey, String etag) { this.operations.add(new DeleteEntityOperation().setTable(table).setPartitionKey(partitionKey).setRowKey(rowKey) .setEtag(etag)); return this; } + /** + * The abstract base class for all batch operations. + */ public static abstract class Operation { } + /** + * Represents the parameters needed for an insert entity batch operation. + */ public static class InsertEntityOperation extends Operation { private String table; private Entity entity; + /** + * Gets the table name parameter for the insert entity batch operation set in this {@link InsertEntityOperation} + * instance. + * + * @return + * A {@link String} containing the name of the table that contains the entity to insert. + */ public String getTable() { return table; } + /** + * Sets the table name parameter for the insert entity batch operation. Note that this value must be the same + * for + * all operations in the batch. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to insert. + * @return + * A reference to this {@link InsertEntityOperation} instance. + */ public InsertEntityOperation setTable(String table) { this.table = table; return this; } + /** + * Gets the entity parameter for the insert entity batch operation set in this {@link InsertEntityOperation} + * instance. + * + * @return + * The {@link Entity} instance containing the entity data to be inserted. + */ public Entity getEntity() { return entity; } + /** + * Sets the entity parameter for the insert entity batch operation. Note that the partition key value + * in the entity must be the same for all operations in the batch. + * + * @param entity + * The {@link Entity} instance containing the entity data to be inserted. + * @return + * A reference to this {@link InsertEntityOperation} instance. + */ public InsertEntityOperation setEntity(Entity entity) { this.entity = entity; return this; } } + /** + * Represents the parameters needed for an update entity batch operation. + */ public static class UpdateEntityOperation extends Operation { private String table; private Entity entity; + /** + * Gets the table name parameter for the update entity batch operation set in this {@link UpdateEntityOperation} + * instance. + * + * @return + * A {@link String} containing the name of the table that contains the entity to update. + */ public String getTable() { return table; } + /** + * Sets the table name parameter for the update entity batch operation. Note that this value must be the same + * for + * all operations in the batch. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to update. + * @return + * A reference to this {@link UpdateEntityOperation} instance. + */ public UpdateEntityOperation setTable(String table) { this.table = table; return this; } + /** + * Gets the entity parameter for the update entity batch operation set in this {@link UpdateEntityOperation} + * instance. + * + * @return + * The {@link Entity} instance containing the entity data to be updated. + */ public Entity getEntity() { return entity; } + /** + * Sets the entity parameter for the update entity batch operation. Note that the partition key value + * in the entity must be the same for all operations in the batch. + * + * @param entity + * The {@link Entity} instance containing the entity data to be updated. + * @return + * A reference to this {@link UpdateEntityOperation} instance. + */ public UpdateEntityOperation setEntity(Entity entity) { this.entity = entity; return this; } } + /** + * Represents the parameters needed for a merge entity batch operation. + */ public static class MergeEntityOperation extends Operation { private String table; private Entity entity; + /** + * Gets the table name parameter for the merge entity batch operation set in this {@link MergeEntityOperation} + * instance. + * + * @return + * A {@link String} containing the name of the table that contains the entity to merge. + */ public String getTable() { return table; } + /** + * Sets the table name parameter for the merge entity batch operation. Note that this value must be the same for + * all operations in the batch. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to merge. + * @return + * A reference to this {@link MergeEntityOperation} instance. + */ public MergeEntityOperation setTable(String table) { this.table = table; return this; } + /** + * Gets the entity parameter for the merge entity batch operation set in this {@link MergeEntityOperation} + * instance. + * + * @return + * The {@link Entity} instance containing the entity data to be merged. + */ public Entity getEntity() { return entity; } + /** + * Sets the entity parameter for the merge entity batch operation. Note that the partition key value + * in the entity must be the same for all operations in the batch. + * + * @param entity + * The {@link Entity} instance containing the entity data to be merged. + * @return + * A reference to this {@link MergeEntityOperation} instance. + */ public MergeEntityOperation setEntity(Entity entity) { this.entity = entity; return this; } } + /** + * Represents the parameters needed for an insert or replace entity batch operation. + */ public static class InsertOrReplaceEntityOperation extends Operation { private String table; private Entity entity; + /** + * Gets the table name parameter for the insert or replace entity batch operation set in this + * {@link InsertOrReplaceEntityOperation} instance. + * + * @return + * A {@link String} containing the name of the table that contains the entity to insert or replace. + */ public String getTable() { return table; } + /** + * Sets the table name parameter for the insert or replace entity batch operation. Note that this value must be + * the same for all operations in the batch. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to insert or replace. + * @return + * A reference to this {@link InsertOrReplaceEntityOperation} instance. + */ public InsertOrReplaceEntityOperation setTable(String table) { this.table = table; return this; } + /** + * Gets the entity parameter for the insert or replace entity batch operation set in this + * {@link InsertOrReplaceEntityOperation} instance. + * + * @return + * The {@link Entity} instance containing the entity data to be inserted or replaced. + */ public Entity getEntity() { return entity; } + /** + * Sets the entity parameter for the insert or replace entity batch operation. Note that the partition key value + * in the entity must be the same for all operations in the batch. + * + * @param entity + * The {@link Entity} instance containing the entity data to be inserted or replaced. + * @return + * A reference to this {@link InsertOrReplaceEntityOperation} instance. + */ public InsertOrReplaceEntityOperation setEntity(Entity entity) { this.entity = entity; return this; } } + /** + * Represents the parameters needed for an insert or merge entity batch operation. + */ public static class InsertOrMergeEntityOperation extends Operation { private String table; private Entity entity; + /** + * Gets the table name parameter for the insert or merge entity batch operation set in this + * {@link InsertOrMergeEntityOperation} instance. + * + * @return + * A {@link String} containing the name of the table that contains the entity to insert or merge. + */ public String getTable() { return table; } + /** + * Sets the table name parameter for the insert or merge entity batch operation. Note that this value must be + * the same for all operations in the batch. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to insert or merge. + * @return + * A reference to this {@link InsertOrMergeEntityOperation} instance. + */ public InsertOrMergeEntityOperation setTable(String table) { this.table = table; return this; } + /** + * Gets the entity parameter for the insert or merge entity batch operation set in this + * {@link InsertOrMergeEntityOperation} instance. + * + * @return + * The {@link Entity} instance containing the entity data to be inserted or merged. + */ public Entity getEntity() { return entity; } + /** + * Sets the entity parameter for the insert or merge entity batch operation. Note that the partition key value + * in the entity must be the same for all operations in the batch. + * + * @param entity + * The {@link Entity} instance containing the entity data to be inserted or merged. + * @return + * A reference to this {@link InsertOrMergeEntityOperation} instance. + */ public InsertOrMergeEntityOperation setEntity(Entity entity) { this.entity = entity; return this; } } + /** + * Represents the parameters needed for a delete entity operation. + */ public static class DeleteEntityOperation extends Operation { private String table; private String partitionKey; private String rowKey; private String etag; + /** + * Gets the table name parameter for the delete entity batch operation set in this {@link DeleteEntityOperation} + * instance. + * + * @return + * A {@link String} containing the name of the table that contains the entity to delete. + */ public String getTable() { return table; } + /** + * Sets the table name parameter for the delete entity batch operation. Note that this value must be the same + * for all operations in the batch. + * + * @param table + * A {@link String} containing the name of the table that contains the entity to delete. + * @return + * A reference to this {@link DeleteEntityOperation} instance. + */ public DeleteEntityOperation setTable(String table) { this.table = table; return this; } + /** + * Gets the partition key parameter for the delete entity batch operation set in this + * {@link DeleteEntityOperation} instance. + * + * @return + * A {@link String} containing the partition key value of the entity to delete. + */ public String getPartitionKey() { return partitionKey; } + /** + * Sets the partition key parameter for the delete entity batch operation. Note that this value must be the same + * for all operations in the batch. + * + * @param partitionKey + * A {@link String} containing the partition key value of the entity to delete. + * @return + * A reference to this {@link DeleteEntityOperation} instance. + */ public DeleteEntityOperation setPartitionKey(String partitionKey) { this.partitionKey = partitionKey; return this; } + /** + * Gets the row key parameter for the delete entity batch operation set in this {@link DeleteEntityOperation} + * instance. + * + * @return + * A {@link String} containing the row key value of the entity to delete. + */ public String getRowKey() { return rowKey; } + /** + * Sets the row key parameter for the delete entity batch operation. + * + * @param rowKey + * A {@link String} containing the row key value of the entity to delete. + * @return + * A reference to this {@link DeleteEntityOperation} instance. + */ public DeleteEntityOperation setRowKey(String rowKey) { this.rowKey = rowKey; return this; } + /** + * Gets the ETag parameter for the delete entity batch operation set in this {@link DeleteEntityOperation} + * instance. + * + * @return + * A {@link String} containing the ETag value of the entity to delete. + */ public String getEtag() { return etag; } + /** + * Sets the ETag parameter for the delete entity batch operation. + * + * @param etag + * A {@link String} containing the ETag value of the entity to delete. + * @return + * A reference to this {@link DeleteEntityOperation} instance. + */ public DeleteEntityOperation setEtag(String etag) { this.etag = etag; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchResult.java index 6ca4400068bb..47496057fb25 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BatchResult.java @@ -18,59 +18,148 @@ import java.util.List; import com.microsoft.windowsazure.services.core.ServiceException; +import com.microsoft.windowsazure.services.table.TableContract; +/** + * Represents the response to a request for a batch transaction returned from a Table Service REST API Entity Group + * Transaction operation. This is returned by calls to implementations of {@link TableContract#batch(BatchOperations)} + * and {@link TableContract#batch(BatchOperations, TableServiceOptions)}. + *

+ * See the Performing Entity Group + * Transactions documentation on MSDN for details of the underlying Table Service REST API operation. + */ public class BatchResult { private List entries = new ArrayList(); + /** + * Gets the collection of {@link Entry} results from each MIME change set response corresponding to each request in + * the batch transaction. + * + * @return + * A {@link java.util.List} of {@link Entry} instances corresponding to the responses to each request in + * the batch transaction. + */ public List getEntries() { return entries; } + /** + * Reserved for internal use. Sets the collection of {@link Entry} results from each MIME change set response + * corresponding to each request in the batch transaction. + * + * @param entries + * The {@link java.util.List} of {@link Entry} instances corresponding to the responses to each request + * in the batch transaction. + * @return + * A reference to this {@link BatchResult} instance. + */ public BatchResult setEntries(List entries) { this.entries = entries; return this; } + /** + * The abstract base class for entries in the batch transaction response. + */ public static abstract class Entry { } + /** + * Represents the result of an insert entity operation within a batch transaction. + */ public static class InsertEntity extends Entry { private Entity entity; + /** + * Gets the table entity inserted by the operation as returned in the server response. + * + * @return + * The {@link Entity} returned in the server response. + */ public Entity getEntity() { return entity; } + /** + * Reserved for internal use. Sets the table entity inserted by the operation from the matching + * entry element in the MIME change set response corresponding to the insert request in the + * batch transaction. + * + * @param entity + * The {@link Entity} returned in the server response. + * @return + * A reference to this {@link InsertEntity} instance. + */ public InsertEntity setEntity(Entity entity) { this.entity = entity; return this; } } + /** + * Represents the result of an update entity operation within a batch transaction. + */ public static class UpdateEntity extends Entry { private String etag; + /** + * Gets the updated ETag value for the entity updated by the operation as returned in the server response. + * + * @return + * A {@link String} containing the updated ETag value for the entity. + */ public String getEtag() { return etag; } + /** + * Reserved for internal use. Sets the ETag for the entity updated by the operation from the matching + * ETag header within the MIME change set response corresponding to the update request in the + * batch transaction. + * + * @param etag + * A {@link String} containing the updated ETag value for the entity. + * @return + * A reference to this {@link UpdateEntity} instance. + */ public UpdateEntity setEtag(String etag) { this.etag = etag; return this; } } + /** + * Represents the result of a delete entity operation within a batch transaction. + */ public static class DeleteEntity extends Entry { } + /** + * Represents an error result for an insert, update, or delete entity operation within a batch transaction. + */ public static class Error extends Entry { private ServiceException error; + /** + * Gets the {@link ServiceException} instance corresponding to the error returned in the server response. + * + * @return + * A {@link ServiceException} instance corresponding to the error returned in the server response. + */ public ServiceException getError() { return error; } + /** + * Reserved for internal use. Sets the {@link ServiceException} instance created in response to an error result + * within the MIME change set response corresponding to the request in the batch transaction. + * + * @param error + * A {@link ServiceException} instance corresponding to the error returned in the server response. + * @return + * A reference to this {@link Error} instance. + */ public Error setError(ServiceException error) { this.error = error; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BinaryFilter.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BinaryFilter.java index 7666da869e05..96a1a6a71b57 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BinaryFilter.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/BinaryFilter.java @@ -14,25 +14,62 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * Represents a table query filter expression consisting of a filter, a binary comparison operator, and a filter. Use + * the static factory methods in the {@link Filter} class to create BinaryFilter instances, rather + * than constructing them directly. + */ public class BinaryFilter extends Filter { private final String operator; private final Filter left; private final Filter right; + /** + * Creates a BinaryFilter expression from a {@link Filter}, a binary comparison operator, and a + * {@link Filter}. + *

+ * Use the static factory methods in the {@link Filter} class to create BinaryFilter instances, rather + * than constructing them directly. + * + * @param left + * The {@link Filter} to use on the left hand side of the expression. + * @param operator + * A {@link String} containing the comparison operator to use in the expression. + * @param right + * The {@link Filter} to use on the right hand side of the expression. + */ public BinaryFilter(Filter left, String operator, Filter right) { this.left = left; this.operator = operator; this.right = right; } + /** + * Gets the comparison operator to use in the BinaryFilter expression. + * + * @return + * A {@link String} containing the comparison operator to use in the expression. + */ public String getOperator() { return operator; } + /** + * Gets the {@link Filter} to use on the left hand side of the BinaryFilter expression. + * + * @return + * A {@link Filter} to use on the left hand side of the expression. + */ public Filter getLeft() { return left; } + /** + * Gets the {@link Filter} to use on the right hand side of the BinaryFilter expression. + * + * @return + * A {@link Filter} to use on the right hand side of the expression. + */ public Filter getRight() { return right; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ConstantFilter.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ConstantFilter.java index aa3dd041be7c..888901e84041 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ConstantFilter.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ConstantFilter.java @@ -14,13 +14,54 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * Represents a constant value used as a filter parameter in a table query request. + *

+ * Use the static factory method in the {@link Filter} class to create a {@link ConstantFilter}, rather than + * constructing one directly. + *

+ * Use this class to pass a constant value as a filter parameter. The value is passed as an Object but must + * be (or have an implicit conversion to) one of the following for successful serialization: + *

+ *

+ * A {@link PropertyNameFilter} may be combined in a {@link BinaryFilter} with a comparison operator and a + * {@link ConstantFilter} to limit query results to properties with values that match the {@link ConstantFilter} value. + * The table service does not support wildcard queries, but you can perform prefix matching by using comparison + * operators on the desired prefix created as a {@link String} in a {@link ConstantFilter} instance. + *

+ * See the Querying Tables and Entities + * topic in MSDN for more information on creating table query filter strings. + */ public class ConstantFilter extends Filter { private final Object value; + /** + * Creates a table query filter constant from the value parameter. + *

+ * Use the static factory method in the {@link Filter} class to create a {@link ConstantFilter}, rather than + * constructing one directly. + * + * @param value + * An {@link Object} containing the constant value to use as a filter parameter in a table query request. + */ public ConstantFilter(Object value) { this.value = value; } + /** + * Gets the constant filter value set in this {@link ConstantFilter} instance. + * + * @return + * The {@link Object} containing the constant value to use as a filter parameter in a table query request. + */ public Object getValue() { return value; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/DeleteEntityOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/DeleteEntityOptions.java index 4cce1e14a24a..2be63a3d9e6b 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/DeleteEntityOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/DeleteEntityOptions.java @@ -14,13 +14,36 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the options that may be set on a + * {@link TableContract#deleteEntity(String, String, String, DeleteEntityOptions)} request. An optional ETag value may + * be set to require that the deleted entity have the same ETag value to be deleted. Set a null ETag value + * to delete the entity unconditionally. + */ public class DeleteEntityOptions extends TableServiceOptions { private String etag; + /** + * Gets the ETag value to match in order to delete the entity set in this {@link DeleteEntityOptions} instance. + * + * @return + * A {@link String} containing the ETag value the entity must match to be deleted. + */ public String getEtag() { return etag; } + /** + * Sets the ETag value to match in order to delete the entity. Set the etag parameter to null + * to delete the entity unconditionally. + * + * @param etag + * A {@link String} containing the ETag value the entity must match to be deleted, or null. + * @return + * A reference to this {@link DeleteEntityOptions} instance. + */ public DeleteEntityOptions setEtag(String etag) { this.etag = etag; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/EdmType.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/EdmType.java index 0f0585f2e22a..a104fdc549e5 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/EdmType.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/EdmType.java @@ -14,13 +14,121 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * A class containing string constants used to represent the primitive types of the Entity Data Model (EDM) in the Open + * Data Protocol (OData). The EDM is the underlying abstract data model used by OData services. The subset defined in + * this class is used for data type definitions of the properties of a table entity in the Windows Azure Storage + * service. + *

+ * The following table shows the supported property data types in Windows Azure storage and the corresponding Java types + * when deserialized. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Storage TypeEdmType ValueJava TypeDescription
Edm.Binary{@link EdmType#BINARY}byte[], Byte[]An array of bytes up to 64 KB in size.
Edm.Boolean{@link EdmType#BOOLEAN}boolean, BooleanA Boolean value.
Edm.DateTime{@link EdmType#DATETIME}DateA 64-bit value expressed as Coordinated Universal Time (UTC). The supported range begins from 12:00 midnight, + * January 1, 1601 A.D. (C.E.), UTC. The range ends at December 31, 9999.
Edm.Double{@link EdmType#DOUBLE}double, DoubleA 64-bit double-precision floating point value.
Edm.Guid{@link EdmType#GUID}UUIDA 128-bit globally unique identifier.
Edm.Int32{@link EdmType#INT32}int, IntegerA 32-bit integer value.
Edm.Int64{@link EdmType#INT64}long, LongA 64-bit integer value.
Edm.String{@link EdmType#STRING}StringA UTF-16-encoded value. String values may be up to 64 KB in size.
+ *

+ * For more information about OData, see the Open Data Protocol website. + *

+ * For an overview of the available EDM primitive data types and names, see the Primitive Data Types section of the + * OData Protocol Overview. + *

+ * The Abstract Type System used to define the primitive types supported by OData is defined in detail in [MC-CSDL] (section 2.2.1). + */ public class EdmType { + /** + * Edm.DateTime Represents date and time with values ranging from 12:00:00 midnight, January 1, + * 1753 A.D. through 11:59:59 P.M, December 9999 A.D. + */ public static final String DATETIME = "Edm.DateTime"; + + /** + * Edm.Binary Represents fixed- or variable-length binary data. + */ public static final String BINARY = "Edm.Binary"; + + /** + * Edm.Boolean Represents the mathematical concept of binary-valued logic. + */ public static final String BOOLEAN = "Edm.Boolean"; + + /** + * Edm.Double Represents a floating point number with 15 digits precision that can represent values + * with approximate range of +/- 2.23e -308 through +/- 1.79e +308. + */ public static final String DOUBLE = "Edm.Double"; + + /** + * Edm.Guid Represents a 16-byte (128-bit) unique identifier value. + */ public static final String GUID = "Edm.Guid"; + + /** + * Edm.Int32 Represents a signed 32-bit integer value. + */ public static final String INT32 = "Edm.Int32"; + + /** + * Edm.Int64 Represents a signed 64-bit integer value. + */ public static final String INT64 = "Edm.Int64"; + + /** + * Edm.String Represents fixed- or variable-length character data. + */ public static final String STRING = "Edm.String"; } \ No newline at end of file diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Entity.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Entity.java index f74bda6d7003..8377a645fa8c 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Entity.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Entity.java @@ -18,72 +18,304 @@ import java.util.HashMap; import java.util.Map; +/** + * Represents an element of structured storage in a table. Tables store data as a collection of uniquely identifiable + * entities. Entities are similar to rows in a database. An entity has a primary key and a set of properties. A property + * is a name, typed-value pair, similar to a database column. + *

+ * The Table service does not enforce any schema for tables, so two entities in the same table may have different sets + * of properties. Developers may choose to enforce a schema on the client side. A table may contain any number of + * entities. + *

+ * An entity always has the following system properties: + *

+ * These system properties are automatically included for every entity in a table. The names of these properties are + * reserved and cannot be changed. The developer is responsible for inserting and updating the values of + * PartitionKey and RowKey. The server manages the value of + * Timestamp, which cannot be modified. + *

+ * An entity can have up to 255 properties, including the three system properties. Therefore, the user may include up to + * 252 custom properties, in addition to the three system properties. The combined size of all data in an entity's + * properties cannot exceed 1 MB. + *

+ * The following table shows the supported property data types in Windows Azure storage and the corresponding Java types + * when deserialized. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Storage TypeEdmType ValueJava TypeDescription
Edm.Binary{@link EdmType#BINARY}byte[], Byte[]An array of bytes up to 64 KB in size.
Edm.Boolean{@link EdmType#BOOLEAN}boolean, BooleanA Boolean value.
Edm.DateTime{@link EdmType#DATETIME}DateA 64-bit value expressed as Coordinated Universal Time (UTC). The supported range begins from 12:00 midnight, + * January 1, 1601 A.D. (C.E.), UTC. The range ends at December 31, 9999.
Edm.Double{@link EdmType#DOUBLE}double, DoubleA 64-bit double-precision floating point value.
Edm.Guid{@link EdmType#GUID}UUIDA 128-bit globally unique identifier.
Edm.Int32{@link EdmType#INT32}int, IntegerA 32-bit integer value.
Edm.Int64{@link EdmType#INT64}long, LongA 64-bit integer value.
Edm.String{@link EdmType#STRING}StringA UTF-16-encoded value. String values may be up to 64 KB in size.
+ *

+ * See the MSDN topic Understanding the + * Table Service Data Model for an overview of tables, entities, and properties as used in the Windows Azure Storage + * service. + *

+ * For an overview of the available EDM primitive data types and names, see the Primitive Data Types section of the + * OData Protocol Overview. + *

+ */ public class Entity { private String etag; private Map properties = new HashMap(); + /** + * Gets the ETag value for the entity. This value is used to determine if the table entity has changed since it was + * last read from Windows Azure storage. When modifying an entity, the ETag value may be set to force the operation + * to fail if the ETag does not match the ETag on the server. + * + * @return + * A String containing the ETag for the entity. + */ public String getEtag() { return etag; } + /** + * Sets the ETag value for the entity. This value is used to determine if the table entity has changed since it was + * last read from Windows Azure storage. When modifying an entity, the ETag value may be set to force the operation + * to fail if the ETag does not match the ETag on the server. Set the etagparameter to null to + * force an unconditional operation. + * + * @param etag + * A String containing the ETag for the entity. + */ public Entity setEtag(String etag) { this.etag = etag; return this; } + /** + * Gets the PartitionKey value for the entity. + * + * @return + * A String containing the PartitionKey value for the entity. + */ public String getPartitionKey() { Property p = getProperty("PartitionKey"); return p == null ? null : (String) p.getValue(); } + /** + * Sets the PartitionKey value for the entity. + *

+ * Tables are partitioned to support load balancing across storage nodes. A table's entities are organized by + * partition. A partition is a consecutive range of entities possessing the same partition key value. The partition + * key is a unique identifier for the partition within a given table, specified by the PartitionKey + * property. The partition key forms the first part of an entity's primary key. The partition key may be a string + * value up to 1 KB in size. + *

+ * You must include the PartitionKey property in every insert, update, and delete operation. + * + * @param partitionKey + * A String containing the PartitionKey value for the entity. + * @return + * A reference to this {@link Entity} instance. + */ public Entity setPartitionKey(String partitionKey) { setProperty("PartitionKey", null, partitionKey); return this; } + /** + * Gets the RowKey value for the entity. + * + * @return + * A String containing the RowKey value for the entity. + */ public String getRowKey() { Property p = getProperty("RowKey"); return p == null ? null : (String) p.getValue(); } + /** + * Sets the RowKey value for the entity. + *

+ * The second part of the primary key is the row key, specified by the RowKey property. The row key + * is a unique identifier for an entity within a given partition. Together the PartitionKey and + * RowKey uniquely identify every entity within a table. + *

+ * The row key is a string value that may be up to 1 KB in size. + *

+ * You must include the RowKey property in every insert, update, and delete operation. + * + * @param rowKey + * A String containing the RowKey value for the entity. + * @return + * A reference to this {@link Entity} instance. + */ public Entity setRowKey(String rowKey) { setProperty("RowKey", null, rowKey); return this; } + /** + * Gets the Timestamp value for the entity. + * + * @return + * A {@link Date} containing the Timestamp value for the entity. + */ public Date getTimestamp() { Property p = getProperty("Timestamp"); return p == null ? null : (Date) p.getValue(); } + /** + * Sets the Timestamp value for the entity. + *

+ * The Timestamp property is a value that is maintained on the server side to record the time an + * entity was last modified. The Table service uses the Timestamp property internally to provide + * optimistic concurrency. You should treat this property as opaque: It should not be read, nor set on insert or + * update operations (the value will be ignored). + * + * @param timestamp + * A {@link Date} containing the Timestamp value for the entity. + * @return + * A reference to this {@link Entity} instance. + */ public Entity setTimestamp(Date timestamp) { setProperty("Timestamp", null, timestamp); return this; } + /** + * Gets the properties collection of name and typed-data pairs in the entity. + * + * @return + * The {@link java.util.HashMap} collection of String property names to {@link Property} + * typed-data value pairs in the entity. + */ public Map getProperties() { return properties; } + /** + * Sets the properties collection of name and typed-data pairs in the entity. + * + * @param properties + * The {@link java.util.HashMap} collection of String property names to {@link Property} + * typed-data value pairs to set in the entity. + * @return + * A reference to this {@link Entity} instance. + */ public Entity setProperties(Map properties) { this.properties = properties; return this; } + /** + * Gets the named property value from the properties collection in the entity. + * + * @param name + * A {@link String} containing the name of the entity property to return. + * @return + * The {@link Property} instance associated with the name parameter value in the entity, + * or null if the name is not in the properties collection. + */ public Property getProperty(String name) { return properties.get(name); } + /** + * Sets the property associated with the specified name in the properties collection in the entity. + * + * @param name + * The {@link String} containing the name to associate with the property value. + * @param property + * The {@link Property} instance to associate with the name parameter value in the entity + * @return + * A reference to this {@link Entity} instance. + */ public Entity setProperty(String name, Property property) { this.properties.put(name, property); return this; } + /** + * Sets the property data type and value associated with the specified name in the properties collection in the + * entity. + * + * @param name + * The {@link String} containing the name to associate with the property value. + * @param edmType + * A {@link String} containing the EDM data type to associate with the property value. This must be one + * of the supported EDM types, defined as string constants in the {@link EdmType} class. + * @param value + * An {@link Object} containing the data value of the property, serializable as the associated EDM data + * type of the property. + * @return + * A reference to this {@link Entity} instance. + */ public Entity setProperty(String name, String edmType, Object value) { setProperty(name, new Property().setEdmType(edmType).setValue(value)); return this; } + /** + * Gets the named property value from the properties collection in the entity cast an an {@link Object}. + * + * @param name + * A {@link String} containing the name of the entity property to return. + * @return + * The value associated with the name parameter in the properties collection in the entity, + * cast as an {@link Object}, or null if the name is not in the properties collection. + */ public Object getPropertyValue(String name) { Property p = getProperty(name); return p == null ? null : p.getValue(); diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Filter.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Filter.java index 1e410d2adfb4..612c8c40d027 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Filter.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Filter.java @@ -14,51 +14,230 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents a table query filter expression, which can be used as an option in a + * {@link TableContract#queryEntities(String, QueryEntitiesOptions)} request. + *

+ * A filter expression is built of operands consisting of property names, constant values, pre-computed query strings, + * or other filter expressions. Filter expressions may be combined with unary and binary operators to create complex + * expressions. + *

+ * See the Querying Tables and Entities + * topic in MSDN for more information on creating table query filters. + */ public class Filter { + /** + * A static factory method that creates a boolean filter expression that is the logical 'not' of the + * operand parameter. + * + * @param operand + * A {@link Filter} instance containing a boolean filter expression. + * @return + * A {@link UnaryFilter} instance containing a filter expression that is the logical 'not' of the + * operand parameter. + */ public static UnaryFilter not(Filter operand) { return new UnaryFilter("not", operand); } + /** + * A static factory method that creates a boolean filter expression that is the logical 'and' of the left + * and right parameters. + * + * @param left + * A {@link Filter} instance containing a boolean filter expression. + * @param right + * A {@link Filter} instance containing a boolean filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression that is the logical 'and' of the + * left and right parameters. + */ public static BinaryFilter and(Filter left, Filter right) { return new BinaryFilter(left, "and", right); } + /** + * A static factory method that creates a boolean filter expression that is the logical 'or' of the left + * and right parameters. + * + * @param left + * A {@link Filter} instance containing a boolean filter expression. + * @param right + * A {@link Filter} instance containing a boolean filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression that is the logical 'or' of the + * left and right parameters. + */ public static BinaryFilter or(Filter left, Filter right) { return new BinaryFilter(left, "or", right); } + /** + * A static factory method that creates a boolean filter expression that expresses whether the left and + * right parameters are equal. + *

+ * Use this method to create a filter that compares the content of a property with a constant value. + *

+ * The value must be of the same type as the property for the comparison operation to return valid results. Note + * that it is not possible to compare a property to a dynamic value; one side of the expression must be a constant. + * + * @param left + * A {@link Filter} instance containing a filter expression. + * @param right + * A {@link Filter} instance containing a filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression expresses whether the left and + * right parameters are equal. + */ public static BinaryFilter eq(Filter left, Filter right) { return new BinaryFilter(left, "eq", right); } + /** + * A static factory method that creates a boolean filter expression that expresses whether the left and + * right parameters are not equal. + *

+ * Use this method to create a filter that compares the content of a property with a constant value. + *

+ * The value must be of the same type as the property for the comparison operation to return valid results. Note + * that it is not possible to compare a property to a dynamic value; one side of the expression must be a constant. + * + * @param left + * A {@link Filter} instance containing a filter expression. + * @param right + * A {@link Filter} instance containing a filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression expresses whether the left and + * right parameters are not equal. + */ public static BinaryFilter ne(Filter left, Filter right) { return new BinaryFilter(left, "ne", right); } + /** + * A static factory method that creates a boolean filter expression that expresses whether the value of the + * left parameter is greater than or equal to the value of the right parameter. + *

+ * Use this method to create a filter that compares the content of a property with a constant value. + *

+ * The value must be of the same type as the property for the comparison operation to return valid results. Note + * that it is not possible to compare a property to a dynamic value; one side of the expression must be a constant. + * + * @param left + * A {@link Filter} instance containing a filter expression. + * @param right + * A {@link Filter} instance containing a filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression expresses whether the value of the + * left parameter is greater than or equal to the value of the right parameter. + */ public static BinaryFilter ge(Filter left, Filter right) { return new BinaryFilter(left, "ge", right); } + /** + * A static factory method that creates a boolean filter expression that expresses whether the value of the + * left parameter is greater than the value of the right parameter. + *

+ * Use this method to create a filter that compares the content of a property with a constant value. + *

+ * The value must be of the same type as the property for the comparison operation to return valid results. Note + * that it is not possible to compare a property to a dynamic value; one side of the expression must be a constant. + * + * @param left + * A {@link Filter} instance containing a filter expression. + * @param right + * A {@link Filter} instance containing a filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression expresses whether the value of the + * left parameter is greater than the value of the right parameter. + */ public static BinaryFilter gt(Filter left, Filter right) { return new BinaryFilter(left, "gt", right); } + /** + * A static factory method that creates a boolean filter expression that expresses whether the value of the + * left parameter is less than the value of the right parameter. + *

+ * Use this method to create a filter that compares the content of a property with a constant value. + *

+ * The value must be of the same type as the property for the comparison operation to return valid results. Note + * that it is not possible to compare a property to a dynamic value; one side of the expression must be a constant. + * + * @param left + * A {@link Filter} instance containing a filter expression. + * @param right + * A {@link Filter} instance containing a filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression expresses whether the value of the + * left parameter is less than the value of the right parameter. + */ public static BinaryFilter lt(Filter left, Filter right) { return new BinaryFilter(left, "lt", right); } + /** + * A static factory method that creates a boolean filter expression that expresses whether the value of the + * left parameter is less than or equal to the value of the right parameter. + *

+ * Use this method to create a filter that compares the content of a property with a constant value. + *

+ * The value must be of the same type as the property for the comparison operation to return valid results. Note + * that it is not possible to compare a property to a dynamic value; one side of the expression must be a constant. + * + * @param left + * A {@link Filter} instance containing a filter expression. + * @param right + * A {@link Filter} instance containing a filter expression. + * @return + * A {@link BinaryFilter} instance containing a filter expression expresses whether the value of the + * left parameter is less than or equal to the value of the right parameter. + */ public static BinaryFilter le(Filter left, Filter right) { return new BinaryFilter(left, "le", right); } + /** + * A static factory method that creates a constant value to use as an operand in a {@link BinaryFilter} expression. + * Case is significant in comparison expressions with constants of type {@link String}. + * + * @param value + * An Object reference to a constant value of a supported type, or null. + * @return + * A {@link ConstantFilter} instance containing the constant value for use in a filter expression. + */ public static ConstantFilter constant(Object value) { return new ConstantFilter(value); } + /** + * A static factory method that creates a property name value to use as an operand in a {@link BinaryFilter} + * expression. When the filter is evaluated, the content of the named property in the entity is used as the operand. + *

+ * Note that case is significant for the PartitionKey and RowKey property names. + * + * @param value + * A {@link String} containing the name of a property. + * @return + * A {@link ConstantFilter} instance containing the constant value for use in a filter expression. + */ public static PropertyNameFilter propertyName(String value) { return new PropertyNameFilter(value); } + /** + * A static factory method that creates a table query filter string from the contents of the value + * parameter. + * + * @param value + * A {@link String} containing a table query filter string. + * + * @return + * A {@link QueryStringFilter} instance containing the table query filter string. + */ public static QueryStringFilter queryString(String value) { return new QueryStringFilter(value); } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetEntityResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetEntityResult.java index 336c436da06c..982a8d55b028 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetEntityResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetEntityResult.java @@ -14,13 +14,40 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the response to a request for a single table entity in the storage account returned + * from a Table Service REST API Query Entities operation. This is returned by calls to implementations of + * {@link TableContract#getEntity(String, String, String)} and + * {@link TableContract#getEntity(String, String, String, TableServiceOptions)}. + *

+ * See the Query Entities documentation + * on MSDN for details of the underlying Table Service REST API operation. + */ public class GetEntityResult { private Entity entity; + /** + * Gets the entity returned in the server response to the request. + * + * @return + * The {@link Entity} instance representing the entity returned in the server response to the request. + */ public Entity getEntity() { return entity; } + /** + * Reserved for internal use. Sets the entity value from the properties of the entry entity + * returned in the body of the server response. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param entity + * An {@link Entity} instance representing the entity returned in the server response to the request. + */ public void setEntity(Entity entity) { this.entity = entity; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetServicePropertiesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetServicePropertiesResult.java index e56a2c8f9368..7f4780fd3c15 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetServicePropertiesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetServicePropertiesResult.java @@ -14,13 +14,45 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * A wrapper class for the service properties returned in response to Table Service REST API operations. This is + * returned by calls to implementations of {@link TableContract#getServiceProperties()} and + * {@link TableContract#getServiceProperties(TableServiceOptions)}. + *

+ * See the Get Table Service Properties + * documentation on MSDN for details of the underlying Table 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 TableContract#setServiceProperties(ServiceProperties)} or + * {@link TableContract#setServiceProperties(ServiceProperties, TableServiceOptions)} 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/table/models/GetTableResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetTableResult.java index 0e23a0d752c2..a5f3e843966b 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetTableResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/GetTableResult.java @@ -14,13 +14,39 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the response to a request for a single table entry in the list of tables in the storage account returned + * from a Table Service REST API Query Tables operation. This is returned by calls to implementations of + * {@link TableContract#getTable(String)} and {@link TableContract#getTable(String, TableServiceOptions)}. + *

+ * See the Query Tables documentation + * on MSDN for details of the underlying Table Service REST API operation. + */ public class GetTableResult { private TableEntry tableEntry; + /** + * Gets the table entry returned in the server response. + * + * @return + * A {@link TableEntry} instance representing the table entry returned in the server response. + */ public TableEntry getTableEntry() { return tableEntry; } + /** + * Reserved for internal use. Sets the table entry value from the TableName entity in the + * properties of the entry entity returned in the body of the server response. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param tableEntry + * A {@link TableEntry} instance representing the table entry returned in the server response. + */ public void setTableEntry(TableEntry tableEntry) { this.tableEntry = tableEntry; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/InsertEntityResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/InsertEntityResult.java index eca020395496..1c786f9b4b08 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/InsertEntityResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/InsertEntityResult.java @@ -14,13 +14,40 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the response to a request to insert a single table entity in the storage account returned + * from a Table Service REST API Insert Entity operation. This is returned by calls to implementations of + * {@link TableContract#insertEntity(String, Entity)} and + * {@link TableContract#insertEntity(String, Entity, TableServiceOptions)}. + *

+ * See the Insert Entity documentation + * on MSDN for details of the underlying Table Service REST API operation. + */ public class InsertEntityResult { private Entity entity; + /** + * Gets the entity returned in the server response to the request. + * + * @return + * The {@link Entity} instance representing the entity returned in the server response to the request. + */ public Entity getEntity() { return entity; } + /** + * Reserved for internal use. Sets the entity value from the properties of the entry entity + * returned in the body of the server response. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param entity + * An {@link Entity} instance representing the entity returned in the server response to the request. + */ public void setEntity(Entity entity) { this.entity = entity; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Property.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Property.java index 197584f920e6..19b7492ec5c9 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Property.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/Property.java @@ -14,23 +14,126 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * Represents a table entity property value as a data-type and value pair. + *

+ * The following table shows the supported property data types in Windows Azure storage and the corresponding Java types + * when deserialized. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Storage TypeEdmType ValueJava TypeDescription
Edm.Binary{@link EdmType#BINARY}byte[], Byte[]An array of bytes up to 64 KB in size.
Edm.Boolean{@link EdmType#BOOLEAN}boolean, BooleanA Boolean value.
Edm.DateTime{@link EdmType#DATETIME}DateA 64-bit value expressed as Coordinated Universal Time (UTC). The supported range begins from 12:00 midnight, + * January 1, 1601 A.D. (C.E.), UTC. The range ends at December 31, 9999.
Edm.Double{@link EdmType#DOUBLE}double, DoubleA 64-bit double-precision floating point value.
Edm.Guid{@link EdmType#GUID}UUIDA 128-bit globally unique identifier.
Edm.Int32{@link EdmType#INT32}int, IntegerA 32-bit integer value.
Edm.Int64{@link EdmType#INT64}long, LongA 64-bit integer value.
Edm.String{@link EdmType#STRING}StringA UTF-16-encoded value. String values may be up to 64 KB in size.
+ *

+ * See the MSDN topic Understanding the + * Table Service Data Model for an overview of tables, entities, and properties as used in the Windows Azure Storage + * service. + *

+ * For an overview of the available EDM primitive data types and names, see the Primitive Data Types section of the + * OData Protocol Overview. + */ public class Property { private String edmType; private Object value; + /** + * Gets the EDM data type of the property. + * + * @return + * A String containing the EDM data type of the property. + */ public String getEdmType() { return edmType; } + /** + * Sets the EDM data type of the property. The edmType parameter must be set to one of the string constants + * defined in the {@link EdmType} class. + * + * @param edmType + * A {@link String} containing the EDM data type to associate with the property value. This must be one + * of the supported EDM types, defined as string constants in the {@link EdmType} class. + * @return + * A reference to this {@link Property} instance. + */ public Property setEdmType(String edmType) { this.edmType = edmType; return this; } + /** + * Gets the data value of the property. + * + * @return + * An {@link Object} containing the data value of the property. + */ public Object getValue() { return value; } + /** + * Sets the data value of the property. The value parameter must contain an {@link Object} serializable as + * the associated EDM data type of the property. + * + * @param value + * An {@link Object} containing the data value of the property, serializable as the associated EDM data + * type of the property. + * @return + * A reference to this {@link Property} instance. + */ public Property setValue(Object value) { this.value = value; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/PropertyNameFilter.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/PropertyNameFilter.java index 49cb129d86e0..9594b838e74e 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/PropertyNameFilter.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/PropertyNameFilter.java @@ -14,13 +14,48 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * Represents a property name used as a filter parameter in a table query request. + *

+ * Use the static factory method in the {@link Filter} class to create a {@link PropertyNameFilter}, rather than + * constructing one directly. + *

+ * Use this class to pass a property name as a filter parameter. When the filter is evaluated, the content of the named + * property in the entity is used in the filter expression. + *

+ * Note that case is significant for the PartitionKey and RowKey property names in a + * filter. + *

+ * A {@link PropertyNameFilter} may be combined in a {@link BinaryFilter} with a comparison operator and a + * {@link ConstantFilter} to limit query results to properties with values that match the {@link ConstantFilter} value. + * The table service does not support wildcard queries, but you can perform prefix matching by using comparison + * operators on the desired prefix created as a {@link String} in a {@link ConstantFilter} instance. + *

+ * See the Querying Tables and Entities + * topic in MSDN for more information on creating table query filter strings. + */ public class PropertyNameFilter extends Filter { private final String propertyName; + /** + * Creates a property name table query filter from the propertyName parameter. + *

+ * Use the static factory method in the {@link Filter} class to create a {@link PropertyNameFilter}, rather than + * constructing one directly. + * + * @param propertyName + * A {@link String} containing the property name to use as a filter parameter in a table query request. + */ public PropertyNameFilter(String propertyName) { this.propertyName = propertyName; } + /** + * Gets the property name set in this {@link PropertyNameFilter} instance. + * + * @return + * The {@link String} containing the property name to use as a filter parameter in a table query request. + */ public String getPropertyName() { return propertyName; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesOptions.java index e5d7a7c51151..fcc04a34d510 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesOptions.java @@ -17,6 +17,15 @@ import java.util.ArrayList; import java.util.List; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the options that may be set on a {@link TableContract#queryEntities(String, QueryEntitiesOptions) + * queryEntities} request. These options include the next partition key and next row key continuation tokens to use to + * resume the query entities request from, a collection of the property names to include in the entities returned in the + * server response, a filter to limit results to entities with certain property values, and a top count to limit the + * response to that number of the first matching results. + */ public class QueryEntitiesOptions extends TableServiceOptions { private List selectFields = new ArrayList(); @@ -28,74 +37,235 @@ public class QueryEntitiesOptions extends TableServiceOptions { public String nextPartitionKey; public String nextRowKey; + /** + * Gets the next partition key continuation token set in this {@link QueryEntitiesOptions} instance. + * + * @return + * A {@link String} containing the next partition key continuation token to use to resume a query entities + * request with. + */ public String getNextPartitionKey() { return nextPartitionKey; } + /** + * Sets the next partition key continuation token to resume a query entities request with. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * Use the {@link QueryEntitiesResult#getNextPartitionKey()} and {@link QueryEntitiesResult#getNextRowKey()} methods + * on the result of a query entities request to determine if there are more results to retrieve. If so, set the + * values returned on a {@link QueryEntitiesOptions} instance with the {@link #setNextPartitionKey(String)} and + * {@link #setNextRowKey(String)} methods, and resume the query with another call to + * {@link TableContract#queryEntities(String, QueryEntitiesOptions)} to get the next set of results. + *

+ * It is possible for a query to return no results but to still return a continuation token. + *

+ * This value only affects calls made on methods where this {@link QueryEntitiesOptions} instance is passed as a + * parameter. + * + * @param nextPartitionKey + * A {@link String} containing the next partition key continuation token to use to resume a query + * entities request with. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions setNextPartitionKey(String nextPartitionKey) { this.nextPartitionKey = nextPartitionKey; return this; } + /** + * Gets the next row key continuation token set in this {@link QueryEntitiesOptions} instance. + * + * @return + * A {@link String} containing the next row key continuation token to use to resume a query entities request + * with. + */ public String getNextRowKey() { return nextRowKey; } + /** + * Sets the next row key continuation token to resume a query entities request with. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * Use the {@link QueryEntitiesResult#getNextPartitionKey()} and {@link QueryEntitiesResult#getNextRowKey()} methods + * on the result of a query entities request to determine if there are more results to retrieve. If so, set the + * values returned on a {@link QueryEntitiesOptions} instance with the {@link #setNextPartitionKey(String)} and + * {@link #setNextRowKey(String)} methods, and resume the query with another call to + * {@link TableContract#queryEntities(String, QueryEntitiesOptions)} to get the next set of results. + *

+ * It is possible for a query to return no results but to still return a continuation token. + *

+ * This value only affects calls made on methods where this {@link QueryEntitiesOptions} instance is passed as a + * parameter. + * + * @param nextRowKey + * A {@link String} containing the next row key continuation token to use to resume a query + * entities request with. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions setNextRowKey(String nextRowKey) { this.nextRowKey = nextRowKey; return this; } + /** + * Gets the collection of properties to include in the entities returned in the server response set in this + * {@link QueryEntitiesOptions} instance. + * + * @return + * The {@link java.util.List} of {@link String} property names to include in the entities returned in the + * server response. + */ public List getSelectFields() { return selectFields; } + /** + * Sets the collection of properties to include in the entities returned in the server response. + * + * @param selectFields + * A {@link java.util.List} of {@link String} property names to include in the entities returned in the + * server response. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions setSelectFields(List selectFields) { this.selectFields = selectFields; return this; } + /** + * Adds a property name to the collection of properties to include in the entities returned in the server response. + * + * @param selectField + * A {@link String} property name to include in the entities returned in the server response. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions addSelectField(String selectField) { this.selectFields.add(selectField); return this; } + /** + * Reserved for future use. Gets the from option value set in this {@link QueryEntitiesOptions} instance. + * + * @return + * A {@link String} containing the from option value set. + */ public String getFrom() { return from; } + /** + * Reserved for future use. Sets the from option value. + * + * @param from + * A {@link String} containing the from option value to set. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions setFrom(String from) { this.from = from; return this; } + /** + * Gets the table query filter set in this {@link QueryEntitiesOptions} instance. + * + * @return + * A {@link Filter} containing the table query filter to apply on the server to limit the entities returned + * in the response. + */ public Filter getFilter() { return filter; } + /** + * Sets the table query filter to apply on the server to limit the entities returned in the response. + * + * @param filter + * A {@link Filter} containing the table query filter to apply on the server to limit the entities + * returned in the response. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions setFilter(Filter filter) { this.filter = filter; return this; } + /** + * Reserved for future use. Gets the list of property names to use to order the results in the server response set + * in this {@link QueryEntitiesOptions} instance. + * + * @return + * The {@link java.util.List} of {@link String} property names to use to order the results in the server + * response. + */ public List getOrderByFields() { return orderByFields; } + /** + * Reserved for future use. Sets the list of property names to use to order the results in the server response. + * + * @param orderByFields + * A {@link java.util.List} of {@link String} property names to use to order the results in the server + * response. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions setOrderByFields(List orderByFields) { this.orderByFields = orderByFields; return this; } + /** + * Reserved for future use. Adds a property name to the list of property names to use to order the results in the + * server response. + * + * @param orderByField + * A {@link String} containing a property name to add to the list to use to order the results in the + * server response. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions addOrderByField(String orderByField) { this.orderByFields.add(orderByField); return this; } + /** + * Gets the number of entities to return in the server response set in this {@link QueryEntitiesOptions} instance. + * + * @return + * The number of entities to return in the server response. + */ public Integer getTop() { return top; } + /** + * Sets the number of entities to return in the server response. The first results in order by partition key and row + * key will be returned. + * + * @param top + * The number of entities to return in the server response. + * @return + * A reference to this {@link QueryEntitiesOptions} instance. + */ public QueryEntitiesOptions setTop(Integer top) { this.top = top; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesResult.java index 9756661eef96..6d050f96843d 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryEntitiesResult.java @@ -17,31 +17,131 @@ import java.util.ArrayList; import java.util.List; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the response to a request for a list of entities in the storage account returned from a Table Service REST + * API Query Tables operation. This is returned by calls to implementations of + * {@link TableContract#queryEntities(String)} and {@link TableContract#queryEntities(String, QueryEntitiesOptions)}. + *

+ * See the Query Entities documentation + * on MSDN for details of the underlying Table Service REST API operation. + */ public class QueryEntitiesResult { private String nextPartitionKey; private String nextRowKey; private List entities = new ArrayList(); + /** + * Gets the list of entities returned in the server response to the query entities request. + * + * @return + * A {@link java.util.List} of {@link Entity} instances representing the entities returned in the server + * response. + */ public List getEntities() { return entities; } + /** + * Reserved for internal use. Sets the list of entities returned in the server response to the query entities + * request. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param entities + * A {@link java.util.List} of {@link Entity} instances representing the entities returned in the server + * response. + */ public void setEntities(List entities) { this.entities = entities; } + /** + * Gets the next partition key continuation token to resume the query entities request with, if any is returned. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * Use the {@link QueryEntitiesResult#getNextPartitionKey()} and {@link QueryEntitiesResult#getNextRowKey()} methods + * on the result of a query entities request to determine if there are more results to retrieve. If so, set the + * values returned on a {@link QueryEntitiesOptions} instance with the {@link #setNextPartitionKey(String)} and + * {@link #setNextRowKey(String)} methods, and resume the query with another call to + * {@link TableContract#queryEntities(String, QueryEntitiesOptions)} to get the next set of results. + *

+ * It is possible for a query to return no results but to still return a continuation token. + * + * @return + * A {@link String} containing the next partition key continuation token to use to resume the query entities + * request with, or null if no token was returned. + */ public String getNextPartitionKey() { return nextPartitionKey; } + /** + * Reserved for internal use. Sets the next partition key continuation token to resume a query entities request with + * from the x-ms-continuation-NextPartitionKey header returned in the response from the server. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param nextPartitionKey + * A {@link String} containing the next partition key continuation token to use to resume a query + * entities request with. + */ public void setNextPartitionKey(String nextPartitionKey) { this.nextPartitionKey = nextPartitionKey; } + /** + * Gets the next row key continuation token to resume the query tables request with, if any is returned. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * Use the {@link QueryEntitiesResult#getNextPartitionKey()} and {@link QueryEntitiesResult#getNextRowKey()} methods + * on the result of a query entities request to determine if there are more results to retrieve. If so, set the + * values returned on a {@link QueryEntitiesOptions} instance with the {@link #setNextPartitionKey(String)} and + * {@link #setNextRowKey(String)} methods, and resume the query with another call to + * {@link TableContract#queryEntities(String, QueryEntitiesOptions)} to get the next set of results. + *

+ * It is possible for a query to return no results but to still return a continuation token. + * + * @return + * A {@link String} containing the next row key continuation token to use to resume the query tables + * request with, or null if no token was returned. + */ public String getNextRowKey() { return nextRowKey; } + /** + * Reserved for internal use. Sets the next row key continuation token to resume a query entities request with from + * the x-ms-continuation-NextRowKey header returned in the response from the server. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param nextRowKey + * A {@link String} containing the next row key continuation token to use to resume a query entities + * request with. + */ public void setNextRowKey(String nextRowKey) { this.nextRowKey = nextRowKey; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryStringFilter.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryStringFilter.java index 77341e2477c5..84db88c276ae 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryStringFilter.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryStringFilter.java @@ -14,13 +14,55 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * Represents a table query filter string passed directly as a filter parameter in a table query request. + *

+ * Use the static factory method in the {@link Filter} class to create a {@link QueryStringFilter}, rather than + * constructing one directly. + *

+ * Use this class to pass a literal query filter string without interpretation as a filter parameter. For example, if + * you have a created a query filter expression independently, this class may be used to add it to a filter expression. + *

+ * The following characters must be URL-encoded if they are to be used in a query string: + *

+ *

+ * See the Querying Tables and Entities + * topic in MSDN for more information on creating table query filter strings. + */ public class QueryStringFilter extends Filter { private final String queryString; + /** + * Creates a table query filter from the queryString parameter. + *

+ * Use the static factory method in the {@link Filter} class to create a {@link QueryStringFilter}, rather than + * constructing one directly. + * + * @param queryString + * A {@link String} containing a table query filter to pass directly as a filter parameter in a table + * query request. + */ public QueryStringFilter(String queryString) { this.queryString = queryString; } + /** + * Gets the table query filter string set in this {@link QueryStringFilter} instance. + * + * @return + * A {@link String} containing a table query filter to pass directly as a filter parameter in a table + * query request. + */ public String getQueryString() { return queryString; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesOptions.java index d72c580a402f..e7c89aeb759e 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesOptions.java @@ -14,33 +14,106 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the options that may be set on a {@link TableContract#queryTables(QueryTablesOptions) queryTables} + * request. These options include a filter to limit results to tables with certain properties, the next table name + * continuation token to use to resume the query tables request from, and a prefix string to match table names with. + */ public class QueryTablesOptions extends TableServiceOptions { private Filter filter; private String nextTableName; private String prefix; + /** + * Gets the filter to use to limit table entries returned set in this {@link TableServiceOptions} instance. + * + * @return + * A {@link Filter} instance containing the filter options to use. + */ public Filter getFilter() { return filter; } + /** + * Sets the filter to use to limit table entries returned by the request to those that match the filter properties. + *

+ * This value only affects calls made on methods where this {@link QueryTablesOptions} instance is passed as a + * parameter. + * + * @param filter + * A {@link Filter} instance containing the filter options to use. + * @return + * A reference to this {@link QueryTablesOptions} instance. + */ public QueryTablesOptions setFilter(Filter filter) { this.filter = filter; return this; } + /** + * Gets the next table name continuation token set in this {@link TableServiceOptions} instance. + * + * @return + * A {@link String} containing the next table name continuation token to use to resume a query tables + * request with. + */ public String getNextTableName() { return nextTableName; } + /** + * Sets the next table name continuation token to resume a query tables request with. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * Use the {@link QueryTablesResult#getNextTableName()} method on the result of a query tables request to determine + * if there are more results to retrieve. If so, pass the value returned as the nextTableName parameter to + * this method to set the next table name continuation token option, and resume the query with another call to + * {@link TableContract#queryTables(QueryTablesOptions)} to get the next set of results. + *

+ * It is possible for a query to return no results but to still return a continuation token. + *

+ * This value only affects calls made on methods where this {@link QueryTablesOptions} instance is passed as a + * parameter. + * + * @param nextTableName + * A {@link String} containing the next table name continuation token to use to resume a query tables + * request with. + * @return + * A reference to this {@link QueryTablesOptions} instance. + */ public QueryTablesOptions setNextTableName(String nextTableName) { this.nextTableName = nextTableName; return this; } + /** + * Gets the prefix filter associated with this {@link QueryTablesOptions} instance. This value is used to return + * only tables from the storage account with names that begin with the prefix in the response to a query tables + * request. + * + * @return + * A {@link String} containing the prefix used to filter the table names returned, if any. + */ public String getPrefix() { return prefix; } + /** + * Sets the optional table name prefix filter value to use in a request. If this value is set, the server will + * return only table entries with names that match the prefix value in the response. + *

+ * The prefix value only affects calls made on methods where this {@link QueryTablesOptions} instance is + * passed as a parameter. + * + * @param prefix + * A {@link String} containing a prefix to use to filter the table names returned. + */ public QueryTablesOptions setPrefix(String prefix) { this.prefix = prefix; return this; diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesResult.java index 9c6158382dba..3cfa1768ea81 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/QueryTablesResult.java @@ -16,22 +16,83 @@ import java.util.List; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the response to a request for a list of tables in the storage account returned + * from a Table Service REST API Query Tables operation. This is returned by calls to implementations of + * {@link TableContract#queryTables()} and {@link TableContract#queryTables(QueryTablesOptions)}. + *

+ * See the Query Tables documentation + * on MSDN for details of the underlying Table Service REST API operation. + */ public class QueryTablesResult { private String nextTableName; private List tables; + /** + * Gets the next table name continuation token to resume the query tables request with, if any is returned. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * Use the {@link QueryTablesResult#getNextTableName()} method on the result of a query tables request to determine + * if there are more results to retrieve. If so, pass the value returned as the nextTableName parameter to + * this method to set the next table name continuation token option, and resume the query with another call to + * {@link TableContract#queryTables(QueryTablesOptions)} to get the next set of results. + *

+ * It is possible for a query to return no results but to still return a continuation token. + * + * @return + * A {@link String} containing the next table name continuation token to use to resume the query tables + * request with, or null if no token was returned. + */ public String getNextTableName() { return nextTableName; } + /** + * Reserved for internal use. Sets the next table name continuation token to resume a query tables request with from + * the x-ms-continuation-NextTableName header returned in the response from the server. + *

+ * A query against the Table service may return a maximum of 1,000 items at one time and may execute for a maximum + * of five seconds. If the result set contains more than 1,000 items, if the query did not complete within five + * seconds, or if the query crosses the partition boundary, the response includes values which provide the client + * with continuation tokens to use in order to resume the query at the next item in the result set. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param nextTableName + * A {@link String} containing the next table name continuation token to use to resume a query tables + * request with. + */ public void setNextTableName(String nextTableName) { this.nextTableName = nextTableName; } + /** + * Gets the list of table entries returned in the server response. + * + * @return + * A {@link List} of {@link TableEntry} instances containing the table entries returned in the response. + */ public List getTables() { return tables; } + /** + * Reserved for internal use. Sets the list of table entries from each TableName entity in the + * properties of the entry entities returned in the body of the server response. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param tables + * A {@link List} of {@link TableEntry} instances containing the table entries returned in the response. + */ public void setTables(List tables) { this.tables = tables; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ServiceProperties.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ServiceProperties.java index 01a18543864b..6f8a4f11c0c0 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ServiceProperties.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/ServiceProperties.java @@ -17,29 +17,65 @@ import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the Storage service properties that can be set on a storage account, including Windows Azure Storage + * Analytics. This class is used by the {@link TableContract#getServiceProperties()} method to return the service + * property values set on the storage account, and by the {@link TableContract#setServiceProperties(ServiceProperties)} + * and {@link TableContract#setServiceProperties(ServiceProperties, TableServiceOptions)} methods to set the values of + * the service properties. + */ @XmlRootElement(name = "StorageServiceProperties") public class ServiceProperties { private Logging logging = new Logging(); private Metrics metrics = new Metrics(); + /** + * Gets the value of the logging options on the storage account. + * + * @return + * A {@link Logging} instance containing the logging options. + */ @XmlElement(name = "Logging") public Logging getLogging() { return logging; } + /** + * Sets the value of the logging options on the storage account. + * + * @param logging + * A {@link Logging} instance containing the logging options. + */ public void setLogging(Logging logging) { this.logging = logging; } + /** + * Gets the value of the metrics options on the storage account. + * + * @return + * A {@link Metrics} instance containing the metrics options. + */ @XmlElement(name = "Metrics") public Metrics getMetrics() { return metrics; } + /** + * Sets the value of the metrics options on the storage account. + * + * @param metrics + * A {@link Metrics} instance containing the metrics options. + */ public void setMetrics(Metrics metrics) { this.metrics = metrics; } + /** + * Represents the logging options that can be set on a storage account. + */ public static class Logging { private String version; private boolean delete; @@ -47,113 +83,258 @@ public static class Logging { private boolean write; private RetentionPolicy retentionPolicy; + /** + * Gets the retention policy for logging data set on the storage account. + * + * @return + * The {@link RetentionPolicy} set on the storage account. + */ @XmlElement(name = "RetentionPolicy") public RetentionPolicy getRetentionPolicy() { return retentionPolicy; } + /** + * Sets the retention policy to use for logging data on the storage account. + * + * @param retentionPolicy + * The {@link RetentionPolicy} to set on the storage account. + */ public void setRetentionPolicy(RetentionPolicy retentionPolicy) { this.retentionPolicy = retentionPolicy; } + /** + * Gets a flag indicating whether all write requests are logged. + * + * @return + * A flag value of true if all write operations are logged; otherwise, false. + */ @XmlElement(name = "Write") public boolean isWrite() { return write; } + /** + * Sets a flag indicating whether all write requests should be logged. + * + * @param write + * Set a flag value of true to log all write operations; otherwise, false. + */ public void setWrite(boolean write) { this.write = write; } + /** + * Gets a flag indicating whether all read requests are logged. + * + * @return + * A flag value of true if all read operations are logged; otherwise, false. + */ @XmlElement(name = "Read") public boolean isRead() { return read; } + /** + * Sets a flag indicating whether all read requests should be logged. + * + * @param read + * Set a flag value of true to log all read operations; otherwise, false. + */ public void setRead(boolean read) { this.read = read; } + /** + * Gets a flag indicating whether all delete requests are logged. + * + * @return + * A flag value of true if all delete operations are logged; otherwise, false. + */ @XmlElement(name = "Delete") public boolean isDelete() { return delete; } + /** + * Sets a flag indicating whether all delete requests should be logged. + * + * @param delete + * Set a flag value of true to log all delete operations; otherwise, false. + */ public void setDelete(boolean delete) { this.delete = delete; } + /** + * Gets the version of logging configured on the storage account. + * + * @return + * A {@link String} containing the version of logging configured on the storage account. + */ @XmlElement(name = "Version") public String getVersion() { return version; } + /** + * Sets the version of logging configured on the storage account. + * + * @param version + * A {@link String} containing the version of logging configured on the storage account. + */ public void setVersion(String version) { this.version = version; } } + /** + * Represents the metrics options that can be set on a storage account. + */ public static class Metrics { private String version; private boolean enabled; private Boolean includeAPIs; private RetentionPolicy retentionPolicy; + /** + * Gets the retention policy for metrics data set on the storage account. + * + * @return + * The {@link RetentionPolicy} set on the storage account. + */ @XmlElement(name = "RetentionPolicy") public RetentionPolicy getRetentionPolicy() { return retentionPolicy; } + /** + * Sets the retention policy to use for metrics data on the storage account. + * + * @param retentionPolicy + * The {@link RetentionPolicy} to set on the storage account. + */ public void setRetentionPolicy(RetentionPolicy retentionPolicy) { this.retentionPolicy = retentionPolicy; } + /** + * Gets a flag indicating whether metrics generates summary statistics for called API operations. + * + * @return + * A flag value of true if metrics generates summary statistics for called API operations; + * otherwise, false. + */ @XmlElement(name = "IncludeAPIs") public Boolean isIncludeAPIs() { return includeAPIs; } + /** + * Sets a flag indicating whether metrics should generate summary statistics for called API operations. This + * flag is optional if metrics is not enabled. + * + * @param includeAPIs + * Set a flag value of true to generate summary statistics for called API operations; + * otherwise, false. + */ public void setIncludeAPIs(Boolean includeAPIs) { this.includeAPIs = includeAPIs; } + /** + * Gets a flag indicating whether metrics is enabled for the storage account. + * + * @return + * A flag value of true if metrics is enabled for the storage account; otherwise, + * false. + */ @XmlElement(name = "Enabled") public boolean isEnabled() { return enabled; } + /** + * Sets a flag indicating whether to enable metrics for the storage account. + * + * @param enabled + * Set a flag value of true to enable metrics for the storage account; otherwise, + * false. + */ public void setEnabled(boolean enabled) { this.enabled = enabled; } + /** + * Gets the version of Storage Analytics configured on the storage account. + * + * @return + * A {@link String} containing the version of Storage Analytics configured on the storage account. + */ @XmlElement(name = "Version") public String getVersion() { return version; } + /** + * Sets the version of Storage Analytics configured on the storage account. + * + * @param version + * A {@link String} containing the version of Storage Analytics configured on the storage account. + */ public void setVersion(String version) { this.version = version; } } + /** + * Represents the optional retention policy that can be applied to logging or metrics on the storage account. + */ 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, if logging is enabled. + * + * @return + * The number of days to retain logging or metrics data if logging is enabled, or null. + */ @XmlElement(name = "Days") public Integer getDays() { return days; } + /** + * Sets the number of days that metrics or logging data should be retained. The minimum value you can specify is + * 1; the largest value is 365 (one year). This value must be specified even if the enabled flag is set + * to false. + * + * @param days + * The number of days to retain logging or metrics data. + */ public void setDays(Integer days) { this.days = days; } + /** + * Gets a flag indicating whether a retention policy is enabled. + * + * @return + * A flag value of true if a retention policy is enabled; otherwise, false. + */ @XmlElement(name = "Enabled") public boolean isEnabled() { return enabled; } + /** + * Sets a flag indicating whether to enable a retention policy. + * + * @param enabled + * Set a flag value of true to enable a retention policy; otherwise, false. + */ public void setEnabled(boolean enabled) { this.enabled = enabled; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableEntry.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableEntry.java index 2e520bc36db1..cc65eff4e1d4 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableEntry.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableEntry.java @@ -14,13 +14,28 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * Represents a single table entry in the list of tables in the storage account. + */ public class TableEntry { private String name; + /** + * Gets the name of the table. + * + * @return + * A {@link String} containing the name of the table. + */ public String getName() { return name; } + /** + * Sets the name of the table. + * + * @param name + * A {@link String} containing the name of the table. + */ public void setName(String name) { this.name = name; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableServiceOptions.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableServiceOptions.java index c4a733a6e3a6..0eb1b91b27aa 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableServiceOptions.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/TableServiceOptions.java @@ -14,5 +14,8 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * This class is a base class for options that may be set on certain Table service requests. + */ public class TableServiceOptions { } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UnaryFilter.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UnaryFilter.java index 99aa90409830..190437d27b53 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UnaryFilter.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UnaryFilter.java @@ -14,19 +14,47 @@ */ package com.microsoft.windowsazure.services.table.models; +/** + * Represents a table query filter expression consisting of a unary logical operator and a boolean filter expression. + * Use the static factory methods in the {@link Filter} class to create UnaryFilter instances, rather + * than constructing them directly. + */ public class UnaryFilter extends Filter { private final String operator; private final Filter operand; + /** + * Creates a UnaryFilter expression from a unary logical operator and a boolean {@link Filter}. + *

+ * Use the static factory methods in the {@link Filter} class to create UnaryFilter instances, rather + * than constructing them directly. + * + * @param operator + * A {@link String} containing the unary logical operator to use in the expression. + * @param operand + * The boolean {@link Filter} to use as the operand of the expression. + */ public UnaryFilter(String operator, Filter operand) { this.operator = operator; this.operand = operand; } + /** + * Gets the unary logical operator to use in the UnaryFilter expression. + * + * @return + * A {@link String} containing the unary logical operator to use in the expression. + */ public String getOperator() { return operator; } + /** + * Gets the boolean {@link Filter} to use as the operand of the UnaryFilter expression. + * + * @return + * A {@link Filter} to use as the operand of the expression. + */ public Filter getOperand() { return operand; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UpdateEntityResult.java b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UpdateEntityResult.java index dc18aa98996e..53dc66738944 100644 --- a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UpdateEntityResult.java +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/UpdateEntityResult.java @@ -14,13 +14,46 @@ */ package com.microsoft.windowsazure.services.table.models; +import com.microsoft.windowsazure.services.table.TableContract; + +/** + * Represents the response to a request to modify a single table entity in the storage account returned + * from a Table Service REST API Update Entity, Merge Entity, Insert or Replace Entity, or Insert or Merge Entity + * operation. This is returned by calls to implementations of {@link TableContract#mergeEntity(String, Entity)}, + * {@link TableContract#mergeEntity(String, Entity, TableServiceOptions)}, + * {@link TableContract#insertOrMergeEntity(String, Entity)}, + * {@link TableContract#insertOrMergeEntity(String, Entity, TableServiceOptions)}, + * {@link TableContract#insertOrReplaceEntity(String, Entity)}, + * {@link TableContract#insertOrReplaceEntity(String, Entity, TableServiceOptions)}, + * {@link TableContract#updateEntity(String, Entity)} and + * {@link TableContract#updateEntity(String, Entity, TableServiceOptions)}. + *

+ * See the Update Entity documentation + * on MSDN for details of the underlying Table Service REST API operations. + */ public class UpdateEntityResult { private String etag; + /** + * Gets the ETag value of the modified entity returned in the server response. + * + * @return + * A {@link String} containing the ETag value of the modified entity. + */ public String getEtag() { return etag; } + /** + * Reserved for internal use. Sets the ETag value of the modified entity from the ETag header value + * in the server response. + *

+ * This method is invoked by the API to set the value from the Table Service REST API operation response returned by + * the server. + * + * @param etag + * A {@link String} containing the ETag value of the modified entity. + */ public void setEtag(String etag) { this.etag = etag; } diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/package.html new file mode 100644 index 000000000000..5d3fb8ac686a --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/models/package.html @@ -0,0 +1,5 @@ + + +This package contains the table data transfer object classes. + + diff --git a/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/package.html b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/package.html new file mode 100644 index 000000000000..74b2c715f988 --- /dev/null +++ b/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/table/package.html @@ -0,0 +1,5 @@ + + +This package contains the table service class, interface, and associated configuration and utility classes. + +