[client] commented AdvancedConfigurator

1 files changed, 71 insertions, 28 deletions

diff --git a/dozentenmodul/src/main/java/org/openslx/dozmod/gui/control/AdvancedConfigurator.java b/dozentenmodul/src/main/java/org/openslx/dozmod/gui/control/AdvancedConfigurator.java
index 775d901b..4f66e54d 100644
--- a/dozentenmodul/src/main/java/org/openslx/dozmod/gui/control/AdvancedConfigurator.java
+++ b/dozentenmodul/src/main/java/org/openslx/dozmod/gui/control/AdvancedConfigurator.java
@@ -38,7 +38,8 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 
 	/**
 	 * Character defining how the rules are parsed, e.g. for whitespace \\s
-	 * Example: "IN 8.8.8.8 80"
+	 * Example: "8.8.8.8 80 in" would be split in -hostname "8.8.8.8" -port "80"
+	 * -direction "in"
 	 */
 	private static final String FIELD_DELIMITER = "\\s";
 
@@ -47,14 +48,19 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 	}
 
 	/**
+	 * Gets the state of the widget. This will first try to parse the tpNetworkRules
+	 * and taRunScript and build the corresponding AdvancedConfiguration Object returned.
 	 * 
+	 * @return advanced configuration object composed of the parsed network
+	 *         rules as List<NetRule> and the raw runscript text as String
+	 * @see org.openslx.dozmod.gui.control.AdvancedConfigurator.AdvancedConfiguration
 	 */
 	public AdvancedConfiguration getState() {
 		// cleanup the TextPane for network rules if needed
-		String input = taNetworkRules.getText().trim();
+		String input = tpNetworkRules.getText().trim();
 		input = input.replaceAll("(?m)^\\s*", "");
 		input = input.replaceAll("(?m)\\s*$", "");
-		taNetworkRules.setText(input);
+		tpNetworkRules.setText(input);
 
 		List<NetRule> rules = parseNetRules(input);
 		if (rules != null) {
@@ -63,13 +69,21 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 		return null;
 	}
 
+	/**
+	 * Sets the state of this widget to the given AdvancedConfiguration. Basicly this sets
+	 * the content of the text areas to the corresponding network rules/runscript as given
+	 * by the AdvancedConfiguration object
+	 * @param config AdvancedConfiguration to set the state to
+	 */
 	public void setState(final AdvancedConfiguration config) {
 		// setText() blanks the text area if null is given, so no null checks
-		this.taNetworkRules.setText(decodeNetRulesToText(config.netRulesList));
+		this.tpNetworkRules.setText(decodeNetRulesToText(config.netRulesList));
 		this.taRunScript.setText(config.runScriptText);
 	}
 
 	/**
+	 * "Decodes" the given list of NetRule to a single String. This should be used
+	 * to set the text in the TextPane for the network rules
 	 * @param netRulesList
 	 *            list of NetRule to decode
 	 * @return String representation of the list of rules
@@ -99,6 +113,8 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 	}
 
 	/**
+	 * Parsed the given rawNetRules String to a list of NetRule
+	 * 
 	 * @param rawNetRules
 	 *            the raw text to be parsed
 	 * @return list of valid net rules parsed from the given rawNetRules,
@@ -113,9 +129,10 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 		if (rawNetRules.isEmpty()) {
 			return rulesList;
 		}
-		// rawNetRules is the text as entered in the textarea
+
 		// split it line by line
-		final String[] netRules = rawNetRules.split("[" + System.lineSeparator() + "]");
+		final String[] netRules = rawNetRules.split("["
+				+ System.lineSeparator() + "]");
 		for (String ruleLine : netRules) {
 			if (ruleLine.isEmpty())
 				continue;
@@ -124,6 +141,7 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 			String[] fields = ruleLine.split(FIELD_DELIMITER);
 			if (fields.length != 3) {
 				markText(ruleLine, Color.RED);
+				// log numbers for fields independently... 
 				LOGGER.debug("Invalid number of fields! Expected 3, got: "
 						+ fields.length);
 				Gui.showMessageBox(
@@ -135,19 +153,17 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 			// start to check fields one by one from the last to the first ....
 			// check net direction: accept either 'in' or 'out' (case
 			// insensitive)
-			// TODO finish this ...
 			String ruleDirection = fields[2].toLowerCase();
 			if (!ruleDirection.matches("^(\\bin\\b|\\bout\\b)$")) {
 				markText(ruleLine, Color.RED);
-				LOGGER.debug("Invalid net direction! Expected 'in' or out'. Got: " + ruleDirection);
+				LOGGER.debug("Invalid net direction! Expected 'in' or out'. Got: "
+						+ ruleDirection);
 				Gui.showMessageBox(
 						"Ungültige Richtung: nur 'in', 'out', 'in/out' und 'out/in' erlaubt!",
 						MessageType.ERROR, LOGGER, null);
 				break;
 			}
-			// TODO match also when both are given.
-
-			// check port: accept if > -2 and < 65535 
+			// check port: accept if > -2 and < 65535
 			int port = -2;
 			try {
 				port = Integer.parseInt(fields[1]);
@@ -176,7 +192,7 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 				ruleHost = InetAddress.getByName(fields[0]);
 			} catch (UnknownHostException e) {
 				// might be good to see this exception in the log file
-				//LOGGER.debug("Invalid hostname (java.net): ", e);
+				// LOGGER.debug("Invalid hostname (java.net): ", e);
 			}
 			if (ruleHost == null) {
 				// either invalid IP-Address or an invalid resolvable hostname
@@ -204,7 +220,8 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 				markText(ruleLine, Color.GREEN);
 			}
 			// valid, put it in the list
-			rulesList.add(new NetRule(NetDirection.valueOf(fields[2].toUpperCase()), fields[0], port));
+			rulesList.add(new NetRule(NetDirection.valueOf(fields[2]
+					.toUpperCase()), fields[0], port));
 		}
 		if (netRules.length == rulesList.size()) {
 			return rulesList;
@@ -212,6 +229,19 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 		return null;
 	}
 
+	/**
+	 * Very simple hostname check for the given String. This will only check for
+	 * some requirements of valid hostnames as stated in
+	 * http://tools.ietf.org/html/rfc1034#section-3.1 To recap: max length of
+	 * the whole hostname must be < 254 ASCII characters, all domain labels
+	 * (between two dots) must be between 1 and 63 chars long and domain labels
+	 * can only contain digits, letters and hyphen. (Note: we also accept
+	 * forward slash to accept subnets!)
+	 * 
+	 * @param hostname
+	 *            as String to check the syntax of
+	 * @return
+	 */
 	private boolean checkHostnameSimple(final String hostname) {
 		if (hostname.length() > 254) {
 			Gui.showMessageBox("Hostname ist zu lang!", MessageType.ERROR,
@@ -219,17 +249,18 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 			return false;
 		}
 		// split by '.' to get domain levels
-		String[] domainLevels = hostname.split("\\.");
-		for (String lvl : domainLevels) {
-			if (lvl.length() > 63) {
+		String[] domainLabels = hostname.split("\\.");
+		for (String domainLabel : domainLabels) {
+			if (domainLabel.length() > 63) {
 				// fail since domain level should be max 63 chars
-				Gui.showMessageBox("Domain-Ebene '" + lvl + "' länger als 63 Zeichen!", MessageType.ERROR,
-					LOGGER, null);
+				Gui.showMessageBox("Domain-Ebene '" + domainLabel
+						+ "' länger als 63 Zeichen!", MessageType.ERROR,
+						LOGGER, null);
 				return false;
 			}
 			// length is ok, check for invalid characters
-			for (int i = 0; i < lvl.length(); i++) {
-				Character c = Character.valueOf(lvl.charAt(i));
+			for (int i = 0; i < domainLabel.length(); i++) {
+				Character c = Character.valueOf(domainLabel.charAt(i));
 				// only accepts numbers, letters, hyphen
 				// forward slash as a special case to accept subnets...
 				if (!(Character.isDigit(c) || Character.isLetter(c)
@@ -243,14 +274,23 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 		return true;
 	}
 
+	/**
+	 * Searches the given txt within tpNetworkRules and changes its color to the
+	 * given color
+	 * 
+	 * @param txt
+	 *            text to search within the tpNetworkRules
+	 * @param color
+	 *            to set the given txt to
+	 */
 	// TODO still buggy with text colors: the marking works fine
 	// but when trying to input new text, funny things happen
 	private void markText(final String txt, final Color color) {
-		MutableAttributeSet origSet = taNetworkRules.getInputAttributes();
+		MutableAttributeSet origSet = tpNetworkRules.getInputAttributes();
 		SimpleAttributeSet set = new SimpleAttributeSet();
 		StyleConstants.setForeground(set, color);
 		StyleConstants.setBold(set, color == Color.red);
-		StyledDocument doc = taNetworkRules.getStyledDocument();
+		StyledDocument doc = tpNetworkRules.getStyledDocument();
 		try {
 			for (int pos = 0; pos < doc.getLength() - txt.length() + 1; ++pos) {
 				String current = doc.getText(pos, txt.length());
@@ -267,13 +307,16 @@ public class AdvancedConfigurator extends AdvancedConfiguratorLayout {
 					"Failed to set '" + txt + "' to color " + color.toString(),
 					e);
 		}
-		taNetworkRules.setCharacterAttributes(origSet, true);
-		taNetworkRules.setStyledDocument(doc);
+		// resetting the char attr to what they were before (buggy) 
+		tpNetworkRules.setCharacterAttributes(origSet, true);
+		tpNetworkRules.setStyledDocument(doc);
 	}
 
 	/**
 	 * Wrapper class for the advanced configuration information needed since we
-	 * need to return a single object from the runAndReturn routine
+	 * need to return a single object from the runAndReturn routine. This class
+	 * has two members: the list of NetRule(s) (as List<NetRule>) and the
+	 * runScriptText (as String)
 	 */
 	public static class AdvancedConfiguration {
 		public List<NetRule> netRulesList;
@@ -303,7 +346,7 @@ class AdvancedConfiguratorLayout extends JPanel {
 
 	private final JPanel pnlNetworkOptions;
 	private final JPanel pnlRunScript;
-	protected final JTextPane taNetworkRules;
+	protected final JTextPane tpNetworkRules;
 	protected final JTextArea taRunScript;
 
 	public AdvancedConfiguratorLayout() {
@@ -317,9 +360,9 @@ class AdvancedConfiguratorLayout extends JPanel {
 				true, new Insets(2, 2, 2, 2));
 		pnlNetworkOptions.setBorder(BorderFactory
 				.createTitledBorder(txtNetworkOptionsTitle));
-		taNetworkRules = new JTextPane();
+		tpNetworkRules = new JTextPane();
 
-		JScrollPane scpNetworkRules = new JScrollPane(taNetworkRules,
+		JScrollPane scpNetworkRules = new JScrollPane(tpNetworkRules,
 				JScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED,
 				JScrollPane.HORIZONTAL_SCROLLBAR_NEVER);
 		pnlNetworkOptions.setBorder(BorderFactory