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

    • 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

    • parseAndValidate

      public ParseResult<M> parseAndValidate() throws ModuleException
      Description copied from interface: ModuleParser
      Parses and validates the eLearning module in a single operation.

      This is the recommended method for most use cases. It parses the manifest once and returns both validation results and extracted metadata.

      Specified by:
      parseAndValidate in interface ModuleParser<T extends ModuleMetadata<M>>
      Returns:
      ParseResult containing validation results and module metadata
      Throws:
      ModuleException - if a fatal error occurs (file not found, XML corruption)

    • parseOnly

      public T parseOnly() throws ModuleException
      Description copied from interface: ModuleParser
      Parses the eLearning module without validation.

      Use this method only in performance-critical scenarios where validation is handled separately. Skips all validation checks.

      Specified by:
      parseOnly in interface ModuleParser<T extends ModuleMetadata<M>>
      Returns:
      ModuleMetadata containing the extracted module information
      Throws:
      ModuleException - if a fatal error occurs (file not found, XML corruption)

    • 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.

    • validateManifest

      protected abstract ValidationResult validateManifest(M manifest)
      Validates a parsed manifest and returns validation results. Subclasses implement this to use their parser-specific validators.
      Parameters:
      manifest - The parsed manifest to validate
      Returns:
      ValidationResult containing any errors or warnings

    • extractMetadata

      protected abstract T extractMetadata(M manifest, ValidationResult validation) throws ModuleException
      Extracts metadata from a parsed and validated manifest.
      Parameters:
      manifest - The parsed manifest
      validation - The validation result (for reference during extraction)
      Returns:
      Module-specific metadata
      Throws:
      ModuleException - if metadata extraction fails

    • getModuleType

      protected String getModuleType()
      Returns the module type name for error messages. Subclasses can override for more specific type names.
      Returns:
      The module type (e.g., "SCORM 1.2", "cmi5")

    • 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.

    • getManifestFileName

      protected abstract String getManifestFileName()
      Abstract method to return the filename of the manifest for the specific parser.
      Returns:
      The manifest filename (e.g., "imsmanifest.xml", "cmi5.xml")

    • 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