Skip to content
This repository
Browse code

finished writing JavaDoc for the ComLib

  • Loading branch information...
commit c62277aec99059932f710eee7afa5a351bd46294 1 parent 23a9bf1
authored April 18, 2012
132  java/src/no/ntnu/osnap/com/Protocol.java
@@ -22,6 +22,14 @@
22 22
 import java.util.LinkedList;
23 23
 import java.util.concurrent.TimeoutException;
24 24
 
  25
+/**
  26
+ * This class defines a communication standard with a remote device. The actual
  27
+ * communication method is defined in the subclass that extends the Protocol class.
  28
+ * For example a BluetoothConnection sends data through bluetooth sockets but this
  29
+ * is transparent to the user because communication is done through the Protocol 
  30
+ * standard. This class can be extended to support new communication methods like
  31
+ * InfraRed, NFC or WiFi.
  32
+ */
25 33
 public abstract class Protocol extends Thread {
26 34
 	/**
27 35
 	 * The version number of this ComLib release
@@ -29,6 +37,11 @@
29 37
 	public final static String LIBRARY_VERSION = "1.2.0";
30 38
 	
31 39
 	/**
  40
+	 * Private mutex flag for atomic methods
  41
+	 */
  42
+	private volatile boolean locked = false;
  43
+	
  44
+	/**
32 45
 	 * The unique metadata package for this connection
33 46
 	 * This is initially set to null and need to be retrieved
34 47
 	 * in getConnectionData() that is inherited by the connection
@@ -41,10 +54,16 @@
41 54
 
42 55
 	private boolean running;
43 56
     
  57
+	/**
  58
+	 * Number of miliseconds to wait for a response before throwing a TimeoutException
  59
+	 */
44 60
 	protected static final int TIMEOUT = 2000;
45 61
 	protected static final int MAX_CONTENT_SIZE = 250;
46 62
 
47  
-	//Package private enumeration
  63
+	/**
  64
+	 * Package private enumeration for all Commands supported by the Protocol standard
  65
+	 *
  66
+	 */
48 67
     enum OpCode {
49 68
     	PING,			//0
50 69
     	TEXT,			//1
@@ -81,6 +100,9 @@ private OpCode(int value) {
81 100
 	
82 101
 	private OpCode tempAckProcessor;
83 102
 
  103
+	/**
  104
+	 * Default constructor called by sub-classes
  105
+	 */
84 106
     public Protocol() {
85 107
         currentCommand = new Command();
86 108
         waitingForAck = null;
@@ -89,6 +111,11 @@ public Protocol() {
89 111
 		running = true;
90 112
     }
91 113
 	
  114
+    /**
  115
+     * Retrieves the ConnectionMetadata associated with the remote device. This
  116
+     * is normally stored internally on the remote device. Implementation of this 
  117
+     * method should be defined by the sub-class
  118
+     */
92 119
     public abstract ConnectionMetadata getConnectionData();
93 120
         
94 121
     /**
@@ -178,6 +205,12 @@ private void queueInstruction(ProtocolInstruction instr){
178 205
 		}
179 206
 	}
180 207
 	
  208
+	/**
  209
+	 * Sends a ping to the remote device and returns when it is finished. This
  210
+	 * method is blocking.
  211
+	 * @throws TimeoutException if the remote device used too long time to respond 
  212
+	 * 							(defined in TIMEOUT)
  213
+	 */
181 214
     public final void ping() throws TimeoutException {
182 215
         lock();
183 216
         
@@ -207,10 +240,23 @@ public final void ping() throws TimeoutException {
207 240
         ackProcessingComplete();
208 241
     }
209 242
     
  243
+    /**
  244
+     * Same as calling print(text, false)
  245
+     * @see public final void print(String text, boolean blocking) throws TimeoutException
  246
+     */
210 247
 	public final void print(String text) throws TimeoutException{
211 248
 		print(text, false);
212 249
 	}
213 250
 	
  251
+    /**
  252
+     * Sends a String to the remote device. How the String is handled or what is done
  253
+     * with the String is application defined by the remote device. The usual thing
  254
+     * is to print the text on a display.
  255
+     * @param text Which String to send to the remote device
  256
+     * @param blocking TRUE if the method should block until a response or timeout happens.
  257
+     * 				   FALSE if the method should return immediately and send the String asynchronously
  258
+     * @throws TimeoutException if the remote device used too long time to receive the String
  259
+     */
214 260
 	public final void print(String text, boolean blocking) throws TimeoutException{
215 261
 		ProtocolInstruction newInstruction =
216 262
 				new ProtocolInstruction(OpCode.TEXT, (byte)0, text.getBytes());
@@ -248,6 +294,16 @@ public final void print(String text, boolean blocking) throws TimeoutException{
248 294
 		}
249 295
 	}
250 296
 
  297
+	/**
  298
+	 * Requests the value of the specified sensor on the remote device. This method is blocking
  299
+	 * until a Timeout happens. What kind of Sensor the remote device supports and how they are
  300
+	 * implemented (and what integer value each sensor represents) is defined on the remote device
  301
+	 * firmware.
  302
+	 * @param sensor which pin to get the value from
  303
+	 * @return the value of the specified sensor
  304
+	 * @throws TimeoutException if the remote device used too long time to respond
  305
+	 * @see The ConnectionMetadata class to retrieve services such as sensor types the remote device supports
  306
+	 */
251 307
     public final int sensor(int sensor) throws TimeoutException {
252 308
 		ProtocolInstruction newInstruction =
253 309
 				new ProtocolInstruction(OpCode.SENSOR, (byte)sensor, new byte[1]);
@@ -284,18 +340,33 @@ public final int sensor(int sensor) throws TimeoutException {
284 340
         return sensorValue;
285 341
     }
286 342
 
287  
-    public short toUnsigned(byte value) {
  343
+    /**
  344
+     * Helper function to convert a signed byte to an unsigned byte (represented using a signed short in Java)
  345
+     */
  346
+    private short toUnsigned(byte value) {
288 347
         if (value < 0) {
289 348
             return (short) ((short) value & (short) 0xFF);
290 349
         }
291 350
         return (short) value;
292 351
     }
293 352
 
294  
-    public final void data(int pin, byte[] data) throws TimeoutException {
295  
-		data(pin, data, false);
  353
+    /**
  354
+     * Same as data(data, false)
  355
+     * @see public final void data(int pin, byte[] data) throws TimeoutException
  356
+     */
  357
+    public final void data(byte[] data) throws TimeoutException {
  358
+		data(data, false);
296 359
     }
297 360
 	
298  
-	public final void data(int pin, byte[] data, boolean blocking) throws TimeoutException{
  361
+    /**
  362
+     * Sends raw data expressed as a byte array to the remote device to the specified pint
  363
+     * @param pin
  364
+     * @param data array of bytes to send
  365
+     * @param blocking determines if method should wait until a Timeout happens or should return
  366
+     * immediately and send data asynchronously.
  367
+     * @throws TimeoutException
  368
+     */
  369
+	public final void data(byte[] data, boolean blocking) throws TimeoutException{
299 370
 		ArrayList<ProtocolInstruction> newInstructions = new ArrayList<ProtocolInstruction>();
300 371
 		
301 372
 		//ProtocolInstruction tempInstruction;
@@ -369,6 +440,13 @@ public final void data(int pin, byte[] data, boolean blocking) throws TimeoutExc
369 440
 		}
370 441
 	}
371 442
 
  443
+	/**
  444
+	 * Requests the value of the specified pin on the remote device. This method is blocking
  445
+	 * until a Timeout happens.
  446
+	 * @param sensor which pin to get the value from
  447
+	 * @return the value of the specified pin
  448
+	 * @throws TimeoutException if the remote device used too long time to respond
  449
+	 */
372 450
     public final boolean read(int pin) throws TimeoutException {
373 451
 		ProtocolInstruction newInstruction =
374 452
 				new ProtocolInstruction(OpCode.PIN_R, (byte)pin, new byte[1]);
@@ -402,10 +480,21 @@ public final boolean read(int pin) throws TimeoutException {
402 480
         return content[0] > 0 ? true : false;
403 481
     }
404 482
 
  483
+    /**
  484
+     * Same as write(pin, value, false)
  485
+     * @see public final void write(int pin, boolean value) throws TimeoutException
  486
+     */
405 487
     public final void write(int pin, boolean value) throws TimeoutException {
406 488
 		write(pin, value, false);
407 489
     }
408 490
 	
  491
+    /**
  492
+     * Set the specified pin on the remote device to HIGH (true) or LOW (false)
  493
+     * @param pin which pin to change
  494
+     * @param value true if the pin is to be set HIGH or false if it is LOW
  495
+     * @param blocking determines if this method should wait until success or Timeout happens
  496
+     * @throws TimeoutException if the remote device used too long to respond
  497
+     */
409 498
 	public final void write(int pin, boolean value, boolean blocking) throws TimeoutException{
410 499
 		ProtocolInstruction newInstruction =
411 500
 				new ProtocolInstruction(OpCode.PIN_W, (byte)pin, new byte[] {value ? (byte)1 : (byte)0});
@@ -439,8 +528,10 @@ public final void write(int pin, boolean value, boolean blocking) throws Timeout
439 528
 		}
440 529
 	}
441 530
 	
442  
-    private volatile boolean locked = false;
443  
-
  531
+    /**
  532
+     * Internal mutex lock to prevent multiple threads from sending or reading data
  533
+     * through the protocol at the same time.
  534
+     */
444 535
     private synchronized void lock() {
445 536
         while (locked) {
446 537
             try {
@@ -466,6 +557,9 @@ private synchronized void lock() {
466 557
 		}
467 558
     }
468 559
 
  560
+    /**
  561
+     * Releases a previously Locked protocol
  562
+     */
469 563
     private synchronized void release() {
470 564
         if (!locked) {
471 565
             throw new IllegalStateException("Already released");
@@ -493,6 +587,11 @@ private void ackProcessingComplete() {
493 587
         processingAck = false;
494 588
     }
495 589
     
  590
+    /**
  591
+     * Called by sub-classes whenever they receive new data. The data is then processed
  592
+     * internally as defined by the protocol standard.
  593
+     * @param data a single byte received from the remote device
  594
+     */
496 595
     protected final void byteReceived(byte data) {
497 596
         if (currentCommand.byteReceived(data)) {
498 597
         	
@@ -527,14 +626,30 @@ protected final void byteReceived(byte data) {
527 626
         }
528 627
     }
529 628
 
  629
+    /**
  630
+     * Same as byteReceived except that it processes multiple bytes
  631
+     * @param data array of bytes received from the remote device
  632
+     */
530 633
     protected final void bytesReceived(byte[] data) {
531 634
         for (byte item : data) {
532 635
             byteReceived(item);
533 636
         }
534 637
     }
535 638
 
  639
+    /**
  640
+     * Sends data to the remote device. The specifics of this method is implemented
  641
+     * by the subclass that inherits Protocol (could be through a Socket or a 
  642
+     * ByteStream for example)
  643
+     * @param data array of bytes to send to the remote
  644
+     * @throws IOException if there was a problem sending the data
  645
+     */
536 646
     protected abstract void sendBytes(byte[] data) throws IOException;
537 647
 
  648
+    /**
  649
+     * The Protocol mechanic is handled internally by a state machine to process
  650
+     * commands and data. This enum defines the different states the protocol class
  651
+     * can enter
  652
+     */
538 653
     private enum State {
539 654
         STATE_START,
540 655
         STATE_SIZE,
@@ -544,6 +659,9 @@ protected final void bytesReceived(byte[] data) {
544 659
         STATE_DONE
545 660
     }
546 661
     
  662
+    /**
  663
+     * Private helper class to process comands
  664
+     */
547 665
     private class Command {
548 666
 
549 667
         private final byte START_BYTE = (byte) 0xFF;
3  java/src/no/ntnu/osnap/com/ProtocolInstruction.java
@@ -19,6 +19,9 @@
19 19
 import no.ntnu.osnap.com.Protocol.OpCode;
20 20
 
21 21
 
  22
+/**
  23
+ * Used internally by the Protocol standard for each communication Packet
  24
+ */
22 25
 public class ProtocolInstruction {
23 26
 	private static final byte START_BYTE = (byte)0xFF;
24 27
 	

0 notes on commit c62277a

Please sign in to comment.
Something went wrong with that request. Please try again.