improved XML_Handler with documentation and style improvements

APED/app/src/main/java/com/example/aped/utils/XMLHandler.java

@@ -10,7 +10,6 @@ import org.xml.sax.SAXException;
 
 import java.io.File;
 import java.io.IOException;
-import java.lang.annotation.Documented;
 import java.util.ArrayList;
 import java.util.Dictionary;
 import java.util.Hashtable;
@@ -26,7 +25,6 @@ import javax.xml.validation.SchemaFactory;
 import javax.xml.validation.Validator;
 import javax.xml.xpath.XPath;
 import javax.xml.xpath.XPathConstants;
-import javax.xml.xpath.XPathException;
 import javax.xml.xpath.XPathExpression;
 import javax.xml.xpath.XPathExpressionException;
 import javax.xml.xpath.XPathFactory;
@@ -35,20 +33,19 @@ import kotlin.NotImplementedError;
 
 public class XMLHandler implements IXML {
 
-    /** the root of the XMl file **/
+    /** the root of the XMl file. **/
     private Document root;
 
     /**
-     * constructor for the XMLHandler
+     * constructor for the XMLHandler.
      * @param xmlPath the path to the XML file
      * @param xsdPath the path to the XSD file
      * @throws ParserConfigurationException the XML parser configuration failed
      * @throws IOException the XML file could not be accessed
      * @throws SAXException the XML parse failed
      */
-    public XMLHandler(String xmlPath, String xsdPath)
+    public XMLHandler(final String xmlPath, final String xsdPath)
-        throws ParserConfigurationException, IOException, SAXException
+        throws ParserConfigurationException, IOException, SAXException {
-    {
         if (!validate(xmlPath, xsdPath)) {
             throw new VerifyError("the XML file is invalid");
         }
@@ -59,12 +56,12 @@ public class XMLHandler implements IXML{
     }
 
     /**
-     * validates a XML file against a XSD file
+     * validates a XML file against a XSD file.
      * @param xmlPath the path to the XML file
      * @param xsdPath the path to the XSD file
      * @return true if XML is valid
      */
-    private boolean validate(String xmlPath, String xsdPath){
+    private boolean validate(final String xmlPath, final String xsdPath) {
         try {
             SchemaFactory factory = SchemaFactory.newInstance(
                     XMLConstants.W3C_XML_SCHEMA_NS_URI
@@ -74,8 +71,8 @@ public class XMLHandler implements IXML{
             validator.validate(new StreamSource(new File(xmlPath)));
         } catch (IOException | SAXException e) {
             Log.e("XMLHandler",
-                    "Error while validating the XML file" +
+                    "Error while validating the XML file"
-                            e.getMessage());
+                        + e.getMessage());
             return false;
         }
         return true;
@@ -91,6 +88,10 @@ public class XMLHandler implements IXML{
         throw new NotImplementedError();
     }
 
+    /**
+     * reads the device names from the XML file.
+     * @return the device names as a list of strings
+     */
     @Override
     public List<String> getDeviceNames() {
         List<String> returnList = new ArrayList<>();
@@ -101,14 +102,21 @@ public class XMLHandler implements IXML{
         return returnList;
     }
 
+    /**
+     * reads the value info from the XML file.
+     * @param deviceName the name of the relevant device
+     * @return the value info as a dictionary {'unit','type','Offset','Factor'}
+     */
     @Override
-    public Dictionary<String, Object> getValueInfo(String deviceName) {
+    public Dictionary<String, Object> getValueInfo(final String deviceName) {
         Dictionary<String, Object> returnDictionary = new Hashtable<>();
         XPathFactory xPathFactory = XPathFactory.newInstance();
         XPath xPath = xPathFactory.newXPath();
         try {
-            XPathExpression xPathExpression = xPath.compile("//Device[@name='" + deviceName + "']/ValueInfo");
+            XPathExpression xPathExpression = xPath.compile(
-            Element result = (Element) xPathExpression.evaluate(root, XPathConstants.NODE);
+                    "//Device[@name='" + deviceName + "']/ValueInfo");
+            Element result = (Element) xPathExpression.evaluate(
+                    root, XPathConstants.NODE);
             returnDictionary.put("type", result.getAttribute("type"));
             returnDictionary.put("unit", result.getAttribute("unit"));
             NodeList childNodes = result.getChildNodes();
@@ -117,10 +125,12 @@ public class XMLHandler implements IXML{
             for (int i = 0; i < childNodes.getLength(); i++) {
                 switch (childNodes.item(i).getNodeName()) {
                     case "Offset":
-                        offset = Float.parseFloat(childNodes.item(i).getTextContent());
+                        offset = Float.parseFloat(childNodes.item(i)
+                                .getTextContent());
                         break;
                     case "Factor":
-                        factor = Float.parseFloat(childNodes.item(i).getTextContent());
+                        factor = Float.parseFloat(childNodes.item(i)
+                                .getTextContent());
                         break;
                     default:
                         break;
@@ -129,19 +139,30 @@ public class XMLHandler implements IXML{
             returnDictionary.put("offset", offset);
             returnDictionary.put("factor", factor);
         } catch (XPathExpressionException e) {
-            Log.e("XMLHandler","the XPath for getting the value info has errors:" + e.getMessage());
+            Log.e(
+                    "XMLHandler",
+                    "the XPath for getting the value info has errors:"
+                            + e.getMessage()
+            );
         }
         return returnDictionary;
     }
 
+    /**
+     * reads the port information from the XML file.
+     * @param deviceName the name of the relevant device
+     * @return the port information as a dictionary {'protocol','pins'}
+     */
     @Override
-    public Dictionary<String, Object> getPort(String deviceName) {
+    public Dictionary<String, Object> getPort(final String deviceName) {
         Dictionary<String, Object> returnDictionary = new Hashtable<>();
         XPathFactory xPathFactory = XPathFactory.newInstance();
         XPath xPath = xPathFactory.newXPath();
         try {
-            XPathExpression xPathExpression = xPath.compile("//Device[@name='" + deviceName + "']/Port");
+            XPathExpression xPathExpression = xPath.compile(
-            Element result = (Element) xPathExpression.evaluate(root, XPathConstants.NODE);
+                    "//Device[@name='" + deviceName + "']/Port");
+            Element result = (Element) xPathExpression.evaluate(
+                    root, XPathConstants.NODE);
             returnDictionary.put("protocol", result.getAttribute("protocol"));
             NodeList childNodes = result.getChildNodes();
             List<String> pins = new ArrayList<>();
@@ -153,7 +174,11 @@ public class XMLHandler implements IXML{
             }
             returnDictionary.put("pins", pins);
         } catch (XPathExpressionException e) {
-            Log.e("XMLHandler","the XPath for getting the value info has errors:" + e.getMessage());
+            Log.e(
+                    "XMLHandler",
+                    "the XPath for getting the value info has errors:"
+                            + e.getMessage()
+            );
         }
         return returnDictionary;
     }