Package org.eclipse.ditto.model.things

Interface Thing

  • All Superinterfaces:
    org.eclipse.ditto.model.base.entity.Entity<ThingRevision>, org.eclipse.ditto.model.base.json.Jsonifiable<org.eclipse.ditto.json.JsonObject>, org.eclipse.ditto.model.base.json.Jsonifiable.WithFieldSelector, org.eclipse.ditto.model.base.json.Jsonifiable.WithFieldSelectorAndPredicate<org.eclipse.ditto.json.JsonField>, org.eclipse.ditto.model.base.json.Jsonifiable.WithPointer<org.eclipse.ditto.json.JsonObject>, org.eclipse.ditto.model.base.json.Jsonifiable.WithPredicate<org.eclipse.ditto.json.JsonObject,​org.eclipse.ditto.json.JsonField>
    @Immutable
public interface Thing
extends org.eclipse.ditto.model.base.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.

    • Field Detail

      • MIN_REQUIRED_PERMISSIONS

        @Deprecated
static final Permissions MIN_REQUIRED_PERMISSIONS
        Deprecated.
        Permissions belong to deprecated API version 1. Use API version 2 with policies instead.
        The set of permissions which at least must be present in the ACL of a Thing for one Authorization Subject.

    • Method Detail

      • 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.model.base.json.JsonSchemaVersion getImplementedSchemaVersion()
        Specified by:
        getImplementedSchemaVersion in interface org.eclipse.ditto.model.base.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.model.base.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.

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

      • getAccessControlList

        @Deprecated
Optional<AccessControlList> getAccessControlList()
        Deprecated.
        AccessControlLists belong to deprecated API version 1. Use API version 2 with policies instead.
        Returns the Access Control List of this Thing.
        Returns:
        the Access Control List of this Thing.

      • setAccessControlList

        @Deprecated
Thing setAccessControlList​(AccessControlList accessControlList)
        Deprecated.
        AccessControlLists belong to deprecated API version 1. Use API version 2 with policies instead.
        Sets the given Access Control List on a copy of this Thing. Removes any Policy and Policy ID from this Thing.
        Parameters:
        accessControlList - the Access Control List to be set.
        Returns:
        a copy of this Thing with accessControlList as its ACL.

      • setAclEntry

        @Deprecated
Thing setAclEntry​(AclEntry aclEntry)
        Deprecated.
        AccessControlLists belong to deprecated API version 1. Use API version 2 with policies instead.
        Sets the given ACL entry to the Access Control List of a copy of this Thing. An already existing entry with the same authorization subject is overwritten.
        Parameters:
        aclEntry - the entry to be set.
        Returns:
        a copy of this Thing with the changed ACL.
        Throws:
        NullPointerException - if aclEntry is null.

      • removeAllPermissionsOf

        @Deprecated
Thing removeAllPermissionsOf​(org.eclipse.ditto.model.base.auth.AuthorizationSubject authorizationSubject)
        Deprecated.
        Permissions belong to deprecated API version 1. Use API version 2 with policies instead.
        Removes all permissions which are associated to the specified authorization subject in the Access Control List of a copy of this Thing.
        Parameters:
        authorizationSubject - the authorization subject of which all permissions are to be removed.
        Returns:
        a copy of this Thing whose ACL does not contain any entries which are associated with the specified authorization subject.
        Throws:
        NullPointerException - if authorizationSubject is null.

      • getPolicyId

        @Deprecated
default Optional<String> getPolicyId()
        Deprecated.
        Policy ID of the thing is now typed. Use getPolicyEntityId() instead.
        Returns the Policy ID of this Thing.
        Returns:
        the Policy ID of this Thing.

      • setPolicyId

        @Deprecated
default Thing setPolicyId​(@Nullable
                          String policyId)
        Deprecated.
        Policy ID of the thing is now typed. Use setPolicyId(PolicyId) ()} instead.
        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.

      • setPolicyId

        Thing setPolicyId​(@Nullable
                  org.eclipse.ditto.model.policies.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.

      • getPolicyEntityId

        Optional<org.eclipse.ditto.model.policies.PolicyId> getPolicyEntityId()
        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.

      • validate

        @Deprecated
default void validate​(org.eclipse.ditto.model.base.headers.DittoHeaders headers)
        Deprecated.
        this method does nothing anymore. IDs are now typed and already validated.