Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.client

Class Client

java.lang.Object

page.codeberg.friedolyn.client.FriedolinClient

page.codeberg.friedolyn.client.Client

public class Client
extends FriedolinClient

A resource-efficient client to automatically interact with the University of Jena's Friedolin system. Does not use a browser, but instead sends HTTP requests directly to the server.

See Also:

• HeadlessBrowser

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	Client.FetchClearname
class	Client.FetchEmailAddress
private class	Client.FetchPersonalData
class	Client.Login	A Task that can be executed in a different Thread to log in to Friedolin using the student's credentials specified in the Configuration previously set via FriedolinClient.setConfiguration(Configuration) (or the constructor).

Nested classes/interfaces inherited from class page.codeberg.friedolyn.client.FriedolinClient

FriedolinClient.HTTP_REQUEST_TYPE, FriedolinClient.InternetConnectivityStatus

Field Summary

Fields

Modifier and Type	Field	Description
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	ACCEPT_OBLIGATION_OF_USE_PARAMETERS	The parameters to send with the requests to accept the obligation of use and fetch the grades table. The value of asi must be updated with the current urlSecretParameter.
private HttpClient	client	The HTTP client to use for sending requests to Friedolin.
private @NonNull Configuration	configuration	Various options that modify Friedolyn's behaviour.
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	GET_COURSE_LIST_PARAMETERS	The parameters to send with the request to retrieve the list of all courses (Studiengänge) the student is enrolled in before the grades can be fetched.
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	GET_EMAIL_ADDRESS_PARAMETERS	The parameters to send with the request to retrieve the student's e-mail address.
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	GET_EMAIL_ADDRESS_REFERRER_PARAMETERS	The parameters for the referrer to use when retrieving the student's e-mail address.
static final @NonNull LinkedHashMap<ExamsPDF,@NonNull LinkedHashMap<@NonNull String,@NonNull String>>	GET_EXAMS_PDF_PARAMETERS	The parameters to send with the request to retrieve the different grade tables as PDFs.
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	GET_GRADES_TABLE_REFERRER_PARAMETERS
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	GET_OBLIGATION_OF_USE_PARAMETERS	The parameters to send with the request to retrieve the obligation-of-use page.
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	GET_OBLIGATION_OF_USE_REFERRER_PARAMETERS	The parameters for the referrer to use when retrieving the obligation-of-use page.
private @NonNull Expiring<Boolean>	isLoggedIn	Whether this HTTP Client is currently logged in at the University of Jena's Friedolin system.
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	LOGIN_PARAMETERS	The parameters to send with the login request to Friedolin.
static final @NonNull LinkedHashMap<@NonNull String,@NonNull String>	LOGIN_REFERRER	The referrer to use when sending the login request to Friedolin.
private @NonNull Client.Login	loginTask	A Task that can be run in a different Thread to log in to Friedolin.
private String	urlSecretParameter	A secret that is included in all internal Friedolin URLs and is newly generated for each session.

Fields inherited from class page.codeberg.friedolyn.client.FriedolinClient

SESSION_LIFETIME

Constructor Summary

Constructors

Constructor	Description
Client(@NonNull Configuration configuration)	Creates a new client that can be used immediately without further configuration or initialisation.

Method Summary

Modifier and Type	Method	Description
private @NonNull HttpResponse<@NonNull String>	acceptObligationOfUse()	Before students can access their grades, they have to accept the "Obligation of Use", i.e.
private HttpRequest.Builder	addHeaders(HttpRequest.Builder builder)	Adds the default headers to the given HttpRequest.Builder, namely: Accept Accept-Encoding Accept-Language Cache-Control Content-Type DNT Origin Sec-Fetch-Dest Sec-Fetch-Mode Sec-Fetch-Site Sec-Fetch-User Sec-GPC Upgrade-Insecure-Requests User-Agent
@NonNull FriedolinClient.InternetConnectivityStatus	checkInternetConnectivity()	Determines whether and how the client can access the internet.
private boolean	downloadFile(@NonNull Map<@NonNull String,@NonNull String> urlParameters, @NonNull Map<@NonNull String,@NonNull String> headers, @NonNull File downloadTarget)	Retrieves some file from the Friedolin server and saves it in the specified location.
boolean	fetchGrades(@NonNull String... degrees)	Fetches the student's grades from the University of Jena's Friedolin system, using the credentials specified in the Configuration previously set via FriedolinClient.setConfiguration(Configuration) (or the constructor).
boolean	fetchMyData()	Deprecated.
private @NonNull HttpResponse<@NonNull String>	fetchObligationOfUse()	Retrieves the obligation-of-use page from Friedolin, which needs to be accepted before the grade table can be accessed.
boolean	fetchStudyProgress()	Deprecated.
void	finish()	Exits the headless browser.
private @NonNull HttpResponse<@NonNull String>	get(@NonNull Map<@NonNull String,@NonNull String> headers)	Sends a GET request to Friedolyn.REQUEST_URL with the given headers.
private @NonNull HttpResponse<@NonNull String>	get(@NonNull Map<@NonNull String,@NonNull String> urlParameters, @NonNull Map<@NonNull String,@NonNull String> headers)	Sends a GET request to Friedolyn.REQUEST_URL with the given parameters and headers.
@NonNull Configuration	getConfiguration()
@NonNull Client.FetchClearname	getFetchClearnameTask()
@NonNull Client.FetchEmailAddress	getFetchEmailAddressTask()
@NonNull Client.Login	getLoginTask()
private boolean	initialise()	Makes an initial GET request to Friedolin to retrieve the initial cookies and headers needed for logging in.
private @NonNull HttpResponse<@NonNull String>	post(@NonNull Map<@NonNull String,@NonNull String> urlParameters, @NonNull Map<@NonNull String,@NonNull String> headers, @NonNull Map<@NonNull String,@NonNull String> body)	Sends a POST request to Friedolyn.REQUEST_URL with the given parameters and headers.
private @NonNull HttpResponse<@NonNull String>	request(FriedolinClient.HTTP_REQUEST_TYPE type, @NonNull Map<@NonNull String,@NonNull String> urlParameters, @NonNull Map<@NonNull String,@NonNull String> headers, @NonNull Map<@NonNull String,@NonNull String> body)	Makes an HTTP request to the Friedolin server.
void	setConfiguration(@NonNull Configuration configuration)	Updates the current configuration with a deep copy of the given one (not the actual reference of it, for security reasons).
void	setConfigurationReference(@NonNull Configuration configuration)	Updates the preferences that determine the behaviour of this client with the exact reference of the given Configuration (instead of just a deep copy).
private boolean	updateCookies(@NonNull URI uri, @NonNull HttpHeaders headers)	Makes the client remember the cookies received from the server in the given headers.

Methods inherited from class page.codeberg.friedolyn.client.FriedolinClient

buildURL, decodeQuery, encodeParameters, fetchEmailAddress, fetchStudentClearname, getIsLoggedIn, login, saveResponse, stripAnchor

Methods inherited from class java.lang.Object

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

Field Details

loginTask

@NonNull
private @NonNull Client.Login loginTask

A Task that can be run in a different Thread to log in to Friedolin. The execution may take a while, so it is recommended to use this task instead of the blocking FriedolinClient.login() method.

LOGIN_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> LOGIN_PARAMETERS

The parameters to send with the login request to Friedolin.

LOGIN_REFERRER

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> LOGIN_REFERRER

The referrer to use when sending the login request to Friedolin.

GET_OBLIGATION_OF_USE_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> GET_OBLIGATION_OF_USE_PARAMETERS

The parameters to send with the request to retrieve the obligation-of-use page. The value of asi must be updated with the current urlSecretParameter.

GET_OBLIGATION_OF_USE_REFERRER_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> GET_OBLIGATION_OF_USE_REFERRER_PARAMETERS

The parameters for the referrer to use when retrieving the obligation-of-use page.

ACCEPT_OBLIGATION_OF_USE_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> ACCEPT_OBLIGATION_OF_USE_PARAMETERS

The parameters to send with the requests to

• accept the obligation of use and
• fetch the grades table.

The value of asi must be updated with the current urlSecretParameter.

GET_COURSE_LIST_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> GET_COURSE_LIST_PARAMETERS

The parameters to send with the request to retrieve the list of all courses (Studiengänge) the student is enrolled in before the grades can be fetched. The value of asi must be updated with the current urlSecretParameter.

GET_GRADES_TABLE_REFERRER_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> GET_GRADES_TABLE_REFERRER_PARAMETERS

GET_EMAIL_ADDRESS_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> GET_EMAIL_ADDRESS_PARAMETERS

The parameters to send with the request to retrieve the student's e-mail address. The value of asi must be updated with the current urlSecretParameter.

GET_EMAIL_ADDRESS_REFERRER_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<@NonNull String,@NonNull String> GET_EMAIL_ADDRESS_REFERRER_PARAMETERS

The parameters for the referrer to use when retrieving the student's e-mail address.

GET_EXAMS_PDF_PARAMETERS

@NonNull
public static final @NonNull LinkedHashMap<ExamsPDF,@NonNull LinkedHashMap<@NonNull String,@NonNull String>> GET_EXAMS_PDF_PARAMETERS

The parameters to send with the request to retrieve the different grade tables as PDFs. For each PDF, the value of asi must be updated with the current urlSecretParameter.

urlSecretParameter

@Nullable
private String urlSecretParameter

A secret that is included in all internal Friedolin URLs and is newly generated for each session. Without this secret, it is not possible to access the user's data.

configuration

@NonNull
private @NonNull Configuration configuration

Various options that modify Friedolyn's behaviour.

Implementation Note:

IntelliJ shows a warning that the NonNull annotation should be removed, because it does not understand that the (only) constructor calls setConfiguration(Configuration) to initialise this field. The use of NonNull is therefore entirely justified, and the warning can be safely ignored.

isLoggedIn

@NonNull
private @NonNull Expiring<Boolean> isLoggedIn

Whether this HTTP Client is currently logged in at the University of Jena's Friedolin system.

client

@Nullable
private HttpClient client

The HTTP client to use for sending requests to Friedolin.

Constructor Details

Client

public Client(@NonNull
 @NonNull Configuration configuration)

Creates a new client that can be used immediately without further configuration or initialisation.

Parameters:

configuration - The preferences that determine the behaviour of this client. The exact reference of this object is stored, so that changes to it are reflected in this client. If this is not desired, call new Client(configuration.copy()) instead of new Client(configuration).

Method Details

getConfiguration

@NonNull
public @NonNull Configuration getConfiguration()

Specified by:

getConfiguration in class FriedolinClient

Returns:

A deep copy of the preferences that determine the behaviour of this client (not the actual reference, for security reasons).

setConfiguration

public void setConfiguration(@NonNull
 @NonNull Configuration configuration)

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

Specified by:

setConfiguration in class FriedolinClient

Parameters:

configuration - The new configuration to use.

See Also:

• FriedolinClient.setConfigurationReference(Configuration)

setConfigurationReference

public void setConfigurationReference(@NonNull
 @NonNull Configuration configuration)

Updates the preferences that determine the behaviour of this client with the exact reference of the given Configuration (instead of just a deep copy).

Specified by:

setConfigurationReference in class FriedolinClient

Parameters:

configuration - The new configuration to use.

See Also:

• FriedolinClient.setConfiguration(Configuration)

initialise

private boolean initialise()

Makes an initial GET request to Friedolin to retrieve the initial cookies and headers needed for logging in.

Returns:

true if the request was successful, false otherwise

finish

public void finish()

Exits the headless browser. This method should be called when the headless browser is no longer needed but the application is still running, in order not to waste resources longer than necessary. Yes, Java has a garbage collector, but there may be situations where the parent of this object is still in use but does not need the headless browser anymore.

Specified by:

finish in class FriedolinClient

getLoginTask

@NonNull
public @NonNull Client.Login getLoginTask()

Specified by:

getLoginTask in class FriedolinClient

Returns:

A Task that can be executed in a different Thread to log in to Friedolin.

fetchGrades

public boolean fetchGrades(@NonNull
 @NonNull String... degrees)
                    throws IllegalArgumentException

Fetches the student's grades from the University of Jena's Friedolin system, using the credentials specified in the Configuration previously set via FriedolinClient.setConfiguration(Configuration) (or the constructor).

Specified by:

fetchGrades in class FriedolinClient

Parameters:

degrees - The academic degrees to fetch the grades for. If none are specified, all degrees present in

invalid reference

Configuration#getAcademicDegrees()

will be fetched.

Returns:

true if the grades were fetched successfully, false otherwise.

Throws:

IllegalArgumentException - If any of the given degrees is not present in the configuration.

getFetchClearnameTask

@NonNull
public @NonNull Client.FetchClearname getFetchClearnameTask()

Specified by:

getFetchClearnameTask in class FriedolinClient

Returns:

A Task that can be executed in a different Thread to fetch the student's real name (e.g. Edward Snowden) from the University of Jena's Friedolin system.

getFetchEmailAddressTask

@NonNull
public @NonNull Client.FetchEmailAddress getFetchEmailAddressTask()

Specified by:

getFetchEmailAddressTask in class FriedolinClient

Returns:

A Task that can be executed in a different Thread to fetch the student's email address (e.g. edward.snowden@uni-jena.de).

checkInternetConnectivity

@NonNull
public @NonNull FriedolinClient.InternetConnectivityStatus checkInternetConnectivity()

Determines whether and how the client can access the internet.

Specified by:

checkInternetConnectivity in class FriedolinClient

Returns:

The status of the internet connectivity.

See Also:

• checkInternetConnectivity()
• HeadlessBrowser.checkInternetConnectivity()

Implementation Note:

In order to rule out DNS issues, we first try to ping 199.7.83.42 (i.e. l.root-servers.net of ICANN). Then, we connect to codeberg.org to take DNS into consideration.

acceptObligationOfUse

@NonNull
private @NonNull HttpResponse<@NonNull String> acceptObligationOfUse()
                                                              throws IllegalStateException,
IOException,
InterruptedException,
IllegalArgumentException,
SecurityException

Before students can access their grades, they have to accept the "Obligation of Use", i.e. Friedolin's terms of service. This method accepts the obligation of use, by "clicking" the "Accept" checkbox.

Returns:

The response from the server to the request, which is a list of all courses (Studiengänge) the student is enrolled in.

Throws:

IllegalStateException - If initialise() has not been called yet.

IOException - See post(Map, Map, Map).

InterruptedException - See post(Map, Map, Map).

IllegalArgumentException - See post(Map, Map, Map).

SecurityException - See post(Map, Map, Map).

fetchObligationOfUse

@NonNull
private @NonNull HttpResponse<@NonNull String> fetchObligationOfUse()
                                                             throws IOException,
InterruptedException,
IllegalArgumentException,
SecurityException

Retrieves the obligation-of-use page from Friedolin, which needs to be accepted before the grade table can be accessed. The obligation of use is basically Friedolin's terms of service, which state that the student is obliged to check Friedolin every two weeks for new grades.

Returns:

The response from the server to the request, which is the obligation-of-use page.

Throws:

IOException - See get(Map, Map).

InterruptedException - See get(Map, Map).

IllegalArgumentException - See get(Map, Map).

SecurityException - See get(Map, Map).

fetchStudyProgress

@Deprecated
public boolean fetchStudyProgress()

Deprecated.

Tests whether internal pages can be fetched at all by trying to get the student's study progress.

Returns:

true if the study progress was successfully fetched, false otherwise

fetchMyData

@Deprecated
public boolean fetchMyData()

Deprecated.

Tests whether internal pages can be fetched at all by trying to get the student's personal data.

Returns:

true if the personal data was successfully fetched, false otherwise

get

@NonNull
private @NonNull HttpResponse<@NonNull String> get(@NonNull
 @NonNull Map<@NonNull String,@NonNull String> headers)
                                            throws IOException,
InterruptedException,
IllegalArgumentException,
SecurityException

Sends a GET request to Friedolyn.REQUEST_URL with the given headers.

Parameters:

headers - Custom headers additionally to the default headers. (See addHeaders(HttpRequest.Builder))

Returns:

The response from the server to the request.

Throws:

IOException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

InterruptedException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

IllegalArgumentException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

SecurityException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

get

@NonNull
private @NonNull HttpResponse<@NonNull String> get(@NonNull
 @NonNull Map<@NonNull String,@NonNull String> urlParameters,
 @NonNull
 @NonNull Map<@NonNull String,@NonNull String> headers)
                                            throws IllegalStateException,
IOException,
InterruptedException,
IllegalArgumentException,
SecurityException

Sends a GET request to Friedolyn.REQUEST_URL with the given parameters and headers.

Parameters:

urlParameters - The query to append to the URL. If the Map includes a key named asi, its value will be replaced with the current urlSecretParameter.

headers - Custom headers additionally to the default headers. (see addHeaders(HttpRequest.Builder))

Returns:

The response from the server to the request.

Throws:

IllegalStateException - If initialise() has not been called yet.

IOException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

InterruptedException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

IllegalArgumentException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

SecurityException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

post

@NonNull
private @NonNull HttpResponse<@NonNull String> post(@NonNull
 @NonNull Map<@NonNull String,@NonNull String> urlParameters,
 @NonNull
 @NonNull Map<@NonNull String,@NonNull String> headers,
 @NonNull
 @NonNull Map<@NonNull String,@NonNull String> body)
                                             throws IllegalStateException,
IOException,
InterruptedException,
IllegalArgumentException,
SecurityException

Sends a POST request to Friedolyn.REQUEST_URL with the given parameters and headers.

Parameters:

urlParameters - The query to append to the URL. If the Map includes a key named asi, its value will be replaced with the current urlSecretParameter.

headers - Custom headers additionally to the default headers. (see addHeaders(HttpRequest.Builder))

body - The body of the request, i.e. form data.

Returns:

The response from the server to the request.

Throws:

IllegalStateException - If initialise() has not been called yet.

IOException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

InterruptedException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

IllegalArgumentException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

SecurityException - See request(FriedolinClient.HTTP_REQUEST_TYPE, Map, Map, Map).

request

@NonNull
private @NonNull HttpResponse<@NonNull String> request(@NonNull
 FriedolinClient.HTTP_REQUEST_TYPE type,
 @NonNull
 @NonNull Map<@NonNull String,@NonNull String> urlParameters,
 @NonNull
 @NonNull Map<@NonNull String,@NonNull String> headers,
 @NonNull
 @NonNull Map<@NonNull String,@NonNull String> body)
                                                throws IOException,
InterruptedException,
IllegalArgumentException,
SecurityException,
IllegalStateException

Makes an HTTP request to the Friedolin server.

Parameters:

type - Whether it's a GET or a POST request.

urlParameters - The query to append to the URL. If the Map includes a key named asi, its value will be replaced with the current urlSecretParameter.

headers - Custom headers additionally to the default headers. (see addHeaders(HttpRequest.Builder))

body - The body of the request, i.e. form data. Is ignored for FriedolinClient.HTTP_REQUEST_TYPE.GET requests.

Returns:

The response from the server to the request.

Throws:

IllegalStateException - If initialise() has not been called yet.

IOException - See HttpClient.send(HttpRequest, HttpResponse.BodyHandler).

InterruptedException - See HttpClient.send(HttpRequest, HttpResponse.BodyHandler).

IllegalArgumentException - See HttpClient.send(HttpRequest, HttpResponse.BodyHandler).

SecurityException - See HttpClient.send(HttpRequest, HttpResponse.BodyHandler).

downloadFile

private boolean downloadFile(@NonNull
 @NonNull Map<@NonNull String,@NonNull String> urlParameters,
 @NonNull
 @NonNull Map<@NonNull String,@NonNull String> headers,
 @NonNull
 @NonNull File downloadTarget)
                      throws IllegalArgumentException,
IllegalStateException

Retrieves some file from the Friedolin server and saves it in the specified location.

Parameters:

urlParameters - The query to append to the Friedolyn.REQUEST_URL. If the Map includes a key named asi, its value will be replaced with the current urlSecretParameter.

headers - Custom headers additionally to the default headers. (see addHeaders(HttpRequest.Builder))

downloadTarget - The path where the file should be saved, including the file name. The file must not exist, but the directory must exist.

Returns:

true if the file was successfully downloaded, false otherwise

Throws:

IllegalArgumentException - If the file could not be fetched and saved.

IllegalStateException - If the client is null.

updateCookies

private boolean updateCookies(@NonNull
 @NonNull URI uri,
 @NonNull
 @NonNull HttpHeaders headers)

Makes the client remember the cookies received from the server in the given headers.

Parameters:

uri - The URI of the server that sent the cookies.

headers - The headers of the HttpResponse that contained the cookies.

Returns:

true if the cookies were successfully saved, false otherwise

addHeaders

@NonNull
private HttpRequest.Builder addHeaders(@NonNull
 HttpRequest.Builder builder)

Adds the default headers to the given HttpRequest.Builder, namely:

• Accept
• Accept-Encoding
• Accept-Language
• Cache-Control
• Content-Type
• DNT
• Origin
• Sec-Fetch-Dest
• Sec-Fetch-Mode
• Sec-Fetch-Site
• Sec-Fetch-User
• Sec-GPC
• Upgrade-Insecure-Requests
• User-Agent

Parameters:

builder - The HttpRequest.Builder to add the headers to.

Returns:

The same HttpRequest.Builder with the headers added.