Package 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:
ISupportsAccessModifier, IConfigurableObject, INotScriptFriendly, ISupportsDeprecation, IDiffableObject, IAvatar, IEntityLifeCycleEvent, IPersistable, IServiceProvider, ITaggableObject, IDependencyScannableObject, IEntityDefinition, IPersistableObject<String>, IDesignTimeSecurable, IDesignTimeSecurableEntity, IRunTimeSecurable, IRunTimeSecurableEntity, ISecurable, IVisibilitySecurable, IVisibilitySecurableEntity, IAspectContainer, INamedObject, Serializable, Cloneable
@ThingworxExtensionApiClass(since={6,6}, canInstantiate=true) public class DataShape extends ServiceProviderEntity implements Cloneable, ISupportsAccessModifier
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:

  • Constructor Details

    • 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 Details

    • validateConfiguration

      @ThingworxExtensionApiMethod(since={6,6}) public void validateConfiguration(ImportedEntityCollection importedEntities) throws Exception
      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.
      Overrides:
      validateConfiguration in class RootEntity
      Parameters:
      importedEntities - a collection of entities that have been successfully imported
      Throws:
      Exception - if the entity is invalid

    • 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:

    • 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:

    • getFieldDefinition

      @ThingworxExtensionApiMethod(since={6,6}) public FieldDefinition getFieldDefinition(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:

    • 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:

    • 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:

    • 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 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:
      Exception - if an error occurs

    • CreateValuesWithData

      @ThingworxExtensionApiMethod(since={6,6}) public InfoTable CreateValuesWithData(org.json.JSONObject values) throws 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:
      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(Double maxItems) throws 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:
      Exception - if an error occurs during dependency calculation

    • GetDataShapeMetadataAsJSON

      @ThingworxExtensionApiMethod(since={6,6}) public org.json.JSONObject GetDataShapeMetadataAsJSON() throws 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:
      Exception - if an error occurs during JSON serialization

    • GetEffectiveDataShapeMetadataAsJSON

      @ThingworxExtensionApiMethod(since={6,6}) public org.json.JSONObject GetEffectiveDataShapeMetadataAsJSON() throws Exception
      Service Category:
      Metadata
      Service Description:
      Get the effective metadata for this data shape as JSON.
      Returns:
      result Field definitions - JSON
      Throws:
      Exception - if an error occurs

    • GetEffectiveFieldDefinitions

      @ThingworxExtensionApiMethod(since={6,6}) public InfoTable GetEffectiveFieldDefinitions() throws Exception
      Service Category:
      Fields
      Service Description:
      Get the effective fields for this data shape.
      Returns:
      result Field definitions - INFOTABLE - Aspects {dataShape:FieldDefinition}
      Throws:
      Exception - if an error occurs

    • GetEffectiveFieldDefinition

      @ThingworxExtensionApiMethod(since={6,6}) public InfoTable GetEffectiveFieldDefinition(String name) throws 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:
      Exception - if an error occurs

    • GetFieldDefinitions

      @ThingworxExtensionApiMethod(since={6,6}) public InfoTable GetFieldDefinitions() throws 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:
      Exception - if an error occurs

    • GetFieldDefinition

      @ThingworxExtensionApiMethod(since={6,6}) public InfoTable GetFieldDefinition(String name) throws 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:
      Exception - if the requested field does not exist

    • AddFieldDefinition

      @ThingworxExtensionApiMethod(since={6,6}) public void AddFieldDefinition(String name, String description, String type, Integer ordinal, Boolean primaryKey, String dataShape) throws 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:
      Exception - if a validation error occurs

    • UpdateFieldDefinition

      @ThingworxExtensionApiMethod(since={6,6}) public void UpdateFieldDefinition(String name, String description, String type, Integer ordinal, Boolean primaryKey, String dataShape) throws 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:
      Exception - if a validation error occurs

    • RemoveFieldDefinition

      @ThingworxExtensionApiMethod(since={6,6}) public void RemoveFieldDefinition(String name) throws 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:
      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 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:
      Exception - if the JSON object does not properly represent a DataShape