GeoLocation.java

  1. /**
  2.  *
  3.  * Copyright 2015-2017 Ishan Khanna, Fernando Ramirez, 2019-2020 Florian Schmaus
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.jivesoftware.smackx.geoloc.packet;

  19. import java.io.Serializable;
  20. import java.net.URI;
  21. import java.util.Date;

  23. import javax.xml.namespace.QName;

  25. import org.jivesoftware.smack.packet.ExtensionElement;
  26. import org.jivesoftware.smack.packet.Message;
  27. import org.jivesoftware.smack.util.EqualsUtil;
  28. import org.jivesoftware.smack.util.HashCode;
  29. import org.jivesoftware.smack.util.XmlStringBuilder;

  31. import org.jivesoftware.smackx.xdata.FormField;
  32. import org.jivesoftware.smackx.xdata.FormFieldChildElement;

  34. /**
  35.  * A GeoLocation Extension packet, which is used by the XMPP clients to exchange their respective geographic locations.
  36.  *
  37.  * @see <a href="http://www.xmpp.org/extensions/xep-0080.html">XEP-0080</a>
  38.  * @author Ishan Khanna
  39.  */
  40. public final class GeoLocation implements Serializable, ExtensionElement, FormFieldChildElement {

  42.     private static final long serialVersionUID = 1L;

  44.     public static final String NAMESPACE = "http://jabber.org/protocol/geoloc";

  46.     public static final String ELEMENT = "geoloc";

  48.     public static final QName QNAME = new QName(NAMESPACE, ELEMENT);

  50.     public static final GeoLocation EMPTY_GEO_LOCATION = GeoLocation.builder().build();

  52.     private final Double accuracy;
  53.     private final Double alt;
  54.     private final Double altAccuracy;
  55.     private final String area;
  56.     private final Double bearing;
  57.     private final String building;
  58.     private final String country;
  59.     private final String countryCode;
  60.     private final String datum;
  61.     private final String description;
  62.     private final Double error;
  63.     private final String floor;
  64.     private final Double lat;
  65.     private final String locality;
  66.     private final Double lon;
  67.     private final String postalcode;
  68.     private final String region;
  69.     private final String room;
  70.     private final Double speed;
  71.     private final String street;
  72.     private final String text;
  73.     private final Date timestamp;
  74.     private final String tzo;
  75.     private final URI uri;

  77.     private GeoLocation(Builder builder) {
  78.         accuracy = builder.accuracy;
  79.         alt = builder.alt;
  80.         altAccuracy = builder.altAccuracy;
  81.         area = builder.area;
  82.         bearing = builder.bearing;
  83.         building = builder.building;
  84.         country = builder.country;
  85.         countryCode = builder.countryCode;
  86.         datum = builder.datum;
  87.         description = builder.description;
  88.         error = builder.error;
  89.         floor = builder.floor;
  90.         lat = builder.lat;
  91.         locality = builder.locality;
  92.         lon = builder.lon;
  93.         postalcode = builder.postalcode;
  94.         region = builder.region;
  95.         room = builder.room;
  96.         speed = builder.speed;
  97.         street = builder.street;
  98.         text = builder.text;
  99.         timestamp = builder.timestamp;
  100.         tzo = builder.tzo;
  101.         uri = builder.uri;
  102.     }

  104.     public Double getAccuracy() {
  105.         return accuracy;
  106.     }

  108.     public Double getAlt() {
  109.         return alt;
  110.     }

  112.     public Double getAltAccuracy() {
  113.         return altAccuracy;
  114.     }

  116.     public String getArea() {
  117.         return area;
  118.     }

  120.     public Double getBearing() {
  121.         return bearing;
  122.     }

  124.     public String getBuilding() {
  125.         return building;
  126.     }

  128.     public String getCountry() {
  129.         return country;
  130.     }

  132.     public String getCountryCode() {
  133.         return countryCode;
  134.     }

  136.     public String getDatum() {
  137.         return datum;
  138.     }

  140.     public String getDescription() {
  141.         return description;
  142.     }

  144.     /**
  145.      * Get the error.
  146.      *
  147.      * @return the error.
  148.      * @deprecated use {@link #getAccuracy()} instead.
  149.      */
  150.     @Deprecated
  151.     public Double getError() {
  152.         return error;
  153.     }

  155.     public String getFloor() {
  156.         return floor;
  157.     }

  159.     public Double getLat() {
  160.         return lat;
  161.     }

  163.     public String getLocality() {
  164.         return locality;
  165.     }

  167.     public Double getLon() {
  168.         return lon;
  169.     }

  171.     public String getPostalcode() {
  172.         return postalcode;
  173.     }

  175.     public String getRegion() {
  176.         return region;
  177.     }

  179.     public String getRoom() {
  180.         return room;
  181.     }

  183.     public Double getSpeed() {
  184.         return speed;
  185.     }

  187.     public String getStreet() {
  188.         return street;
  189.     }

  191.     public String getText() {
  192.         return text;
  193.     }

  195.     public Date getTimestamp() {
  196.         return timestamp;
  197.     }

  199.     public String getTzo() {
  200.         return tzo;
  201.     }

  203.     public URI getUri() {
  204.         return uri;
  205.     }

  207.     @Override
  208.     public QName getQName() {
  209.         return QNAME;
  210.     }

  212.     @Override
  213.     public String getElementName() {
  214.         return ELEMENT;
  215.     }

  217.     @Override
  218.     public CharSequence toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) {
  219.         XmlStringBuilder xml = new XmlStringBuilder(this);
  220.         xml.rightAngleBracket();
  221.         xml.optElement("accuracy", accuracy);
  222.         xml.optElement("alt", alt);
  223.         xml.optElement("altaccuracy", altAccuracy);
  224.         xml.optElement("area", area);
  225.         xml.optElement("bearing", bearing);
  226.         xml.optElement("building", building);
  227.         xml.optElement("country", country);
  228.         xml.optElement("countrycode", countryCode);
  229.         xml.optElement("datum", datum);
  230.         xml.optElement("description", description);
  231.         xml.optElement("error", error);
  232.         xml.optElement("floor", floor);
  233.         xml.optElement("lat", lat);
  234.         xml.optElement("locality", locality);
  235.         xml.optElement("lon", lon);
  236.         xml.optElement("postalcode", postalcode);
  237.         xml.optElement("region", region);
  238.         xml.optElement("room", room);
  239.         xml.optElement("speed", speed);
  240.         xml.optElement("street", street);
  241.         xml.optElement("text", text);
  242.         xml.optElement("timestamp", timestamp);
  243.         xml.optElement("tzo", tzo);
  244.         xml.optElement("uri", uri);
  245.         xml.closeElement(this);
  246.         return xml;
  247.     }

  249.     @Override
  250.     public String getNamespace() {
  251.         return NAMESPACE;
  252.     }

  254.     private final HashCode.Cache hashCodeCache = new HashCode.Cache();

  256.     @Override
  257.     public int hashCode() {
  258.         return hashCodeCache.getHashCode(c ->
  259.             c
  260.             .append(accuracy)
  261.             .append(alt)
  262.             .append(altAccuracy)
  263.             .append(area)
  264.             .append(bearing)
  265.             .append(building)
  266.             .append(country)
  267.             .append(countryCode)
  268.             .append(datum)
  269.             .append(description)
  270.             .append(error)
  271.             .append(floor)
  272.             .append(lat)
  273.             .append(locality)
  274.             .append(lon)
  275.             .append(postalcode)
  276.             .append(region)
  277.             .append(room)
  278.             .append(speed)
  279.             .append(street)
  280.             .append(text)
  281.             .append(timestamp)
  282.             .append(tzo)
  283.             .append(uri)
  284.         );
  285.     }

  287.     @Override
  288.     public boolean equals(Object obj) {
  289.         return EqualsUtil.equals(this, obj, (e, o) -> {
  290.             e
  291.             .append(accuracy, o.accuracy)
  292.             .append(altAccuracy, o.altAccuracy)
  293.             .append(area, o.area)
  294.             .append(bearing, o.bearing)
  295.             .append(building, o.building)
  296.             .append(country, o.country)
  297.             .append(countryCode, o.countryCode)
  298.             .append(datum, o.datum)
  299.             .append(description, o.description)
  300.             .append(error, o.error)
  301.             .append(floor, o.floor)
  302.             .append(lat, o.lat)
  303.             .append(locality, o.locality)
  304.             .append(lon, o.lon)
  305.             .append(postalcode, o.postalcode)
  306.             .append(region, o.region)
  307.             .append(room, o.room)
  308.             .append(speed, o.speed)
  309.             .append(street, o.street)
  310.             .append(text, o.text)
  311.             .append(timestamp, o.timestamp)
  312.             .append(tzo, o.tzo)
  313.             .append(uri, o.uri)
  314.             ;
  315.         });
  316.     }

  318.     /**
  319.      * Returns a new instance of {@link Builder}.
  320.      * @return Builder
  321.      */
  322.     public static Builder builder() {
  323.         return new GeoLocation.Builder();
  324.     }

  326.     @Override
  327.     public boolean isExclusiveElement() {
  328.         return true;
  329.     }

  331.     /**
  332.      * Returns the first GeoLocation, or <code>null</code> if it doesn't exist in {@link Message}.
  333.      * <br>
  334.      * @param message The Message stanza containing GeoLocation
  335.      * @return GeoLocation
  336.      */
  337.     public static GeoLocation from(Message message) {
  338.         return message.getExtension(GeoLocation.class);
  339.     }

  341.     /**
  342.      * Returns the first GeoLocation, or <code>null</code> if it doesn't exist in {@link FormField}.
  343.      * <br>
  344.      * @param formField the Formfield containing GeoLocation
  345.      * @return GeoLocation
  346.      */
  347.     public static GeoLocation from(FormField formField) {
  348.         return (GeoLocation) formField.getFormFieldChildElement(QNAME);
  349.     }

  351.     /**
  352.      * This class defines a builder class for {@link GeoLocation}.
  353.      * <br>
  354.      * {@link GeoLocation} instance can be obtained using {@link #build()} method as follows.<br><br>
  355.      * <code>GeoLocation.Builder builder = GeoLocation.builder(); <br>
  356.      *       GeoLocation geoLocation = builder.build();</code>
  357.      *  <br><br>
  358.      *  To set GeoLocation parameters, use their respective setters.
  359.      */
  360.     public static final class Builder {

  362.         private Double accuracy;
  363.         private Double alt;
  364.         private Double altAccuracy;
  365.         private String area;
  366.         private Double bearing;
  367.         private String building;
  368.         private String country;
  369.         private String countryCode;

  371.         // If datum is not included, receiver MUST assume WGS84; receivers MUST implement WGS84; senders MAY use another
  372.         // datum, but it is not recommended.
  373.         private String datum = "WGS84";

  375.         private String description;
  376.         private Double error;
  377.         private String floor;
  378.         private Double lat;
  379.         private String locality;
  380.         private Double lon;
  381.         private String postalcode;
  382.         private String region;
  383.         private String room;
  384.         private Double speed;
  385.         private String street;
  386.         private String text;
  387.         private Date timestamp;
  388.         private String tzo;
  389.         private URI uri;

  391.         /**
  392.          * Deprecated, do not use.
  393.          * @deprecated use {@link GeoLocation#builder()} instead.
  394.          */
  395.         @Deprecated
  396.         // TODO Make constructor private in Smack 4.6.
  397.         public Builder() {
  398.         }

  400.         /**
  401.          * Sets accuracy of horizontal GPS error in meters.
  402.          *
  403.          * @param accuracy accuracy in meters
  404.          * @return Builder
  405.          */
  406.         public Builder setAccuracy(Double accuracy) {
  407.             this.accuracy = accuracy;
  408.             return this;
  409.         }

  411.         /**
  412.          * Sets Altitude in meters above or below sea level.
  413.          *
  414.          * @param alt altitude in meters
  415.          * @return Builder
  416.          */
  417.         public Builder setAlt(Double alt) {
  418.             this.alt = alt;
  419.             return this;
  420.         }

  422.         /**
  423.          * Sets Vertical GPS error in meters.
  424.          *
  425.          * @param altAccuracy altAccuracy in meters
  426.          * @return Builder
  427.          */
  428.         public Builder setAltAccuracy(Double altAccuracy) {
  429.             this.altAccuracy = altAccuracy;
  430.             return this;
  431.         }

  433.         /**
  434.          * Sets a named area such as a campus or neighborhood.
  435.          *
  436.          * @param area the named area
  437.          * @return Builder
  438.          */
  439.         public Builder setArea(String area) {
  440.             this.area = area;
  441.             return this;
  442.         }

  444.         /**
  445.          * Sets GPS bearing (direction in which the entity is heading<br>
  446.          * to reach its next waypoint), measured in decimal degrees,<br>
  447.          * relative to true north.
  448.          *
  449.          * @param bearing bearing in decimal degrees
  450.          * @return Builder
  451.          */
  452.         public Builder setBearing(Double bearing) {
  453.             this.bearing = bearing;
  454.             return this;
  455.         }

  457.         /**
  458.          * Sets a specific building on a street or in an area.
  459.          *
  460.          * @param building name of the building
  461.          * @return Builder
  462.          */
  463.         public Builder setBuilding(String building) {
  464.             this.building = building;
  465.             return this;
  466.         }

  468.         /**
  469.          * Sets the nation where the user is located.
  470.          *
  471.          * @param country user's country of location
  472.          * @return Builder
  473.          */
  474.         public Builder setCountry(String country) {
  475.             this.country = country;
  476.             return this;
  477.         }

  479.         /**
  480.          * Sets The ISO 3166 two-letter country code.
  481.          *
  482.          * @param countryCode two-letter country code
  483.          * @return Builder
  484.          */
  485.         public Builder setCountryCode(String countryCode) {
  486.             this.countryCode = countryCode;
  487.             return this;
  488.         }

  490.         /**
  491.          * Sets GPS Datum.
  492.          *
  493.          * @param datum GPS datum
  494.          * @return Builder
  495.          */
  496.         public Builder setDatum(String datum) {
  497.             this.datum = datum;
  498.             return this;
  499.         }

  501.         /**
  502.          * Sets A natural-language name for or description of the location.
  503.          *
  504.          * @param description description of the location
  505.          * @return Builder
  506.          */
  507.         public Builder setDescription(String description) {
  508.             this.description = description;
  509.             return this;
  510.         }

  512.         /**
  513.          * Sets Horizontal GPS error in arc minutes;<br>
  514.          * this element is deprecated in favor of accuracy.
  515.          *
  516.          * @param error error in arc minutes
  517.          * @return Builder
  518.          * @deprecated use {@link #setAccuracy(Double)} instead.
  519.          */
  520.         @Deprecated
  521.         public Builder setError(Double error) {
  522.             this.error = error;
  523.             return this;
  524.         }

  526.         /**
  527.          * Sets a particular floor in a building.
  528.          *
  529.          * @param floor floor in a building
  530.          * @return Builder
  531.          */
  532.         public Builder setFloor(String floor) {
  533.             this.floor = floor;
  534.             return this;
  535.         }

  537.         /**
  538.          * Sets Latitude in decimal degrees North.
  539.          *
  540.          * @param lat latitude in decimal degrees
  541.          * @return Builder
  542.          */
  543.         public Builder setLat(Double lat) {
  544.             this.lat = lat;
  545.             return this;
  546.         }

  548.         /**
  549.          * Sets Locality within the administrative region,<br>
  550.          * such as a town or city.
  551.          *
  552.          * @param locality locality in a region
  553.          * @return Builder
  554.          */
  555.         public Builder setLocality(String locality) {
  556.             this.locality = locality;
  557.             return this;
  558.         }

  560.         /**
  561.          * Sets Longitude in decimal degrees East.
  562.          *
  563.          * @param lon longitude in decimal degrees
  564.          * @return Builder
  565.          */
  566.         public Builder setLon(Double lon) {
  567.             this.lon = lon;
  568.             return this;
  569.         }

  571.         /**
  572.          * Sets PostalCode used for postal delivery.
  573.          *
  574.          * @param postalcode code for postal delivery
  575.          * @return Builder
  576.          */
  577.         public Builder setPostalcode(String postalcode) {
  578.             this.postalcode = postalcode;
  579.             return this;
  580.         }

  582.         /**
  583.          * Sets an administrative region of the nation,<br>
  584.          * such as a state or province.
  585.          *
  586.          * @param region an administrative region
  587.          * @return Builder
  588.          */
  589.         public Builder setRegion(String region) {
  590.             this.region = region;
  591.             return this;
  592.         }

  594.         /**
  595.          * Sets a particular room in a building.
  596.          *
  597.          * @param room room inside a building
  598.          * @return Builder
  599.          */
  600.         public Builder setRoom(String room) {
  601.             this.room = room;
  602.             return this;
  603.         }

  605.         /**
  606.          * Sets Speed at which the entity is moving, in meters per second.
  607.          *
  608.          * @param speed speed in meters per second
  609.          * @return Builder
  610.          */
  611.         public Builder setSpeed(Double speed) {
  612.             this.speed = speed;
  613.             return this;
  614.         }

  616.         /**
  617.          * Sets a thoroughfare within the locality, or a crossing of two thoroughfares.
  618.          *
  619.          * @param street name of the street
  620.          * @return Builder
  621.          */
  622.         public Builder setStreet(String street) {
  623.             this.street = street;
  624.             return this;
  625.         }

  627.         /**
  628.          * Sets a catch-all element that captures any other information about the location.
  629.          *
  630.          * @param text distinctive feature about the location
  631.          * @return Builder
  632.          */
  633.         public Builder setText(String text) {
  634.             this.text = text;
  635.             return this;
  636.         }

  638.         /**
  639.          * Sets UTC timestamp specifying the moment when the reading was taken.
  640.          *
  641.          * @param timestamp timestamp of the reading
  642.          * @return Builder
  643.          */
  644.         public Builder setTimestamp(Date timestamp) {
  645.             this.timestamp = timestamp;
  646.             return this;
  647.         }

  649.         /**
  650.          * Sets the time zone offset from UTC for the current location.
  651.          *
  652.          * @param tzo time zone offset
  653.          * @return Builder
  654.          */
  655.         public Builder setTzo(String tzo) {
  656.             this.tzo = tzo;
  657.             return this;
  658.         }

  660.         /**
  661.          * Sets URI or URL pointing to information about the location.
  662.          *
  663.          * @param uri uri to the location
  664.          * @return Builder
  665.          */
  666.         public Builder setUri(URI uri) {
  667.             this.uri = uri;
  668.             return this;
  669.         }

  671.         /**
  672.          * This method is called to build {@link GeoLocation} from the Builder.
  673.          *
  674.          * @return GeoLocation
  675.          */
  676.         public GeoLocation build() {
  677.             return new GeoLocation(this);
  678.         }
  679.     }
  680. }
Created with JaCoCo 0.8.6.202009150832