Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.meta

Class PolledMetadata

java.lang.Object

page.codeberg.friedolyn.meta.Downloadable

page.codeberg.friedolyn.meta.PolledMetadata

All Implemented Interfaces:

Copyable<PolledMetadata>

public class PolledMetadata
extends Downloadable
implements Copyable<PolledMetadata>

Represents information about the Friedolyn application that is fetched from the Friedolyn data repository.

See Also:

• download()
• importFromConfigurationDirectory()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	PolledMetadata.BannedUserCallback	Someone who is interested in being informed if the currently logged-in user is found to be banned from using the application.

Field Summary

Fields

Modifier and Type	Field	Description
private final @NonNull HashSet<PolledMetadata.BannedUserCallback>	BANNED_USER_LISTENERS	Everyone interested in being informed if the currently logged-in user is found to be banned from using the application.
private @NonNull ArrayList<BannedUser>	bannedUsers	A list of users who, for some reason, are not allowed to use the application.
private @NonNull Configuration	configuration	Specifies the Configuration object that contains the directory where the metadata file is stored.
private static URL	dataURL	The URL that points to the metadata file of the application.
private boolean	decryptPollURL	Whether the pollUrl should be decrypted or not.
private static final @NonNull String	DEFAULT_METADATA_FILE_NAME	The default metadata file that is shipped with the application.
private static final @NonNull ReentrantLock	DEFAULT_METADATA_LOCK	Facilitates mutual exclusion for loading the defaultPolledMetadata.
private static final @NonNull URL	DEFAULT_POLL_URL	The default full URL that points to a poll made by the developers asking the end-users for feedback on the application.
private static PolledMetadata	defaultPolledMetadata	The metadata that is shipped with the application in the metadata.default.json file.
private static final @NonNull String	FILE_NAME	The name of the file that contains the metadata of the application.
private static final @NonNull String	JSON_SCHEMA	The format that the metadata.json file must adhere to.
private static final byte[]	PASSWORD	The password that is used to decrypt the pollUrl.
private static final @NonNull String	POLL_PREFIX	The first part of the URL that points to a poll made by the developers asking the end-users for feedback on the application.
private URL	pollUrl	A new URL that points to a poll made by the developers asking the end-users for feedback on the application, according to the metadata fetched from the dataURL.
private static final @NonNull Preferences	PREFERENCES	Stores metadata about the metadata, e.g.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	PolledMetadata()	Deprecated. Only used by Jackson for deserialisation.
private	PolledMetadata(@NonNull String pollUrl)	Deprecated. Only used by Jackson for deserialisation.
	PolledMetadata(@NonNull Configuration configuration)	Creates a new PolledMetadata object and tries to import the metadata.json file from the invalid reference directory specified in the given Configuration.
	PolledMetadata(@NonNull Configuration configuration, boolean decryptPollURL)	Creates a new PolledMetadata object and tries to import the metadata.json file from the invalid reference directory specified in the given Configuration.

Method Summary

Modifier and Type	Method	Description
@NonNull Optional<BannedUser>	checkForBans()	Compares the configuration of the currently logged-in user with the bannedUsers to see whether the user is prohibited to use the application.
@NonNull PolledMetadata	copy()
private @NonNull Optional<String>	decryptPollURL(@NonNull String cipherTextRaw)	Decrypts the given cipher text and stores it as the new pollUrl.
boolean	download()	Fetches up-to-date metadata from the dataURL and saves it to the invalid reference directory specified in the configuration as metadata.json.
(package private) static @NonNull PolledMetadata	fromFile(@NonNull File file)	Converts a given JSON file to a PolledMetadata object.
static @NonNull PolledMetadata	fromJSON(@NonNull String json)	Converts a given JSON string to a PolledMetadata object.
@NonNull ArrayList<@NonNull BannedUser>	getBannedUsers()
static @NonNull Optional<PolledMetadata>	getDefaultPolledMetadata()	Returns a deep copy of the defaultPolledMetadata object that holds the metadata shipped with the application.
Optional<URL>	getPollUrl()
boolean	importFromConfigurationDirectory()	Tries to read the metadata.json file from the invalid reference directory specified in the configuration and load the pollUrl and the bannedUsers from it.
void	importFromFile(@NonNull File file)	Tries to load the pollUrl and the bannedUsers from the given File.
private static @NonNull PolledMetadata	loadDefaultMetadata()	Converts metadata.default.json resource file shipped with the application to a PolledMetadata object.
void	registerBannedUserCallback(@NonNull PolledMetadata.BannedUserCallback callback)	Adds the given PolledMetadata.BannedUserCallback to the list of listeners that are informed if the currently logged-in user is found to be banned from using the application.
boolean	removeBannedUserCallback(@NonNull PolledMetadata.BannedUserCallback callback)	Unsubscribes the given PolledMetadata.BannedUserCallback from the list of listeners, meaning it will no longer be notified if the currently logged-in user is found to be banned from using the application.
private void	setPollUrl(@NonNull String url)	Deprecated. Only used by Jackson for deserialisation.
boolean	wasDownloadedWithin(@NonNull Duration duration)	Checks if the Friedolyn application's metadata was polled more recently than the specified duration, i.e.

Methods inherited from class page.codeberg.friedolyn.meta.Downloadable

wasDownloadedWithin

Methods inherited from class java.lang.Object

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

Field Details

PREFERENCES

@NonNull
private static final @NonNull Preferences PREFERENCES

Stores metadata about the metadata, e.g. the date and time of the last download.

defaultPolledMetadata

@Nullable
private static PolledMetadata defaultPolledMetadata

The metadata that is shipped with the application in the metadata.default.json file.

DEFAULT_METADATA_FILE_NAME

@NonNull
private static final @NonNull String DEFAULT_METADATA_FILE_NAME

The default metadata file that is shipped with the application. It is used as a fallback if the metadata file could not be downloaded from the dataURL.

See Also:

• PolledMetadata(Configuration)
• Constant Field Values

dataURL

@Nullable
private static URL dataURL

The URL that points to the metadata file of the application. It is stored in the Friedolyn data repository.

FILE_NAME

@NonNull
private static final @NonNull String FILE_NAME

The name of the file that contains the metadata of the application. It is stored in the

invalid reference

directory

specified in the Configuration.

See Also:

• Constant Field Values

JSON_SCHEMA

@NonNull
private static final @NonNull String JSON_SCHEMA

The format that the metadata.json file must adhere to. Available online.

DEFAULT_POLL_URL

@NonNull
private static final @NonNull URL DEFAULT_POLL_URL

The default full URL that points to a poll made by the developers asking the end-users for feedback on the application.

DEFAULT_METADATA_LOCK

@NonNull
private static final @NonNull ReentrantLock DEFAULT_METADATA_LOCK

Facilitates mutual exclusion for loading the defaultPolledMetadata.

POLL_PREFIX

@NonNull
private static final @NonNull String POLL_PREFIX

The first part of the URL that points to a poll made by the developers asking the end-users for feedback on the application.

See Also:

• Constant Field Values

configuration

@NonNull
private @NonNull Configuration configuration

Specifies the Configuration object that contains the directory where the metadata file is stored.

pollUrl

@Nullable
private URL pollUrl

A new URL that points to a poll made by the developers asking the end-users for feedback on the application, according to the metadata fetched from the dataURL. In order to make it harder for users to find out the full poll URL just by looking at the source code, it is AES-encrypted.

See Also:

• decryptPollURL(String)

decryptPollURL

private boolean decryptPollURL

Whether the pollUrl should be decrypted or not. Will be respected by decryptPollURL(String).

PASSWORD

private static final byte[] PASSWORD

The password that is used to decrypt the pollUrl.

bannedUsers

@NonNull
private @NonNull ArrayList<BannedUser> bannedUsers

A list of users who, for some reason, are not allowed to use the application. The application must refuse to work for these users.

BANNED_USER_LISTENERS

@NonNull
private final @NonNull HashSet<PolledMetadata.BannedUserCallback> BANNED_USER_LISTENERS

Everyone interested in being informed if the currently logged-in user is found to be banned from using the application.

See Also:

• checkForBans()

Constructor Details

PolledMetadata

public PolledMetadata(@NonNull
 @NonNull Configuration configuration)

Creates a new PolledMetadata object and tries to import the metadata.json file from the

invalid reference

directory

specified in the given Configuration.

Parameters:

configuration - Specifies the directory to import the metadata from.

See Also:

• PolledMetadata(Configuration, boolean)

PolledMetadata

public PolledMetadata(@NonNull
 @NonNull Configuration configuration,
 boolean decryptPollURL)

Creates a new PolledMetadata object and tries to import the metadata.json file from the

invalid reference

directory

specified in the given Configuration.

Parameters:

configuration - Specifies the directory to import the metadata from.

decryptPollURL - Whether the pollUrl should be decrypted or not. Set this to false, if the user has recently taken part in the poll, in order not to waste resources on the heavy decryption process.

See Also:

• PolledMetadata(Configuration)

PolledMetadata

@Deprecated
private PolledMetadata(@NonNull
 @NonNull String pollUrl)

Deprecated.

Only used by Jackson for deserialisation.

Parameters:

pollUrl - The pollUrl specified in the JSON metadata.

PolledMetadata

@Deprecated
private PolledMetadata()

Deprecated.

Only used by Jackson for deserialisation.

Method Details

getPollUrl

public Optional<URL> getPollUrl()

Returns:

The pollUrl that points to a poll made by the developers asking the end-users for feedback on the application. Empty if it is unset or could not be decrypted.

importFromConfigurationDirectory

public boolean importFromConfigurationDirectory()

Tries to read the metadata.json file from the

invalid reference

directory

specified in the configuration and load the pollUrl and the bannedUsers from it.

Returns:

true if the metadata file was successfully imported, false otherwise.

importFromFile

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

Tries to load the pollUrl and the bannedUsers from the given File.

Parameters:

file - The file to read the metadata from.

Throws:

IllegalArgumentException - If the metadata file is formatted incorrectly. See fromFile(File) for details.

wasDownloadedWithin

public boolean wasDownloadedWithin(@NonNull
 @NonNull Duration duration)

Checks if the Friedolyn application's metadata was polled more recently than the specified duration, i.e. whether the metadata was downloaded within `now - duration`.

Specified by:

wasDownloadedWithin in class Downloadable

Parameters:

duration - The time between the oldest acceptable download date and now.

Returns:

true if the metadata was downloaded within the specified duration, false otherwise.

download

public boolean download()

Fetches up-to-date metadata from the dataURL and saves it to the

invalid reference

directory

specified in the configuration as metadata.json.

Specified by:

download in class Downloadable

Returns:

true if the metadata was successfully downloaded, false otherwise.

getBannedUsers

@NonNull
public @NonNull ArrayList<@NonNull BannedUser> getBannedUsers()

Returns:

A deep copy of the bannedUsers list.

registerBannedUserCallback

public void registerBannedUserCallback(@NonNull
 @NonNull PolledMetadata.BannedUserCallback callback)

Adds the given PolledMetadata.BannedUserCallback to the list of listeners that are informed if the currently logged-in user is found to be banned from using the application. The listener's exact reference will be used (instead of a deep copy) in order to make removal easier.

Parameters:

callback - The new listener to be added.

removeBannedUserCallback

public boolean removeBannedUserCallback(@NonNull
 @NonNull PolledMetadata.BannedUserCallback callback)

Unsubscribes the given PolledMetadata.BannedUserCallback from the list of listeners, meaning it will no longer be notified if the currently logged-in user is found to be banned from using the application.

Parameters:

callback - The listener to be removed. Must be the exact reference that was previously registered.

Returns:

true if the listener was successfully removed, false otherwise.

fromFile

@NonNull
static @NonNull PolledMetadata fromFile(@NonNull
 @NonNull File file)
                                 throws IOException,
IllegalArgumentException,
SecurityException,
OutOfMemoryError

Converts a given JSON file to a PolledMetadata object.

Parameters:

file - The file to read the metadata from.

Returns:

The metadata object represented by the JSON.

Throws:

IllegalArgumentException - If the metadata file is formatted incorrectly. See fromJSON(String) for details.

IOException - If the file could not be read.

SecurityException - If the file could not be read due to security restrictions.

OutOfMemoryError - If the file is too large to be read.

loadDefaultMetadata

@NonNull
private static @NonNull PolledMetadata loadDefaultMetadata()
                                                    throws RuntimeException

Converts metadata.default.json resource file shipped with the application to a PolledMetadata object.

Returns:

The metadata represented by the default metadata file.

Throws:

RuntimeException - If the default metadata file could not be found, read, or parsed.

fromJSON

@NonNull
public static @NonNull PolledMetadata fromJSON(@NonNull
 @NonNull String json)
                                        throws IllegalArgumentException,
com.fasterxml.jackson.core.JsonProcessingException

Converts a given JSON string to a PolledMetadata object.

Parameters:

json - The JSON string to read the metadata from. Must adhere to the JSON schema.

Returns:

The metadata object represented by the JSON.

Throws:

IllegalArgumentException - If the JSON does not match the expected format.

com.fasterxml.jackson.core.JsonProcessingException - See ObjectMapper.readValue(String, Class).

setPollUrl

@Deprecated
private void setPollUrl(@NonNull
 @NonNull String url)
                 throws IllegalArgumentException

Deprecated.

Only used by Jackson for deserialisation.

Parameters:

url - The new pollUrl specified in the JSON metadata.

Throws:

IllegalArgumentException - See decryptPollURL(String).

decryptPollURL

@NonNull
private @NonNull Optional<String> decryptPollURL(@NonNull
 @NonNull String cipherTextRaw)
                                          throws IllegalArgumentException

Decrypts the given cipher text and stores it as the new pollUrl.

Parameters:

cipherTextRaw - The cipher text to decrypt. Must match the format of CipherText.parse(String). Must have been encrypted with the password of this class.

Returns:

The decrypted poll URL.

Throws:

IllegalArgumentException - If the cipher text could not be decrypted.

checkForBans

@NonNull
public @NonNull Optional<BannedUser> checkForBans()

Compares the configuration of the currently logged-in user with the bannedUsers to see whether the user is prohibited to use the application. If the user is banned, onBansFound will be called on all listeners.

Returns:

The current user's BannedUser equivalent if they're banned. If the developers have left a message to the banned user with an explanation and if decrypting it succeeded, it will be made available via BannedUser.getDecryptedMessage(). If the user is not banned, an empty Optional will be returned.

copy

@NonNull
public @NonNull PolledMetadata copy()

Specified by:

copy in interface Copyable<PolledMetadata>

Returns:

An entirely new PolledMetadata object with

• deep copies of all bannedUsers
• a copy of the pollUrl if it is not null

getDefaultPolledMetadata

@NonNull
public static @NonNull Optional<PolledMetadata> getDefaultPolledMetadata()

Returns a deep copy of the defaultPolledMetadata object that holds the metadata shipped with the application. If necessary, the metadata will be loaded from the resources first.

Returns:

The default metadata. Empty if it could not be loaded.