Rework semantics for openHAB 4.0.0.M5

.github/workflows/ci.yml

@@ -70,7 +70,7 @@ jobs:
     if: "!contains(github.event.head_commit.message, 'ci skip')"
     outputs:
       openhab_matrix: |
-        ["3.4.3", "4.0.0.M3", "4.0.0-SNAPSHOT"]
+        ["3.4.3", "4.0.0.RC1", "4.0.0-SNAPSHOT"]
       snapshot_date: |
         ${{ steps.snapshot-date.outputs.SNAPSHOT_DATE }}
     steps:
@@ -128,7 +128,7 @@ jobs:
         openhab_version: ${{ fromJson(needs.openhab-matrix.outputs.openhab_matrix) }}
         jruby_version: ["jruby-9.3.10.0", "jruby-9.4.3.0"]
         exclude:
-          - openhab_version: 4.0.0.M3
+          - openhab_version: 4.0.0.RC1
             jruby_version: jruby-9.3.10.0
           - openhab_version: 4.0.0-SNAPSHOT
             jruby_version: jruby-9.3.10.0

lib/openhab/core/items/item.rb

@@ -218,9 +218,19 @@ def metadata
         # @example
         #   event.item.tagged?("Setpoint")
         #
+        # @example
+        #   event.item.tagged?(Semantics::Switch)
+        #
         def tagged?(*tags)
           tags.map! do |tag|
-            tag.is_a?(Module) ? tag.simple_name : tag
+            # @deprecated OH3.4
+            if tag.is_a?(Module)
+              tag.simple_name
+            elsif defined?(Semantics::SemanticTag) && tag.is_a?(Semantics::SemanticTag)
+              tag.name
+            else
+              tag
+            end
           end
           !(self.tags.to_a & tags).empty?
         end

lib/openhab/core/items/semantics/provider.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      module Semantics
+        #
+        # Provides {SemanticTag SemanticTags} created in Ruby to openHAB
+        #
+        class Provider < Core::Provider
+          begin
+            include org.openhab.core.semantics.SemanticTagProvider
+          rescue NameError
+            # @deprecated OH3.4
+          end
+
+          class << self
+            #
+            # The SemanticTag registry
+            #
+            # @return [org.openhab.core.semantics.SemanticTagRegistry, nil]
+            # @since openHAB 4.0
+            #
+            def registry
+              unless instance_variable_defined?(:@registry)
+                @registry = OSGi.service("org.openhab.core.semantics.SemanticTagRegistry")
+              end
+              @registry
+            end
+          end
+        end
+      end
+    end
+  end
+end

lib/openhab/core/items/semantics/semantic_tag.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# @deprecated OH3.4
+return unless OpenHAB::Core::Items::Semantics::Provider.registry
+
+module OpenHAB
+  module Core
+    module Items
+      module Semantics
+        java_import org.openhab.core.semantics.SemanticTag
+
+        # @since openHAB 4.0
+        module SemanticTag
+          # @attribute [r] uid
+          #
+          # The tag's full UID, including ancestors.
+          #
+          # @return [String]
+
+          # @attribute [r] parent_uid
+          #
+          # The UID of the tag's parent.
+          #
+          # @return [String]
+
+          # @attribute [r] name
+          #
+          # The tag's simple name.
+          #
+          # @return [String]
+
+          # @attribute [r] label
+          #
+          # The tag's human readable label.
+          #
+          # @return [String]
+
+          # @attribute [r] description
+          #
+          # The tag's full description.
+          #
+          # @return [String]
+
+          # @attribute [r] synonyms
+          #
+          # Allowed synonyms for the tag.
+          #
+          # @return [java.util.List<String>]
+
+          # @method localized(locale)
+          #
+          # Returns a new {SemanticTag SemanticTag} localized to the specified locale.
+          #
+          # @param locale [java.util.Locale] The locale to localize this tag to
+          # @return [SemanticTag]
+
+          # @!visibility private
+          def <(other)
+            check_type(other)
+            uid != other.uid && uid.start_with?(other.uid)
+          end
+
+          # @!visibility private
+          def <=(other)
+            check_type(other)
+            uid.start_with?(other.uid)
+          end
+
+          # @!visibility private
+          def ==(other)
+            check_type(other)
+            uid == other.uid
+          end
+
+          # @!visibility private
+          def >=(other)
+            check_type(other)
+            other.uid.start_with?(uid)
+          end
+
+          # @!visibility private
+          def >(other)
+            check_type(other)
+            uid != other.uid && other.uid.start_with?(uid)
+          end
+
+          # @return [String]
+          def inspect
+            parent = "(#{parent_uid})" unless parent_uid.empty?
+            "#<OpenHAB::Core::Items::Semantics::#{name}#{parent} " \
+              "label=#{label.inspect} " \
+              "description=#{description.inspect} " \
+              "synonyms=#{synonyms.to_a.inspect}>"
+          end
+
+          private
+
+          def check_type(other)
+            raise ArgumentError, "comparison of #{other.class} with SemanticTag failed" unless other.is_a?(SemanticTag)
+          end
+        end
+      end
+    end
+  end
+end

lib/openhab/core/items/semantics/tag_class_methods.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Items
+      module Semantics
+        # @deprecated OH3.4 didn't have SemanticTag class
+
+        #
+        # Adds tag attributes to the semantic tag class
+        #
+        module TagClassMethods
+          # @!visibility private
+          java_import org.openhab.core.semantics.SemanticTags
+
+          #
+          # Returns the tag's label
+          #
+          # @param [java.util.Locale] locale The locale that the label should be in, if available.
+          #   When nil, the system's default locale is used.
+          #
+          # @return [String] The tag's label
+          #
+          def label(locale = nil)
+            SemanticTags.get_label(java_class, locale || java.util.Locale.default)
+          end
+
+          #
+          # Returns the tag's synonyms
+          #
+          # @param [java.util.Locale] locale The locale that the label should be in, if available.
+          #   When nil, the system's default locale is used.
+          #
+          # @return [Array<String>] The list of synonyms in the requested locale.
+          #
+          def synonyms(locale = nil)
+            unless SemanticTags.respond_to?(:get_synonyms)
+              return java_class.get_annotation(org.openhab.core.semantics.TagInfo.java_class).synonyms
+                               .split(",").map(&:strip)
+            end
+
+            SemanticTags.get_synonyms(java_class, locale || java.util.Locale.default).to_a
+          end
+
+          #
+          # Returns the tag's description
+          #
+          # @param [java.util.Locale] locale The locale that the description should be in, if available.
+          #   When nil, the system's default locale is used.
+          #
+          # @return [String] The tag's description
+          #
+          def description(locale = nil)
+            unless SemanticTags.respond_to?(:get_description)
+              return java_class.get_annotation(org.openhab.core.semantics.TagInfo.java_class).description
+            end
+
+            SemanticTags.get_description(java_class, locale || java.util.Locale.default)
+          end
+        end
+      end
+    end
+  end
+end

lib/openhab/core/provider.rb

@@ -214,15 +214,17 @@ def update(element)
 
       # @!visibility private
       def unregister
-        self.class.registry.remove_provider(self)
+        # @deprecated OH3.4 safe navigation only required for missing Semantics registry
+        self.class.registry&.remove_provider(self)
       end
 
       private
 
       def initialize(unload_priority: nil)
         super()
         @elements = java.util.concurrent.ConcurrentHashMap.new
-        self.class.registry.add_provider(self)
+        # @deprecated OH3.4 safe navigation only required for missing Semantics registry
+        self.class.registry&.add_provider(self)
         ScriptHandling.script_unloaded(priority: unload_priority) { unregister }
       end
     end

lib/openhab/dsl/items/builder.rb

@@ -222,13 +222,17 @@ def item_factory
           #
           # @!visibility private
           def normalize_tags(*tags)
-            semantics = proc { |tag| tag.respond_to?(:java_class) && tag < Semantics::Tag }
+            # @deprecated OH3.4 didn't have SemanticTag
+            old_semantics = proc { |tag| tag.is_a?(Module) && tag < Semantics::Tag }
+            # @deprecated OH3.4 defined? check is unnecessary
+            semantics = proc { |tag| defined?(Semantics::SemanticTag) && tag.is_a?(Semantics::SemanticTag) }
 
             tags.compact.map do |tag|
               case tag
               when String then tag
               when Symbol then tag.to_s
-              when semantics then tag.java_class.simple_name
+              when old_semantics then tag.java_class.simple_name
+              when semantics then tag.name
               else raise ArgumentError, "`#{tag}` must be a subclass of Semantics::Tag, a `Symbol`, or a `String`."
               end
             end

lib/openhab/rspec/hooks.rb

@@ -65,6 +65,7 @@ class << self
         # Each spec gets temporary providers
         [Core::Items::Provider,
          Core::Items::Metadata::Provider,
+         Core::Items::Semantics::Provider,
          Core::Rules::Provider,
          Core::Things::Provider,
          Core::Things::Links::Provider].each do |klass|

spec/openhab/core/items/semantics_spec.rb

@@ -276,13 +276,13 @@ def points(*args)
     describe "#add" do
       it "works" do
         Semantics.add(SecretRoom: Semantics::Room)
-        expect(Semantics::SecretRoom.java_class < Semantics::Room.java_class).to be true
+        expect(Semantics::SecretRoom < Semantics::Room).to be true
 
         Semantics.add(SecretEquipment: Semantics::Equipment)
-        expect(Semantics::SecretEquipment.java_class < Semantics::Equipment.java_class).to be true
+        expect(Semantics::SecretEquipment < Semantics::Equipment).to be true
 
         Semantics.add(SecretPoint: Semantics::Point)
-        expect(Semantics::SecretPoint.java_class < Semantics::Point.java_class).to be true
+        expect(Semantics::SecretPoint < Semantics::Point).to be true
 
         items.build do
           group_item TestLoc, tag: Semantics::SecretRoom do
@@ -302,17 +302,17 @@ def points(*args)
 
       it "supports tag name as string" do
         Semantics.add("StringTag" => Semantics::Equipment)
-        expect(Semantics::StringTag.java_class < Semantics::Tag.java_class).to be true
+        expect(Semantics::StringTag < Semantics::Equipment).to be true
       end
 
       it "supports parent name as string" do
         Semantics.add(StringParent: "Equipment")
-        expect(Semantics::StringParent.java_class < Semantics::Tag.java_class).to be true
+        expect(Semantics::StringParent < Semantics::Equipment).to be true
       end
 
       it "supports parent name as symbol" do
         Semantics.add(SymParent: :Equipment)
-        expect(Semantics::SymParent.java_class < Semantics::Tag.java_class).to be true
+        expect(Semantics::SymParent < Semantics::Equipment).to be true
       end
 
       it "supports creating multiple tags" do
@@ -331,7 +331,6 @@ def points(*args)
         created = Semantics.add(ArrayTag1: :Equipment, ArrayTag2: :Location, ArrayTag3: :Point,
                                 LivingRoom: Semantics::Room)
         expect(created).to match_array([Semantics::ArrayTag1, Semantics::ArrayTag2, Semantics::ArrayTag3])
-        expect(created).not_to include(Semantics::LivingRoom)
 
         created = Semantics.add(ArrayTag1: :Equipment, ArrayTag2: :Location, ArrayTag3: :Point)
         expect(created).to be_empty
@@ -340,14 +339,9 @@ def points(*args)
       it "supports specifying label, synonyms, and description for the tag" do
         Semantics.add(Detailed: Semantics::Equipment, label: "Label 1", synonyms: "Synonym 2",
                       description: "Description 3")
-        java_import org.openhab.core.semantics.SemanticTags
-        locale = java.util.Locale.default
         expect(Semantics::Detailed.label).to eq "Label 1"
-        expect(SemanticTags.get_by_label_or_synonym("Synonym 2", locale).first).to eql Semantics::Detailed.java_class
-        description = Semantics::Detailed.java_class
-                                         .get_annotation(org.openhab.core.semantics.TagInfo.java_class)
-                                         .description
-        expect(description).to eq "Description 3"
+        expect(Semantics.lookup("Synonym 2")).to eql Semantics::Detailed
+        expect(Semantics::Detailed.description).to eq "Description 3"
       end
 
       it "supports synonyms in an array" do