TableServiceEntity (Microsoft Azure Storage Android Client SDK 2.0.0 API)

java.lang.Object
- com.microsoft.azure.storage.table.TableServiceEntity

All Implemented Interfaces:: TableEntity

Direct Known Subclasses:: DynamicTableEntity

public class TableServiceEntity
extends Object
implements TableEntity

The TableServiceEntity class represents the base object type for a table entity in the Storage service. TableServiceEntity provides a base implementation for the TableEntity interface that provides readEntity and writeEntity methods that by default serialize and deserialize all properties via reflection. A table entity class may extend this class and override the readEntity and writeEntity methods to provide customized or more performant serialization logic.

The use of reflection allows subclasses of TableServiceEntity to be serialized and deserialized without having to implement the serialization code themselves. When both a getter method and setter method are found for a given property name and data type, then the appropriate method is invoked automatically to serialize or deserialize the data. To take advantage of the automatic serialization code, your table entity classes should provide getter and setter methods for each property in the corresponding table entity in Microsoft Azure table storage. The reflection code looks for getter and setter methods in pairs of the form

public type getPropertyName() { ... }

and

public void setPropertyName(type parameter) { ... }

where PropertyName is a property name for the table entity, and type is compatible with the EDM data type of the property. See the table below for a map of property types to their language equivalents. The StoreAs annotation may be applied with a name attribute to specify a property name for reflection on getter and setter methods that do not follow the property name convention. Method names and the name attribute of StoreAs annotations are case sensitive for matching property names with reflection. Use the Ignore annotation to prevent methods from being used by reflection for automatic serialization and deserialization. Note that the names "PartitionKey", "RowKey", "Timestamp", and "Etag" are reserved and will be ignored if set with the StoreAs annotation in a subclass.

The following table shows the supported property data types in Microsoft Azure storage and the corresponding Java types when deserialized.

Storage Type	EdmType Value	Java Type	Description
Edm.Binary	`EdmType.BINARY`	`byte[], Byte[]`	An array of bytes up to 64 KB in size.
Edm.Boolean	`EdmType.BOOLEAN`	`boolean, Boolean`	A Boolean value.
Edm.DateTime	`EdmType.DATE_TIME`	`java.util.Date`	A 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	`EdmType.DOUBLE`	`double, Double`	A 64-bit double-precision floating point value.
Edm.Guid	`EdmType.GUID`	`UUID`	A 128-bit globally unique identifier.
Edm.Int32	`EdmType.INT32`	`int, Integer`	A 32-bit integer value.
Edm.Int64	`EdmType.INT64`	`long, Long`	A 64-bit integer value.
Edm.String	`EdmType.STRING`	`String`	A 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 Microsoft 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.

See Also:: EdmType

Constructor Summary

Constructors
Constructor and Description
`TableServiceEntity()` Initializes an empty `TableServiceEntity` instance.
`TableServiceEntity(String partitionKey, String rowKey)` Initializes a new instance of the `TableServiceEntity` class with the specified partition key and row key.

Method Summary

Methods
Modifier and Type	Method and Description
`String`	`getEtag()` Gets the ETag value to verify for the entity.
`String`	`getPartitionKey()` Gets the PartitionKey value for the entity.
`String`	`getRowKey()` Gets the RowKey value for the entity.
`Date`	`getTimestamp()` Gets the Timestamp for the entity.
`static boolean`	`isReflectedEntityCacheDisabled()` Gets a value indicating whether or not the reflected entity cache is disabled.
`void`	`readEntity(HashMap<String,EntityProperty> properties, OperationContext opContext)` Populates this table entity instance using the map of property names to `EntityProperty` data typed values.
`static void`	`readEntityWithReflection(Object instance, HashMap<String,EntityProperty> properties, OperationContext opContext)` Deserializes the table entity property map into the specified object instance using reflection.
`void`	`setEtag(String etag)` Sets the ETag value to verify for the entity.
`void`	`setPartitionKey(String partitionKey)` Sets the PartitionKey value for the entity.
`static void`	`setReflectedEntityCacheDisabled(boolean disableReflectedEntityCache)` Sets a boolean representing whether or not the reflected entity cache is disabled.
`void`	`setRowKey(String rowKey)` Sets the RowKey value for the entity.
`void`	`setTimestamp(Date timeStamp)` Sets the `timeStamp` value for the entity.
`HashMap<String,EntityProperty>`	`writeEntity(OperationContext opContext)` Returns a map of property names to `EntityProperty` data typed values created by serializing this table entity instance.
`static HashMap<String,EntityProperty>`	`writeEntityWithReflection(Object instance)` Serializes the property data from a table entity instance into a property map using reflection.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - TableServiceEntity
```
public TableServiceEntity()
```
    Initializes an empty TableServiceEntity instance.
  - TableServiceEntity
```
public TableServiceEntity(String partitionKey,
                  String rowKey)
```
    Initializes a new instance of the TableServiceEntity class with the specified partition key and row key.
    
    Parameters:
    partitionKey - A String which represents the partition key of the TableServiceEntity to be initialized.
    rowKey - A String which represents the row key of the TableServiceEntity to be initialized.
- Method Detail
  - readEntityWithReflection
```
public static void readEntityWithReflection(Object instance,
                            HashMap<String,EntityProperty> properties,
                            OperationContext opContext)
                                     throws IllegalArgumentException,
                                            IllegalAccessException,
                                            InvocationTargetException
```
    Deserializes the table entity property map into the specified object instance using reflection.
    This static method takes an object instance that represents a table entity type and uses reflection on its class type to find methods to deserialize the data from the property map into the instance.
    Each property name and data type in the properties map is compared with the methods in the class type for a pair of getter and setter methods to use for serialization and deserialization. The class is scanned for methods with names that match the property name with "get" and "set" prepended, or with the StoreAs annotation set with the property name. The methods must have return types or parameter data types that match the data type of the corresponding EntityProperty value. If such a pair is found, the data is copied into the instance object by invoking the setter method on the instance. Properties that do not match a method pair by name and data type are not copied.
    
    Parameters:
    instance - An Object reference to an instance of a class implementing TableEntity to deserialize the table entity data into.
    properties - A java.util.HashMap object which maps String property names to EntityProperty objects containing typed data values to deserialize into the instance parameter object.
    opContext - An OperationContext object that represents the context for the current operation.
    
    Throws:
    
    IllegalArgumentException - if the table entity response received is invalid or improperly formatted.
    
    IllegalAccessException - if the table entity threw an exception during deserialization.
    
    InvocationTargetException - if a method invoked on the instance parameter threw an exception during deserialization.
  - writeEntityWithReflection
```
public static HashMap<String,EntityProperty> writeEntityWithReflection(Object instance)
                                                                throws IllegalArgumentException,
                                                                       IllegalAccessException,
                                                                       InvocationTargetException
```
    Serializes the property data from a table entity instance into a property map using reflection.
    This static method takes an object instance that represents a table entity type and uses reflection on its class type to find methods to serialize the data from the instance into the property map.
    Each property name and data type in the properties map is compared with the methods in the class type for a pair of getter and setter methods to use for serialization and deserialization. The class is scanned for methods with names that match the property name with "get" and "set" prepended, or with the StoreAs annotation set with the property name. The methods must have return types or parameter data types that match the data type of the corresponding EntityProperty value. If such a pair is found, the data is copied from the instance object by invoking the getter method on the instance. Properties that do not have a method pair with matching name and data type are not copied.
    
    Parameters:
    instance - An Object reference to an instance of a class implementing TableEntity to serialize the table entity data from.
    
    Returns:
    A java.util.HashMap object which maps String property names to EntityProperty objects containing typed data values serialized from the instance parameter object.
    
    Throws:
    
    IllegalArgumentException - if the table entity is invalid or improperly formatted.
    
    IllegalAccessException - if the table entity threw an exception during serialization.
    
    InvocationTargetException - if a method invoked on the instance parameter threw an exception during serialization.
  - getEtag
```
public String getEtag()
```
    Gets the ETag value to verify for the entity. This value is used to determine if the table entity has changed since it was last read from Microsoft Azure storage. The client cannot update this value on the service.
    
    Specified by:
    
    getEtag in interface TableEntity
    
    Returns:
    A String containing the ETag for the entity.
  - getPartitionKey
```
public String getPartitionKey()
```
    Gets the PartitionKey value for the entity.
    
    Specified by:
    
    getPartitionKey in interface TableEntity
    
    Returns:
    A String containing the PartitionKey value for the entity.
  - getRowKey
```
public String getRowKey()
```
    Gets the RowKey value for the entity.
    
    Specified by:
    
    getRowKey in interface TableEntity
    
    Returns:
    A String containing the RowKey value for the entity.
  - getTimestamp
```
public Date getTimestamp()
```
    Gets the Timestamp for the entity. The server manages the value of Timestamp, which cannot be modified.
    
    Specified by:
    
    getTimestamp in interface TableEntity
    
    Returns:
    A java.util.Date object which represents the Timestamp value for the entity.
  - isReflectedEntityCacheDisabled
```
public static boolean isReflectedEntityCacheDisabled()
```
    Gets a value indicating whether or not the reflected entity cache is disabled. For most scenarios, disabling the reflected entity cache is not recommended due to its effect on performance. The reflected entity cache stores known entity types and their respective reflected entity dictionaries. Rather than using reflection on a known entity type, the values from the dictionary are used instead.
    
    Returns:
    true if the reflected entity cache is disabled; otherwise, false.
  - setReflectedEntityCacheDisabled
```
public static void setReflectedEntityCacheDisabled(boolean disableReflectedEntityCache)
```
    Sets a boolean representing whether or not the reflected entity cache is disabled. For most scenarios, disabling the reflected entity cache is not recommended due to its effect on performance. The reflected entity cache stores known entity types and their respective reflected entity dictionaries. Rather than using reflection on a known entity type, the values from the dictionary are used instead.
    
    Parameters:
    disableReflectedEntityCache - true to disable the reflected entity cache; otherwise, false.
  - readEntity
```
public void readEntity(HashMap<String,EntityProperty> properties,
              OperationContext opContext)
                throws StorageException
```
    Populates this table entity instance using the map of property names to EntityProperty data typed values.
    This method invokes readEntityWithReflection(java.lang.Object, java.util.HashMap<java.lang.String, com.microsoft.azure.storage.table.EntityProperty>, com.microsoft.azure.storage.OperationContext) to populate the table entity instance the method is called on using reflection. Table entity classes that extend TableServiceEntity can take advantage of this behavior by implementing getter and setter methods for the particular properties of the table entity in Microsoft Azure storage the class represents.
    Override this method in classes that extend TableServiceEntity to invoke custom serialization code.
    
    Specified by:
    
    readEntity in interface TableEntity
    
    Parameters:
    properties - The java.util.HashMap of String property names to EntityProperty data values to deserialize and store in this table entity instance.
    opContext - An OperationContext object used to track the execution of the operation.
    
    Throws:
    
    StorageException - if an error occurs during the deserialization.
  - setEtag
```
public void setEtag(String etag)
```
    Sets the ETag value to verify for the entity. This value is used to determine if the table entity has changed since it was last read from Microsoft Azure storage. The client cannot update this value on the service.
    
    Specified by:
    
    setEtag in interface TableEntity
    
    Parameters:
    etag - A String containing the ETag for the entity.
  - setPartitionKey
```
public void setPartitionKey(String partitionKey)
```
    Sets the PartitionKey value for the entity.
    
    Specified by:
    
    setPartitionKey in interface TableEntity
    
    Parameters:
    partitionKey - A String containing the PartitionKey value for the entity.
  - setRowKey
```
public void setRowKey(String rowKey)
```
    Sets the RowKey value for the entity.
    
    Specified by:
    
    setRowKey in interface TableEntity
    
    Parameters:
    rowKey - A String containing the RowKey value for the entity.
  - setTimestamp
```
public void setTimestamp(Date timeStamp)
```
    Sets the timeStamp value for the entity. Note that the timestamp property is a read-only property, set by the service only.
    
    Specified by:
    
    setTimestamp in interface TableEntity
    
    Parameters:
    timeStamp - A java.util.Date containing the timeStamp value for the entity.
  - writeEntity
```
public HashMap<String,EntityProperty> writeEntity(OperationContext opContext)
                                           throws StorageException
```
    Returns a map of property names to EntityProperty data typed values created by serializing this table entity instance.
    This method invokes writeEntityWithReflection(java.lang.Object) to serialize the table entity instance the method is called on using reflection. Table entity classes that extend TableServiceEntity can take advantage of this behavior by implementing getter and setter methods for the particular properties of the table entity in Microsoft Azure storage the class represents. Note that the property names "PartitionKey", "RowKey", and "Timestamp" are reserved and will be ignored if set on other methods with the StoreAs annotation.
    Override this method in classes that extend TableServiceEntity to invoke custom serialization code.
    
    Specified by:
    
    writeEntity in interface TableEntity
    
    Parameters:
    opContext - An OperationContext object used to track the execution of the operation.
    
    Returns:
    A java.util.HashMap of String property names to EntityProperty data typed values representing the properties serialized from this table entity instance.
    
    Throws:
    
    StorageException - if an error occurs during the serialization.

/** 
* Copyright 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 
* 
* 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. 
*/

Class TableServiceEntity

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TableServiceEntity

TableServiceEntity

Method Detail

readEntityWithReflection

writeEntityWithReflection

getEtag

getPartitionKey

getRowKey

getTimestamp

isReflectedEntityCacheDisabled

setReflectedEntityCacheDisabled

readEntity

setEtag

setPartitionKey

setRowKey

setTimestamp

writeEntity