added location field to Thing

fixes eclipse-archived#1083
Signed-off-by: Simon Kaufmann <[email protected]>

bundles/core/org.eclipse.smarthome.core.thing/src/main/java/org/eclipse/smarthome/core/thing/Thing.java

@@ -22,7 +22,7 @@
  *
  * @author Dennis Nobel - Initial contribution and API
  * @author Thomas Höfer - Added thing and thing type properties
- * @author Simon Kaufmann - Added label
+ * @author Simon Kaufmann - Added label, location
  * @author Kai Kreuzer - Removed linked items from Thing
  */
 public interface Thing {
@@ -176,4 +176,20 @@ public interface Thing {
      * @param properties the properties to set (must not be null)
      */
     void setProperties(Map<String, String> properties);
+
+    /**
+     * Get the physical location of the {@link Thing}.
+     *
+     * @return the location identifier (presumably an item name) or <code>null</code> if no location has been
+     *         configured.
+     */
+    String getLocation();
+
+    /**
+     * Set the physical location of the {@link Thing}.
+     *
+     * @param location the location identifier (preferably an item name) or <code>null</code> if no location has been
+     *            configured.
+     */
+    void setLocation(String location);
 }

bundles/core/org.eclipse.smarthome.core.thing/src/main/java/org/eclipse/smarthome/core/thing/binding/builder/GenericThingBuilder.java

@@ -68,6 +68,11 @@ public T withProperties(Map<String, String> properties) {
         return self();
     }
 
+    public T withLocation(String location) {
+        this.thing.setLocation(location);
+        return self();
+    }
+
     public Thing build() {
         return this.thing;
     }

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

@@ -56,6 +56,8 @@ public class ThingImpl implements Thing {
 
     private ThingTypeUID thingTypeUID;
 
+    private String location;
+
     transient volatile private ThingStatusInfo status = ThingStatusInfoBuilder
             .create(ThingStatus.UNINITIALIZED, ThingStatusDetail.NONE).build();
 
@@ -225,6 +227,16 @@ public void setProperties(Map<String, String> properties) {
         this.properties = new HashMap<>(properties);
     }
 
+    @Override
+    public String getLocation() {
+        return location;
+    }
+
+    @Override
+    public void setLocation(String location) {
+        this.location = location;
+    }
+
     @Override
     public int hashCode() {
         final int prime = 31;

bundles/model/org.eclipse.smarthome.model.thing.tests/src/org/eclipse/smarthome/model/thing/tests/GenericThingProviderTest.groovy

@@ -50,7 +50,7 @@ class GenericThingProviderTest extends OSGiTest {
 
         String model =
                 '''
-			Bridge hue:bridge:myBridge [ ip = "1.2.3.4", username = "123" ] {
+			Bridge hue:bridge:myBridge @ "basement" [ ip = "1.2.3.4", username = "123" ] {
 				LCT001 bulb1 [ lightId = "1" ] { Switch : notification }
 				Bridge bridge myBridge2 [ ] {
 					LCT001 bulb2 [ ]
@@ -60,7 +60,7 @@ class GenericThingProviderTest extends OSGiTest {
                 Switch : notification [ duration = "5" ]
             }
 
-			hue:LCT001:bulb3 [ lightId = "4" ] {
+			hue:LCT001:bulb3 @ "livingroom" [ lightId = "4" ] {
 				Switch : notification [ duration = "5" ]
 			}
 			'''
@@ -81,6 +81,7 @@ class GenericThingProviderTest extends OSGiTest {
         assertThat bridge1.configuration.get("ip"), is("1.2.3.4")
         assertThat bridge1.configuration.get("username"), is("123")
         assertThat bridge1.thingTypeUID.toString(), is("hue:bridge")
+        assertThat bridge1.location, is("basement")
 
         def bridge2 = actualThings.find {
             "hue:bridge:myBridge:myBridge2".equals(it.UID.toString())
@@ -142,6 +143,7 @@ class GenericThingProviderTest extends OSGiTest {
         assertThat bulb3.configuration.values().size(), is(1)
         assertThat bulb3.configuration.get("lightId"), is("4")
         assertThat bulb3.thingTypeUID.toString(), is("hue:LCT001")
+        assertThat bulb3.location, is("livingroom")
     }
 
     @Test

bundles/model/org.eclipse.smarthome.model.thing/src/org/eclipse/smarthome/model/thing/Thing.xtext

@@ -21,14 +21,15 @@ ModelBridge returns ModelThing:
 	{ModelBridge}
 	bridge?='Bridge' (id=UID | thingTypeId=UID_SEGMENT thingId=UID_SEGMENT)
     (label=STRING)?
+    ('@' location=STRING)?
 	('['
 		properties+=ModelProperty? (',' properties+=ModelProperty)*
 	']')?
 	('{'
 		('Things:')?
 		things+=(ModelThing|ModelBridge)*
 		('Channels:')?			
-		channels+=ModelChannel*
+		channels+=ModelChannel*   
 
 	'}')?
 ;
@@ -37,6 +38,7 @@ ModelThing:
 	('Thing')? (id=UID | thingTypeId=UID_SEGMENT thingId=UID_SEGMENT)
 	(label=STRING)?
 	('(' bridgeUID = UID ')')?
+	('@' location=STRING)?
 	('['
 		properties+=ModelProperty? (',' properties+=ModelProperty)*
 	']')?

bundles/model/org.eclipse.smarthome.model.thing/src/org/eclipse/smarthome/model/thing/internal/GenericThingProvider.xtend

@@ -139,6 +139,8 @@ class GenericThingProvider extends AbstractProvider<Thing> implements ThingProvi
         val thingType = thingTypeUID.thingType
 
         val label = if(modelThing.label != null) modelThing.label else thingType?.label
+
+        val location = modelThing.location
 
         val thingFromHandler = getThingFromThingHandlerFactories(thingTypeUID, label, configuration, thingUID,
             bridgeUID, thingHandlerFactory)
@@ -152,6 +154,7 @@ class GenericThingProvider extends AbstractProvider<Thing> implements ThingProvi
         thingBuilder.withConfiguration(configuration)
         thingBuilder.withBridge(bridgeUID)
         thingBuilder.withLabel(label)
+        thingBuilder.withLocation(location)
 
         val channels = createChannels(thingTypeUID, thingUID, modelThing.channels,
             thingType?.channelDefinitions ?: newArrayList)
@@ -229,7 +232,7 @@ class GenericThingProvider extends AbstractProvider<Thing> implements ThingProvi
         targetThing.bridgeUID = sourceThing.bridgeUID
         targetThing.configuration.merge(sourceThing.configuration)
         targetThing.merge(sourceThing.channels)
-
+        targetThing.location = sourceThing.location
     }
 
     def dispatch void merge(Configuration target, Configuration source) {

docs/documentation/features/dsl.md

@@ -20,10 +20,14 @@ Things can be defined as followed:
 
 ```
 Thing yahooweather:weather:berlin [ location="638242" ]
-Thing yahooweather:weather:losangeles "Los Angeles" [ location="2442047", unit="us", refresh=120 ]
+Thing yahooweather:weather:losangeles "Los Angeles" @ "home" [ location="2442047", unit="us", refresh=120 ]
 ```
 
-The first keyword defines whether the entry is a bridge or a thing. The next statement defines the UID of the thing which contains of the following three segments: binding id, thing type id, thing id. So the first two segments must match to thing type supported by a binding (e.g. `yahooweather:weatheryahooweather`), whereas the thing id can be freely defined. Optionally, you may provide a label in order to recognize it easily, otherwise the default label from the thing type will be displayed. Inside the squared brackets configuration parameters of the thing are defined.
+The first keyword defines whether the entry is a bridge or a thing. The next statement defines the UID of the thing which contains of the following three segments: binding id, thing type id, thing id. So the first two segments must match to thing type supported by a binding (e.g. `yahooweather:weatheryahooweather`), whereas the thing id can be freely defined. Optionally, you may provide a label in order to recognize it easily, otherwise the default label from the thing type will be displayed. 
+
+To help organizing your things, you also may define a location (here: "home"), which should point to an item. This item can either be a simple String item carrying e.g. the room name, or you may of course also use a Location item containing some geo coordinates.  
+
+Inside the squared brackets configuration parameters of the thing are defined.
 
 The type of the configuration parameter is determined by the binding and must be specified accordingly in the DSL. If the binding requires a text the configuration parameter must be specified as a string: `location="2442047"`. Other types are decimal values (`refresh=12`) and boolean values (`refreshEnabled=true`).