Skip navigation links
Thingworx Platform API
8.5.0
com.thingworx.datashape

Class DataShape

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