Label and description added for channel groups (eclipse-archived#2970)

Implements eclipse-archived#2717

Signed-off-by: Laurent Garnier <[email protected]>

bundles/core/org.eclipse.smarthome.core.thing.xml/src/main/java/org/eclipse/smarthome/core/thing/xml/internal/ThingTypeXmlResult.java

@@ -100,7 +100,8 @@ protected List<ChannelGroupDefinition> toChannelGroupDefinitions(List<ChannelXml
                 String typeUID = String.format("%s:%s", this.thingTypeUID.getBindingId(), typeId);
 
                 ChannelGroupDefinition channelGroupDefinition = new ChannelGroupDefinition(id,
-                        new ChannelGroupTypeUID(typeUID));
+                        new ChannelGroupTypeUID(typeUID), channelGroupTypeReference.getLabel(),
+                        channelGroupTypeReference.getDescription());
 
                 channelGroupTypeDefinitions.add(channelGroupDefinition);
 

bundles/core/org.eclipse.smarthome.core.thing.xml/thing-description-1.0.0.xsd

@@ -113,6 +113,10 @@
     </xs:complexType>
 
     <xs:complexType name="channelGroup">
+        <xs:sequence>
+            <xs:element name="label" type="xs:string" minOccurs="0"/>
+            <xs:element name="description" type="xs:string" minOccurs="0"/>
+        </xs:sequence>
         <xs:attribute name="id" type="config-description:idRestrictionPattern" use="required"/>
         <xs:attribute name="typeId" type="config-description:idRestrictionPattern" use="required"/>
     </xs:complexType>

bundles/core/org.eclipse.smarthome.core.thing/src/main/java/org/eclipse/smarthome/core/thing/i18n/ThingTypeI18nLocalizationService.java

@@ -57,7 +57,12 @@ public ThingType createLocalizedThingType(Bundle bundle, ThingType thingType, Lo
         final List<ChannelGroupDefinition> localizedChannelGroupDefinitions = new ArrayList<>(
                 thingType.getChannelGroupDefinitions().size());
         for (final ChannelGroupDefinition channelGroupDefinition : thingType.getChannelGroupDefinitions()) {
-            localizedChannelGroupDefinitions.add(channelGroupDefinition);
+            final String channelGroupLabel = this.thingTypeI18nUtil.getChannelGroupLabel(bundle,
+                    channelGroupDefinition.getTypeUID(), channelGroupDefinition.getLabel(), locale);
+            final String channelGroupDescription = this.thingTypeI18nUtil.getChannelGroupDescription(bundle,
+                    channelGroupDefinition.getTypeUID(), channelGroupDefinition.getDescription(), locale);
+            localizedChannelGroupDefinitions.add(new ChannelGroupDefinition(channelGroupDefinition.getId(),
+                    channelGroupDefinition.getTypeUID(), channelGroupLabel, channelGroupDescription));
         }
 
         if (thingType instanceof BridgeType) {

bundles/core/org.eclipse.smarthome.core.thing/src/main/java/org/eclipse/smarthome/core/thing/type/ChannelGroupDefinition.java

@@ -23,16 +23,21 @@ public class ChannelGroupDefinition {
 
     private String id;
     private ChannelGroupTypeUID typeUID;
+    private final String label;
+    private final String description;
 
     /**
      * Creates a new instance of this class with the specified parameters.
      *
      * @param id the identifier of the channel group (must neither be null nor empty)
      * @param typeUID the type UID of the channel group (must not be null)
+     * @param label the label for the channel group to override ChannelGroupType (could be null)
+     * @param description the description for the channel group to override ChannelGroupType (could be null)
      *
      * @throws IllegalArgumentException if the ID is null or empty, or the type is null
      */
-    public ChannelGroupDefinition(String id, ChannelGroupTypeUID typeUID) throws IllegalArgumentException {
+    public ChannelGroupDefinition(String id, ChannelGroupTypeUID typeUID, String label, String description)
+            throws IllegalArgumentException {
         if ((id == null) || (id.isEmpty())) {
             throw new IllegalArgumentException("The ID must neither be null nor empty!");
         }
@@ -43,6 +48,20 @@ public ChannelGroupDefinition(String id, ChannelGroupTypeUID typeUID) throws Ill
 
         this.id = id;
         this.typeUID = typeUID;
+        this.label = label;
+        this.description = description;
+    }
+
+    /**
+     * Creates a new instance of this class with the specified parameters.
+     *
+     * @param id the identifier of the channel group (must neither be null nor empty)
+     * @param typeUID the type UID of the channel group (must not be null)
+     *
+     * @throws IllegalArgumentException if the ID is null or empty, or the type is null
+     */
+    public ChannelGroupDefinition(String id, ChannelGroupTypeUID typeUID) throws IllegalArgumentException {
+        this(id, typeUID, null, null);
     }
 
     /**
@@ -63,6 +82,27 @@ public ChannelGroupTypeUID getTypeUID() {
         return this.typeUID;
     }
 
+    /**
+     * Returns the label (if set).
+     * If no label is set, getLabel will return null and the default label for the {@link ChannelGroupType} is used.
+     *
+     * @return the label for the channel group. Can be null.
+     */
+    public String getLabel() {
+        return this.label;
+    }
+
+    /**
+     * Returns the description (if set).
+     * If no description is set, getDescription will return null and the default description for the
+     * {@link ChannelGroupType} is used.
+     *
+     * @return the description for the channel group. Can be null.
+     */
+    public String getDescription() {
+        return this.description;
+    }
+
     @Override
     public String toString() {
         return "ChannelGroupDefinition [id=" + id + ", typeUID=" + typeUID + "]";

bundles/io/org.eclipse.smarthome.io.rest.core/src/main/java/org/eclipse/smarthome/io/rest/core/thing/ThingTypeResource.java

@@ -167,8 +167,20 @@ private List<ChannelGroupDefinitionDTO> convertToChannelGroupDefinitionDTOs(
             String id = channelGroupDefinition.getId();
             ChannelGroupType channelGroupType = TypeResolver.resolve(channelGroupDefinition.getTypeUID(), locale);
 
-            String label = channelGroupType.getLabel();
-            String description = channelGroupType.getDescription();
+            // Default to the channelGroupDefinition label to override the
+            // channelGroupType
+            String label = channelGroupDefinition.getLabel();
+            if (label == null) {
+                label = channelGroupType.getLabel();
+            }
+
+            // Default to the channelGroupDefinition description to override the
+            // channelGroupType
+            String description = channelGroupDefinition.getDescription();
+            if (description == null) {
+                description = channelGroupType.getDescription();
+            }
+
             List<ChannelDefinition> channelDefinitions = channelGroupType.getChannelDefinitions();
             List<ChannelDefinitionDTO> channelDefinitionDTOs = convertToChannelDefinitionDTOs(channelDefinitions,
                     locale);

docs/documentation/development/bindings/xml-reference.md

@@ -299,6 +299,11 @@ Bridge and *Thing* descriptions must be placed as XML file(s) (with the ending `
     OR
     <channel-groups>
       <channel-group id="channelGroupID" typeId="channelGroupTypeID" />
+      OR
+      <channel-group id="channelGroupID" typeId="channelGroupTypeID">
+        <label>String</label>
+        <description>String</description>
+      </channel-group>
       ...
     </channel-groups>
 
@@ -330,6 +335,11 @@ Bridge and *Thing* descriptions must be placed as XML file(s) (with the ending `
     OR
     <channel-groups>
       <channel-group id="channelGroupID" typeId="channelGroupTypeID" />
+      OR
+      <channel-group id="channelGroupID" typeId="channelGroupTypeID">
+        <label>String</label>
+        <description>String</description>
+      </channel-group>
       ...
     </channel-groups>