Interface VilleSubmissionFields

All Superinterfaces:
Comparable<VilleSubmissionFields>
All Known Subinterfaces:
GitLabSubmissionFields
All Known Implementing Classes:
demopalautus, GitLabSubmission, MyOwnGitlabSubmission, MyOwnVilleGitLabSubmission, VilleSubmission, VilleTestObject
public interface VilleSubmissionFields extends Comparable<VilleSubmissionFields>
Base interface for all ViLLe submission types.

Represents the minimal metadata guaranteed to exist in all ViLLe CSV exports, regardless of the specific submission box type (e.g., GitLab link, essay, quiz).

The source of this metadata is typically the first fields of any ViLLe CSV header, regardless of submission type. For example: 

 User$First name$Last name$Time$Student number or other id code$

⚠ Note: Although the example uses $ as a delimiter, ViLLe allows the user to choose any delimiter during export. The default semicolon ; is discouraged and explicitly rejected by the parsing logic in VilleCsvUtils.readAllRows(...)}.

This interface defines only the required accessors. All implementing classes must:

  • Provide a constructor that accepts a single String[] representing a CSV row
  • Ensure that each getter returns exactly one value from that array
  • Not reuse a field across multiple getters — all mappings must be 1-to-1

The input String[] is typically one of the rows returned by: ViLLeCsvFile.getEntries(), where each array represents a single parsed entry from the CSV file (excluding the header).

All arrays in this list are guaranteed to have the same length — matching the number of columns in the header. However, not all fields in the array need to be used, but each getter method must return exactly one unique field from this array. No two getters may map to the same index.

A default implementation — DefaultVilleSubmission — is provided for basic cases where custom field sanitation or logic is not required.

  • Method Summary

    Modifier and Type
    Method
    Description
    default int
    compareTo(VilleSubmissionFields other)
    Enables sorting of submissions using getID() as the primary sort key.
    String
    getFirstName()
    Returns the student's given name.
    default String
    getFolderName()
    Constructs a filesystem-safe folder name for storing this student's submission.
    default String
    getID()
    Extracts a simplified ID from the user's email by removing dots and the domain part.
    String
    getLastName()
    Returns the student's surname.
    String
    getParentFolderName()
    Returns the name of the parent folder under which this submission and other similar submissions should be grouped on disk.
    String
    getStudentId()
    Returns the student's official identifier, such as a student number or other ID code.
    String
    getTime()
    Returns the timestamp of the submission as a raw string.
    String
    getUser()
    Returns the full user identifier, typically an email address.

  • Method Details

    • getUser

      String getUser()
      Returns the full user identifier, typically an email address.

      This value should be unique across submissions, and is often used to derive internal IDs.

      Returns:
      the user's identifier (e.g., "student@university.fi")

    • getFirstName

      String getFirstName()
      Returns the student's given name.
      Returns:
      first name

    • getLastName

      String getLastName()
      Returns the student's surname.
      Returns:
      last name

    • getTime

      String getTime()
      Returns the timestamp of the submission as a raw string.

      No specific format is enforced — it is the implementer's responsibility to parse or sanitize this if needed.

      Returns:
      submission time as string

    • getStudentId

      String getStudentId()
      Returns the student's official identifier, such as a student number or other ID code.
      Returns:
      student ID

    • getFolderName

      default String getFolderName()
      Constructs a filesystem-safe folder name for storing this student's submission.

      The folder name is structured as getID() + "_" + getLastName() + "_" + getFirstName(), and is designed to be:

      • Lexicographically sortable
      • Safe for filesystem use
      • Compatible with alphabetical partitioning across assistants

      The cleaned email identifier (from getID()) is placed first to ensure consistent sort order, even when names are missing or contain special characters.

      Returns:
      filesystem-safe folder name

    • getID

      default String getID()
      Extracts a simplified ID from the user's email by removing dots and the domain part.

      For example, "john.doe@student.edu" becomes "johndoe". This ID is intended to be:

      • Short and stable
      • Safe to use as a filename prefix
      • Lexicographically sortable

      This method can be overridden if the default derivation is unsuitable for a specific implementation.

      Returns:
      cleaned identifier string

    • getParentFolderName

      String getParentFolderName()
      Returns the name of the parent folder under which this submission and other similar submissions should be grouped on disk.

      This value is typically used to construct file trees such as: 

       clones/
 └── getParentFolderName()/
     ├── getFolderName()/
     └── ...
      where each student's folder (or file) under this parent directory is named according to getFolderName().

      The default implementations — DefaultVilleSubmission and DefaultGitLabSubmission — derive this parent name from the original ViLLe export file they were constructed from. These implementations use constructors like: 

       new DefaultGitLabSubmission(String[] villeCsvRow, ViLLeCsvFile source)
      and retain the ViLLeCsvFile instance in order to expose its filename.

      When using SubmissionMapper, this constructor signature is enforced. Any class meant to work with the mapper must follow this pattern if they want deterministic file layout or per-batch isolation in the output structure.

      If you are not using `SubmissionMapper`, a timestamp or other batch-level identifier can be returned instead.

      Returns:
      filesystem-safe parent folder name for output grouping

    • compareTo

      default int compareTo(VilleSubmissionFields other)
      Enables sorting of submissions using getID() as the primary sort key.

      This is useful for consistent ordering of output folders or filenames, especially when names contain special characters or are missing entirely.

      Specified by:
      compareTo in interface Comparable<VilleSubmissionFields>
      Parameters:
      other - another VilleSubmission to compare to
      Returns:
      comparison result based on getID()