Core Connection to UI - Revision history

Tom Parker: /* Defer fixing to a game mode as long as possible */

2014-05-26T01:24:35Z

‎Defer fixing to a game mode as long as possible

Tom Parker at 00:59, 26 May 2014

2014-05-26T00:59:06Z

Tom Parker: /* Isolation provided by the output layer & facades */

2014-05-25T22:35:25Z

‎Isolation provided by the output layer & facades

Tom Parker at 21:47, 25 May 2014

2014-05-25T21:47:04Z

Tom Parker at 19:27, 25 May 2014

2014-05-25T19:27:36Z

Tom Parker: /* Scope of the project */

2014-05-25T19:21:01Z

‎Scope of the project

Tom Parker at 19:19, 25 May 2014

2014-05-25T19:19:47Z

Show changes

Tom Parker: /* Consolidated Event */

2014-05-25T16:49:03Z

‎Consolidated Event

Tom Parker: /* Resulting Architecture */

2014-05-25T16:48:49Z

‎Resulting Architecture

Tom Parker: /* Facet to UI element */

2014-05-25T16:48:00Z

‎Facet to UI element

@@ Line 204: / Line 204: @@
 ==Defer fixing to a game mode as long as possible==
-Another consideration to be balanced is to defer fixing behaviors to a game mode as long as possible.  For example, having an item call getInteger(IntegerKey.LEGS) is generic to any game mode (since the key would not exist in a game mode that wasn't worried about legs).  Once it becomes a method called getLegs(), then it is fixed to that game mode and the class is no longer reusable across a wide variety of game modes.  While this is not a hard requirement to avoid binding, there should be a balance, and deferring the "fixing" to a game mode as long as possible would seem desirable.
+Another consideration to be balanced is to defer fixing behaviors to a game mode as long as possible.
 ==Undo/Redo and keeping the core isolated==

@@ Line 10: / Line 10: @@
 =Scope of the project=
-This discusses the design of a series of classes and layers acting as an interface between the core of PCGen and the UI.  Due to the responsibilities of those layers, other subsystems are subsumed into the discussion, but only in as much as they are impacted by the layers between the core and UI.  (Layers is currently, and intentionally, plural.  It is possible that the best design will include both an output layer and then a facade on top of that output to interface with the UI)
+This discusses the design of a series of classes and layers acting as an interface between the core of PCGen and the UI.  Due to the responsibilities of those layers, other subsystems are subsumed into the discussion, but only in as much as they are impacted by the layers between the core and UI.  (Layers is currently, and intentionally, plural.  It is possible that the best design will include both an output layer and then an adapter layer on top of that output to interface with the UI)
 It should be recognized that it will take time to implement the results of this discussion and this will likely be phased in over time.  However, the timing of the discussion is critical to understanding at least some key points of the eventual direction, so that systems which will depend on these changes can avoid creating problems in how they would be converted to this architecture.
@@ Line 18: / Line 18: @@
 =The (somewhat aging) principle=
-If we look at [[Architecture]], the core is acting as the "character data store" and "event controller".  The UI is shown in the light blue layer at the top.  In between is the "Character Output" subsystem.  So the general principle has always been that there is an output subsystem that is responsible for preparing output.  This would include things such as taking the list of Languages on a PC and sorting that list based on the currently active language.  Right now, the items in this layer are a mixed responsibility.  Some are still handled in the core, some are handled in the facade.  It is hoped that all of these can be moved to a consistent location so that they are handled appropriately and isolated from either the UI or the core.
+If we look at [[Architecture]], the core is acting as the "character data store" and "event controller".  The UI is shown in the light blue layer at the top.  In between is the "Character Output" subsystem.  So the general principle has always been that there is an output subsystem that is responsible for preparing output.  This would include things such as taking the list of Languages on a PC and sorting that list based on the currently active language.  Right now, the items in this layer are a mixed responsibility.  Some are still handled in the core, some are handled in the adapter layer.  It is hoped that all of these can be moved to a consistent location so that they are handled appropriately and isolated from either the UI or the core.
-==One item missing in the above structure==
+The intent would be that the output layer and the adapter layer would make up the "Character Output" section of the diagram.
-	The architecture as shown ignore the output sheet system.  It really should be along-side the UI, also attaching to the "Character Output" subsystem.
@@ Line 38: / Line 41: @@
 * The "core" refers to the classes that perform the logical analysis in order to take in a command and produce a response.  Generally this is done with our facets, but there are still exceptions to that design.
 * The "UI" refers to the graphical elements of the interface.
 * "Output Sheets" refers to the subsystem used to produce our output sheets, including the ExportHandler as well as the output tokens.
 * "Output" refers to methods of getting information to a human user.  From the core's perspective this includes both "output sheets" as well as "UI".
-* The "output layer" is a layer of code that is potentially between the core and the facades (recognizing that there are some universal items for output that can be shared.  However, it is not certain that this can be or replace the facade layer entirely, as there are still concepts we would have to decide how they are used or not used in output sheets (the facades in particular)
+* The "adapter layer" refers to the translation from core-awareness to UI-awareness.  Currently this is implemented in the *FacadeImpl classes.
 Related to Flow of messages:
@@ Line 62: / Line 69: @@
 In order to put the terms in a useful context, the following "life cycle" is provided:
 * The scenario is that the user adds a Domain to a character (we'll use "Light").  We assume for simplicity that there are no other side effects.
-* The UI is responsible for sending a message  to the Facade layer that says something to the effect of "add Domain Light".
+* The UI is responsible for sending a message  to the Facade layer that says something to the effect of "add DomainFacade Light".
-* The Facade then converts that to a "command" for the core (also "add Domain Light").  Currently, the only difference between the initial message and the command is that the UI message refers to a DomainFacade and the command to the core must refer to a Domain.
+* The Facade then converts that to a "command" for the core (now "add Domain Light").  Currently, the only difference between the initial message and the command is that the UI message refers to a DomainFacade and the command to the core must refer to a Domain.
 * When the core receives the command, it eventually moves that to a call on the DomainFacet in the core that adds the Domain to the PlayerCharacter.
 * DomainFacet then throws an event, which in this case is also something displayed in the UI (a selected Domain), so that event is more broadly a "response event".
@@ Line 82: / Line 89: @@
 ==Isolation provided by the output layer & facades==
-One of the principle design considerations is to insulate the core from the UI (and vice versa).  Therefore, the Output Layer should be making the effort to do that conversion, rather than creating dependencies back in the core.  As part of this work, the pcgen.core.facade interfaces will be moved out of pcgen.core (into something like pcgen.output).  This also means that the concrete classes in pcgen.core that implement those interfaces will no longer do that, and there will need to be a FacadeImpl to adapt the core classes to the expectations of the UI.  This will complete the primary isolation of those two subsystems.
+One of the principle design considerations is to insulate the core from the UI (and vice versa).  Therefore, the Adapter Layer should be making the effort to do that conversion, rather than creating dependencies back in the core.  As part of this work, the pcgen.core.facade interfaces will be moved out of pcgen.core (into something like pcgen.output or pcgen.adapter - TBD).  This also means that the concrete classes in pcgen.core that implement those interfaces will no longer do that, and there will need to be a FacadeImpl to adapt the core classes to the expectations of the UI.  This will complete the primary isolation of those two subsystems.
 One challenge is in sharing infrastructure in output while not destroying isolation between the UI and output sheets.
@@ Line 94: / Line 101: @@
 ==Responsibility of the Adapter (Facade) Layer==
-As the adapter layer was built without a complete event-based core (simply based on necessity), there are a number of functions it performs that it should not perform, as it should merely be serving as an adapter layer.  This is perhaps best characterized with some of the functions is currently does around abilities.  These should be subsumed into the core, into a more capable output layer, or into the UI, as appropriate.  The facade should be as transparent as possible, acting solely as in the role of an Adapter (design pattern), translating from core-speak to UI-speak and back.
+As the adapter layer was built without a complete event-based core (simply based on necessity), there are a number of functions it performs that it should not perform, as it should merely be serving as an adapter layer and translating between the core and UI.  This is perhaps best characterized with some of the functions is currently does around abilities.  These should be subsumed into the core, into a more capable output layer, or into the UI, as appropriate.  The facade should be as transparent as possible, acting solely as in the role of an Adapter (design pattern), translating from core-speak to UI-speak and back.

← Older revision		Revision as of 22:35, 25 May 2014
Line 86:		Line 86:
	One challenge is in sharing infrastructure in output while not destroying isolation between the UI and output sheets.		One challenge is in sharing infrastructure in output while not destroying isolation between the UI and output sheets.

		+	A specific example of this isolation can be shown with Race and RaceFacade. Today, there is no RaceFacadeImpl, Race actually implements RaceFacade. The side effect is that a number of UI-specific methods (such as getRaceType()) must be implemented by the core. Since we have already discussed the necessary connection from the UI to the game mode (and that we are willing to maintain that tight connection for now) we need to be careful about the now game-mode-specific UI imposing requirements back on the core (because it can easily make the core game-mode-specific, which is counter to the design principles of the core).
		+
		+	This leads to one of two possible solutions:
		+	* Break the assumption that the "generic" methods like getListFor(ListKey) on CDOMObject (including and especially the xKey objects themselves) can safely be shared with the UI
		+	* Make a separate RaceFacadeImpl that can convert getRaceType() [UI specific call] to getListFor(ListKey.RACE_TYPE) [core specific call]. In this case, it kind of implies that RaceFacadeImpl has-a Race. In order to avoid circular dependencies, it is advised that doing conversion at the full object level (e.g. Determine the appropriate RaceFacadeImpl for a given Race) is done by a 3rd party object.

	==Responsibility of the Adapter (Facade) Layer==		==Responsibility of the Adapter (Facade) Layer==

← Older revision		Revision as of 21:47, 25 May 2014
Line 229:		Line 229:
	* Return responses of the command to the UI (both for undo as well as display update)		* Return responses of the command to the UI (both for undo as well as display update)
	* Interface to the output layer		* Interface to the output layer
		+
		+	=Possible Event Flow in resulting architecture=
		+
		+	At Load:
		+
		+	* Data load request by user, actual LST data is loaded
		+	** In the future, specifies the tabs that are to be displayed
		+	** In the future, controls what components in core are active
		+	* Core registers with OutputLayerChannelDatabase what responses will be available to a consumer
		+	* UI registers demands for responses with OutputLayerChannelDatabase (This can - at most - link the tab to the channel name - a specific ListFacade doesn't exist until a PC is instantiated)
		+	* OutputLayerChannelDatabase reports any inconsistencies in channel requests as data load issue
		+	* Data load declared complete by RulesDataStore
		+
		+	At character creation:
		+
		+	* Need to instantiate all the ListFacade objects (NOT like it is today - right now CFI is basically too complicated to be debugged. Rather, the OLCD should be given the CFI and should load into it a series of xFacade objects with the output channel name. - this works because the channel name is known by the tab and by the core, so at that point the CFI is basically just a map of name->object and is rather easily testable!)
		+
		+	At runtime:
		+
		+	* UI receives a request from a user, such as adding a DomainFacade to a character
		+	* UI sends a message to the adapter layer, indicating the action and the target (e.g. "grant" "DomainFacade:Light") these are not literally strings, and may be in a form like addDomain(DomainFacade df) [though they MAY BE strings - as that is much more generic and avoids d20 assumptions]
		+	* Adapter layer converts the message to a core-compatible command (e.g. "grant" "Domain:Light")
		+	* Adapter layer submits the command to (the core?)
		+	* Command is transferred to the core thread via a BlockingQueue
		+	* (the core?) consumes from the BlocakingQueue and executes the command
		+	* Events flow through the core, triggering responses
		+	* Responses are captured by a ResponseAggregator
		+	* ResponseAggregator provides the complete set of changes in 2 forms: UndoableEdit and CombinedResponse.
		+	** UndoableEdit for the undo/redo system
		+	** CombinedResponse for the Output system
		+	** Consider: are these the same thing?
		+	* The CombinedResponse is placed into the BlockingQueue for the Output System
		+	* The OutputSystem takes (consumes) the CombinedResponse
		+	**Question: does this then need to pass this CombinedResponse to the UI processing thread? so blah.runLater?
		+	* The OutputSystem decomposes into a series of individual actions (e.g. "CharID:33fd" "added" "Channel:DOMAIN", "Domain:Light")
		+	**Order of operations: This decomposition order before CoR indicates the CoR will be walked many times. Should the CoR be called first and then have the PCF(I) pass off the CombinedResponse to a decomposer for the decomposer to call back into the PCF(I) ... so that we walk the CoR once yet keep decomposition out of the PCF(I)
		+	* Individual actions provided to the PCF(I) Chain of Responsibility
		+	* Each PCF(I) that does not match the CharID ignores the event
		+	* When a PCF(I) recognizes the CharID, it triggers processing of the event
		+	* PCFI does a lookup of the output channel to find the xFacade for that and then performs the appropriate action for that type of facade
		+	* PCF(I) consumes the event, so other PCF(I)s are not notified of the event
		+	* Output System sees the action was consumed and iterates to the next individual action, if appropriate
		+	* Warning produced if an action is not consumed (indicates core was asked to work on a PC that the PCF(I) CoR does not recognize
		+	* When all individual actions are complete, Output System blocks on BlockingQueue in order to find another CombinedResponse

@@ Line 3: / Line 3: @@
 This is a WORKING DRAFT.  It is woefully incomplete and lacks appropriate organization.
 =Scope of the project=
@@ Line 17: / Line 21: @@
 ==One item missing in the above structure==
-	The architectue as shown ignore the output sheet system.  It really should be along-side the UI, also attaching to the "Character Output" subsystem.
+	The architecture as shown ignore the output sheet system.  It really should be along-side the UI, also attaching to the "Character Output" subsystem.
@@ Line 35: / Line 39: @@
 * The "UI" refers to the graphical elements of the interface.
 * The "facades" refers to the classes acting as an adapter between the core and the UI
-* "Ouput Sheets" refers to the subsystem used to produce our output sheets, including the ExportHandler as well as the output tokens.
+* "Output Sheets" refers to the subsystem used to produce our output sheets, including the ExportHandler as well as the output tokens.
 * "Output" refers to methods of getting information to a human user.  From the core's perspective this includes both "output sheets" as well as "UI".
 * The "output layer" is a layer of code that is potentially between the core and the facades (recognizing that there are some universal items for output that can be shared.  However, it is not certain that this can be or replace the facade layer entirely, as there are still concepts we would have to decide how they are used or not used in output sheets (the facades in particular)
@@ Line 46: / Line 50: @@
 * An "output channel" is an abstraction of a specific response message from the core to a consumer, such as the output system.  It can be thought of as the pathway for a generic response that is not tied to the classes within the core.
-==Lifecycle of a Player Character change using the provided terms==
+Abbreviations:
-In order to put the terms in a useful context, the following "lifecycle" is provided:
+In order to put the terms in a useful context, the following "life cycle" is provided:
 * The scenario is that the user adds a Domain to a character (we'll use "Light").  We assume for simplicity that there are no other side effects.
 * The UI is responsible for sending a message  to the Facade layer that says something to the effect of "add Domain Light".
@@ Line 66: / Line 78: @@
 =Key Characteristics=
-The following are key characeristics of the strategic solution.  Primary measurement of design goals is against these characteristics.
+The following are key characteristics of the strategic solution.  Primary measurement of design goals is against these characteristics.
 ==Isolation provided by the output layer & facades==
@@ Line 82: / Line 94: @@
 =Required Conversions=
-In implemeting this communication from the core to the UI, a number of key conversions and transformations need to take place.  Enumerating these and then identifying good designs and appropriate owners is a significant part of developing the full architecture for interfacing the core to the UI
+In implementing this communication from the core to the UI, a number of key conversions and transformations need to take place.  Enumerating these and then identifying good designs and appropriate owners is a significant part of developing the full architecture for interfacing the core to the UI
 ==Sorting==
@@ Line 88: / Line 100: @@
 The core is generally order-independent (there are a few exceptions, but most of those will be designed out over time).  This generally means "Law" and "Fire" being selected as Domains have no order to their selection.  So the core generally operates with things like HashMap that ignore order (and are designed for speed).  The result is that the export of lists from the core does NOT guarantee order.
-When items are displayed to the end user, they must be sorted.  So one transformation that needs to take place before a list is output is for it to be sorted.  Note that this universallly applies to output (both output sheets and UI) and thus this is a reasonable candidate to be placed in a shared output layer.
+When items are displayed to the end user, they must be sorted.  So one transformation that needs to take place before a list is output is for it to be sorted.  Note that this universally applies to output (both output sheets and UI) and thus this is a reasonable candidate to be placed in a shared output layer.
 ==Core Object to Facade==
@@ Line 168: / Line 180: @@
 ===Consolidated Event===
-If we following the path of a consolidated event, we then note that the event must only contain 2 pieces of information: The CharID of the character that has been changed, and the name of the Output Channel.  Note that if the name is something more generic, such as "DOMAIN" (just a String), we no longer have to have the Facade recognizing that the core is composed of Facets.  Rather, it can just link up a known display element in the UI that is looking for the "DOMAIN" output channel with the response coming from the core containing that channel name.  The advantage of that is that it keeps the Ouptut layer generic to game mode.  As long as the channel is defined by the core (presumably controlled by the data) and the UI (designed to match the data), then it should be okay.
+If we following the path of a consolidated event, we then note that the event must only contain 2 pieces of information: The CharID of the character that has been changed, and the name of the Output Channel.  Note that if the name is something more generic, such as "DOMAIN" (just a String), we no longer have to have the Facade recognizing that the core is composed of Facets.  Rather, it can just link up a known display element in the UI that is looking for the "DOMAIN" output channel with the response coming from the core containing that channel name.  The advantage of that is that it keeps the Output layer generic to game mode.  As long as the channel is defined by the core (presumably controlled by the data) and the UI (designed to match the data), then it should be okay.
 This implies a need to have an error checking mechanism that ensures that any output channel requested by the UI actually exists in the core.
@@ Line 204: / Line 216: @@
 		PC Registration (-contract)
 	output channel
-		message to CFI (with name as arg)
+		message to PCFI (with name as arg)
 		use arg to look up method name in some way (hashtable to instances of an interface)
 		reflection

← Older revision		Revision as of 16:49, 25 May 2014
Line 142:		Line 142:

	====Consolidated Event====		====Consolidated Event====
−	~~For a consolidated~~
−
−
−
−


		+	If we following the path of a consolidated event, we then note that the event must only contain 2 pieces of information: The CharID of the character that has been changed, and the name of the Output Channel. Note that if the name is something more generic, such as "DOMAIN" (just a String), we no longer have to have the Facade recognizing that the core is composed of Facets. Rather, it can just link up a known display element in the UI that is looking for the "DOMAIN" output channel with the response coming from the core containing that channel name. The advantage of that is that it keeps the Ouptut layer generic to game mode. As long as the channel is defined by the core (presumably controlled by the data) and the UI (designed to match the data), then it should be okay.
		+	This implies a need to have an error checking mechanism that ensures that any output channel requested by the UI actually exists in the core.

	=Resulting Architecture=		=Resulting Architecture=

← Older revision		Revision as of 16:48, 25 May 2014
Line 156:		Line 156:
	This may actually be more convenient anyway, as it provides a single, well structured entity to capture events passing through the BlockingQueue.		This may actually be more convenient anyway, as it provides a single, well structured entity to capture events passing through the BlockingQueue.

−	~~==Contents of consolidated response events==~~
−	If we following the path of a consolidated event, we then note that the event must only contain 2 pieces of information: The CharID of the character that has been changed, and the name of the Output Channel. Note that if the name is something more generic, such as "DOMAIN" (just a String), we no longer have to have the Facade recognizing that the core is composed of Facets. Rather, it can just link up a known display element in the UI that is looking for the "DOMAIN" output channel with the response coming from the core containing that channel name. The advantage of that is that it keeps the Ouptut layer generic to game mode. As long as the channel is defined by the core (presumably controlled by the data) and the UI (designed to match the data), then it should be okay.
−	~~This implies a need to have an error checking mechanism that ensures that any output channel requested by the UI actually exists in the core.~~

	==Distributing Response Events==		==Distributing Response Events==

@@ Line 108: / Line 108: @@
 ===Facet to UI element===
-Through Output Channel
 ===Converting Core abstractions to concrete information===
 	In addition to the core moving to an event-based system, it is moving more toward a system that is independent of the assumptions in d20.  Therefore, what was once a set of specific methods to get information (getLegs() on Race.java) is now abstracted (now is getInteger(IntegerKey.LEGS)).  The result is a significant reduction in the assumptions in the core about what the data contains.  This provides flexibility as well as a way to reduce duplicate code.  As a result of this design in the core, the facade layer has taken on much of the responsibility of converting the core's "xKeys" to methods, so that the UI can directly access specific information about an object.  (There are a few exceptions where the facade has reached back and re-added those methods to the core, and that should be changed so the core does not have methods imposed upon it by the facades).  At some point, that abstracted information (IntegerKey.LEGS) needs to be converted to a concrete piece of information.  The question is where this occurs, and impacts the adapter/facade design.