Package dev.jcputney.elearning.parser.parsers

Class BaseParser<T extends ModuleMetadata<M>,M extends PackageManifest>

java.lang.Object
dev.jcputney.elearning.parser.parsers.BaseParser<T,M>
Type Parameters:
T - The type of ModuleMetadata that this parser will return.
M - The type of PackageManifest that this parser will work with.
All Implemented Interfaces:
ModuleParser<M>
Direct Known Subclasses:
AiccParser, Cmi5Parser, Scorm12Parser, Scorm2004Parser, XapiParser
public abstract sealed class BaseParser<T extends ModuleMetadata<M>,M extends PackageManifest> extends Object implements ModuleParser<M> permits AiccParser, Cmi5Parser, Scorm12Parser, Scorm2004Parser, XapiParser
Abstract base class for all module parsers, providing shared capability for common operations, like detecting xAPI-related files and utility methods for file parsing.

This class shouldn't parse any module types directly but should provide utility methods and abstract methods to be implemented by the specific module parsers (SCORM, cmi5, LTI, etc.).

  • Field Details

    • XAPI_JS_FILE

      public static final String XAPI_JS_FILE
      The name of the xAPI JavaScript file.
      See Also:

    • XAPI_SEND_STATEMENT_FILE

      public static final String XAPI_SEND_STATEMENT_FILE
      The name of the sendStatement JavaScript file.
      See Also:

    • moduleFileProvider

      protected final ModuleFileProvider moduleFileProvider
      The ModuleFileProvider instance used for reading files in the module package.

    • options

      protected final ParserOptions options
      The parser options controlling validation and calculation behavior.

  • Constructor Details

    • BaseParser

      protected BaseParser(ModuleFileProvider moduleFileProvider, ParserOptions options)
      Constructs a BaseParser with the specified ModuleFileProvider instance and parser options.
      Parameters:
      moduleFileProvider - An instance of ModuleFileProvider for reading files in the module package.
      options - Parser options controlling validation and calculation behavior (null for defaults)
      Throws:
      IllegalArgumentException - if moduleFileProvider is null

    • BaseParser

      protected BaseParser(ModuleFileProvider moduleFileProvider)
      Constructs a BaseParser with the specified ModuleFileProvider instance and default options.
      Parameters:
      moduleFileProvider - An instance of ModuleFileProvider for reading files in the module package.
      Throws:
      IllegalArgumentException - if moduleFileProvider is null

    • BaseParser

      protected BaseParser(FileAccess fileAccess, ParserOptions options)
      Constructs a BaseParser with the specified FileAccess instance and parser options. This constructor creates a DefaultModuleFileProvider that wraps the FileAccess instance.
      Parameters:
      fileAccess - An instance of FileAccess for reading files in the module package.
      options - Parser options controlling validation and calculation behavior (null for defaults)
      Throws:
      IllegalArgumentException - if fileAccess is null

    • BaseParser

      protected BaseParser(FileAccess fileAccess)
      Constructs a BaseParser with the specified FileAccess instance and default options. This constructor creates a DefaultModuleFileProvider that wraps the FileAccess instance.
      Parameters:
      fileAccess - An instance of FileAccess for reading files in the module package.
      Throws:
      IllegalArgumentException - if fileAccess is null

  • Method Details

    • parse

      public abstract T parse() throws ModuleException
      Abstract method that parses the module and returns the corresponding metadata object. This must be implemented by the child parsers (for example, SCORM, cmi5, LTI).
      Specified by:
      parse in interface ModuleParser<T extends ModuleMetadata<M>>
      Returns:
      A ModuleMetadata object containing the parsed module metadata.
      Throws:
      ModuleException - If the module type can't be determined or there's an error parsing.

    • getOptions

      public ParserOptions getOptions()
      Gets the parser options controlling validation behavior.
      Specified by:
      getOptions in interface ModuleParser<T extends ModuleMetadata<M>>
      Returns:
      ParserOptions for this parser

    • validate

      public ValidationResult validate()
      Validates the module without parsing. Returns validation result with errors/warnings. Default implementation parses the module and returns any validation errors. Subclasses can override for more specific validation logic.
      Specified by:
      validate in interface ModuleParser<T extends ModuleMetadata<M>>
      Returns:
      ValidationResult containing errors and warnings

    • parseManifest

      public M parseManifest(String manifestPath) throws IOException, XMLStreamException, ManifestParseException
      Parses a manifest file from the given path, processes its content, and returns the parsed manifest object.
      Parameters:
      manifestPath - the file path to the manifest file to be parsed. This cannot be null.
      Returns:
      an object of type M representing the parsed manifest content.
      Throws:
      IOException - if an error occurs while reading the manifest file.
      XMLStreamException - if an error occurs while parsing the XML content of the manifest.
      ManifestParseException - if the manifest file cannot be read or parsed.
      IllegalArgumentException - if the provided manifestPath is null.

    • getManifestClass

      protected abstract Class<M> getManifestClass()
      Abstract method to return the class of the manifest object for the specific parser.
      Returns:
      The class of the manifest object.

    • checkForXapi

      protected boolean checkForXapi()
      Checks if the module contains xAPI-related files (for example, xAPI.js, sendStatement.js). These files indicate whether xAPI tracking is enabled for the module.
      Returns:
      true if xAPI is enabled, false otherwise.

    • parseXmlToObject

      protected <C> C parseXmlToObject(InputStream stream, Class<C> clazz) throws IOException, XMLStreamException
      Parses an XML file into an object of the specified class using Jackson's XmlMapper.
      Type Parameters:
      C - The type of the class to parse the XML into.
      Parameters:
      stream - The InputStream for the XML file.
      clazz - The class to parse the XML into.
      Returns:
      A new instance of the specified class with the parsed XML data.
      Throws:
      IOException - If an error occurs while reading the file.
      XMLStreamException - If an error occurs while parsing the XML.
      IllegalArgumentException - if stream or clazz is null

    • loadExternalMetadataIntoMetadata

      protected void loadExternalMetadataIntoMetadata(LoadableMetadata subMetadata) throws XMLStreamException, IOException
      Loads an external LOM metadata file into the specified LoadableMetadata object.

      This method reads the external metadata file and sets the LOM object in the LoadableMetadata instance if the file exists and can be parsed.

      If the external metadata file doesn't exist or can't be parsed, the LoadableMetadata object won't be modified.

      This method is intended to be used by parsers that support external metadata files, such as SCORM 1.2 and SCORM 2004.

      Parameters:
      subMetadata - The LoadableMetadata object to load the external metadata into.
      Throws:
      XMLStreamException - If an error occurs while parsing the XML.
      IOException - If an error occurs while reading the file.
      IllegalArgumentException - if subMetadata is null