openhab-jrubyscripting 5.0.0.rc4 → 5.0.0.rc6

data/lib/openhab/core/items/generic_item.rb

@@ -10,15 +10,9 @@ module OpenHAB
       #
       # @see https://www.openhab.org/javadoc/latest/org/openhab/core/items/genericitem
       #
-      # @!attribute [r] name
-      #   The item's name.
-      #   @return [String]
-      #
-      # @!attribute [r] label
-      #   The item's descriptive label.
-      #   @return [String, nil]
-      #
       class GenericItem
+        # @!parse include Item
+
         # rubocop:disable Naming/MethodName these mimic Java fields, which are
         # actually methods
         class << self
@@ -36,7 +30,10 @@ module OpenHAB
 
           # @!visibility private
           #
-          # Override to support Proxy
+          # Override to support {Proxy}
+          #
+          # Item.=== isn't actually included (on the Ruby side) into
+          # {GenericItem}
           #
           def ===(other)
             other.is_a?(self)
@@ -44,11 +41,13 @@ module OpenHAB
         end
         # rubocop:enable Naming/MethodName
 
-        # @!attribute [r] accepted_command_types
-        #   @return [Array<Class>] An array of {Command}s that can be sent as commands to this item
+        # @!attribute [r] name
+        #   The item's name.
+        #   @return [String]
 
-        # @!attribute [r] accepted_data_types
-        #   @return [Array<Class>] An array of {State}s that can be sent as commands to this item
+        # @!attribute [r] label
+        #   The item's descriptive label.
+        #   @return [String, nil]
 
         alias_method :hash, :hash_code
 
@@ -62,6 +61,35 @@ module OpenHAB
         #
         alias_method :raw_state, :state
 
+        #
+        # Check if the item has a state (not {UNDEF} or {NULL})
+        #
+        # @return [true, false]
+        #
+        def state?
+          !raw_state.is_a?(Types::UnDefType)
+        end
+
+        #
+        # @!attribute [r] state
+        # @return [State, nil]
+        #   openHAB item state if state is not {UNDEF} or {NULL}, nil otherwise.
+        #   This makes it easy to use with the
+        #   [Ruby safe navigation operator `&.`](https://ruby-doc.org/core-2.6/doc/syntax/calling_methods_rdoc.html)
+        #   Use {#undef?} or {#null?} to check for those states.
+        #
+        def state
+          raw_state if state?
+        end
+
+        # @!method null?
+        #   Check if the item state == {NULL}
+        #   @return [true,false]
+
+        # @!method undef?
+        #   Check if the item state == {UNDEF}
+        #   @return [true,false]
+
         #
         # Send a command to this item
         #
@@ -91,6 +119,10 @@ module OpenHAB
 
         # @!parse alias_method :<<, :command
 
+        # @!method refresh
+        #   Send the {REFRESH} command to the item
+        #   @return [Item] `self`
+
         #
         # Send an update to this item
         #
@@ -105,200 +137,6 @@ module OpenHAB
           Proxy.new(self)
         end
 
-        #
-        # Check if the item has a state (not {UNDEF} or {NULL})
-        #
-        # @return [true, false]
-        #
-        def state?
-          !raw_state.is_a?(Types::UnDefType)
-        end
-
-        #
-        # @!attribute [r] state
-        # @return [State, nil]
-        #   OpenHAB item state if state is not {UNDEF} or {NULL}, nil otherwise.
-        #   This makes it easy to use with the
-        #   [Ruby safe navigation operator `&.`](https://ruby-doc.org/core-2.6/doc/syntax/calling_methods_rdoc.html)
-        #   Use {#undef?} or {#null?} to check for those states.
-        #
-        def state
-          raw_state if state?
-        end
-
-        #
-        # The item's {#label} if one is defined, otherwise it's {#name}.
-        #
-        # @return [String]
-        #
-        def to_s
-          label || name
-        end
-
-        #
-        # @!attribute [r] groups
-        #
-        # Return all groups that this item is part of
-        #
-        # @return [Array<Group>] All groups that this item is part of
-        #
-        def groups
-          group_names.map { |name| EntityLookup.lookup_item(name) }.compact
-        end
-
-        # rubocop:disable Layout/LineLength
-
-        # @!attribute [r] metadata
-        # @return [Metadata::NamespaceHash]
-        #
-        # Access to the item's metadata.
-        #
-        # Both the return value of this method as well as the individual
-        # namespaces can be treated as Hashes.
-        #
-        # Examples assume the following items:
-        #
-        # ```xtend
-        # Switch Item1 { namespace1="value" [ config1="foo", config2="bar" ] }
-        # String StringItem1
-        # ```
-        #
-        # @example Check namespace's existence
-        #   Item1.metadata["namespace"].nil?
-        #   Item1.metadata.key?("namespace")
-        #
-        # @example Access item's metadata value
-        #   Item1.metadata["namespace1"].value
-        #
-        # @example Access namespace1's configuration
-        #   Item1.metadata["namespace1"]["config1"]
-        #
-        # @example Safely search for the specified value - no errors are raised, only nil returned if a key in the chain doesn"t exist
-        #   Item1.metadata.dig("namespace1", "config1") # => "foo"
-        #   Item1.metadata.dig("namespace2", "config1") # => nil
-        #
-        # @example Set item's metadata value, preserving its config
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace1"].value = "new value"
-        #   # Item1's metadata after: {"namespace1"=>["new value", {"config1"=>"foo", "config2"=>"bar"]}}
-        #
-        # @example Set item's metadata config, preserving its value
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace1"].replace({ "scooby"=>"doo" })
-        #   # Item1's metadata after: {"namespace1"=>["value", {scooby="doo"}]}
-        #
-        # @example Set a namespace to a new value and config in one line
-        #   # Item1's metadata before: {"namespace1"=>"value", {"config1"=>"foo", "config2"=>"bar"}}
-        #   Item1.metadata["namespace1"] = "new value", { "scooby"=>"doo" }
-        #   # Item1's metadata after: {"namespace1"=>["new value", {scooby="doo"}]}
-        #
-        # @example Set item's metadata value and clear its previous config
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace1"] = "new value"
-        #   # Item1's metadata after: {"namespace1"=>"value" }
-        #
-        # @example Set item's metadata config, set its value to nil, and wiping out previous config
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace1"] = { "newconfig"=>"value" }
-        #   # Item1's metadata after: {"namespace1"=>{"config1"=>"foo", "config2"=>"bar"}}
-        #
-        # @example Update namespace1's specific configuration, preserving its value and other config
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace1"]["config1"] = "doo"
-        #   # Item1's metadata will be: {"namespace1"=>["value", {"config1"=>"doo", "config2"=>"bar"}]}
-        #
-        # @example Add a new configuration to namespace1
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace1"]["config3"] = "boo"
-        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar", config3="boo"}]}
-        #
-        # @example Delete a config
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace1"].delete("config2")
-        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo"}]}
-        #
-        # @example Add a namespace and set it to a value
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace2"] = "qx"
-        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>"qx"}
-        #
-        # @example Add a namespace and set it to a value and config
-        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace2"] = "qx", { "config1"=>"doo" }
-        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>["qx", {"config1"=>"doo"}]}
-        #
-        # @example Enumerate Item1's namespaces
-        #   Item1.metadata.each { |namespace, metadata| logger.info("Item1's namespace: #{namespace}=#{metadata}") }
-        #
-        # @example Add metadata from a hash
-        #   Item1.metadata.merge!({"namespace1"=>{"foo", {"config1"=>"baz"} ], "namespace2"=>{"qux", {"config"=>"quu"} ]})
-        #
-        # @example Merge Item2's metadata into Item1's metadata
-        #   Item1.metadata.merge!(Item2.metadata)
-        #
-        # @example Delete a namespace
-        #   Item1.metadata.delete("namespace1")
-        #
-        # @example Delete all metadata of the item
-        #   Item1.metadata.clear
-        #
-        # @example Does this item have any metadata?
-        #   Item1.metadata.any?
-        #
-        # @example Store another item's state
-        #   StringItem1.update "TEST"
-        #   Item1.metadata["other_state"] = StringItem1.state
-        #
-        # @example Store event's state
-        #   rule "save event state" do
-        #     changed StringItem1
-        #     run { |event| Item1.metadata["last_event"] = event.was }
-        #   end
-        #
-        # @example If the namespace already exists: Update the value of a namespace but preserve its config; otherwise create a new namespace with the given value and nil config.
-        #   Item1.metadata["namespace"] = "value", Item1.metadata["namespace"]
-        #
-        # @example Copy another namespace
-        #   # Item1's metadata before: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #   Item1.metadata["namespace"] = Item1.metadata["namespace2"]
-        #   # Item1's metadata after: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
-        #
-        def metadata
-          @metadata ||= Metadata::NamespaceHash.new(name)
-        end
-        # rubocop:enable Layout/LineLength
-
-        # Return the item's thing if this item is linked with a thing. If an item is linked to more than one thing,
-        # this method only returns the first thing.
-        #
-        # @return [Thing] The thing associated with this item or nil
-        def thing
-          all_linked_things.first
-        end
-        alias_method :linked_thing, :thing
-
-        # Returns all of the item's linked things.
-        #
-        # @return [Array<Thing>] An array of things or an empty array
-        def things
-          registry = OSGi.service("org.openhab.core.thing.link.ItemChannelLinkRegistry")
-          channels = registry.get_bound_channels(name).to_a
-          channels.map(&:thing_uid).uniq.map { |tuid| EntityLookup.lookup_thing(tuid) }.compact
-        end
-        alias_method :all_linked_things, :things
-
-        # @!method null?
-        #   Check if the item state == {NULL}
-        #   @return [true,false]
-
-        # @!method undef?
-        #   Check if the item state == {UNDEF}
-        #   @return [true,false]
-
-        # @!method refresh
-        #   Send the {REFRESH} command to the item
-        #   @return [GenericItem] `self`
-
         # @!visibility private
         def format_command(command)
           command = format_type(command)
@@ -327,23 +165,6 @@ module OpenHAB
 
           type.to_s
         end
-
-        # @return [String]
-        def inspect
-          s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
-          s += " category=#{category.inspect}" if category
-          s += " tags=#{tags.to_a.inspect}" unless tags.empty?
-          s += " groups=#{group_names}" unless group_names.empty?
-          meta = metadata.to_h
-          s += " metadata=#{meta.inspect}" unless meta.empty?
-          "#{s}>"
-        end
-
-        private
-
-        # Allows sub-classes to append additional details to the type in an inspect string
-        # @return [String]
-        def type_details; end
       end
     end
   end

data/lib/openhab/core/items/group_item.rb

@@ -33,7 +33,7 @@ module OpenHAB
       # ```
       #
       # @!attribute [r] base_item
-      #   @return [GenericItem, nil] A typed item if the group has a particular type.
+      #   @return [Item, nil] A typed item if the group has a particular type.
       #
       # @example Operate on items in a group using enumerable methods
       #   logger.info("Total Temperatures: #{Temperatures.members.count}")
@@ -99,7 +99,9 @@ module OpenHAB
 
           # @return [String]
           def inspect
-            "#<OpenHAB::Core::Items::GroupItems::Members #{name} #{map(&:name).inspect}>"
+            r = "#<OpenHAB::Core::Items::GroupItems::Members #{name}"
+            r += " #{map(&:name).inspect}>" unless @group.__getobj__.nil?
+            "#{r}>"
           end
           alias_method :to_s, :inspect
         end
@@ -120,7 +122,7 @@ module OpenHAB
         # @see Enumerable
         #
         def members
-          Members.new(self)
+          Members.new(Proxy.new(self))
         end
 
         #

data/lib/openhab/core/items/image_item.rb

@@ -79,12 +79,12 @@ module OpenHAB
         private
 
         #
-        # Encode image information in the format required by OpenHAB
+        # Encode image information in the format required by openHAB
         #
         # @param [String] mime_type for image
         # @param [Object] bytes image data
         #
-        # @return [String] OpenHAB image format with image data Base64 encoded
+        # @return [String] openHAB image format with image data Base64 encoded
         #
         def encode_image(mime_type:, bytes:)
           "data:#{mime_type};base64,#{Base64.strict_encode64(bytes)}"

data/lib/openhab/core/items/item.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      # @interface
+      java_import org.openhab.core.items.Item
+
+      #
+      # The core features of an openHAB item.
+      #
+      module Item
+        class << self
+          # @!visibility private
+          #
+          # Override to support {Proxy}
+          #
+          def ===(other)
+            other.is_a?(self)
+          end
+        end
+
+        # @!attribute [r] name
+        #   The item's name.
+        #   @return [String]
+
+        # @!attribute [r] label
+        #   The item's descriptive label.
+        #   @return [String, nil]
+
+        # @!attribute [r] accepted_command_types
+        #   @return [Array<Class>] An array of {Command}s that can be sent as commands to this item
+
+        # @!attribute [r] accepted_data_types
+        #   @return [Array<Class>] An array of {State}s that can be sent as commands to this item
+
+        #
+        # The item's {#label} if one is defined, otherwise it's {#name}.
+        #
+        # @return [String]
+        #
+        def to_s
+          label || name
+        end
+
+        #
+        # @!attribute [r] groups
+        #
+        # Return all groups that this item is part of
+        #
+        # @return [Array<Group>] All groups that this item is part of
+        #
+        def groups
+          group_names.map { |name| EntityLookup.lookup_item(name) }.compact
+        end
+
+        # rubocop:disable Layout/LineLength
+
+        # @!attribute [r] metadata
+        # @return [Metadata::NamespaceHash]
+        #
+        # Access to the item's metadata.
+        #
+        # Both the return value of this method as well as the individual
+        # namespaces can be treated as Hashes.
+        #
+        # Examples assume the following items:
+        #
+        # ```xtend
+        # Switch Item1 { namespace1="value" [ config1="foo", config2="bar" ] }
+        # String StringItem1
+        # ```
+        #
+        # @example Check namespace's existence
+        #   Item1.metadata["namespace"].nil?
+        #   Item1.metadata.key?("namespace")
+        #
+        # @example Access item's metadata value
+        #   Item1.metadata["namespace1"].value
+        #
+        # @example Access namespace1's configuration
+        #   Item1.metadata["namespace1"]["config1"]
+        #
+        # @example Safely search for the specified value - no errors are raised, only nil returned if a key in the chain doesn"t exist
+        #   Item1.metadata.dig("namespace1", "config1") # => "foo"
+        #   Item1.metadata.dig("namespace2", "config1") # => nil
+        #
+        # @example Set item's metadata value, preserving its config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"].value = "new value"
+        #   # Item1's metadata after: {"namespace1"=>["new value", {"config1"=>"foo", "config2"=>"bar"]}}
+        #
+        # @example Set item's metadata config, preserving its value
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"].replace({ "scooby"=>"doo" })
+        #   # Item1's metadata after: {"namespace1"=>["value", {scooby="doo"}]}
+        #
+        # @example Set a namespace to a new value and config in one line
+        #   # Item1's metadata before: {"namespace1"=>"value", {"config1"=>"foo", "config2"=>"bar"}}
+        #   Item1.metadata["namespace1"] = "new value", { "scooby"=>"doo" }
+        #   # Item1's metadata after: {"namespace1"=>["new value", {scooby="doo"}]}
+        #
+        # @example Set item's metadata value and clear its previous config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"] = "new value"
+        #   # Item1's metadata after: {"namespace1"=>"value" }
+        #
+        # @example Set item's metadata config, set its value to nil, and wiping out previous config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"] = { "newconfig"=>"value" }
+        #   # Item1's metadata after: {"namespace1"=>{"config1"=>"foo", "config2"=>"bar"}}
+        #
+        # @example Update namespace1's specific configuration, preserving its value and other config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"]["config1"] = "doo"
+        #   # Item1's metadata will be: {"namespace1"=>["value", {"config1"=>"doo", "config2"=>"bar"}]}
+        #
+        # @example Add a new configuration to namespace1
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"]["config3"] = "boo"
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar", config3="boo"}]}
+        #
+        # @example Delete a config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace1"].delete("config2")
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo"}]}
+        #
+        # @example Add a namespace and set it to a value
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace2"] = "qx"
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>"qx"}
+        #
+        # @example Add a namespace and set it to a value and config
+        #   # Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace2"] = "qx", { "config1"=>"doo" }
+        #   # Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>["qx", {"config1"=>"doo"}]}
+        #
+        # @example Enumerate Item1's namespaces
+        #   Item1.metadata.each { |namespace, metadata| logger.info("Item1's namespace: #{namespace}=#{metadata}") }
+        #
+        # @example Add metadata from a hash
+        #   Item1.metadata.merge!({"namespace1"=>{"foo", {"config1"=>"baz"} ], "namespace2"=>{"qux", {"config"=>"quu"} ]})
+        #
+        # @example Merge Item2's metadata into Item1's metadata
+        #   Item1.metadata.merge!(Item2.metadata)
+        #
+        # @example Delete a namespace
+        #   Item1.metadata.delete("namespace1")
+        #
+        # @example Delete all metadata of the item
+        #   Item1.metadata.clear
+        #
+        # @example Does this item have any metadata?
+        #   Item1.metadata.any?
+        #
+        # @example Store another item's state
+        #   StringItem1.update "TEST"
+        #   Item1.metadata["other_state"] = StringItem1.state
+        #
+        # @example Store event's state
+        #   rule "save event state" do
+        #     changed StringItem1
+        #     run { |event| Item1.metadata["last_event"] = event.was }
+        #   end
+        #
+        # @example If the namespace already exists: Update the value of a namespace but preserve its config; otherwise create a new namespace with the given value and nil config.
+        #   Item1.metadata["namespace"] = "value", Item1.metadata["namespace"]
+        #
+        # @example Copy another namespace
+        #   # Item1's metadata before: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #   Item1.metadata["namespace"] = Item1.metadata["namespace2"]
+        #   # Item1's metadata after: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
+        #
+        def metadata
+          @metadata ||= Metadata::NamespaceHash.new(name)
+        end
+        # rubocop:enable Layout/LineLength
+
+        # Return the item's thing if this item is linked with a thing. If an item is linked to more than one thing,
+        # this method only returns the first thing.
+        #
+        # @return [Thing] The thing associated with this item or nil
+        def thing
+          all_linked_things.first
+        end
+        alias_method :linked_thing, :thing
+
+        # Returns all of the item's linked things.
+        #
+        # @return [Array<Thing>] An array of things or an empty array
+        def things
+          registry = OSGi.service("org.openhab.core.thing.link.ItemChannelLinkRegistry")
+          channels = registry.get_bound_channels(name).to_a
+          channels.map(&:thing_uid).uniq.map { |tuid| EntityLookup.lookup_thing(tuid) }.compact
+        end
+        alias_method :all_linked_things, :things
+
+        # @return [String]
+        def inspect
+          s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
+          s += " category=#{category.inspect}" if category
+          s += " tags=#{tags.to_a.inspect}" unless tags.empty?
+          s += " groups=#{group_names}" unless group_names.empty?
+          meta = metadata.to_h
+          s += " metadata=#{meta.inspect}" unless meta.empty?
+          "#{s}>"
+        end
+
+        private
+
+        # Allows sub-classes to append additional details to the type in an inspect string
+        # @return [String]
+        def type_details; end
+      end
+    end
+  end
+end
+
+# @!parse Item = OpenHAB::Core::Items::Item

data/lib/openhab/core/items/metadata/hash.rb

@@ -111,7 +111,7 @@ module OpenHAB
           end
 
           # @!attribute [r] item
-          #   @return [GenericItem, nil] The item this namespace is attached to.
+          #   @return [Item, nil] The item this namespace is attached to.
           def item
             return nil unless attached?
 

data/lib/openhab/core/items/metadata/namespace_hash.rb

@@ -288,7 +288,7 @@ module OpenHAB
 
           # @!visibility private
           def hash
-            "metadata_namespace_hash".hash + @item_name.hash
+            ["metadata_namespace_hash", @item_name.hash]
           end
 
           # @!visibility private

data/lib/openhab/core/items/persistence.rb

@@ -9,7 +9,7 @@ module OpenHAB
     module Items
       #
       # Items extensions to support
-      # {https://www.openhab.org/docs/configuration/persistence.html OpenHAB's Persistence} feature.
+      # {https://www.openhab.org/docs/configuration/persistence.html openHAB's Persistence} feature.
       #
       # @see OpenHAB::DSL.persistence Persistence Block
       #
@@ -40,16 +40,26 @@ module OpenHAB
       module Persistence
         GenericItem.prepend(self)
 
-        # A state class with an added timestamp attribute. This is used to hold OpenHAB's HistoricItem.
+        #
+        # A state class with an added timestamp attribute.
+        #
+        # This wraps {org.openhab.core.persistence.HistoricItem HistoricItem}
+        # to allow implicitly treating the object as its state, and wrapping of
+        # that state into a {QuantityType} as necessary.
+        #
         class HistoricState < SimpleDelegator
-          attr_reader :timestamp
-
           alias_method :state, :__getobj__
 
-          def initialize(state, timestamp)
-            @timestamp = timestamp
+          def initialize(state, historic_item)
+            @historic_item = historic_item
             super(state)
           end
+
+          # @!attribute [r] timestamp
+          # @return [ZonedDateTime]
+          def timestamp
+            @historic_item.timestamp
+          end
         end
 
         # All persistence methods that could return a QuantityType
@@ -77,7 +87,7 @@ module OpenHAB
         # @!method last_update(service = nil)
         #   Return the time the item was last updated.
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
-        #   @return [ZonedDateTime] The timestamp of the last update
+        #   @return [ZonedDateTime, nil] The timestamp of the last update
 
         # @!method average_since(timestamp, service = nil)
         #   Return the average value of the item's state since the given time
@@ -245,7 +255,7 @@ module OpenHAB
         def previous_state(service = nil, skip_equal: false)
           service ||= persistence_service
           result = Actions::PersistenceExtensions.previous_state(self, skip_equal, service&.to_s)
-          HistoricState.new(quantify(result.state), result.timestamp)
+          HistoricState.new(quantify(result.state), result) if result
         end
 
         PERSISTENCE_METHODS.each do |method|
@@ -307,8 +317,7 @@ module OpenHAB
         #
         def wrap_result(result, method)
           if result.is_a?(org.openhab.core.persistence.HistoricItem)
-            return HistoricState.new(quantify(result.state),
-                                     result.timestamp)
+            return HistoricState.new(quantify(result.state), result)
           end
           return quantify(result) if QUANTITY_METHODS.include?(method)