Added more comments and made some interfaces more generic

src/main/java/riomhaire/lti/JavaLti13ToolApplication.java

@@ -64,7 +64,7 @@ public class JavaLti13ToolApplication {
      * @return the Spring View-Model result of applyings a command to a message
      */
     @Bean
-    CommandDispatcher<ModelAndView, ApplicationRegistry, LTIMessage> buildCommandDispatcher() {
+    CommandDispatcher<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> buildCommandDispatcher() {
         return new LTIMessageDispatcher()
                 .addCommand(LTIMessageType.ProcessOidcRequest.name(), new InitiateOidcCommand())
                 .addCommand(LTIMessageType.ProcessLTIMessage.name(), new LTILaunchCommand())
@@ -80,7 +80,7 @@ public class JavaLti13ToolApplication {
      * @return Registry            environment links  we execute within
      */
     @Bean
-    public Registry buildRegistry(@NonNull CommandDispatcher<ModelAndView, ApplicationRegistry, LTIMessage> commandDispatcher, @NonNull ClientRegistrationResolver clientRegistrationResolver) {
+    public Registry buildRegistry(@NonNull CommandDispatcher<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> commandDispatcher, @NonNull ClientRegistrationResolver clientRegistrationResolver) {
         return new Registry(commandDispatcher, clientRegistrationResolver);
     }
 

src/main/java/riomhaire/lti/Registry.java

@@ -7,21 +7,43 @@ import riomhaire.lti.core.model.interfaces.ApplicationRegistry;
 import riomhaire.lti.core.model.interfaces.ClientRegistrationResolver;
 import riomhaire.lti.core.model.interfaces.CommandDispatcher;
 
+/**
+ *  ApplicationRegistry is the 'environment' within which commands ... it should contain things like
+ *  downstream service proxies etc.
+ *
+ *  The registry is also where the command dispatcher resides so that commands can call other commands.
+ *
+ *  The Environment os specific to the message that the command processes and the responses they generate.
+ *  In this model all commands take the same message model and return the same consistent model.
+ */
 @AllArgsConstructor
-public class Registry implements ApplicationRegistry {
+public class Registry implements ApplicationRegistry<ModelAndView,LTIMessage> {
 
-    private CommandDispatcher<ModelAndView, ApplicationRegistry, LTIMessage> commandDispatcher;
-    private ClientRegistrationResolver clientRegistrationResolver;
+    // This is the command dispatcher
+    private final CommandDispatcher<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> commandDispatcher;
+    // We need somewhere to read a tool/partner integration from - this service proxy performs that role.
+    private final ClientRegistrationResolver clientRegistrationResolver;
 
 
+    /**
+     *  Return the current client configuration resolver
+     * @return     ClientRegistrationResolver
+     */
     @Override
     public ClientRegistrationResolver clientRegistrationResolver() {
         return clientRegistrationResolver;
     }
 
+    /**
+     * Returns access to the current command dispatcher
+     *
+     * @return  CommandDispatcher
+     */
     @Override
-    public CommandDispatcher<ModelAndView, ApplicationRegistry, LTIMessage> commandDispatcher() {
+    public CommandDispatcher<ModelAndView, ApplicationRegistry<ModelAndView, LTIMessage>, LTIMessage> commandDispatcher() {
         return commandDispatcher;
     }
+
+
 }
 

src/main/java/riomhaire/lti/core/adapters/token/JWKBasedJwtToMapAdapter.java

@@ -14,17 +14,32 @@ import riomhaire.lti.core.model.interfaces.Decoder;
 
 import java.util.Map;
 
+/**
+ * This class is a helper class which takes a JWT token an verifies it is valid based on the jwk link provided
+ */
 @Slf4j
 public class JWKBasedJwtToMapAdapter implements Decoder<Map<String, Object>, String> {
-
+    // Issuer JWKS endpoint
     protected final String jwksUrl;
+    // True if we dont want to actually verify the token
     protected final boolean skipVerification;
 
+    /**
+     * Constructor
+     * @param jwksUrl  - the issuer endpoint where jwks is returned
+     * @param skipVerification - you can choose to verify or not.
+     */
     public JWKBasedJwtToMapAdapter(String jwksUrl, boolean skipVerification) {
         this.jwksUrl = jwksUrl;
         this.skipVerification = skipVerification;
     }
 
+    /**
+     * Decode and optionally verify the token
+     * @param token  jwt token to verify
+     * @return  the claims
+     * @throws DecodeException if there is something wrong - invalid token etc
+     */
     public Map<String, Object> decode(String token) throws DecodeException {
         DecodedJWT jwt = JWT.decode(token);
         JwtClaims verifiedClaims;

src/main/java/riomhaire/lti/core/business/LTIMessageDispatcher.java

@@ -17,29 +17,36 @@ import java.util.HashMap;
  */
 @Slf4j
 @NoArgsConstructor
-public class LTIMessageDispatcher implements CommandDispatcher<ModelAndView, ApplicationRegistry, LTIMessage> {
+public class LTIMessageDispatcher implements CommandDispatcher<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> {
     // This stores the mapping of command to command handler
-    private final HashMap<String, Command<ModelAndView, ApplicationRegistry, LTIMessage>> commands = new HashMap<>();
+    private final HashMap<String, Command<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage>> commands = new HashMap<>();
 
     // This is the action that is (optionally) executed if no match is made
-    private Command<ModelAndView, ApplicationRegistry, LTIMessage> defaultCommand;
+    private Command<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> defaultCommand;
 
     /**
-     * Adds a command handler for goven command
-     *
-     * @param commandName we allow same command to handle multiple requests
-     * @param command     does the work
-     * @return reference to dispatcher to allow fluent style usage.
+     * This adds a mapping of a message type to the command that can handle that type
+     * At the moment its a 1-1 mapping
+     * @param commandName  name of command ... we allow this because we want a command to potentially respond to more than one message type
+     * @param command   implementor
+     * @return  Command dispatcher so we can have some form of fluent style construction.
      */
     @Override
-    public CommandDispatcher<ModelAndView, ApplicationRegistry, LTIMessage> addCommand(String commandName, Command<ModelAndView, ApplicationRegistry, LTIMessage> command) {
+    public CommandDispatcher<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> addCommand(String commandName, Command<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> command) {
         commands.put(commandName, command);
         return this;
     }
 
 
+    /**
+     * This is called by an invoker with
+     *
+     * @param registry  to execute within
+     * @param message  the message to process.. the implementer of this interface should have a strategy of mapping message to command
+     * @return response from executing the command
+     */
     @Override
-    public ModelAndView dispatch(ApplicationRegistry registry, LTIMessage message) {
+    public ModelAndView dispatch(ApplicationRegistry<ModelAndView,LTIMessage> registry, LTIMessage message) {
         var mav = new ModelAndView("nop");
         // If we have a handler for this command execute it
         if (message != null && commands.containsKey(message.getMessageType())) {
@@ -50,7 +57,12 @@ public class LTIMessageDispatcher implements CommandDispatcher<ModelAndView, App
         return mav;
     }
 
-    public void setDefaultCommand(Command<ModelAndView, ApplicationRegistry, LTIMessage> defaultCommand) {
+    /**
+     * This implementation allows a default action to be taken  if no mapping is found. This is the setter for that
+     *
+     * @param defaultCommand  what command/action to execute if no mapping is found - something to generate an error
+     */
+    public void setDefaultCommand(Command<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> defaultCommand) {
         this.defaultCommand = defaultCommand;
     }
 

src/main/java/riomhaire/lti/core/business/commands/InitiateOidcCommand.java

@@ -11,12 +11,21 @@ import riomhaire.lti.core.model.interfaces.Command;
 
 import java.util.UUID;
 
+/**
+ * Defines  execute command on message P within environment E returning T
+ *
+ * @param <T> What object is returned by the command
+ * @param <E> WHat execution environment is to be used (usually some form of Application Registry)
+ * @param <P> The message the command can process
+ *
+ * This implementation is for the OIDC Initiation call made by an issuer as part of the security specification.
+ */
 @AllArgsConstructor
 @Slf4j
-public class InitiateOidcCommand implements Command<ModelAndView, ApplicationRegistry, LTIMessage> {
+public class InitiateOidcCommand implements Command<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> {
 
 
-    public ModelAndView execute(ApplicationRegistry registry, LTIMessage message) {
+    public ModelAndView execute(ApplicationRegistry<ModelAndView,LTIMessage> registry, LTIMessage message) {
         final ModelAndView mav;
         var queryParams = message.getQueryParams();
         String iss = queryParams.get("iss");

src/main/java/riomhaire/lti/core/business/commands/LTILaunchCommand.java

@@ -16,18 +16,24 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
+ * Defines  execute command on message P within environment E returning T
+ *
+ * @param <T> What object is returned by the command
+ * @param <E> WHat execution environment is to be used (usually some form of Application Registry)
+ * @param <P> The message the command can process
+ *
  * Processes lti launch content and create deep link messages - IE claims within a JWT
- * Delegates to the actual handler
+ * Delegates to the actual handler  depending on if its just a launch or a create-deep-link launch
  */
 @AllArgsConstructor
 @Slf4j
-public class LTILaunchCommand implements Command<ModelAndView, ApplicationRegistry, LTIMessage> {
+public class LTILaunchCommand implements Command<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> {
     public static final String CLAIM_MESSAGE_TYPE = "https://purl.imsglobal.org/spec/lti/claim/message_type";
     public static final String LTI_RESOURCE_LINK_REQUEST = "LtiResourceLinkRequest";
     public static final String LTI_DEEP_LINKING_REQUEST = "LtiDeepLinkingRequest";
 
     @Override
-    public ModelAndView execute(ApplicationRegistry registry, LTIMessage message) {
+    public ModelAndView execute(ApplicationRegistry<ModelAndView,LTIMessage> registry, LTIMessage message) {
         var idToken = message.getQueryParams().get("id_token");
         var jwtToken = message.getQueryParams().get("JWT");
         // Crack open so we can find the config

src/main/java/riomhaire/lti/core/business/commands/LaunchContentCommand.java

@@ -8,10 +8,20 @@ import riomhaire.lti.core.model.interfaces.Command;
 import java.util.HashMap;
 import java.util.function.Function;
 
-public class LaunchContentCommand implements Command<ModelAndView, ApplicationRegistry, LTIMessage> {
+/**
+ * Defines  execute command on message P within environment E returning T
+ *
+ * @param <T> What object is returned by the command
+ * @param <E> WHat execution environment is to be used (usually some form of Application Registry)
+ * @param <P> The message the command can process
+ *
+ * This is what should render or redirect to the actual content. In this case we just pretty-print what was sent as
+ * metadata and what claims are in the JWT
+ */
+public class LaunchContentCommand implements Command<ModelAndView, ApplicationRegistry<ModelAndView,LTIMessage>, LTIMessage> {
 
     @Override
-    public ModelAndView execute(ApplicationRegistry environment, LTIMessage message) {
+    public ModelAndView execute(ApplicationRegistry<ModelAndView,LTIMessage> environment, LTIMessage message) {
         final String prefix = "https://purl.imsglobal.org/spec/lti/claim/";
         var simplifiedClaims = new HashMap<String, Object>();
         var mav = new ModelAndView("dump-launch");

src/main/java/riomhaire/lti/core/infrastructure/facades/clientregistration/ConfigBasedClientRegistrationResolver.java

@@ -6,8 +6,21 @@ import riomhaire.lti.core.model.interfaces.ClientRegistrationResolver;
 
 import java.util.Optional;
 
-public class ConfigBasedClientRegistrationResolver implements ClientRegistrationResolver {
+/**
+ *  When a tool/partner-lms is registered we need to store this information somewhere ... and we have
+ *  abstracted this out as a  'ClientRegistrationResolver'. Implementations of this interface  could be
+ *  to a file, DB or Redis - but all the call wants to know about is I want to find out about this deployment
+ *
+ * This is a config file based implementation
+ */
+ public class ConfigBasedClientRegistrationResolver implements ClientRegistrationResolver {
 
+    /**
+     * Return the registration information related to this issuer/client-id pair
+     * @param issuer    ... This is canvas/blackboard or some other entity
+     * @param clientId  ... This is a particular tool within the issuer environment
+     * @return  ClientConfiguration if found
+     */
     @Override
     public Optional<ClientConfiguration> lookupClient(String issuer, String clientId) {
         return Optional.empty();

src/main/java/riomhaire/lti/core/infrastructure/facades/clientregistration/RedisBasedClientRegistrationResolver.java

@@ -10,14 +10,31 @@ import riomhaire.lti.core.model.interfaces.ClientRegistrationResolver;
 import java.util.Optional;
 
 
+/**
+ *  When a tool/partner-lms is registered we need to store this information somewhere ... and we have
+ *  abstracted this out as a  'ClientRegistrationResolver'. Implementations of this interface  could be
+ *  to a file, DB or Redis - but all the call wants to know about is I want to find out about this deployment
+ *
+ *  This implementation is for Redis
+ */
 public class RedisBasedClientRegistrationResolver implements ClientRegistrationResolver {
     final ObjectMapper objectMapper = new ObjectMapper();
     private final RedisTemplate<String, String> template;
 
+    /**
+     *
+     * @param template THe spring redis template
+     */
     public RedisBasedClientRegistrationResolver(RedisTemplate<String, String> template) {
         this.template = template;
     }
 
+    /**
+     * Return the registration information related to this issuer/client-id pair
+     * @param issuer    ... This is canvas/blackboard or some other entity
+     * @param clientId  ... This is a particular tool within the issuer environment
+     * @return  ClientConfiguration if found
+     */
     @SneakyThrows
     @Override
     public Optional<ClientConfiguration> lookupClient(String issuer, String clientId) {

src/main/java/riomhaire/lti/core/model/interfaces/ApplicationRegistry.java

@@ -7,15 +7,24 @@ import riomhaire.lti.core.model.LTIMessage;
  * This is the minimal Registry info on the environment. Its the context within which commands run and can get
  * Access to other components
  */
-public interface ApplicationRegistry {
+public interface ApplicationRegistry<R,M> {
 
-    // This is a entity which allows tool to verify token etc is from some reputible source
-    // The default implementation is a caller to redis where we have information on a deployed registered tool
-    // And where to find the JWKS etc
+    /**
+     * Return the current client configuration resolver
+     * This is a entity which allows tool to verify token etc is from some reliable source
+     * The default implementation is a caller to redis where we have information on a deployed registered tool
+     * And where to find the JWKS etc
+     * @return     ClientRegistrationResolver
+     */
     ClientRegistrationResolver clientRegistrationResolver();
 
-    // command dispatcher... this is the entity that stores a mapping between a message type and its handler
-    // command. It looks up the message type and delegates to a command to handle it. There is a default command
-    // handler if no command has been registered. At the moment its a 1-1 mapping
-    CommandDispatcher<ModelAndView, ApplicationRegistry, LTIMessage> commandDispatcher();
+
+    /**
+     * command dispatcher... this is the entity that stores a mapping between a message type and its handler
+     * command. It looks up the message type and delegates to a command to handle it. There is a default command
+     * handler if no command has been registered. At the moment its a 1-1 mapping
+     *
+     * @return  CommandDispatcher
+     */
+    CommandDispatcher<R, ApplicationRegistry<R,M>, M> commandDispatcher();
 }

src/main/java/riomhaire/lti/core/model/interfaces/ClientRegistrationResolver.java

@@ -4,6 +4,17 @@ import riomhaire.lti.core.model.ClientConfiguration;
 
 import java.util.Optional;
 
+/**
+ *  When a tool/partner-lms is registered we need to store this information somewhere ... and we have
+ *  abstracted this out as a  'ClientRegistrationResolver'. Implementations of this interface  could be
+ *  to a file, DB or Redis - but all the call wants to know about is I want to find out about this deployment
+ */
 public interface ClientRegistrationResolver {
+    /**
+     * Return the registration information related to this issuer/client-id pair
+     * @param issuer    ... This is canvas/blackboard or some other entity
+     * @param clientId  ... This is a particular tool within the issuer environment
+     * @return  ClientConfiguration if found
+     */
     Optional<ClientConfiguration> lookupClient(String issuer, String clientId);
 }

src/main/java/riomhaire/lti/core/model/interfaces/Command.java

@@ -3,10 +3,16 @@ package riomhaire.lti.core.model.interfaces;
 /**
  * Defines  execute command on message P within environment E returning T
  *
- * @param <T>
- * @param <E>
- * @param <P>
+ * @param <T> What object is returned by the command
+ * @param <E> WHat execution environment is to be used (usually some form of Application Registry)
+ * @param <P> The message the command can process
  */
 public interface Command<T, E, P> {
+    /**
+     * This is the signature a message processing command can implement when invoked by the dispatcher
+     * @param environment  - usually some form of application registry
+     * @param message - what message format the command will get
+     * @return some response
+     */
     T execute(E environment, P message);
 }

src/main/java/riomhaire/lti/core/model/interfaces/CommandDispatcher.java

@@ -1,8 +1,30 @@
 package riomhaire.lti.core.model.interfaces;
 
+/**
+ * A command dispatcher matches commands to actions that proccess them based off of some message
+ *
+ * @param <T> What object is returned by the command
+ * @param <E> WHat execution environment is to be used (usually some form of Application Registry)
+ * @param <P> The message the command can process
+
+ */
 public interface CommandDispatcher<R, E, P> {
 
+    /**
+     * This adds a mapping of a message type to the command that can handle that type
+     * At the moment its a 1-1 mapping
+     * @param commandName  name of command ... we allow this because we want a command to potentially respond to more than one message type
+     * @param command   implementor
+     * @return  Command dispatcher so we can have some form of fluwnt style construction.
+     */
     CommandDispatcher<R, E, P> addCommand(String commandName, Command<R, E, P> command);
 
+    /**
+     * This is called by an invoker with
+     *
+     * @param environment  to execute within
+     * @param message  the message to process.. the implementer of this interface should have a strategy of mapping message to command
+     * @return response from executing the command
+     */
     R dispatch(E environment, P message);
 }