openhab-jrubyscripting 5.0.0.rc10 → 5.0.0.rc12

data/lib/openhab/core/events/item_command_event.rb

@@ -10,7 +10,7 @@ module OpenHAB
       # Adds methods to core openHAB ItemCommandEvent to make it more natural in Ruby
       class ItemCommandEvent < ItemEvent
         # @!attribute [r] command
-        # @return [Type] The command sent to the item.
+        # @return [Command] The command sent to the item.
         alias_method :command, :item_command
 
         # @!method refresh?

data/lib/openhab/core/events/item_state_changed_event.rb

@@ -14,26 +14,26 @@ module OpenHAB
         include ItemState
 
         #
-        # Check if state was == UNDEF
+        # Check if state was == {UNDEF}
         #
-        # @return [true,false] True if the state is UNDEF, false otherwise
+        # @return [true,false] True if the state is {UNDEF}, false otherwise
         #
         def was_undef?
           old_item_state == UNDEF
         end
 
         #
-        # Check if state was == NULL
+        # Check if state was == {NULL}
         #
-        # @return [true,false] True if the state is NULL, false otherwise
+        # @return [true,false] True if the state is {NULL}, false otherwise
         def was_null?
           old_item_state == NULL
         end
 
         #
-        # Check if state was defined (not UNDEF or NULL)
+        # Check if state was defined (not {UNDEF} or {NULL})
         #
-        # @return [true,false] True if state is not UNDEF or NULL
+        # @return [true,false] True if state is not {UNDEF} or {NULL}
         #
         def was?
           !old_item_state.is_a?(UnDefType)

data/lib/openhab/core/events/item_state_event.rb

@@ -8,26 +8,26 @@ module OpenHAB
       # Helpers common to {ItemStateEvent} and {ItemStateChangedEvent}.
       module ItemState
         #
-        # Check if the state == UNDEF
+        # Check if the state == {UNDEF}
         #
-        # @return [true,false] True if the state is UNDEF, false otherwise
+        # @return [true,false] True if the state is {UNDEF}, false otherwise
         #
         def undef?
           item_state == UNDEF
         end
 
         #
-        # Check if the state == NULL
+        # Check if the state == {NULL}
         #
-        # @return [true,false] True if the state is NULL, false otherwise
+        # @return [true,false] True if the state is {NULL}, false otherwise
         def null?
           item_state == NULL
         end
 
         #
-        # Check if the state is defined (not UNDEF or NULL)
+        # Check if the state is defined (not {UNDEF} or {NULL})
         #
-        # @return [true,false] True if state is not UNDEF or NULL
+        # @return [true,false] True if state is not {UNDEF} or {NULL}
         #
         def state?
           !item_state.is_a?(UnDefType)

data/lib/openhab/core/events/thing_status_info_event.rb

@@ -6,16 +6,18 @@ module OpenHAB
       java_import org.openhab.core.thing.events.ThingStatusInfoChangedEvent,
                   org.openhab.core.thing.events.ThingStatusInfoEvent
 
-      # The {AbstractEvent} sent when a {Things::Thing}'s status has changed.
+      #
+      # The {AbstractEvent} sent when a {Things::Thing Thing's} status has changed.
+      #
       class ThingStatusInfoChangedEvent < AbstractEvent
         # @!attribute [r] uid
-        # @return [Things::ThingUID] The UID of the [Things::Thing] that triggered this event.
+        # @return [Things::ThingUID] The UID of the {Things::Thing Thing} that triggered this event.
         alias_method :uid, :get_thing_uid
         # @!attribute [r] was
-        # @return [Things::ThingStatusInfo] The thing's prior status.
+        # @return [org.openhab.core.thing.ThingStatusInfo] The thing's prior status.
         alias_method :was, :get_old_status_info
         # @!attribute [r] status
-        # @return [Things::ThingStatusInfo] The thing's status.
+        # @return [org.openhab.core.thing.ThingStatusInfo] The thing's status.
         alias_method :status, :status_info
 
         #
@@ -31,12 +33,12 @@ module OpenHAB
       class ThingStatusInfoEvent < AbstractEvent
         #
         # @!attribute [r] uid
-        # @return [Things::ThingUID] The UID of the [Things::Thing] that triggered this event.
+        # @return [Things::ThingUID] The UID of the {Things::Thing Thing} that triggered this event.
         #
         alias_method :uid, :get_thing_uid
         #
         # @!attribute [r] status
-        # @return [Things::ThingStatusInfo] The thing's status.
+        # @return [org.openhab.core.thing.ThingStatusInfo] The thing's status.
         #
         alias_method :status, :status_info
 

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

@@ -45,9 +45,10 @@ module OpenHAB
         # Time types need formatted as ISO8601
         # @!visibility private
         def format_type(command)
-          return Types::DateTimeType.new(command) if command.is_a?(java.time.ZonedDateTime)
+          return command if command.is_a?(Types::DateTimeType)
+          return Types::DateTimeType.new(command.to_zoned_date_time) if command.respond_to?(:to_zoned_date_time)
+          return Types::DateTimeType.new(DSL.try_parse_time_like(command.to_str)) if command.respond_to?(:to_str)
 
-          command = command.iso8601 if command.respond_to?(:iso8601)
           super
         end
       end

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

@@ -8,7 +8,7 @@ module OpenHAB
       #
       # The abstract base class for all items.
       #
-      # @see https://www.openhab.org/javadoc/latest/org/openhab/core/items/genericitem
+      # @see org.openhab.core.items.GenericItem
       #
       class GenericItem
         # @!parse include Item
@@ -49,6 +49,7 @@ module OpenHAB
         #   The item's descriptive label.
         #   @return [String, nil]
 
+        # @!visibility private
         alias_method :hash, :hash_code
 
         # @!attribute [r] raw_state
@@ -162,9 +163,99 @@ module OpenHAB
           # make sure to use Type, because this method is used for both
           # #update and #command
           return type if type.is_a?(Types::Type)
+          return NULL if type.nil?
 
           type.to_s
         end
+
+        #
+        # Defers notifying openHAB of modifications to multiple attributes until the block is complete.
+        #
+        # @param [true, false] force When true, allow modifications to file-based items.
+        #   Normally a FrozenError is raised when attempting to modify file-based items, since
+        #   they will then be out-of-sync with the definition on disk. Advanced users may do this
+        #   knowingly and intentionally though, so an escape hatch is provided to allow runtime
+        #   modifications.
+        # @yield
+        # @return [Object] the block's return value
+        #
+        # @example Modify label and tags for an item
+        #   MySwitch.modify do
+        #     MySwitch.label = "New Label"
+        #     MySwitch.tags = :labeled
+        #   end
+        #
+        def modify(force: false)
+          raise ArgumentError, "you must pass a block to modify" unless block_given?
+          return yield if instance_variable_defined?(:@modifying) && @modifying
+
+          begin
+            provider = self.provider
+            if provider && !provider.is_a?(org.openhab.core.common.registry.ManagedProvider)
+              raise FrozenError, "Cannot modify item #{name} from provider #{provider.inspect}." unless force
+
+              provider = nil
+              logger.debug("Forcing modifications to non-managed item #{name}")
+            end
+            @modified = false
+            @modifying = true
+
+            r = yield
+
+            provider&.update(self) if @modified
+            r
+          ensure
+            @modifying = false
+          end
+        end
+
+        # @!attribute [rw] label
+        # The item's descriptive label.
+        # @return [String]
+        def label=(value)
+          modify do
+            next if label == value
+
+            @modified = true
+            set_label(value)
+          end
+        end
+
+        # @!attribute [rw] category
+        # The item's category.
+        # @return [String]
+        def category=(value)
+          modify do
+            value = value&.to_s
+            next if category == value
+
+            @modified = true
+            set_category(value)
+          end
+        end
+
+        # @!attribute [rw] tags
+        #   The item's tags
+        #   @return [Array<String>]
+        #   @overload tags
+        #     Returns the item's tags.
+        #     @return [Array<String>]
+        #   @overload tags=(values)
+        #     Sets the item's tags.
+        #
+        #     To remove all tags, assign an empty array or nil.
+        #     @param [Array<String,Symbol,Semantics::Tag>] values Tags to set.
+        #     @return [void]
+        def tags=(values)
+          modify do
+            values = DSL::Items::ItemBuilder.normalize_tags(*values)
+            next if values.to_set == tags.to_set
+
+            @modified = true
+            remove_all_tags
+            add_tags(values)
+          end
+        end
       end
     end
   end

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

@@ -24,10 +24,6 @@ module OpenHAB
         #   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
 
@@ -35,7 +31,7 @@ module OpenHAB
         #   @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}.
+        # The item's {GenericItem#label label} if one is defined, otherwise its {#name}.
         #
         # @return [String]
         #
@@ -46,7 +42,7 @@ module OpenHAB
         #
         # @!attribute [r] groups
         #
-        # Return all groups that this item is part of
+        # Returns all groups that this item is part of
         #
         # @return [Array<Group>] All groups that this item is part of
         #
@@ -81,7 +77,7 @@ module OpenHAB
         # @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
+        # @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
         #
@@ -189,7 +185,7 @@ module OpenHAB
         #
         # @return [Array<Thing>] An array of things or an empty array
         def things
-          registry = OSGi.service("org.openhab.core.thing.link.ItemChannelLinkRegistry")
+          registry = Things::Links::Provider.registry
           channels = registry.get_bound_channels(name).to_a
           channels.map(&:thing_uid).uniq.map { |tuid| EntityLookup.lookup_thing(tuid) }.compact
         end
@@ -206,6 +202,11 @@ module OpenHAB
           "#{s}>"
         end
 
+        # @return [org.openhab.core.common.registry.Provider]
+        def provider
+          Provider.registry.provider_for(self)
+        end
+
         private
 
         # Allows sub-classes to append additional details to the type in an inspect string

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

@@ -384,7 +384,7 @@ module OpenHAB
           alias_method :to_s, :inspect
 
           #
-          # @raise [RuntimeError] if the provider is not a
+          # @raise [FrozenError] if the provider is not a
           #   {org.openhab.core.common.registry.ManagedProvider ManagedProvider} that can be updated.
           # @return [org.openhab.core.common.registry.ManagedProvider]
           #

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

@@ -218,8 +218,12 @@ module OpenHAB
             return @hash.each_key(&block) unless attached?
             return to_enum(:each_key) unless block
 
-            Provider.registry.all.each do |meta|
-              yield meta.uid.namespace if meta.uid.item_name == @item_name
+            if Provider.registry.respond_to?(:get_all_namespaces)
+              keys.each(&block)
+            else
+              Provider.registry.all.each do |meta|
+                yield meta.uid.namespace if meta.uid.item_name == @item_name
+              end
             end
             self
           end
@@ -313,6 +317,10 @@ module OpenHAB
 
           # @!visibility private
           def keys
+            if Provider.registry.respond_to?(:get_all_namespaces)
+              return Provider.registry.get_all_namespaces(@item_name).to_a
+            end
+
             each_key.to_a
           end
 

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

@@ -32,8 +32,8 @@ module OpenHAB
           # @return [void]
           #
           def remove_item_metadata(item_name)
-            @elements.delete_if do |k, v|
-              next unless k.item_name == item_name
+            @elements.delete_if do |_k, v|
+              next unless v.uid.item_name == item_name
 
               notify_listeners_about_removed_element(v)
               true

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

@@ -48,6 +48,8 @@ module OpenHAB
         # that state into a {QuantityType} as necessary.
         #
         class HistoricState < SimpleDelegator
+          # @!attribute [r] state
+          # @return [Types::State]
           alias_method :state, :__getobj__
 
           def initialize(state, historic_item)
@@ -70,9 +72,11 @@ module OpenHAB
                               variance_since].freeze
 
         # All persistence methods that require a timestamp
+        # Note the _between methods are automatically created from the _since methods
         PERSISTENCE_METHODS = (QUANTITY_METHODS +
                               %i[changed_since?
-                                 evolution_rate
+                                 count_since
+                                 count_state_changes_since
                                  historic_state
                                  maximum_since
                                  minimum_since
@@ -80,24 +84,24 @@ module OpenHAB
         private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
 
         # @!method persist(service = nil)
-        #   Persist the state of the item
+        #   Persists the state of the item
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [void]
 
         # @!method last_update(service = nil)
-        #   Return the time the item was last updated.
+        #   Returns the time the item was last updated.
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @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
+        #   Returns the average value of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [DecimalType, QuantityType, nil] The average value since `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method average_between(start, finish, service = nil)
-        #   Return the average value of the item's state between two points in time
+        #   Returns the average value of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
@@ -105,14 +109,14 @@ module OpenHAB
         #     or nil if no previous state could be found.
 
         # @!method delta_since(timestamp, service = nil)
-        #   Return the difference value of the item's state since the given time
+        #   Returns the difference value of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [DecimalType, QuantityType, nil] The difference value since `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method delta_between(start, finish, service = nil)
-        #   Return the difference value of the item's state between two points in time
+        #   Returns the difference value of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
@@ -120,14 +124,14 @@ module OpenHAB
         #     or nil if no previous state could be found.
 
         # @!method deviation_since(timestamp, service = nil)
-        #   Return the standard deviation of the item's state since the given time
+        #   Returns the standard deviation of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [DecimalType, QuantityType, nil] The standard deviation since `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method deviation_between(start, finish, service = nil)
-        #   Return the standard deviation of the item's state between two points in time
+        #   Returns the standard deviation of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
@@ -135,14 +139,14 @@ module OpenHAB
         #     or nil if no previous state could be found.
 
         # @!method sum_since(timestamp, service = nil)
-        #   Return the sum of the item's state since the given time
+        #   Returns the sum of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [DecimalType, QuantityType, nil] The sum since `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method sum_between(start, finish, service = nil)
-        #   Return the sum of the item's state between two points in time
+        #   Returns the sum of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
@@ -150,14 +154,14 @@ module OpenHAB
         #     or nil if no previous state could be found.
 
         # @!method variance_since(timestamp, service = nil)
-        #   Return the variance of the item's state since the given time
+        #   Returns the variance of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [DecimalType, QuantityType, nil] The variance since `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method variance_between(start, finish, service = nil)
-        #   Return the variance of the item's state between two points in time
+        #   Returns the variance of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
@@ -178,28 +182,39 @@ module OpenHAB
         #   @return [true,false] True if the item's state changed between `start` and `finish`, False otherwise.
 
         # @!method evolution_rate(timestamp, service = nil)
-        #   Return the evolution rate of the item's state since the given time
-        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
-        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   Returns the evolution rate of the item's state
         #   @return [DecimalType, QuantityType, nil] The evolution rate since `timestamp`,
         #     or nil if no previous state could be found.
+        #   @overload evolution_rate(timestamp, service = nil)
+        #     Returns the evolution rate of the item's state since the given time
+        #     @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #     @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #     @return [DecimalType, QuantityType, nil] The evolution rate since `timestamp`,
+        #       or nil if no previous state could be found.
+        #   @overload evolution_rate(start, finish, service = nil)
+        #     Returns the evolution rate of the item's state between two points in time
+        #     @param [#to_zoned_date_time] start The point in time from which to search
+        #     @param [#to_zoned_date_time] finish The point in time to which to search
+        #     @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #     @return [DecimalType, QuantityType, nil] The evolution rate between `start` and `finish`,
+        #       or nil if no previous state could be found.
 
         # @!method historic_state(timestamp, service = nil)
-        #   Return the the item's state at the given time
+        #   Returns the the item's state at the given time
         #   @param [#to_zoned_date_time] timestamp The point in time at which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [HistoricState, nil] The item's state at `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method maximum_since(timestamp, service = nil)
-        #   Return the maximum value of the item's state since the given time
+        #   Returns the maximum value of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [HistoricState, nil] The maximum value since `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method maximum_between(start, finish, service = nil)
-        #   Return the maximum value of the item's state between two points in time
+        #   Returns the maximum value of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
@@ -207,14 +222,14 @@ module OpenHAB
         #     or nil if no previous state could be found.
 
         # @!method minimum_since(timestamp, service = nil)
-        #   Return the minimum value of the item's state since the given time
+        #   Returns the minimum value of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [HistoricState, nil] The minimum value since `timestamp`,
         #     or nil if no previous state could be found.
 
         # @!method minimum_between(start, finish, service = nil)
-        #   Return the minimum value of the item's state between two points in time
+        #   Returns the minimum value of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
@@ -234,6 +249,32 @@ module OpenHAB
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
         #   @return [true,false] True if the item's state was updated between `start` and `finish`, False otherwise.
 
+        # @!method count_since(timestamp, service = nil)
+        #   Returns the number of available historic data points from a point in time until now.
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
+        # @!method count_between(start, finish, service = nil)
+        #   Returns the number of available historic data points between two points in time.
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
+        # @!method count_state_changes_since(timestamp, service = nil)
+        #   Returns the number of changes in historic data points from a point in time until now.
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
+        # @!method count_state_changes_between(start, finish, service = nil)
+        #   Returns the number of changes in historic data points between two points in time.
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Integer] The number of values persisted for this item.
+
         %i[persist last_update].each do |method|
           define_method(method) do |service = nil|
             service ||= persistence_service
@@ -286,6 +327,43 @@ module OpenHAB
           end
         end
 
+        # evolution_rate's "between" method is overloaded with the same name
+        method = :evolution_rate
+        define_method(method) do |start, finish_or_service = nil, service = nil|
+          if service.nil?
+            if finish_or_service.respond_to?(:to_zoned_date_time)
+              service = persistence_service
+              finish = finish_or_service
+            else
+              service = finish_or_service || persistence_service
+              finish = nil
+            end
+          else
+            finish = finish_or_service
+          end
+
+          result = if finish
+                     Actions::PersistenceExtensions.public_send(
+                       method,
+                       self,
+                       start.to_zoned_date_time,
+                       finish.to_zoned_date_time,
+                       service&.to_s
+                     )
+                   else
+                     Actions::PersistenceExtensions.public_send(
+                       method,
+                       self,
+                       start.to_zoned_date_time,
+                       service&.to_s
+                     )
+                   end
+          wrap_result(result, method)
+        end
+
+        alias_method :state_changes_since, :count_state_changes_since
+        alias_method :state_changes_between, :count_state_changes_between
+
         private
 
         #

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

@@ -16,7 +16,7 @@ module OpenHAB
       # @example Start playing on a player item
       #   Chromecast.play
       # @example Check if a player is paused
-      #   logger.warn("#{item.name} is paused) if Chromecast.paused?
+      #   logger.warn("#{item.name} is paused") if Chromecast.paused?
       #
       class PlayerItem < GenericItem
         # @!method play?