Share via

TableServiceEntity Class

  • Reference
Package:
com.microsoft.azure.storage.table
  • java.lang.Object
    • TableEntity
      • com.microsoft.azure.storage.table.TableServiceEntity

public class TableServiceEntity 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 and methods that by default serialize and deserialize all properties via reflection. A table entity class may extend this class and override the and 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

and

where PropertyName is a property name for the table entity, and type is a Java type compatible with the EDM data type of the property. See the table below for a map of property types to their Java equivalents. The StoreAs annotation may be applied with a 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 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.

Supported property data types in Microsoft Azure storage

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.

Field Summary

Modifier and Type Field and Description
String etag

Reserved for internal use. The value of the ETag for the entity.

String partitionKey

Reserved for internal use. The value of the partition key in the entity.

String rowKey

Reserved for internal use. The value of the row key in the entity.

Date timeStamp

Reserved for internal use. The value of the Timestamp in the entity.

Constructor Summary

Constructor 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

Modifier and Type Method and Description
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.
String getPartitionKey()

Gets the PartitionKey value for the entity.
ConcurrentHashMap<Class<?>, HashMap<String, PropertyPair>> getReflectedEntityCache()

The reflected entity cache caches known entity types and their respective reflected entity dictionaries when entities are deserialized and the payload does not include JSON metadata.
String getRowKey()

Gets the RowKey value for the entity.
Date getTimestamp()

Gets the Timestamp for the entity. The server manages the value of Timestamp, which cannot be modified.
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.
void readEntity(final HashMap<String, EntityProperty> properties, final OperationContext opContext)

Populates this table entity instance using the map of property names to EntityProperty data typed values.

This method invokes readEntityWithReflection(final Object instance, final HashMap<String, EntityProperty> properties, final OperationContext opContext) 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.
void readEntityWithReflection(final Object instance, final HashMap<String, EntityProperty> properties, final OperationContext opContext)

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.
void setEtag(final 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.
void setPartitionKey(final String partitionKey)

Sets the PartitionKey value for the entity.
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.
void setRowKey(final String rowKey)

Sets the RowKey value for the entity.
void setTimestamp(final Date timeStamp)

Sets the value for the entity. Note that the timestamp property is a read-only property, set by the service only.
HashMap<String, EntityProperty> writeEntity(final OperationContext opContext)

Returns a map of property names to EntityProperty data typed values created by serializing this table entity instance.

This method invokes writeEntityWithReflection(final Object instance) 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.
HashMap<String, EntityProperty> writeEntityWithReflection(final Object instance)

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.

Field Details

etag

protected String etag= null

Reserved for internal use. The value of the ETag for the entity.

partitionKey

protected String partitionKey= null

Reserved for internal use. The value of the partition key in the entity.

rowKey

protected String rowKey= null

Reserved for internal use. The value of the row key in the entity.

timeStamp

protected Date timeStamp= new Date()

Reserved for internal use. The value of the Timestamp in the entity.

Constructor Details

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 Details

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.

Overrides:

TableServiceEntity.getEtag()

Returns:

A String containing the ETag for the entity.

getPartitionKey

public String getPartitionKey()

Gets the PartitionKey value for the entity.

Overrides:

TableServiceEntity.getPartitionKey()

Returns:

A String containing the PartitionKey value for the entity.

getReflectedEntityCache

protected static ConcurrentHashMap, HashMap> getReflectedEntityCache()

The reflected entity cache caches known entity types and their respective reflected entity dictionaries when entities are deserialized and the payload does not include JSON metadata.

Returns:

The ConcurrentHashMap<Class<?>, HashMap<String, PropertyPair>> representing the known entity types and their reflected entity dictionaries

getRowKey

public String getRowKey()

Gets the RowKey value for the entity.

Overrides:

TableServiceEntity.getRowKey()

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.

Overrides:

TableServiceEntity.getTimestamp()

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.

readEntity

public void readEntity(final HashMap properties, final OperationContext opContext)

Populates this table entity instance using the map of property names to EntityProperty data typed values.

This method invokes readEntityWithReflection(final Object instance, final HashMap<String, EntityProperty> properties, final OperationContext opContext) 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.

Overrides:

TableServiceEntity.readEntity(final HashMap<String, EntityProperty> properties, final OperationContext opContext)

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.

readEntityWithReflection

public static void readEntityWithReflection(final Object instance, final HashMap properties, final OperationContext opContext)

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.

setEtag

public void setEtag(final 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.

Overrides:

TableServiceEntity.setEtag(final String etag)

Parameters:

etag - A String containing the ETag for the entity.

setPartitionKey

public void setPartitionKey(final String partitionKey)

Sets the PartitionKey value for the entity.

Overrides:

TableServiceEntity.setPartitionKey(final String partitionKey)

Parameters:

partitionKey - A String containing the PartitionKey value for the entity.

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.

setRowKey

public void setRowKey(final String rowKey)

Sets the RowKey value for the entity.

Overrides:

TableServiceEntity.setRowKey(final String rowKey)

Parameters:

rowKey - A String containing the RowKey value for the entity.

setTimestamp

public void setTimestamp(final Date timeStamp)

Sets the value for the entity. Note that the timestamp property is a read-only property, set by the service only.

Overrides:

TableServiceEntity.setTimestamp(final Date timeStamp)

Parameters:

timeStamp - A java.util.Date containing the timeStamp value for the entity.

writeEntity

public HashMap writeEntity(final OperationContext opContext)

Returns a map of property names to EntityProperty data typed values created by serializing this table entity instance.

This method invokes writeEntityWithReflection(final Object instance) 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.

Overrides:

TableServiceEntity.writeEntity(final OperationContext opContext)

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.

writeEntityWithReflection

public static HashMap writeEntityWithReflection(final Object instance)

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.

Applies to