Report-Observer-Pattern.md

+Within one machine of the game, many places need to observe the model for state changes.  For example, when the state of the model changes, the GUI might need to know so it can correctly render the screen or the communications subsystem might need to send a message to another one of the machines in the game.   While we could use the Observer pattern, we really don't want the observers to know where in the model they need to observe.  That would expose a lot of the internals of the model and make our layers pretty tightly coupled. In order to keep things loosely coupled, we've created a variant of the observer pattern that we call Qualified Observer.  Yes, we need observables and observers, but, instead of registering as an observer of a particular object, we register what information the observer is interested in and we'll give it to them no matter what object sources it.  The pieces of information the model can source are objects that implement QualifiedObservableReport (we just call these objects "reports"). In other words, with each update, the model sends on object that is from a subclass of QualifiedObservableReport.  Each observer specifies which of these reports it wants to receive.  With this information, the QualifiedObservableConnector sets up necessary the observer/observable connections.
+
+For example, suppose that some place in the view wants to know when the current player has moved.  In other words, it wants to receive ThisPlayerMovedReports from the model.  It must implement QualifiedObserver and register this interest with
+
+```java
+QualifiedObservableConnector.getSingleton().registerObserver(viewObject, ThisPlayerMovedReport.class);
+```
+
+The parameters to registerObserver() are the object that wants the information and the class of the report it wants to receive.
+
+Somewhere in the model knows when the player moves.  When that occurs, the appropriate report is sent to the ReportObserverConnector like this:
+
+```java
+ReportObserverConnector .getSingleton().sendReport(
+				new ThisClientsPlayerMovedReport(this.id, playerPosition));
+```
+The ReportObserverConnector will notify every ReportObserver who has expressed interest in that report type.
+
+If a ReportObserver is no longer interested in a given report type, it can unregister itself with:
+
+```java
+ReportObserverConnector .getSingleton().unregisterObserver(viewObject, ThisPlayerMovedReport.class);
+```
+
+Important implementation note:  If an object is registered as a report observer, it will never be garbage collected!  If you create a transient object that is a qualified observer, you are responsible for making sure it unregisters itself when it has finished its responsibilities.
\ No newline at end of file