- registerDict updated using Class objects

- comment added

git-svn-id: https://svn.code.sf.net/p/libusbjava/code/trunk@60 94ad28fe-ef68-46b1-9651-e7ae4fcf1c4c

mcdp/src/ch/ntb/mcdp/dict/Register.java

@@ -1,11 +1,61 @@
 package ch.ntb.mcdp.dict;
 
-public class Register {
+/**
+ * Representation of a register.
+ * 
+ * @author schlaepfer
+ */
+public abstract class Register {
 
-	// Register Types
+	/**
+	 * Register specific type values. <br>
+	 * The index of each type in the types array represents its numeric value.
+	 * When the register is read from an xml file, its type is converted from a
+	 * string (xml file) to an integer (index of types field). Therefore each
+	 * type in the corresponding xml file must be included in the type array.<br>
+	 * The type field must be initialised in the <code>static { }</code>
+	 * section of the subclass.
+	 */
 	protected static String[] types = null;
 
-	public Register(String name, int type, int value, int size,
+	/**
+	 * Name of the register. Registers are identified by this value.
+	 */
+	public String name = "NOT INITIALISED";
+
+	/**
+	 * Register specific type
+	 */
+	public int type;
+
+	/**
+	 * Address or a register specific value (e.g. BDI-identifier)
+	 */
+	public int value;
+
+	/**
+	 * Size in bytes (width)
+	 */
+	public int size;
+
+	/**
+	 * A string description of the register
+	 */
+	public String description;
+
+	/**
+	 * @param name
+	 *            name of the register. Registers are identified by this value.
+	 * @param type
+	 *            register specific type
+	 * @param value
+	 *            address or a register specific value (e.g. BDI-identifier)
+	 * @param size
+	 *            size in bytes
+	 * @param description
+	 *            a string description of the register
+	 */
+	public void init(String name, int type, int value, int size,
 			String description) {
 		this.name = name;
 		this.type = type;
@@ -14,23 +64,18 @@ public class Register {
 		this.description = description;
 	}
 
-	public final String name;
-
-	public final int type;
-
-	public final int value;
-
-	public final int size;
-
-	public final String description;
-
 	@Override
 	public String toString() {
 		return new String(name + "\t" + types[type] + "\t0x"
 				+ Integer.toHexString(value) + "\t" + size + "\t" + description);
 	}
-	
-	public String[] getTypes(){
-		return types;		
+
+	/**
+	 * Get the register specific type strings.
+	 * 
+	 * @return types strings
+	 */
+	public static String[] getTypes() {
+		return types;
 	}
 }

mcdp/src/ch/ntb/mcdp/dict/RegisterDict.java

@@ -2,7 +2,7 @@ package ch.ntb.mcdp.dict;
 
 import java.io.File;
 import java.io.IOException;
-import java.lang.reflect.Constructor;
+import java.lang.reflect.Method;
 import java.util.Iterator;
 import java.util.LinkedList;
 
@@ -18,11 +18,27 @@ import org.xml.sax.ErrorHandler;
 import org.xml.sax.SAXException;
 import org.xml.sax.SAXParseException;
 
+/**
+ * Representation of a register dictionary. All registers are read from an
+ * xml-file specified by <code>registerDictionary.dtd</code>. Note that the
+ * type values are implementation specific. Therefore each <i>Register</i> has
+ * its own <i>registerDictionary.dtd</i> definition. For an example see
+ * <code>MPC555Register</code> and the corresponding
+ * <code>resources/targets/mpc555/registerDictionary.dtd</code> file.
+ * 
+ * @author schlaepfer
+ */
 public abstract class RegisterDict {
 
 	private LinkedList registers;
 
-	private Class regClass;
+	private Class<? extends Register> regClass;
+
+	private Method regClassGetTypesMethod;
+
+	private static final String GetTypes_METHOD_NAME = "getTypes";
+
+	private String[] types;
 
 	private static final long serialVersionUID = -582382284126896830L;
 
@@ -44,29 +60,58 @@ public abstract class RegisterDict {
 
 	private static final String REG_ATTR_SIZE = "size";
 
-	protected RegisterDict(String registerClass) {
+	/**
+	 * Default constructor which takes the Class object from a
+	 * <code>Register</code> subclass as argument. The registerDict will be of
+	 * this Register-type.<br>
+	 * An example:<br>
+	 * MPC555Register extends Register -> use MPC555Register.class as parameter.
+	 * 
+	 * @param registerClass
+	 *            subclass of Register
+	 */
+	protected RegisterDict(Class<? extends Register> registerClass) {
+		this.regClass = registerClass;
 		try {
-			this.regClass = Class.forName(registerClass);
-		} catch (ClassNotFoundException e) {
+			this.regClassGetTypesMethod = regClass.getMethod(
+					GetTypes_METHOD_NAME, (Class[]) null);
+			this.regClass.newInstance();
+			this.types = (String[]) regClassGetTypesMethod.invoke(
+					(Object[]) null, (Object[]) null);
+		} catch (Exception e) {
 			e.printStackTrace();
 			System.exit(1);
 		}
 		this.registers = new LinkedList();
 	}
 
+	/**
+	 * Add a new register to the registerDict.
+	 * 
+	 * @param name
+	 *            name of the register. Registers are identified by this value.
+	 * @param type
+	 *            register specific type
+	 * @param value
+	 *            address or a register specific value (e.g. BDI-identifier)
+	 * @param size
+	 *            size in bytes
+	 * @param description
+	 *            a string description of the register
+	 */
 	@SuppressWarnings("unchecked")
-	protected void add(String name, int type, int value, int size,
+	public void add(String name, int type, int value, int size,
 			String description) {
 		// remove before add for updates
 		for (Iterator i = registers.iterator(); i.hasNext();) {
-			if (((Register)i.next()).name.equals(name)) {
+			if (((Register) i.next()).name.equals(name)) {
 				i.remove();
 			}
 		}
-		Constructor[] regConstructors = regClass.getDeclaredConstructors();
 		Register reg = null;
 		try {
-			reg = (Register) regConstructors[0].newInstance(name, type, value, size, description);
+			reg = (Register) regClass.newInstance();
+			reg.init(name, type, value, size, description);
 		} catch (Exception e) {
 			e.printStackTrace();
 			System.exit(1);
@@ -74,7 +119,7 @@ public abstract class RegisterDict {
 		registers.add(reg);
 	}
 
-	protected int parseInt(String s) {
+	private int parseInt(String s) {
 		if (s == "")
 			return 0;
 		if (s.indexOf('x') > 0) {
@@ -94,6 +139,13 @@ public abstract class RegisterDict {
 		}
 	}
 
+	/**
+	 * Get a register by its name.
+	 * 
+	 * @param name
+	 *            the register name
+	 * @return register on null if no register is found
+	 */
 	public Register getRegister(String name) {
 		for (Iterator i = registers.iterator(); i.hasNext();) {
 			Register r = (Register) i.next();
@@ -104,6 +156,9 @@ public abstract class RegisterDict {
 		return null;
 	}
 
+	/**
+	 * Print a list of Registers to standard out.
+	 */
 	public void printRegisters() {
 		System.out
 				.println("******************** register dictionary *********************");
@@ -122,14 +177,21 @@ public abstract class RegisterDict {
 	 * Adds the registers from the specified xml-file to the register
 	 * dictionary. <br>
 	 * The xml-file must be structured according to
-	 * <code>registerDictionary.dtd</code>. Include
+	 * <code>registerDictionary.dtd</code>. The dtd-file must be adapted to
+	 * the type values specific to this register. Include
 	 * <code><!DOCTYPE registerDefinitions SYSTEM "registerDictionary.dtd"></code>
 	 * in your xml file.
 	 * 
 	 * @param xmlPathname
+	 *            path to the xml file
 	 * @throws IOException
+	 *             throws an IOException if the file is not found
 	 * @throws ParserConfigurationException
+	 *             throws an ParserConfigurationException if the SAX parser
+	 *             can't be configured
 	 * @throws SAXException
+	 *             throws an SAXException if the file could not be successfully
+	 *             parsed
 	 */
 	public void addRegistersFromFile(String xmlPathname) throws IOException,
 			ParserConfigurationException, SAXException {
@@ -189,8 +251,8 @@ public abstract class RegisterDict {
 	}
 
 	protected int convertType(String typeStr) throws SAXException {
-		for (int index = 0; index < Register.types.length; index++) {
-			if (typeStr.equals(Register.types[index])) {
+		for (int index = 0; index < types.length; index++) {
+			if (typeStr.equals(types[index])) {
 				return index;
 			}
 		}

mcdp/src/ch/ntb/mcdp/mc68332/MC68332Register.java

@@ -21,8 +21,4 @@ public class MC68332Register extends Register {
 
 	static final int CtrlReg = 2;
 
-	public MC68332Register(String name, int type, int value, int size,
-			String description) {
-		super(name, type, value, size, description);
-	}
 }

mcdp/src/ch/ntb/mcdp/mc68332/MC68332RegisterDict.java

@@ -1,35 +1,10 @@
 package ch.ntb.mcdp.mc68332;
 
-import java.io.IOException;
-
-import javax.xml.parsers.ParserConfigurationException;
-
-import org.xml.sax.SAXException;
-
 import ch.ntb.mcdp.dict.RegisterDict;
 
 public class MC68332RegisterDict extends RegisterDict {
 
-	private static final String REGISTER_CLASS = "ch.ntb.mcdp.mc68332.MC68332Register";
-
-	private static final String PATH_TO_REGISTER_FILE = "resources/targets/mc68332/registerDictionary.xml";
-
 	public MC68332RegisterDict() {
-		super(REGISTER_CLASS);
-
-		// TODO: remove
-		try {
-			addRegistersFromFile(PATH_TO_REGISTER_FILE);
-		} catch (IOException e) {
-			// TODO Auto-generated catch block
-			e.printStackTrace();
-		} catch (ParserConfigurationException e) {
-			// TODO Auto-generated catch block
-			e.printStackTrace();
-		} catch (SAXException e) {
-			// TODO Auto-generated catch block
-			e.printStackTrace();
-		}
-		printRegisters();
+		super(MC68332Register.class);
 	}
 }

mcdp/src/ch/ntb/mcdp/mpc555/MPC555Register.java

@@ -24,8 +24,4 @@ public class MPC555Register extends Register {
 
 	static final int CtrlReg = 6;
 
-	public MPC555Register(String name, int type, int value, int size,
-			String description) {
-		super(name, type, value, size, description);
-	}
 }

mcdp/src/ch/ntb/mcdp/mpc555/MPC555RegisterDict.java

@@ -4,9 +4,7 @@ import ch.ntb.mcdp.dict.RegisterDict;
 
 public class MPC555RegisterDict extends RegisterDict {
 
-	private static final String REGISTER_CLASS = "ch.ntb.mcdp.mpc555.MPC555Register";
-
 	public MPC555RegisterDict() {
-		super(REGISTER_CLASS);
+		super(MPC555Register.class);
 	}
 }