Package org.eclipse.ditto.things.model

Interface Thing

All Superinterfaces:
org.eclipse.ditto.base.model.entity.Entity<ThingRevision>, org.eclipse.ditto.base.model.json.Jsonifiable<org.eclipse.ditto.json.JsonObject>, org.eclipse.ditto.base.model.json.Jsonifiable.WithFieldSelector, org.eclipse.ditto.base.model.json.Jsonifiable.WithFieldSelectorAndPredicate<org.eclipse.ditto.json.JsonField>, org.eclipse.ditto.base.model.json.Jsonifiable.WithPointer<org.eclipse.ditto.json.JsonObject>, org.eclipse.ditto.base.model.json.Jsonifiable.WithPredicate<org.eclipse.ditto.json.JsonObject,org.eclipse.ditto.json.JsonField>
@Immutable public interface Thing extends org.eclipse.ditto.base.model.entity.Entity<ThingRevision>
A generic entity which can be used as a "handle" for multiple Features belonging to this Thing. A Thing can be for example:
  • a physical device like a lawn mower, a sensor, a vehicle or a lamp;
  • a virtual device like a room in a house, a virtual power plant spanning multiple power plants, the weather information for a specific location collected by various sensors;
  • a transactional entity like a tour of a vehicle (from start until stop) or a series of measurements of a machine;
  • a master data entity like a supplier of devices or a service provider for devices or an entity representing a city/region;
  • anything else – if it can be modeled and managed appropriately by the supported concepts/capabilities of Ditto.

  • Method Details

    • newBuilder

      static ThingBuilder.FromScratch newBuilder()
      Returns a mutable builder with a fluent API for an immutable Thing from scratch.
      Returns:
      the new builder.

    • toBuilder

      default ThingBuilder.FromCopy toBuilder()
      Returns a mutable builder with a fluent API for immutable Thing. The builder is initialised with the entries of this instance.
      Returns:
      the new builder.

    • getImplementedSchemaVersion

      default org.eclipse.ditto.base.model.json.JsonSchemaVersion getImplementedSchemaVersion()
      Specified by:
      getImplementedSchemaVersion in interface org.eclipse.ditto.base.model.json.Jsonifiable<org.eclipse.ditto.json.JsonObject>

    • getNamespace

      Optional<String> getNamespace()
      Returns the namespace this Thing was created in. The namespace is derived from the ID of this Thing.
      Returns:
      the namespace this Thing was created in.

    • getAttributes

      Optional<Attributes> getAttributes()
      Returns the attributes of this Thing.
      Returns:
      the attributes of this Thing.

    • setAttributes

      Thing setAttributes(@Nullable Attributes attributes)
      Sets the attributes on a copy of this Thing.
      Parameters:
      attributes - the attributes.
      Returns:
      a copy of this Thing with the given attributes.

    • removeAttributes

      Thing removeAttributes()
      Removes all attributes from a copy of this Thing.
      Returns:
      a copy of this Thing with all of its attributes removed.

    • getEntityId

      Optional<ThingId> getEntityId()
      Specified by:
      getEntityId in interface org.eclipse.ditto.base.model.entity.Entity<ThingRevision>

    • setAttribute

      default Thing setAttribute(CharSequence attributePath, org.eclipse.ditto.json.JsonValue attributeValue)
      Sets the given attribute on a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute value.
      attributeValue - the attribute value to be set.
      Returns:
      a copy of this Thing with the given attribute.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if attributePath is empty.

    • setAttribute

      default Thing setAttribute(CharSequence attributePath, boolean attributeValue)
      Sets the given attribute on a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute value.
      attributeValue - the attribute value to be set.
      Returns:
      a copy of this Thing with the given attribute.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if attributePath is empty.

    • setAttribute

      default Thing setAttribute(CharSequence attributePath, int attributeValue)
      Sets the given attribute on a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute value.
      attributeValue - the attribute value to be set.
      Returns:
      a copy of this Thing with the given attribute.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if attributePath is empty.

    • setAttribute

      default Thing setAttribute(CharSequence attributePath, long attributeValue)
      Sets the given attribute on a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute value.
      attributeValue - the attribute value to be set.
      Returns:
      a copy of this Thing with the given attribute.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if attributePath is empty.

    • setAttribute

      default Thing setAttribute(CharSequence attributePath, double attributeValue)
      Sets the given attribute on a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute value.
      attributeValue - the attribute value to be set.
      Returns:
      a copy of this Thing with the given attribute.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if attributePath is empty.

    • setAttribute

      default Thing setAttribute(CharSequence attributePath, String attributeValue)
      Sets the given attribute on a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute value.
      attributeValue - the attribute value to be set.
      Returns:
      a copy of this Thing with the given attribute.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if attributePath is empty.

    • setAttribute

      Thing setAttribute(org.eclipse.ditto.json.JsonPointer attributePath, org.eclipse.ditto.json.JsonValue attributeValue)
      Sets the given attribute on a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute value.
      attributeValue - the attribute value to be set.
      Returns:
      a copy of this Thing with the given attribute.
      Throws:
      NullPointerException - if any argument is null.
      IllegalArgumentException - if attributePath is empty.

    • removeAttribute

      default Thing removeAttribute(CharSequence attributePath)
      Removes the attribute at the given path from a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute to be removed.
      Returns:
      a copy of this Thing without the removed attribute.
      Throws:
      NullPointerException - if pointer is null.
      IllegalArgumentException - if pointer is empty.

    • removeAttribute

      Thing removeAttribute(org.eclipse.ditto.json.JsonPointer attributePath)
      Removes the attribute at the given path from a copy of this Thing.
      Parameters:
      attributePath - the hierarchical path to the attribute to be removed.
      Returns:
      a copy of this Thing without the removed attribute.
      Throws:
      NullPointerException - if pointer is null.
      IllegalArgumentException - if pointer is empty.

    • getDefinition

      Optional<ThingDefinition> getDefinition()
      Gets the definition of this Thing.
      Returns:
      the Definition of this Thing.

    • setDefinition

      Thing setDefinition(@Nullable CharSequence definitionIdentifier)
      Sets the definition on a copy of this Thing.
      Parameters:
      definitionIdentifier - the Thing's definition to set.
      Returns:
      a copy of this Thing with the given definition.
      Throws:
      DefinitionIdentifierInvalidException - if definitionIdentifier is invalid.

    • removeDefinition

      Thing removeDefinition()
      Removes the Thing's definition on a copy of this Thing.
      Returns:
      a copy of this Thing without definition.

    • setFeatureDefinition

      Thing setFeatureDefinition(String featureId, FeatureDefinition definition)
      Sets the given definition of a Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      definition - the definition to be set.
      Returns:
      a copy of this Thing with the Feature containing the given definition.
      Throws:
      NullPointerException - if featureId is null.

    • removeFeatureDefinition

      Thing removeFeatureDefinition(String featureId)
      Removes the definition from the Feature of this thing with the specified feature ID.
      Parameters:
      featureId - the identifier of the Feature to delete the definition from.
      Returns:
      a copy of this Thing with the Feature without definition.
      Throws:
      NullPointerException - if featureId is null.

    • setFeatureProperties

      Thing setFeatureProperties(String featureId, FeatureProperties properties)
      Sets the given properties of a Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      properties - the properties to be set.
      Returns:
      a copy of this Thing with the Feature containing the given properties.
      Throws:
      NullPointerException - if featureId is null.

    • setFeatureProperty

      default Thing setFeatureProperty(String featureId, CharSequence propertyPath, org.eclipse.ditto.json.JsonValue propertyValue)
      Sets the given property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be set.
      propertyValue - the property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given property.
      Throws:
      NullPointerException - if any argument is null.

    • setFeatureProperty

      default Thing setFeatureProperty(String featureId, CharSequence propertyPath, boolean propertyValue)
      Sets the given property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be set.
      propertyValue - the property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given property.
      Throws:
      NullPointerException - if any argument is null.

    • setFeatureProperty

      default Thing setFeatureProperty(String featureId, CharSequence propertyPath, int propertyValue)
      Sets the given property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be set.
      propertyValue - the property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given property.
      Throws:
      NullPointerException - if any argument is null.

    • setFeatureProperty

      default Thing setFeatureProperty(String featureId, CharSequence propertyPath, long propertyValue)
      Sets the given property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be set.
      propertyValue - the property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given property.
      Throws:
      NullPointerException - if any argument is null.

    • setFeatureProperty

      default Thing setFeatureProperty(String featureId, CharSequence propertyPath, double propertyValue)
      Sets the given property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be set.
      propertyValue - the property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given property.
      Throws:
      NullPointerException - if any argument is null.

    • setFeatureProperty

      default Thing setFeatureProperty(String featureId, CharSequence propertyPath, String propertyValue)
      Sets the given property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be set.
      propertyValue - the property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given property.
      Throws:
      NullPointerException - if any argument is null.

    • setFeatureProperty

      Thing setFeatureProperty(String featureId, org.eclipse.ditto.json.JsonPointer propertyPath, org.eclipse.ditto.json.JsonValue propertyValue)
      Sets the given property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be set.
      propertyValue - the property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given property.
      Throws:
      NullPointerException - if any argument is null.

    • removeFeatureProperties

      Thing removeFeatureProperties(String featureId)
      Removes all properties from the given Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature of which all properties are to be removed.
      Returns:
      a copy of this Thing with all of the Feature's properties removed.
      Throws:
      NullPointerException - if featureId is null.

    • removeFeatureProperty

      default Thing removeFeatureProperty(String featureId, CharSequence propertyPath)
      Removes the given property from a Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be removed.
      Returns:
      a copy of this Thing with the given Feature property removed.
      Throws:
      NullPointerException - if any argument is null.

    • removeFeatureProperty

      Thing removeFeatureProperty(String featureId, org.eclipse.ditto.json.JsonPointer propertyPath)
      Removes the given property from a Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the property to be removed.
      Returns:
      a copy of this Thing with the given Feature property removed.
      Throws:
      NullPointerException - if any argument is null.

    • setFeatureDesiredProperties

      Thing setFeatureDesiredProperties(CharSequence featureId, FeatureProperties desiredProperties)
      Sets the given desired properties of a Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredProperties - the desired properties to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired properties.
      Throws:
      NullPointerException - if featureId is null.
      Since:
      1.5.0

    • setFeatureDesiredProperty

      default Thing setFeatureDesiredProperty(CharSequence featureId, CharSequence desiredPropertyPath, org.eclipse.ditto.json.JsonValue desiredPropertyValue)
      Sets the given desired property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredPropertyPath - the hierarchical path within the Feature to the desired property to be set.
      desiredPropertyValue - the desired property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired property.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • setFeatureDesiredProperty

      default Thing setFeatureDesiredProperty(CharSequence featureId, CharSequence desiredPropertyPath, boolean desiredPropertyValue)
      Sets the given desired property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredPropertyPath - the hierarchical path within the Feature to the desired property to be set.
      desiredPropertyValue - the desired property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired property.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • setFeatureDesiredProperty

      default Thing setFeatureDesiredProperty(CharSequence featureId, CharSequence desiredPropertyPath, int desiredPropertyValue)
      Sets the given desired property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredPropertyPath - the hierarchical path within the Feature to the desired property to be set.
      desiredPropertyValue - the desired property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired property.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • setFeatureDesiredProperty

      default Thing setFeatureDesiredProperty(CharSequence featureId, CharSequence desiredPropertyPath, long desiredPropertyValue)
      Sets the given desired property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredPropertyPath - the hierarchical path within the Feature to the desired property to be set.
      desiredPropertyValue - the desired property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired property.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • setFeatureDesiredProperty

      default Thing setFeatureDesiredProperty(CharSequence featureId, CharSequence desiredPropertyPath, double desiredPropertyValue)
      Sets the given desired property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredPropertyPath - the hierarchical path within the Feature to the desired property to be set.
      desiredPropertyValue - the desired property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired property.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • setFeatureDesiredProperty

      default Thing setFeatureDesiredProperty(CharSequence featureId, CharSequence desiredPropertyPath, String desiredPropertyValue)
      Sets the given desired property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredPropertyPath - the hierarchical path within the Feature to the desired property to be set.
      desiredPropertyValue - the desired property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired property.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • setFeatureDesiredProperty

      Thing setFeatureDesiredProperty(CharSequence featureId, org.eclipse.ditto.json.JsonPointer desiredPropertyPath, org.eclipse.ditto.json.JsonValue desiredPropertyValue)
      Sets the given desired property to the Feature with the given ID on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      desiredPropertyPath - the hierarchical path within the Feature to the desired property to be set.
      desiredPropertyValue - the desired property value to be set.
      Returns:
      a copy of this Thing with the Feature containing the given desired property.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • removeFeatureDesiredProperties

      Thing removeFeatureDesiredProperties(CharSequence featureId)
      Removes all desired properties from the given Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature of which all desired properties are to be removed.
      Returns:
      a copy of this Thing with all of the Feature's desired properties removed.
      Throws:
      NullPointerException - if featureId is null.
      Since:
      1.5.0

    • removeFeatureDesiredProperty

      default Thing removeFeatureDesiredProperty(CharSequence featureId, CharSequence propertyPath)
      Removes the given desired property from a Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the desired property to be removed.
      Returns:
      a copy of this Thing with the given Features desired property removed.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • removeFeatureDesiredProperty

      Thing removeFeatureDesiredProperty(CharSequence featureId, org.eclipse.ditto.json.JsonPointer propertyPath)
      Removes the given desired property from a Feature on a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature.
      propertyPath - the hierarchical path within the Feature to the desired property to be removed.
      Returns:
      a copy of this Thing with the given Feature desired property removed.
      Throws:
      NullPointerException - if any argument is null.
      Since:
      1.5.0

    • getLifecycle

      Optional<ThingLifecycle> getLifecycle()
      Returns the current lifecycle of this Thing.
      Returns:
      the current lifecycle of this Thing.

    • setLifecycle

      Thing setLifecycle(ThingLifecycle newLifecycle)
      Sets the given lifecycle to a copy of this Thing.
      Parameters:
      newLifecycle - the lifecycle to set.
      Returns:
      a copy of this Thing with the lifecycle set to newLifecycle.
      Throws:
      NullPointerException - if newLifecycle is null.

    • hasLifecycle

      default boolean hasLifecycle(ThingLifecycle lifecycle)
      Indicates whether this Thing has the given lifecycle.
      Parameters:
      lifecycle - the lifecycle to be checked for.
      Returns:
      true if this Thing has lifecycle as its lifecycle, false else.

    • setPolicyId

      Thing setPolicyId(@Nullable org.eclipse.ditto.policies.model.PolicyId policyId)
      Sets the given Policy ID on a copy of this Thing.
      Parameters:
      policyId - the Policy ID to set.
      Returns:
      a copy of this Thing with policyId as its Policy ID.

    • getPolicyId

      Optional<org.eclipse.ditto.policies.model.PolicyId> getPolicyId()
      Returns the Policy ID of this Thing.
      Returns:
      the Policy ID of this Thing.

    • getFeatures

      Optional<Features> getFeatures()
      Returns the Features of this Thing.
      Returns:
      the Features of this Thing.

    • setFeatures

      Thing setFeatures(@Nullable Features features)
      Sets the given Features to a copy of this Thing.
      Parameters:
      features - the Features to be set.
      Returns:
      a copy of this Thing with the features set.

    • removeFeatures

      Thing removeFeatures()
      Removes all Features from a copy of this Thing.
      Returns:
      a copy of this Thing with all of its Features removed.

    • setFeature

      Thing setFeature(Feature feature)
      Sets the given Feature to a copy of this Thing. An already existing Feature with the same ID is replaced.
      Parameters:
      feature - the Feature to be set.
      Returns:
      a copy of this Thing with the given feature.
      Throws:
      NullPointerException - if feature is null.

    • removeFeature

      Thing removeFeature(String featureId)
      Removes the Feature with the specified ID from a copy of this Thing.
      Parameters:
      featureId - the ID of the Feature to be removed.
      Returns:
      a copy of this Thing without the Feature with the given ID.