Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.configuration

Class Configuration

java.lang.Object

page.codeberg.friedolyn.configuration.Configuration

All Implemented Interfaces:

Copyable<Configuration>, Redactable

public class Configuration
extends Object
implements Redactable, Copyable<Configuration>

Represents the configuration of the Friedolyn application.

Field Summary

Fields

Modifier and Type	Field	Description
private @NonNull Set<String>	academicDegrees	The academic degrees that the student is currently pursuing, for example "Bachelor of Science".
static final @NonNull String[]	ALLOWED_CONFIGURATION_FILENAMES	Default file names for the configuration that will be used if no explicit file name is specified.
private @NonNull Argon2Configuration	argon2Configuration	The parameters for the Argon2 hashing algorithm to use when computing the userHash, clearnameHash and emailHash.
private BannedUser	ban	The student represented by this configuration, as an item in the polled metadata's blacklist if they are, in fact, banned.
private String	clearname	The real name of the student, for example "Edward Snowden".
private HashingResult	clearnameHash	The Argon2 hash of the clearname, that matches the argon2Configuration.
private @NonNull HashSet<HashingResult>	clearnameHashes	Other hashes of the clearname field with possibly different Argon2Configurations.
private @NonNull Client	client	Options for the HTTP client that will connect to the server.
private ContactMethods	contactMethods	How the developers can contact the student, for example if the student has sent an email to the developers.
private @NonNull DebugLevel	debugLevel	How verbose the application should be.
private @NonNull File	directory	The path to the folder in the file system where the configuration and other application data shall be stored.
private jakarta.mail.internet.InternetAddress	email	The email address of the student used for notifications.
private HashingResult	emailHash	The Argon2 hash of the email field, that matches the argon2Configuration.
private @NonNull HashSet<HashingResult>	emailHashes	Other hashes of the email field with possibly different Argon2Configurations.
private @NonNull Set<@NonNull ExamsPDF>	examPDFs	Which of the available PDF files that include the student's grades should be downloaded from Friedolin.
private @NonNull File	file	The path to the file in the file system where the configuration shall be written to.
private @NonNull Boolean	hideGraphicalUserInterface	Whether the graphical user interface (GUI) of the application should be hidden.
private @NonNull Duration	interval	How often the application should fetch the student's grades from the Friedolin server.
private static final @NonNull String	JSON_SCHEMA	The JSON schema that the content of any input passed to the fromFile(File) method must adhere to.
private Notifications	notifications	The user's preferences for receiving notifications about their grades.
private @NonNull Boolean	overwriteExistingExamsPDFs	When repeatedly fetching the student's examPDFs, should the existing files be deleted and replaced with the new, updated ones? If false, the current date and time will be prepended to the file names.
private char[]	password	The password (login secret) of the Friedolin account.
private @NonNull Boolean	useKeePassXC	Whether the application should use KeePassXC to retrieve the Friedolin login credentials.
private String	user	The username of the Friedolin account to use, for example "es13nsa".
private HashingResult	userHash	The Argon2 hash of the user field, that matches the argon2Configuration.
private @NonNull HashSet<HashingResult>	userHashes	Other hashes of the user field with possibly different Argon2Configurations.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Configuration()	Creates a new configuration without a user and without a password.
	Configuration(@NonNull String user, char[] password)	Creates a new configuration with the given user and password.
private	Configuration(String user, String password, Boolean useKeePassXC)	Creates a new configuration with the given user, password and academic degrees.

Method Summary

Modifier and Type	Method	Description
@NonNull Optional<HashingResult>	computeClearnameHash()	Forcibly computes the clearnameHash and returns it, even if it already exists.
@NonNull Optional<HashingResult>	computeEmailHash()	Forcibly computes the emailHash and returns it, even if it already exists.
@NonNull Optional<HashingResult>	computeUserHash()	Forcibly computes the userHash (even if it already exists) and returns it.
@NonNull Configuration	copy()
static @NonNull Configuration	fromFile(File file)	Creates a new Configuration from a given JSON file.
static @NonNull Configuration	fromJSON(String json)	Creates a new Configuration from a given JSON.
Optional<BannedUser>	getBan()
@NonNull Optional<String>	getClearname()
@NonNull Optional<HashingResult>	getClearnameHash()	Returns the Argon2 hash of the clearname field (if it is set).
@NonNull HashSet<HashingResult>	getClearnameHashes()
@NonNull Client	getClient()
@NonNull Optional<ContactMethods>	getContactMethods()
@NonNull Optional<jakarta.mail.internet.InternetAddress>	getEmail()
@NonNull File	getEmailDirectory()
@NonNull Optional<HashingResult>	getEmailHash()	Returns the Argon2 hash of the email field (if it is set).
@NonNull HashSet<HashingResult>	getEmailHashes()
@NonNull Optional<Notifications>	getNotifications()
@NonNull Optional<char[]>	getPassword()
@NonNull Client	getReferenceToClient()
@NonNull Optional<ContactMethods>	getReferenceToContactMethods()
@NonNull Optional<String>	getUser()
@NonNull Optional<HashingResult>	getUserHash()	Returns the Argon2 hash of the user field (if it is set).
@NonNull HashSet<HashingResult>	getUserHashes()
boolean	isBanned()
void	resetClearname()	Deletes the current value of the clearname, removes its hash and empties the clearnameHashes.
void	saveToFile()	Writes this configuration to the file in JSON format.
private Set<String>	serialiseAcademicDegrees()	Deprecated. Used only for Jackson deserialisation.
private Client	serialiseClient()	Deprecated. Used only for Jackson deserialisation.
private ContactMethods	serialiseContactMethods()	Deprecated. Used only for Jackson deserialisation.
private String	serialiseDebugLevel()	Deprecated. Used only for Jackson deserialisation.
private @NonNull Optional<String>	serialiseEmail()	Deprecated. Used only for Jackson deserialisation.
private HashSet<ExamsPDF>	serialiseExamsPDFs()	Deprecated. Used only for Jackson deserialisation.
private Long	serialiseInterval()	Deprecated. Used only for Jackson deserialisation.
private String	serialisePassword()	Deprecated. Used only for Jackson deserialisation.
private String	serialiseUser()	Deprecated. Used only for Jackson deserialisation.
void	setAcademicDegrees(@NonNull Set<@NonNull String> academicDegrees)	Updates the academicDegrees field with the given one.
void	setArgon2Configuration(@NonNull Argon2Configuration argon2Configuration, boolean resetHashes)	Updates the argon2Configuration field with a deep copy of the given Argon2Configuration and, optionally, deletes the userHash, clearnameHash and emailHash fields as well as the userHashes, clearnameHashes and emailHashes sets.
void	setBan(@NonNull BannedUser ban)
void	setClearname(@NonNull String clearname)	Updates the clearname field with the given one, deletes the clearnameHash and empties the clearnameHashes.
void	setClient(@NonNull Client client)	Updates the client with the deep copy of a new one.
void	setContactMethods(@NonNull ContactMethods contactMethods)	Updates the contactMethods field with a deep copy of the given one.
private void	setContactMethodsNullable(ContactMethods contactMethods)	Deprecated. This method is only used for Jackson deserialisation.
private void	setDebugLevel(String debugLevel)	Updates the debugLevel and invalid reference Main.debugLevel fields with the given one.
void	setDebugLevel(@NonNull DebugLevel debugLevel)	Updates the debugLevel and invalid reference Main.debugLevel fields with the given one.
void	setDirectory(@NonNull File directory)	Updates the directory field with the given one and also saves it into the persistent Preferences of the Friedolyn class as directory.
void	setEmail(@NonNull jakarta.mail.internet.InternetAddress email)	Updates the email field with the given one, deletes the emailHash and empties the emailHashes.
private void	setExamPDFs(String[] examPDFs)	Deprecated. This method is only used for Jackson deserialisation.
void	setExamPDFs(@NonNull Set<ExamsPDF> examsPdfs)	Updates the examPDFs field with the given one.
void	setFile(@NonNull File file)	Updates the file field with the given one and also saves it into the persistent Preferences of the Friedolyn class as file.
void	setInterval(@NonNull Duration interval)	Updates the interval field with the given one.
private void	setIntervalMinutes(long interval)	Deprecated. Used only for Jackson deserialisation.
void	setNotifications(@NonNull Notifications notifications)	Updates the notifications field with the exact reference of the given one.
void	setPassword(char[] password)	Updates the password field with the given one.
private void	setPassword(@NonNull String password)	Deprecated. This method is only used for Jackson deserialisation.
void	setReferenceToContactMethods(@NonNull ContactMethods contactMethods)	Updates the contactMethods field with the exact reference of the given one.
void	setUseKeePassXC(boolean useKeePassXC)	Updates the user's preference whether the KeePassXC password manager should be used to retrieve the user's login credentials for Friedolin, i.e.
void	setUser(@NonNull String user)	Updates the user field accordingly.
@NonNull String	toJSON()
@NonNull String	toString()
@NonNull String	toStringRedacted()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

JSON_SCHEMA

@NonNull
private static final @NonNull String JSON_SCHEMA

The JSON schema that the content of any input passed to the fromFile(File) method must adhere to.

directory

@NonNull
private @NonNull File directory

The path to the folder in the file system where the configuration and other application data shall be stored. Defaults to Friedolyn.DEFAULT_ROOT.

file

@NonNull
private @NonNull File file

The path to the file in the file system where the configuration shall be written to. Defaults to friedolyn.json in the directory.

user

@Nullable
private String user

The username of the Friedolin account to use, for example "es13nsa".

See Also:

• userHash
• userHashes

userHash

@Nullable
private HashingResult userHash

The Argon2 hash of the user field, that matches the argon2Configuration. Used for banning users.

See Also:

• userHashes
• computeUserHash()

userHashes

@NonNull
private @NonNull HashSet<HashingResult> userHashes

Other hashes of the user field with possibly different Argon2Configurations. Used for banning users.

See Also:

• userHash
• computeUserHash()

argon2Configuration

@NonNull
private @NonNull Argon2Configuration argon2Configuration

The parameters for the Argon2 hashing algorithm to use when computing the userHash, clearnameHash and emailHash.

password

@Nullable
private char[] password

The password (login secret) of the Friedolin account. There is no two-factor authentication.

clearname

@Nullable
private String clearname

The real name of the student, for example "Edward Snowden".

See Also:

• clearnameHash
• clearnameHashes

clearnameHash

@Nullable
private HashingResult clearnameHash

The Argon2 hash of the clearname, that matches the argon2Configuration. Used for banning users.

See Also:

• computeClearnameHash()

clearnameHashes

@NonNull
private @NonNull HashSet<HashingResult> clearnameHashes

Other hashes of the clearname field with possibly different Argon2Configurations.

See Also:

• clearnameHash
• computeClearnameHash()

academicDegrees

@NonNull
private @NonNull Set<String> academicDegrees

The academic degrees that the student is currently pursuing, for example "Bachelor of Science".

email

@Nullable
private jakarta.mail.internet.InternetAddress email

The email address of the student used for notifications.

See Also:

• emailHash
• emailHashes

emailHash

@Nullable
private HashingResult emailHash

The Argon2 hash of the email field, that matches the argon2Configuration. Used for banning users.

See Also:

• emailHashes
• computeEmailHash()

emailHashes

@NonNull
private @NonNull HashSet<HashingResult> emailHashes

Other hashes of the email field with possibly different Argon2Configurations. Used for banning users.

See Also:

• emailHash
• computeEmailHash()

examPDFs

@NonNull
private @NonNull Set<@NonNull ExamsPDF> examPDFs

Which of the available PDF files that include the student's grades should be downloaded from Friedolin.

overwriteExistingExamsPDFs

@NonNull
private @NonNull Boolean overwriteExistingExamsPDFs

When repeatedly fetching the student's examPDFs, should the existing files be deleted and replaced with the new, updated ones? If false, the current date and time will be prepended to the file names. Defaults to false.

interval

@NonNull
private @NonNull Duration interval

How often the application should fetch the student's grades from the Friedolin server. Defaults to Friedolyn.DEFAULT_INTERVAL. Must be at least Friedolyn.MINIMUM_INTERVAL and at most Friedolyn.MAXIMUM_INTERVAL.

client

@NonNull
private @NonNull Client client

Options for the HTTP client that will connect to the server.

contactMethods

@Nullable
private ContactMethods contactMethods

How the developers can contact the student, for example if the student has sent an email to the developers.

debugLevel

@NonNull
private @NonNull DebugLevel debugLevel

How verbose the application should be. Defaults to DebugLevel.WARN.

hideGraphicalUserInterface

@NonNull
private @NonNull Boolean hideGraphicalUserInterface

Whether the graphical user interface (GUI) of the application should be hidden. Defaults to false. This has nothing to do with the HeadlessBrowser.

useKeePassXC

@NonNull
private @NonNull Boolean useKeePassXC

Whether the application should use KeePassXC to retrieve the Friedolin login credentials. Defaults to false. If true, the user and password fields may be null; then they need to be requested from KeePassXC by calling KeePassXC.getFriedolinLogins(). This might fail though, then the application should just throw an exception.

notifications

@Nullable
private Notifications notifications

The user's preferences for receiving notifications about their grades.

ban

@Nullable
private BannedUser ban

The student represented by this configuration, as an item in the polled metadata's blacklist if they are, in fact, banned.

ALLOWED_CONFIGURATION_FILENAMES

@NonNull
public static final @NonNull String[] ALLOWED_CONFIGURATION_FILENAMES

Default file names for the configuration that will be used if no explicit file name is specified.

Constructor Details

Configuration

public Configuration(@NonNull
 @NonNull String user,
 char[] password)
              throws IllegalArgumentException

Creates a new configuration with the given user and password.

Parameters:

user - The username of the Friedolin account to use, for example "es13nsa".

password - The password of the Friedolin account.

Throws:

IllegalArgumentException - If the user is empty or if the password is null or empty.

Configuration

private Configuration(@Nullable
 String user,
 @Nullable
 String password,
 @Nullable
 Boolean useKeePassXC)
               throws IllegalArgumentException

Creates a new configuration with the given user, password and academic degrees.

This constructor only exists for fromFile(File) to work properly (when no directory is specified in the configuration file).

Parameters:

user - The username of the Friedolin account to use, for example "es13nsa". Must not be empty.

password - The password of the Friedolin account. Will be stored as a char[] for security reasons. Must not be empty.

Throws:

IllegalArgumentException - See setUser(String), setPassword(char[]).

Configuration

private Configuration()

Creates a new configuration without a user and without a password. This constructor is only to be used by the copy() method in the case that the currently set user and password fields are null (this is the case when useKeePassXC is set to true).

All other callers are obliged to provide login credentials via Configuration(String, char[]). If they want to use KeePassXC, they have no choice but to retrieve the login credentials from KeePassXC before creating the configuration.

Method Details

setUser

public void setUser(@NonNull
 @NonNull String user)

Updates the user field accordingly. If the contactMethods field is already set, its user field will be updated as well, otherwise a new ContactMethods object will be created with the given user. If the new user name not equal to the current one, the userHash field will be deleted.

Parameters:

user - The username of the Friedolin account to use, for example "es13nsa". Must not be empty.

Throws:

IllegalArgumentException - If the user is empty.

setArgon2Configuration

public void setArgon2Configuration(@NonNull
 @NonNull Argon2Configuration argon2Configuration,
 boolean resetHashes)

Updates the argon2Configuration field with a deep copy of the given Argon2Configuration and, optionally, deletes the userHash, clearnameHash and emailHash fields as well as the userHashes, clearnameHashes and emailHashes sets. Does nothing if the given configuration is equal to the current one.

Parameters:

argon2Configuration - The Argon2 configuration to use for hashing various fields.

resetHashes - Whether to delete the hashes of the user, clearname and email fields.

computeUserHash

@NonNull
public @NonNull Optional<HashingResult> computeUserHash()

Forcibly computes the userHash (even if it already exists) and returns it. Adds the hash to the userHashes set if it is not already present.

Returns:

The Argon2 hash of the user name field. Empty if the user name is not set.

computeClearnameHash

@NonNull
public @NonNull Optional<HashingResult> computeClearnameHash()

Forcibly computes the clearnameHash and returns it, even if it already exists. Adds the hash to the clearnameHashes set if it is not already present.

Returns:

The Argon2 hash of the clear name field. Empty if the clear name is not set.

computeEmailHash

@NonNull
public @NonNull Optional<HashingResult> computeEmailHash()

Forcibly computes the emailHash and returns it, even if it already exists. Adds the hash to the emailHashes set if it is not already present.

Returns:

The Argon2 hash of the email field. Empty if the email is not set.

setPassword

public void setPassword(char[] password)

Updates the password field with the given one.

Parameters:

password - The password of the student's Friedolin account.

Throws:

IllegalArgumentException - If the password is empty.

setPassword

@Deprecated
private void setPassword(@NonNull
 @NonNull String password)
                  throws IllegalArgumentException

Deprecated.

This method is only used for Jackson deserialisation. Use setPassword(char[]) instead.

Updates the password field with the given one.

Parameters:

password - The password of the Friedolin account. Will be stored as a char[] for security reasons. Must not be empty.

Throws:

IllegalArgumentException - If the password is empty.

See Also:

• Stack Overflow: Why is char[] preferred over String for passwords?

setAcademicDegrees

public void setAcademicDegrees(@NonNull
 @NonNull Set<@NonNull String> academicDegrees)
                        throws IllegalArgumentException

Updates the academicDegrees field with the given one.

Parameters:

academicDegrees - The academic degrees that the student is currently pursuing, for example "Abschluss 82 Bachelor of Science". Must not be empty. Must not contain null or blank strings.

Throws:

IllegalArgumentException - If the set is empty or if there's a null or blank academic degrees in the given set.

setEmail

public void setEmail(@NonNull
 @NonNull jakarta.mail.internet.InternetAddress email)
              throws IllegalArgumentException

Updates the email field with the given one, deletes the emailHash and empties the emailHashes. Does nothing if the new e-mail equals the current one.

Parameters:

email - The email address of the student used for notifications. Must be a valid university email address, for example edward.snowden@uni-jena.de.

Throws:

IllegalArgumentException - If the email is not a valid university email address.

setClearname

public void setClearname(@NonNull
 @NonNull String clearname)
                  throws IllegalArgumentException

Updates the clearname field with the given one, deletes the clearnameHash and empties the clearnameHashes. Does nothing if the new clear name equals the current one.

Parameters:

clearname - The real name of the student, for example "Edward Snowden". Must not be empty.

Throws:

IllegalArgumentException - If the clear name is empty.

resetClearname

public void resetClearname()

Deletes the current value of the clearname, removes its hash and empties the clearnameHashes.

setDirectory

public void setDirectory(@NonNull
 @NonNull File directory)
                  throws IllegalArgumentException

Updates the directory field with the given one and also saves it into the persistent Preferences of the Friedolyn class as directory.

Parameters:

directory - The directory to use for the configuration. Must exist and be readable and writable.

Throws:

IllegalArgumentException - If the directory is null, does not exist, is not a directory, is not readable or is not writable.

setFile

public void setFile(@NonNull
 @NonNull File file)
             throws IllegalArgumentException

Updates the file field with the given one and also saves it into the persistent Preferences of the Friedolyn class as file.

Parameters:

file - The path that the configuration should be written to. Not required to exist. If it exists, it must be a file (not a directory), readable and writable.

Throws:

IllegalArgumentException - If the file exists but

• is not a file,
• is not readable or
• is not writable.

setIntervalMinutes

@Deprecated
private void setIntervalMinutes(long interval)
                         throws IllegalArgumentException

Deprecated.

Used only for Jackson deserialisation. Use setInterval(Duration) instead.

Parameters:

interval - The interval in minutes. Must be at least Friedolyn.MINIMUM_INTERVAL and at most Friedolyn.MAXIMUM_INTERVAL.

Throws:

IllegalArgumentException - If the interval is less than Friedolyn.MINIMUM_INTERVAL or greater than Friedolyn.MAXIMUM_INTERVAL.

setInterval

public void setInterval(@NonNull
 @NonNull Duration interval)
                 throws IllegalArgumentException

Updates the interval field with the given one.

Parameters:

interval - How often the application should fetch the student's grades from the Friedolin server. Must be at least Friedolyn.MINIMUM_INTERVAL and at most Friedolyn.MAXIMUM_INTERVAL.

Throws:

IllegalArgumentException - If the interval is less than Friedolyn.MINIMUM_INTERVAL or greater than Friedolyn.MAXIMUM_INTERVAL.

setDebugLevel

public void setDebugLevel(@NonNull
 @NonNull DebugLevel debugLevel)

Updates the debugLevel and

invalid reference

Main.debugLevel

fields with the given one.

Parameters:

debugLevel - How verbose the application should be.

setDebugLevel

private void setDebugLevel(@Nullable
 String debugLevel)

Updates the debugLevel and

invalid reference

Main.debugLevel

fields with the given one.

Parameters:

debugLevel - How verbose the application should be. If it is null or does not match any member of the DebugLevel enum, the field will not be updated.

setExamPDFs

public void setExamPDFs(@NonNull
 @NonNull Set<ExamsPDF> examsPdfs)

Updates the examPDFs field with the given one.

Parameters:

examsPdfs - Which of the available PDF files that include the student's grades should be downloaded from Friedolin.

Implementation Note:

Lombok refuses to generate a Setter because of setExamPDFs(String[]).

setExamPDFs

@Deprecated
private void setExamPDFs(@Nullable
 String[] examPDFs)
                  throws IllegalArgumentException

Deprecated.

This method is only used for Jackson deserialisation. Use setExamPDFs(Set) instead.

Updates the examPDFs field with the given one.

Parameters:

examPDFs - Which of the available PDF files that include the student's grades should be downloaded from Friedolin. Will be treated as an empty set if it is null or if the only item is null or empty. All non-null non-empty items must be valid members of the ExamsPDF enum.

Throws:

IllegalArgumentException - If any of the given non-null non-empty strings is not a member of the ExamsPDF enum.

setClient

public void setClient(@NonNull
 @NonNull Client client)

Updates the client with the deep copy of a new one.

Parameters:

client - Options for the client that will connect to the Friedolin server.

getClient

@NonNull
public @NonNull Client getClient()

Returns:

A deep copy of the current client (does NOT return the actual reference, for security reasons).

See Also:

• getReferenceToClient()

getReferenceToClient

@NonNull
public @NonNull Client getReferenceToClient()

Returns:

The actual object reference of the client field. Only use this method if you are sure that you actually need the reference. If you only need to read the data in it, use getClient() instead.

serialiseClient

@Deprecated
@Nullable
private Client serialiseClient()

Deprecated.

Used only for Jackson deserialisation. Use getClient() instead.

Returns:

The client if it's not the default one, null otherwise.

getNotifications

@NonNull
public @NonNull Optional<Notifications> getNotifications()

Returns:

A deep copy of the current notifications (does NOT return the actual reference, for security reasons).

getContactMethods

@NonNull
public @NonNull Optional<ContactMethods> getContactMethods()

Returns:

A deep copy of the current contactMethods (does NOT return the actual reference, for security reasons). Use getReferenceToContactMethods() if you need the actual reference.

See Also:

• getReferenceToContactMethods()

serialiseContactMethods

@Deprecated
@Nullable
private ContactMethods serialiseContactMethods()

Deprecated.

Used only for Jackson deserialisation. Use getContactMethods() instead.

Returns:

The contactMethods if they're not the default ones, null otherwise.

setContactMethods

public void setContactMethods(@NonNull
 @NonNull ContactMethods contactMethods)

Updates the contactMethods field with a deep copy of the given one.

Parameters:

contactMethods - The user's preferences for being contacted by the developers.

setReferenceToContactMethods

public void setReferenceToContactMethods(@NonNull
 @NonNull ContactMethods contactMethods)

Updates the contactMethods field with the exact reference of the given one.

Parameters:

contactMethods - The user's preferences for being contacted by the developers.

setContactMethodsNullable

@Deprecated
private void setContactMethodsNullable(@Nullable
 ContactMethods contactMethods)

Deprecated.

This method is only used for Jackson deserialisation. Use setContactMethods(ContactMethods) instead.

Updates the contactMethods field with the given one.

Parameters:

contactMethods - The user's preferences for being contacted by the developers. If null, will be ignored.

setNotifications

public void setNotifications(@NonNull
 @NonNull Notifications notifications)
                      throws IllegalArgumentException

Updates the notifications field with the exact reference of the given one.

Parameters:

notifications - The user's preferences for receiving notifications about their grades.

Throws:

IllegalArgumentException - If no notifier is set.

getReferenceToContactMethods

@NonNull
public @NonNull Optional<ContactMethods> getReferenceToContactMethods()

Returns:

The actual object reference of the contactMethods field. Only use this method if you are sure that you actually need the reference. If you only need to read the data in it, use getContactMethods() instead.

See Also:

• getContactMethods()

getEmailDirectory

@NonNull
public @NonNull File getEmailDirectory()

Returns:

The directory in the file system where copies of all e-mails sent by the user to the developers shall be stored. It is NOT guaranteed that the directory exists! The directory is called emails and is located in the Friedolyn directory root, such as ~/.friedolyn/emails.

getUser

@NonNull
public @NonNull Optional<String> getUser()

Returns:

The username of the student's Friedolin account. May be empty if useKeePassXC is set to true. In that case, the username needs to be retrieved from the KeePassXC password manager. Use KeePassXC.getFriedolinLogins() for that.

See Also:

• invalid reference

  #getUseKeePassXC()

getUserHash

@NonNull
public @NonNull Optional<HashingResult> getUserHash()

Returns the Argon2 hash of the user field (if it is set). The hash is computed using the argon2Configuration. May take a bit longer to return if the hash has not been computed yet.

Returns:

The Argon2 hash of the user field.

getUserHashes

@NonNull
public @NonNull HashSet<HashingResult> getUserHashes()

Returns:

A deep copy of the current argon2Configuration (does NOT return the actual reference, for security reasons).

getClearnameHash

@NonNull
public @NonNull Optional<HashingResult> getClearnameHash()

Returns the Argon2 hash of the clearname field (if it is set). The hash is computed using the argon2Configuration. May take a bit longer to return if the hash has not been computed yet.

Returns:

The Argon2 hash of the clearname field. Empty if the clear name is not set.

getClearnameHashes

@NonNull
public @NonNull HashSet<HashingResult> getClearnameHashes()

Returns:

A deep copy of the current clearnameHashes (does NOT return the actual reference, for security reasons).

getEmailHash

@NonNull
public @NonNull Optional<HashingResult> getEmailHash()

Returns the Argon2 hash of the email field (if it is set). The hash is computed using the argon2Configuration. May take a bit longer to return if the hash has not been computed yet.

Returns:

The Argon2 hash of the email field. Empty if the email is not set.

See Also:

• Wikipedia: Hash function

getEmailHashes

@NonNull
public @NonNull HashSet<HashingResult> getEmailHashes()

Returns:

A deep copy of the current emailHashes (does NOT return the actual reference, for security reasons).

isBanned

public boolean isBanned()

Returns:

True if the user represented by this configuration is banned, false otherwise. False especially if the ban has explicitly been lifted.

getBan

public Optional<BannedUser> getBan()

Returns:

The user represented by this configuration as a BannedUser if they are banned, empty if they are not banned.

setBan

public void setBan(@NonNull
 @NonNull BannedUser ban)

getPassword

@NonNull
public @NonNull Optional<char[]> getPassword()

Returns:

The password of the Friedolin account. May be empty if useKeePassXC is set to true. In that case, the password needs to be retrieved from the KeePassXC password manager. Use KeePassXC.getFriedolinLogins() for that.

See Also:

• invalid reference

  #getUseKeePassXC()

serialiseUser

@Deprecated
@Nullable
private String serialiseUser()

Deprecated.

Used only for Jackson deserialisation. Use getUser() instead.

Returns:

The user name if useKeePassXC is set to false, null otherwise.

serialisePassword

@Deprecated
@Nullable
private String serialisePassword()

Deprecated.

Used only for Jackson deserialisation. Use getPassword() instead.

Returns:

The password if useKeePassXC is set to false, null otherwise.

serialiseAcademicDegrees

@Deprecated
@Nullable
private Set<String> serialiseAcademicDegrees()

Deprecated.

Used only for Jackson deserialisation. Use

invalid reference

#getAcademicDegrees()

instead.

Returns:

The academicDegrees if they're not the default ones, null otherwise.

Implementation Note:

If two sets A and B are equal, then every element of A is also an element of B and vice versa. If we remove all B elements from A (and vice versa) and then both sets are empty, we know that they contained the exact same elements, i.e. they were equal.

serialiseExamsPDFs

@Deprecated
@Nullable
private HashSet<ExamsPDF> serialiseExamsPDFs()

Deprecated.

Used only for Jackson deserialisation. Use

invalid reference

#getExamPDFs()

instead.

Returns:

The examPDFs if they're not the default ones, null otherwise.

Implementation Note:

If two sets A and B are equal, then every element of A is also an element of B and vice versa. If we remove all B elements from A (and vice versa) and then both sets are empty, we know that they contained the exact same elements, i.e. they were equal.

serialiseInterval

@Deprecated
@Nullable
private Long serialiseInterval()

Deprecated.

Used only for Jackson deserialisation. Use

invalid reference

#getInterval()

instead.

Returns:

The interval if it's not the default one, null otherwise.

serialiseDebugLevel

@Deprecated
@Nullable
private String serialiseDebugLevel()

Deprecated.

Used only for Jackson deserialisation. Use

invalid reference

#getDebugLevel()

instead.

Returns:

The debugLevel if it's not the default one, null otherwise.

getClearname

@NonNull
public @NonNull Optional<String> getClearname()

Returns:

The real name of the student as indicated in the University of Jena's Friedolin system, for example Edward Snowden. Empty if it has not been fetched yet.

getEmail

@NonNull
public @NonNull Optional<jakarta.mail.internet.InternetAddress> getEmail()

Returns:

The student's university e-mail address as indicated by the Friedolin system, for example edward.snowden@uni -jena.de. Empty if it has not been fetched yet.

serialiseEmail

@NonNull
private @NonNull Optional<String> serialiseEmail()

Deprecated.

Used only for Jackson deserialisation. Use getEmail() instead.

Returns:

The email address if it's not the default one, null otherwise.

setUseKeePassXC

public void setUseKeePassXC(boolean useKeePassXC)

Updates the user's preference whether the KeePassXC password manager should be used to retrieve the user's login credentials for Friedolin, i.e. user and password. If this is set to true, the user and password fields will not be included in the JSON representation of this configuration.

Parameters:

useKeePassXC - true if KeePassXC should be used, false otherwise.

See Also:

• getUser()
• getPassword()

saveToFile

public void saveToFile()
                throws IOException,
SecurityException

Writes this configuration to the file in JSON format. Does not care if the file already exists, it will be overwritten if it does. If necessary, all parent directories of the file will be created.

Throws:

IOException - If the file cannot be written to.

SecurityException

fromFile

@NonNull
public static @NonNull Configuration fromFile(File file)
                                       throws IOException,
com.fasterxml.jackson.core.exc.StreamReadException,
com.fasterxml.jackson.databind.DatabindException,
IllegalArgumentException,
SecurityException,
OutOfMemoryError,
InvalidPathException

Creates a new Configuration from a given JSON file.

Parameters:

file - The JSON file that contains the properties of the Configuration to be created. Must be a valid JSON file. Required properties:

• user (String): The username of the Friedolin account to use, for example "es13nsa".
• password (String): The password of the Friedolin account.
• academicDegrees (String): The academic degrees that the student is currently pursuing, for example "Abschluss 82 Bachelor of Science".

The file's parent directory will be used as the directory of the configuration. If that is not possible, then ~/.friedolyn will be used. (Use setDirectory(File) if you don't like that location.)

For more information on how the JSON file must be formatted, see the JSON schema.

Returns:

The configuration created from the given file.

Throws:

IOException - See ObjectMapper.readValue(File, Class).

com.fasterxml.jackson.core.exc.StreamReadException - See ObjectMapper.readValue(File, Class).

com.fasterxml.jackson.databind.DatabindException - See ObjectMapper.readValue(File, Class).

IllegalArgumentException - If the configuration does not include a directory, but the file's parent directory and the default directory are both invalid.

SecurityException

OutOfMemoryError

InvalidPathException

fromJSON

@NonNull
public static @NonNull Configuration fromJSON(String json)
                                       throws IOException,
IllegalArgumentException,
SecurityException,
OutOfMemoryError

Creates a new Configuration from a given JSON.

Parameters:

json - The JSON string that represents a Configuration. Required properties:

• user (String): The username of the Friedolin account to use, for example "es13nsa".
• password (String): The password of the Friedolin account.
• academicDegrees (String): The academic degrees that the student is currently pursuing, for example "Abschluss 82 Bachelor of Science".

For more information on how the JSON file must be formatted, see the JSON schema.

Returns:

The configuration created from the given JSON.

Throws:

IllegalArgumentException - If the JSON does not adhere to the schema or if useKeePassXC is set to false, but no password is specified.

IOException - See ObjectMapper.readValue(String, Class).

SecurityException - See ValidatorFactory.validate(String, String).

OutOfMemoryError - See ObjectMapper.readValue(String, Class).

copy

@NonNull
public @NonNull Configuration copy()

Specified by:

copy in interface Copyable<Configuration>

Returns:

A deep copy of this configuration, i.e. a new instance with the same properties but different references.

toJSON

@NonNull
public @NonNull String toJSON()
                       throws com.fasterxml.jackson.core.JsonProcessingException

Returns:

A JSON representation of this configuration.

Throws:

com.fasterxml.jackson.core.JsonProcessingException - See ObjectWriter.writeValueAsString(Object).

toString

@NonNull
public @NonNull String toString()

Specified by:

toString in interface Redactable

Overrides:

toString in class Object

Returns:

A string representation of this configuration with all its properties, including sensitive data.

See Also:

• toStringRedacted()

toStringRedacted

@NonNull
public @NonNull String toStringRedacted()

Specified by:

toStringRedacted in interface Redactable

Returns:

A string representation of this configuration with all its properties. Sensitive data will be redacted according to the policy specified by the debugLevel.

See Also:

• toString()