Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn

Class Friedolyn

java.lang.Object

page.codeberg.friedolyn.Friedolyn

public class Friedolyn
extends Object

A class that logs in as a student at the University of Jena's Friedolin system, most importantly to retrieve grades.

After constructing a new Friedolyn object with the student's credentials, the grades can be fetched with the fetchGrades() method. The student's clear name can be retrieved with the fetchStudentClearname().

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	Friedolyn.BannedUserCallback	A callback that is to be called as soon as the currently logged-in user has been identified as banned from using Friedolyn.
static enum	Friedolyn.ContactRequest	The various types of requests that can be sent via the contact form.
class	Friedolyn.FetchGradesTask	Fetches the student's grades from the University of Jena's Friedolin system by calling the fetchGrades().
static interface	Friedolyn.FriedolynListener	Subscribes to status changes of the periodic grades fetching on the respective Friedolyn object.
static class	Friedolyn.LocalDirectories	Various folders in the invalid reference Friedolyn directory that are used to store different kinds of data relevant to the application.
static enum	Friedolyn.Status	Whether the fetchGradesTask is currently running or not and what this means for calling various methods.

Field Summary

Fields

Modifier and Type	Field	Description
private final @NonNull ReentrantLock	BAN_LEVEL_LOCK	Facilitates mutual exclusion when updating the banLevels.
private @NonNull Set<BanLevel>	banLevels	The application's features that the user is disallowed from using.
static final @NonNull URL	BASE_URL	The base URL to access the Friedolin server.
private @NonNull FriedolinClient	client	The FriedolinClient to use for interacting with the Friedolin system.
private @NonNull Configuration	configuration	Various options that modify Friedolyn's behaviour.
private @NonNull Countdown	countdown	The time left until the next execution of the fetchGradesTask.
static final @NonNull KnownDegree	DEFAULT_DEGREE	The default degrees to search for in the grades.
static final @NonNull Duration	DEFAULT_INTERVAL	The default amount of time between two grade fetches from the Friedolin server: See DEFAULT_INTERVAL_MINUTES.
static final int	DEFAULT_INTERVAL_MINUTES	The default amount of hours between two grade fetches from the Friedolin server: 5 minutes.
static final @NonNull Path	DEFAULT_ROOT	The default Friedolyn directory where all application data is stored.
static final @NonNull String	DOMAIN	The hostname of the Friedolin server.
private int	fetchCount	The total number of all fetches that have been executed so far, including both successful and unsuccessful ones.
private @NonNull Friedolyn.FetchGradesTask	fetchGradesTask	Fetches the student's grades from the University of Jena's Friedolin system by calling the fetchGrades().
static final @NonNull Duration	INTER_WAVE_RETRY_DELAY	Default amount of time to wait before retrying to fetch the grades from the Friedolin server after a failure: 10 seconds.
static final @NonNull Duration	INTRA_WAVE_DELAY	Default amount of time to wait before retrying to fetch the grades from the Friedolin server after a failure: 5 seconds.
private final @NonNull Set<Friedolyn.FriedolynListener>	LISTENERS	Subscribers that are interested in the status changes of the periodic grades fetching.
private final @NonNull ReentrantLock	LOCK	Facilitates mutual exclusion when running the fetchGradesTask.
static final String	LOG_FILE_NAME	The default name of the log file which the Friedolyn application's Log4J logs are written to.
static final @NonNull Duration	MAXIMUM_INTERVAL	The maximum amount of time between two grade fetches from the Friedolin server: 7 days.
static final int	MAXIMUM_INTERVAL_DAYS	The maximum amount of days between two grade fetches from the Friedolin server: 7 days.
private PolledMetadata	metadata	Stores information about the application, fetched from the Codeberg repository, most notably the URL to a user poll and a list of banned users.
static final @NonNull Duration	MINIMUM_INTERVAL	The minimum amount of time between two grade fetches from the Friedolin server: 5 minutes.
static final int	MINIMUM_INTERVAL_MINUTES	The minimum amount of minutes between two grade fetches from the Friedolin server: 1 minutes.
static final @NonNull String	NAME	The name of this application.
private static final @NonNull Preferences	PREFERENCES
static final @NonNull String	REQUEST_PATH	The path to the Friedolin server's request handler.
static final @NonNull URL	REQUEST_URL	The full URL to access Friedolin's request handler.
static final int	RETRY_ATTEMPTS	Number of attempt waves to fetch the grades from the Friedolin server before giving up: 3.
private Friedolyn.Status	status	Indicates whether the fetchGradesTask is currently running, paused etc.
static final @NonNull String	SYSTEM_INFO_FILE_NAME	The name of the file where the system information should be stored when invoking getSystemInfoFile().
private final @NonNull UserAgentManager	USERAGENT_MANAGER	Stores various user agents of Friedolyn and real web browsers.
static final @NonNull com.fasterxml.jackson.core.Version	VERSION	The version of this application.

Constructor Summary

Constructors

Constructor	Description
Friedolyn(@NonNull Configuration configuration)	Creates a new Friedolyn object with a deep copy of the given configuration.

Method Summary

Modifier and Type	Method	Description
@NonNull jakarta.mail.internet.InternetAddress	fetchEmailAddress()	Fetches the student's email address from the University of Jena's Friedolin system and updates the configuration accordingly.
boolean	fetchGrades()	Fetches the student's grades from the University of Jena's Friedolin system (once).
@NonNull String	fetchStudentClearname()
void	finish()	Explicitly frees the resources of the client.
@NonNull Configuration	getConfiguration()
@NonNull Configuration	getReferenceToConfiguration()
static String	getSystemInfo()
static @NonNull File	getSystemInfoFile()	Writes the system information to a file in the system's temporary directory.
void	pausePeriodicGradesFetch()	Stops the task that fetches the student's grades from the University of Jena's Friedolin system periodically, but does not reset the countdown.
void	registerCountdownListener(Countdown.CountdownListener listener)	Adds another Countdown.CountdownListener to the set of objects interested in when the next grades fetching run will be executed.
void	registerListener(@NonNull Friedolyn.FriedolynListener listener)	Registers a new Friedolyn.FriedolynListener to the set of objects interested in the status changes of the periodic grades fetching.
boolean	removeCountdownListener(Countdown.CountdownListener listener)	Deletes an already registered Countdown.CountdownListener from the set of objects interested in when the next grades fetching run will be executed.
boolean	removeListener(@NonNull Friedolyn.FriedolynListener listener)	Deletes an already registered Friedolyn.FriedolynListener from the set of objects interested in the status changes of the periodic grades fetching.
void	resumePeriodicGradesFetch()	Continues the periodic fetching of the student's grades from the University of Jena's Friedolin system at the point where it was paused previously by calling the pausePeriodicGradesFetch() method.
void	setConfiguration(@NonNull Configuration configuration)	Updates the current configuration with the deep copy of a new one (not the actual reference of it, for security reasons).
void	startPeriodicGradesFetch()	Starts fetching the student's grades from the University of Jena's Friedolin system periodically according to the invalid reference interval specified in the configuration.
private void	startPeriodicGradesFetch(@NonNull Duration delay)	Starts fetching the student's grades from the University of Jena's Friedolin system periodically according to the invalid reference interval specified in the configuration and with a certain delay.
boolean	stopPeriodicGradesFetch()	Cancels the task that fetches the student's grades from the University of Jena's Friedolin system periodically.

Methods inherited from class java.lang.Object

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

Field Details

NAME

@NonNull
public static final @NonNull String NAME

The name of this application.

See Also:

• Constant Field Values

VERSION

@NonNull
public static final @NonNull com.fasterxml.jackson.core.Version VERSION

The version of this application.

PREFERENCES

@NonNull
private static final @NonNull Preferences PREFERENCES

DOMAIN

@NonNull
public static final @NonNull String DOMAIN

The hostname of the Friedolin server.

See Also:

• Constant Field Values

BASE_URL

@NonNull
public static final @NonNull URL BASE_URL

The base URL to access the Friedolin server.

REQUEST_PATH

@NonNull
public static final @NonNull String REQUEST_PATH

The path to the Friedolin server's request handler.

See Also:

• Constant Field Values

REQUEST_URL

@NonNull
public static final @NonNull URL REQUEST_URL

The full URL to access Friedolin's request handler.

DEFAULT_DEGREE

@NonNull
public static final @NonNull KnownDegree DEFAULT_DEGREE

The default degrees to search for in the grades.

DEFAULT_ROOT

@NonNull
public static final @NonNull Path DEFAULT_ROOT

The default Friedolyn directory where all application data is stored.

MINIMUM_INTERVAL_MINUTES

public static final int MINIMUM_INTERVAL_MINUTES

The minimum amount of minutes between two grade fetches from the Friedolin server: 1 minutes.

See Also:

• Constant Field Values

MINIMUM_INTERVAL

@NonNull
public static final @NonNull Duration MINIMUM_INTERVAL

The minimum amount of time between two grade fetches from the Friedolin server: 5 minutes.

MAXIMUM_INTERVAL_DAYS

public static final int MAXIMUM_INTERVAL_DAYS

The maximum amount of days between two grade fetches from the Friedolin server: 7 days.

See Also:

• Constant Field Values

MAXIMUM_INTERVAL

@NonNull
public static final @NonNull Duration MAXIMUM_INTERVAL

The maximum amount of time between two grade fetches from the Friedolin server: 7 days.

DEFAULT_INTERVAL_MINUTES

public static final int DEFAULT_INTERVAL_MINUTES

The default amount of hours between two grade fetches from the Friedolin server: 5 minutes.

See Also:

• Constant Field Values

DEFAULT_INTERVAL

@NonNull
public static final @NonNull Duration DEFAULT_INTERVAL

The default amount of time between two grade fetches from the Friedolin server: See DEFAULT_INTERVAL_MINUTES.

INTER_WAVE_RETRY_DELAY

@NonNull
public static final @NonNull Duration INTER_WAVE_RETRY_DELAY

Default amount of time to wait before retrying to fetch the grades from the Friedolin server after a failure: 10 seconds.

RETRY_ATTEMPTS

public static final int RETRY_ATTEMPTS

Number of attempt waves to fetch the grades from the Friedolin server before giving up: 3. (Each wave consists of two attempts with a delay of 5 seconds between each attempt.)

See Also:

• Constant Field Values

INTRA_WAVE_DELAY

@NonNull
public static final @NonNull Duration INTRA_WAVE_DELAY

Default amount of time to wait before retrying to fetch the grades from the Friedolin server after a failure: 5 seconds.

SYSTEM_INFO_FILE_NAME

@NonNull
public static final @NonNull String SYSTEM_INFO_FILE_NAME

The name of the file where the system information should be stored when invoking getSystemInfoFile().

See Also:

• Constant Field Values

LOG_FILE_NAME

public static final String LOG_FILE_NAME

The default name of the log file which the Friedolyn application's Log4J logs are written to.

See Also:

• Constant Field Values

configuration

@NonNull
private @NonNull Configuration configuration

Various options that modify Friedolyn's behaviour.

client

@NonNull
private @NonNull FriedolinClient client

The FriedolinClient to use for interacting with the Friedolin system.

USERAGENT_MANAGER

@NonNull
private final @NonNull UserAgentManager USERAGENT_MANAGER

Stores various user agents of Friedolyn and real web browsers. The user agents are intended to be used by the client to identify itself to the Friedolin server.

metadata

@Nullable
private PolledMetadata metadata

Stores information about the application, fetched from the Codeberg repository, most notably the URL to a user poll and a list of banned users.

fetchGradesTask

@NonNull
private @NonNull Friedolyn.FetchGradesTask fetchGradesTask

Fetches the student's grades from the University of Jena's Friedolin system by calling the fetchGrades(). This task can be scheduled to updateCountdown periodically by calling the startPeriodicGradesFetch(). Cancel periodic execution by calling stopPeriodicGradesFetch().

LISTENERS

@NonNull
private final @NonNull Set<Friedolyn.FriedolynListener> LISTENERS

Subscribers that are interested in the status changes of the periodic grades fetching.

See Also:

• registerListener(FriedolynListener)

countdown

@NonNull
private @NonNull Countdown countdown

The time left until the next execution of the fetchGradesTask.

LOCK

@NonNull
private final @NonNull ReentrantLock LOCK

Facilitates mutual exclusion when running the fetchGradesTask.

fetchCount

private int fetchCount

The total number of all fetches that have been executed so far, including both successful and unsuccessful ones.

status

private Friedolyn.Status status

Indicates whether the fetchGradesTask is currently running, paused etc.

banLevels

@NonNull
private @NonNull Set<BanLevel> banLevels

The application's features that the user is disallowed from using.

BAN_LEVEL_LOCK

@NonNull
private final @NonNull ReentrantLock BAN_LEVEL_LOCK

Facilitates mutual exclusion when updating the banLevels.

Constructor Details

Friedolyn

public Friedolyn(@NonNull
 @NonNull Configuration configuration)

Creates a new Friedolyn object with a deep copy of the given configuration.

It is strongly recommended to execute the construction in a separate thread when invoking this constructor from a graphical user interface (GUI), because the construction may take a while, especially if a HeadlessBrowser is used as the client.

Downloads the user agents and the PolledMetadata.download() metadata if the last download was more than a day ago. Checks for bans of the currently logged-in user.

Parameters:

configuration - The configuration to use for this Friedolyn object.

Implementation Note:

Downloading the user agents and the metadata happens in two separate threads in order to speed up the construction of the Friedolyn object, considering that neither of these resources are immediately required for the application to function properly. Especially with the metadata, multi-threading is viable, because both decrypting the poll URL (called by the download method) and checking for bans is very computationally expensive due to the nature of the cryptographic algorithms employed.

Method Details

getSystemInfo

public static String getSystemInfo()

Returns:

A string containing various system information:

• name, version and architecture of the operating system
• version, vendor, home directory, library path and temporary directory of the Java runtime
• home directory of the user
• current working directory

getSystemInfoFile

@NonNull
public static @NonNull File getSystemInfoFile()
                                       throws IOException

Writes the system information to a file in the system's temporary directory.

Returns:

A temporary file containing the system information.

Throws:

IOException - If the system's temporary directory could not be found or could not be written to.

registerListener

public void registerListener(@NonNull
 @NonNull Friedolyn.FriedolynListener listener)

Registers a new Friedolyn.FriedolynListener to the set of objects interested in the status changes of the periodic grades fetching.

Parameters:

listener - The object that will be notified about the Friedolyn object's status changes.

removeListener

public boolean removeListener(@NonNull
 @NonNull Friedolyn.FriedolynListener listener)

Deletes an already registered Friedolyn.FriedolynListener from the set of objects interested in the status changes of the periodic grades fetching.

Parameters:

listener - The object that will no longer be notified about the Friedolyn object's status changes. Must be the exact same reference that was passed to registerListener(FriedolynListener) previously.

Returns:

true if the listener was removed, false if the listener could not be found.

registerCountdownListener

public void registerCountdownListener(@NonNull
 Countdown.CountdownListener listener)

Adds another Countdown.CountdownListener to the set of objects interested in when the next grades fetching run will be executed.

Parameters:

listener - The object that will be notified about the countdown's progress.

removeCountdownListener

public boolean removeCountdownListener(@NonNull
 Countdown.CountdownListener listener)

Deletes an already registered Countdown.CountdownListener from the set of objects interested in when the next grades fetching run will be executed.

Parameters:

listener - The object that will no longer be notified about the countdown's progress. Must be the exact same reference that was passed to registerCountdownListener(Countdown.CountdownListener) previously.

Returns:

true if the listener was removed, false if the listener could not be found.

finish

public void finish()

Explicitly frees the resources of the client. This method should be called if the current Friedolyn object is still needed, but the client is not, because in that scenario, the Java garbage collector would not free the client. Notifies all Friedolyn.FriedolynListeners that the Friedolyn object has been stopped, by calling Friedolyn.FriedolynListener.onStopped() on each of them.

setConfiguration

public void setConfiguration(@NonNull
 @NonNull Configuration configuration)

Updates the current configuration with the deep copy of a new one (not the actual reference of it, for security reasons).

Parameters:

configuration - New preferences for the current Friedolyn object.

getConfiguration

@NonNull
public @NonNull Configuration getConfiguration()

Returns:

A deep copy of the current configuration (not the actual reference of it, for security reasons). Use getReferenceToConfiguration() if you need the actual reference.

See Also:

• getReferenceToConfiguration()

getReferenceToConfiguration

@NonNull
public @NonNull Configuration getReferenceToConfiguration()

Returns:

The actual object reference of the configuration 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 getConfiguration() instead.

See Also:

• getConfiguration()

startPeriodicGradesFetch

public void startPeriodicGradesFetch()
                              throws IllegalStateException

Starts fetching the student's grades from the University of Jena's Friedolin system periodically according to the

invalid reference

interval

specified in the configuration. This process will run until the stopPeriodicGradesFetch() method is called. (Of course, external factors like the computer being shut down or the application being closed will also stop the process.)

Throws:

IllegalStateException - If the fetchGradesTask has already been scheduled.

See Also:

• pausePeriodicGradesFetch()
• stopPeriodicGradesFetch()

startPeriodicGradesFetch

private void startPeriodicGradesFetch(@NonNull
 @NonNull Duration delay)
                               throws IllegalStateException

Starts fetching the student's grades from the University of Jena's Friedolin system periodically according to the

invalid reference

interval

specified in the configuration and with a certain delay.

Parameters:

delay - Amount of time to wait before the first execution of the fetchGradesTask.

Throws:

IllegalStateException - If the fetchGradesTask has already been scheduled.

See Also:

• pausePeriodicGradesFetch()
• stopPeriodicGradesFetch()

Implementation Note:

Since we do not care about the absolute point in time of each execution (we only care about the relative time between two executions), we can use the Timer.schedule(TimerTask, long, long) method instead of Timer.scheduleAtFixedRate(TimerTask, long, long).

Sets the status to scheduled but does not notify the LISTENERS, because this method cannot distinguish between starting and resuming.

pausePeriodicGradesFetch

public void pausePeriodicGradesFetch()

Stops the task that fetches the student's grades from the University of Jena's Friedolin system periodically, but does not reset the countdown. Use resumePeriodicGradesFetch() to later continue the periodic fetching at the point where it was paused.

Implementation Note:

Notifies all LISTENERS that the periodic fetching has been paused.

resumePeriodicGradesFetch

public void resumePeriodicGradesFetch()
                               throws IllegalStateException

Continues the periodic fetching of the student's grades from the University of Jena's Friedolin system at the point where it was paused previously by calling the pausePeriodicGradesFetch() method.

Throws:

IllegalStateException - If the fetchGradesTask is already scheduled.

Implementation Note:

Notifies all LISTENERS that the periodic fetching has been resumed.

stopPeriodicGradesFetch

public boolean stopPeriodicGradesFetch()

Cancels the task that fetches the student's grades from the University of Jena's Friedolin system periodically.

• If the task has been scheduled, it will not be executed again.
• If the task is currently running, it will finish its current execution and then stop.
• If the task has not been scheduled yet, nothing will happen.

Returns:

True if the task had been scheduled (and was cancelled), false if it had not been scheduled.

Implementation Note:

Notifies all LISTENERS that the periodic fetching has been stopped.

fetchGrades

public boolean fetchGrades()

Fetches the student's grades from the University of Jena's Friedolin system (once).

Returns:

true if the grades were fetched successfully, false otherwise.

See Also:

• startPeriodicGradesFetch()

fetchStudentClearname

@NonNull
public @NonNull String fetchStudentClearname()
                                      throws org.openqa.selenium.NotFoundException

Returns:

The student's clear name as indicated in the University of Jena's Friedolin system.

Throws:

org.openqa.selenium.NotFoundException - If the student's clear name could not be found.

fetchEmailAddress

@NonNull
public @NonNull jakarta.mail.internet.InternetAddress fetchEmailAddress()
                                                                 throws org.openqa.selenium.NotFoundException

Fetches the student's email address from the University of Jena's Friedolin system and updates the configuration accordingly.

Returns:

The student's email address as indicated in the University of Jena's Friedolin system.

Throws:

org.openqa.selenium.NotFoundException - If the student's email address could not be determined.