com.thingworx.datashape

Class DataShape

java.lang.Object

com.thingworx.types.NamedObject

com.thingworx.persistence.common.PersistableNamedObject

com.thingworx.entities.RootEntity

com.thingworx.entities.ServiceProviderEntity

com.thingworx.datashape.DataShape

All Implemented Interfaces:

IConfigurableObject, INotScriptFriendly, IDiffableObject, IAvatar, IEntityLifeCycleEvent, IPersistable, IServiceProvider, ITaggableObject, IDependencyScannableObject, IEntityDefinition, IPersistableObject<java.lang.String>, IDesignTimeSecurable, IDesignTimeSecurableEntity, IRunTimeSecurable, IRunTimeSecurableEntity, ISecurable, IVisibilitySecurable, IVisibilitySecurableEntity, IAspectContainer, INamedObject, java.io.Serializable, java.lang.Cloneable

@ThingworxExtensionApiClass(since={6,6},
                            canInstantiate=true)
public class DataShape
extends ServiceProviderEntity
implements java.lang.Cloneable

The concrete implementation of a data shape entity.

Data shapes are an exposed form of a persistable data format in the ThingWorx platform. All entities that can be persisted, including data shapes themselves, have a data shape describing their format. Data shapes are also used to define the format of an InfoTable , DataTableThing, and com.thingworx.streams.StreamThing.

The DataShape class should not be confused with the {link DataShapeDefinition} class. DataShapeDefinition is a transient, serializable collection of field definitions. DataShape is an actual entity backed by at least one DataShapeDefinition object. It is persistent and modifiable via the REST APIs and user interface.

See Also:

DataShapeDefinition, RootEntity, Serialized Form

Field Summary

Fields inherited from class com.thingworx.entities.RootEntity

BASIC_PROPERTIES

Fields inherited from class com.thingworx.types.NamedObject

NAME_COMPARATOR

Constructor Summary

Constructors

Constructor and Description
DataShape() Constructs a new, unnamed data shape object without any fields defined.

Method Summary

Modifier and Type	Method and Description
void	addFieldDefinition(FieldDefinition field) Add a field definition to this data shape.
void	AddFieldDefinition(java.lang.String name, java.lang.String description, java.lang.String type, java.lang.Integer ordinal, java.lang.Boolean primaryKey, java.lang.String dataShape) Service Category: Fields Service Description: Add a field definition. An entity service that adds a new field to the current data shape.
InfoTable	CreateValues() Service Category: Values Service Description: Create an empty info table of the correct datashape for this data table. An entity service that generates an info table backed by this data shape.
InfoTable	CreateValuesWithData(org.json.JSONObject values) Service Category: Crawl Service Description: Create an info table of the correct datashape for this stream and include data values. An entity service that generates an info table backed by this data shape with a single row containing the values from the provided JSON object that match the fields defined in this shape.
static DataShape	fromJSON(org.json.JSONObject jsonObject) Deprecated.
DataShapeDefinition	getDataShape() Returns the definition of this data shape independent of its hierarchy; inherited fields are not visible through this method.
org.json.JSONObject	GetDataShapeMetadataAsJSON() Service Category: Metadata Service Description: Get the metadata for this data shape as JSON. An entity service that returns a JSON object describing the metadata for this data shape.
EntityReferenceTypeMap	getDependencies() Returns a mapping describing all upstream and downstream dependencies for this data shape and its underlying fields.
org.json.JSONObject	GetEffectiveDataShapeMetadataAsJSON() Service Category: Metadata Service Description: Get the effective metadata for this data shape as JSON.
InfoTable	GetEffectiveFieldDefinition(java.lang.String name) Service Category: Fields Service Description: Get an effective field definition by name for this data shape.
InfoTable	GetEffectiveFieldDefinitions() Service Category: Fields Service Description: Get the effective fields for this data shape.
RelationshipTypes.ThingworxRelationshipTypes	getEntityType() Returns the entity type for this data shape.
FieldDefinition	getFieldDefinition(java.lang.String name) Returns the definition of the field with the supplied name.
InfoTable	GetFieldDefinition(java.lang.String name) Service Category: Fields Service Description: Get a field definition by name for this data shape. An entity service that returns an info table describing a requested field relevant to this data shape.
InfoTable	GetFieldDefinitions() Service Category: Fields Service Description: Get the fields for this data shape. An entity service that returns an info table describing the fields relevant to this data shape.
FieldDefinitionCollection	getFields() Returns a collection containing all of the fields relevant to this data shape.
InfoTable	GetRelatedEntities(java.lang.Double maxItems) Service Category: Queries Service Description: Get the entities that use this data shape. An entity service that returns an info table listing all entities that utilize this data shape (i.e., all downstream dependencies).
boolean	hasPrimaryKey() Tests if any field defined in this data shape has been set as a primary key.
boolean	matches(DataShapeDefinition ds1) Determines whether or not the provided DataShapeDefinition matches this data shape.
void	RemoveFieldDefinition(java.lang.String name) Service Category: Fields Service Description: Remove a field definition. An entity service that removes a field from this data shape.
void	setFields(FieldDefinitionCollection fields) Assigns the collection of fields to this data shape, overwriting all existing fields.
ValueCollection	toValueCollection() A helper method that creates a ValueCollection containing mappings describing the data shape and its field definitions.
void	UpdateFieldDefinition(java.lang.String name, java.lang.String description, java.lang.String type, java.lang.Integer ordinal, java.lang.Boolean primaryKey, java.lang.String dataShape) Service Category: Fields Service Description: Update a field definition. An entity service that modifies an existing field definition.
void	validateConfiguration(ImportedEntityCollection importedEntities)

Methods inherited from class com.thingworx.entities.ServiceProviderEntity

getInstancePublicServiceDefinitions, getInstanceServiceDefinition, getInstanceServiceDefinitions, initializeEntity, preInitializeEntity, processAPIServiceRequest, processServiceRequest

Methods inherited from class com.thingworx.entities.RootEntity

AddConfigurationTableDefinition, addDesignTimePermission, AddDesignTimePermission, addRunTimePermission, AddRunTimePermission, AddTags, addVisibilityPermission, AddVisibilityPermission, CheckDesignTimePermission, CheckDesignTimePermissionForGroup, CheckDesignTimePermissionForUser, CheckPermission, CheckPermissionForGroup, CheckPermissionForUser, cleanupEntity, cleanupEntity, DeleteAllConfigurationTableRows, DeleteConfigurationTable, DeleteConfigurationTableRows, deleteDesignTimePermission, DeleteDesignTimePermission, deleteRunTimePermission, DeleteRunTimePermission, deleteVisibilityPermission, DeleteVisibilityPermission, dispose, getAspects, GetAvatar, getAvatarContent, GetAvatarURL, GetConfigurationChangeHistory, getConfigurationSetting, getConfigurationTable, GetConfigurationTable, GetConfigurationTableDefinition, GetConfigurationTableRow, GetConfigurationTables, GetDescription, getDesignTimePermissions, GetDesignTimePermissions, GetDesignTimePermissionsAsJSON, getDocumentationContent, getEntityTypeAsString, GetEventDefinition, GetEventDefinitions, GetHomeMashup, GetIncomingDependencies, GetIncomingDependenciesAsNetwork, GetInstanceMetadataAsJSON, GetInstanceMetadataWithPermissionsAsJSON, GetLastModifiedDate, GetMetadata, GetMetadataAsJSON, GetMetadataWithPermissionsAsJSON, GetOutgoingDependencies, GetOutgoingDependenciesAsNetwork, getOwner, GetPermissionsForCurrentUser, GetPermissionsForGroup, GetPermissionsForUser, GetProjectName, GetPropertyDefinition, GetPropertyDefinitions, getRunTimePermissions, GetRunTimePermissions, GetRunTimePermissionsAsJSON, GetServiceDefinition, GetServiceDefinitions, getStringConfigurationSetting, getStringConfigurationSettingWithDefault, GetSummaryInformation, getTags, GetTags, GetTagsAsInfoTable, getVisibilityPermissions, GetVisibilityPermissions, GetVisibilityPermissionsAsJSON, HasIncomingDependencies, HasOutgoingDependencies, isEditable, isEditableExtensionObject, isEditableSystemObject, isExtensionObject, IsMultiRowTable, isOwner, isSystemObject, isThemeObject, isVisible, isVisible, persistDesignTimePermissions, persistRunTimePermissions, persistVisibilityPermissions, RemoveTags, SaveConfigurationTables, SetAvatar, setConfigurationSetting, SetConfigurationTable, SetConfigurationTableRows, SetDescription, setDesignTimePermissions, SetDesignTimePermissionsAsJSON, setDocumentationContent, setExtensionObject, SetHomeMashup, setLastModifiedDate, SetMultiRowConfigurationTable, setOwner, SetOwner, SetProjectName, setRunTimePermissions, SetRunTimePermissionsAsJSON, setStringConfigurationSetting, SetTags, setVisibilityPermissions, SetVisibilityPermissionsAsJSON, toJSON, toJSONDefinition

Methods inherited from class com.thingworx.persistence.common.PersistableNamedObject

getID, hasID, isTransient

Methods inherited from class com.thingworx.types.NamedObject

getDescription, getName, setDescription, setName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.thingworx.entities.interfaces.IPersistable

getID, hasID

Methods inherited from interface com.thingworx.types.INamedObject

getDescription, getName

Methods inherited from interface com.thingworx.security.permissions.ISecurable

getID, getName

Constructor Detail

DataShape

@ThingworxExtensionApiMethod(since={6,6})
public DataShape()

Constructs a new, unnamed data shape object without any fields defined. The data shape is not yet persisted.

Method Detail

validateConfiguration

@ThingworxExtensionApiMethod(since={6,6})
public void validateConfiguration(ImportedEntityCollection importedEntities)
                                                                     throws java.lang.Exception

Description copied from class: RootEntity

Validates the configuration of the entity during the import process. This method is called whenever a entity is created or modified via the REST APIs. During the validation step, there may be other associated entities that are being imported. These can be accessed via the importedEntities collection if needed.

Note that some resources belonging to the entity or other associated entities may not be available during this step in the lifecycle.

It is required for all subclasses of RootEntity to call super.validateConfiguration(importedEntityCollections) if they override this method.

Overrides:

validateConfiguration in class RootEntity

Parameters:

importedEntities - a collection of entities that have been successfully imported

Throws:

java.lang.Exception - If an error occurs

Verifies that this data shape is valid and that any other entities it references have been imported or persisted. This includes the following:

1. The data shape inheritance hierarchy does not contain any cycles
2. The base data shape, if defined, refers to a data shape that exists or is in the list of entities that are imported
3. Each field name is valid
4. If a field has a base type of InfoTable with a data shape assigned to it, that the backing data shape has been persisted.

getDataShape

@ThingworxExtensionApiMethod(since={6,6})
public DataShapeDefinition getDataShape()

Returns the definition of this data shape independent of its hierarchy; inherited fields are not visible through this method.

Returns:

the data shape definition for this shape, ignoring any inherited fields

hasPrimaryKey

@ThingworxExtensionApiMethod(since={6,6})
public boolean hasPrimaryKey()

Tests if any field defined in this data shape has been set as a primary key.

Returns:

true if a field set as a primary key exists

See Also:

DataShapeDefinition.hasPrimaryKey()

addFieldDefinition

@ThingworxExtensionApiMethod(since={6,6})
public void addFieldDefinition(FieldDefinition field)

Add a field definition to this data shape.

Parameters:

field - the field definition to add to this data shape

See Also:

DataShapeDefinition.addFieldDefinition(FieldDefinition)

getFieldDefinition

@ThingworxExtensionApiMethod(since={6,6})
public FieldDefinition getFieldDefinition(java.lang.String name)

Returns the definition of the field with the supplied name.

Parameters:

name - the name of the field to retrieve

Returns:

the FieldDefinition of the field with the supplied name, or null if the field does not exist

See Also:

DataShapeDefinition.getFieldDefinition(String)

getFields

@ThingworxExtensionApiMethod(since={6,6})
public FieldDefinitionCollection getFields()

Returns a collection containing all of the fields relevant to this data shape.

Returns:

a {code FieldDefinitionCollection} containing all of the fields relevant to this data shape

See Also:

DataShapeDefinition.getFields()

setFields

@ThingworxExtensionApiMethod(since={6,6})
public void setFields(FieldDefinitionCollection fields)

Assigns the collection of fields to this data shape, overwriting all existing fields.

Parameters:

fields - a collection containing the new fields for this data shape

See Also:

DataShapeDefinition.setFields(FieldDefinitionCollection)

matches

@ThingworxExtensionApiMethod(since={6,6})
public boolean matches(DataShapeDefinition ds1)

Determines whether or not the provided DataShapeDefinition matches this data shape.

Parameters:

ds1 - the definition to match against this data shape

Returns:

true if the definition matches against this data shape

CreateValues

@ThingworxExtensionApiMethod(since={6,6})
public InfoTable CreateValues()
                                                                 throws java.lang.Exception

Service Category:

Values

Service Description:

Create an empty info table of the correct datashape for this data table.

An entity service that generates an info table backed by this data shape.

Returns:

an info table using this data shape for its field definitions

Throws:

java.lang.Exception - if an error occurs

CreateValuesWithData

@ThingworxExtensionApiMethod(since={6,6})
public InfoTable CreateValuesWithData(org.json.JSONObject values)
                                                                         throws java.lang.Exception

Service Category:

Crawl

Service Description:

Create an info table of the correct datashape for this stream and include data values.

An entity service that generates an info table backed by this data shape with a single row containing the values from the provided JSON object that match the fields defined in this shape.

Parameters:

values - a JSON object mapping the desired values to the field names

Returns:

the generated InfoTable with a single row of data

Throws:

java.lang.Exception - if the value in the JSON object is not a legal representation of the field's base type

GetRelatedEntities

@ThingworxExtensionApiMethod(since={6,6})
public InfoTable GetRelatedEntities(java.lang.Double maxItems)
                                                                       throws java.lang.Exception

Service Category:

Queries

Service Description:

Get the entities that use this data shape.

An entity service that returns an info table listing all entities that utilize this data shape (i.e., all downstream dependencies).

Parameters:

maxItems - the maximum number of entities to list (by default, it will be set to the value of RESTAPIConstants.DEFAULT_ITEM_COUNT)

Returns:

an info table of entities

Throws:

java.lang.Exception - if an error occurs during dependency calculation

GetDataShapeMetadataAsJSON

@ThingworxExtensionApiMethod(since={6,6})
public org.json.JSONObject GetDataShapeMetadataAsJSON()
                                                                                         throws java.lang.Exception

Service Category:

Metadata

Service Description:

Get the metadata for this data shape as JSON.

An entity service that returns a JSON object describing the metadata for this data shape.

Returns:

the metadata represented in JSON

Throws:

java.lang.Exception - if an error occurs during JSON serialization

GetEffectiveDataShapeMetadataAsJSON

@ThingworxExtensionApiMethod(since={6,6})
public org.json.JSONObject GetEffectiveDataShapeMetadataAsJSON()
                                                                                                  throws java.lang.Exception

Service Category:

Metadata

Service Description:

Get the effective metadata for this data shape as JSON.

Returns:

result Field definitions - JSON

Throws:

java.lang.Exception - If an error occurs

GetEffectiveFieldDefinitions

@ThingworxExtensionApiMethod(since={6,6})
public InfoTable GetEffectiveFieldDefinitions()
                                                                                 throws java.lang.Exception

Service Category:

Fields

Service Description:

Get the effective fields for this data shape.

Returns:

result Field definitions - INFOTABLE - Aspects {dataShape:FieldDefinition}

Throws:

java.lang.Exception - If an error occurs

GetEffectiveFieldDefinition

@ThingworxExtensionApiMethod(since={6,6})
public InfoTable GetEffectiveFieldDefinition(java.lang.String name)
                                                                                throws java.lang.Exception

Service Category:

Fields

Service Description:

Get an effective field definition by name for this data shape.

Parameters:

name - Field name - STRING

Returns:

result Field definitions - INFOTABLE - Aspects {dataShape:FieldDefinition}

Throws:

java.lang.Exception - If an error occurs

GetFieldDefinitions

@ThingworxExtensionApiMethod(since={6,6})
public InfoTable GetFieldDefinitions()
                                                                        throws java.lang.Exception

Service Category:

Fields

Service Description:

Get the fields for this data shape.

An entity service that returns an info table describing the fields relevant to this data shape.

Returns:

an InfoTable describing the fields

Throws:

java.lang.Exception - if an error occurs

GetFieldDefinition

@ThingworxExtensionApiMethod(since={6,6})
public InfoTable GetFieldDefinition(java.lang.String name)
                                                                       throws java.lang.Exception

Service Category:

Fields

Service Description:

Get a field definition by name for this data shape.

An entity service that returns an info table describing a requested field relevant to this data shape.

Parameters:

name - the name of the field

Returns:

an info table describing the requested field

Throws:

java.lang.Exception - if the requested field does not exist

AddFieldDefinition

@ThingworxExtensionApiMethod(since={6,6})
public void AddFieldDefinition(java.lang.String name,
                                                                         java.lang.String description,
                                                                         java.lang.String type,
                                                                         java.lang.Integer ordinal,
                                                                         java.lang.Boolean primaryKey,
                                                                         java.lang.String dataShape)
                                                                  throws java.lang.Exception

Service Category:

Fields

Service Description:

Add a field definition.

An entity service that adds a new field to the current data shape.

Parameters:

name - the name of the field to create

description - the description of the field

type - the type of the field, corresponding to a type in the BaseTypes enumeration

ordinal - the ordinality of the field to insert

primaryKey - a boolean indicating if this field is a primary key

dataShape - the underlying data shape, if the type is assigned to INFOTABLE

Throws:

java.lang.Exception - if a validation error occurs

UpdateFieldDefinition

@ThingworxExtensionApiMethod(since={6,6})
public void UpdateFieldDefinition(java.lang.String name,
                                                                            java.lang.String description,
                                                                            java.lang.String type,
                                                                            java.lang.Integer ordinal,
                                                                            java.lang.Boolean primaryKey,
                                                                            java.lang.String dataShape)
                                                                     throws java.lang.Exception

Service Category:

Fields

Service Description:

Update a field definition.

An entity service that modifies an existing field definition.

Parameters:

name - the name of the field to modify

description - the description of the field

type - the type of the field, corresponding to a type in the BaseTypes enumeration

ordinal - the ordinality of the field

primaryKey - a boolean indicating if this field is a primary key

dataShape - the underlying data shape, if the type is assigned to INFOTABLE

Throws:

java.lang.Exception - if a validation error occurs

RemoveFieldDefinition

@ThingworxExtensionApiMethod(since={6,6})
public void RemoveFieldDefinition(java.lang.String name)
                                                                     throws java.lang.Exception

Service Category:

Fields

Service Description:

Remove a field definition.

An entity service that removes a field from this data shape.

Parameters:

name - the name of the field to remove

Throws:

java.lang.Exception - if the field does not exist

getDependencies

@ThingworxExtensionApiMethod(since={6,6})
public EntityReferenceTypeMap getDependencies()

Returns a mapping describing all upstream and downstream dependencies for this data shape and its underlying fields.

Returns:

a map of dependent entities that refer to this data shape or are referred to by this data shape and/or its fields

toValueCollection

@ThingworxExtensionApiMethod(since={6,6})
public ValueCollection toValueCollection()

A helper method that creates a ValueCollection containing mappings describing the data shape and its field definitions.

Overrides:

toValueCollection in class NamedObject

Returns:

a map describing this data shape

getEntityType

@ThingworxExtensionApiMethod(since={6,6})
public RelationshipTypes.ThingworxRelationshipTypes getEntityType()

Returns the entity type for this data shape.

Specified by:

getEntityType in class RootEntity

Returns:

the DataShape constant

fromJSON

@Deprecated
 @ThingworxExtensionApiMethod(since={6,6},
                             deprecatedSince={8,4})
public static DataShape fromJSON(org.json.JSONObject jsonObject)
                                                                                                                                     throws java.lang.Exception

Deprecated.

Parses a serialized data shape as a JSON object. The JSON object must contain, at a minimum, the required properties for an entity as well as the JSON object describing the field definitions for the data shape. It may also optionally include the name of the base data shape.

Parameters:

jsonObject - the JSON object describing the serialized data shape

Returns:

the deserialized DataShape described by the JSON object

Throws:

java.lang.Exception - if the JSON object does not properly represent a DataShape