Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.configuration.client

Class UserAgentManager

java.lang.Object

page.codeberg.friedolyn.meta.Downloadable

page.codeberg.friedolyn.configuration.client.UserAgentManager

public class UserAgentManager
extends Downloadable

A utility class to manage a collection of user agents for different clients and platforms. The default user agents shipped with the application are available statically and can be accessed with getDefaultUserAgents(). If a custom (up-to-date) user-agent collection should be used, it is necessary to create an instance of this class and import the user agents from a file or JSON string.

See Also:

• getDefaultUserAgents()
• UserAgentManager(Configuration)
• importFromFile(File)
• importFromJson(String)
• getUserAgents()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	UserAgentManager.Client	The clients present in the user-agent collection by default.
static enum	UserAgentManager.Platform	The platforms used in the user-agent collection by default.
static class	UserAgentManager.UserAgentCollection	A HashMap in the form of <client, <platform, user-agent>> that contains the user agents for various clients on different platforms.

Field Summary

Fields

Modifier and Type	Field	Description
private @NonNull Configuration	configuration	We need this in order to know where to store the user-agents file.
private static UserAgentManager.UserAgentCollection	DEFAULT_USER_AGENTS	Contains all the user agents for different clients and platforms that are available in the application by default.
private static final @NonNull String	DEFAULT_USER_AGENTS_FILE_NAME	The file name of the default user-agents collection shipped with the application.
private static final @NonNull ReentrantLock	DEFAULT_USER_AGENTS_LOCK	A lock to ensure that the user agents are not used before they are fully initialised and translated.
private static @NonNull Boolean	defaultUserAgentsAreInitialised	Will be set to true once the user agents are fully initialised and translated.
private static final @NonNull Preferences	PREFERENCES
private static final @NonNull String	USER_AGENTS_FILE_NAME	The file name under which the up-to-date user agents will be stored once they have been fetched from the internet.
private static final @NonNull URL	USER_AGENTS_URL	The URL where an up-to-date user-agent collection can be downloaded from in order to update userAgents.
private UserAgentManager.UserAgentCollection	userAgents	Contains all the user agents for different clients and platforms that are available in the application.
private static String	userAgentsSchema	The JSON schema for the user-agent collection.

Constructor Summary

Constructors

Constructor	Description
UserAgentManager(@NonNull Configuration configuration)	Creates a new user-agent manager and tries to import the user-agents.json file from the invalid reference Friedolyn directory specified in the given configuration.

Method Summary

Modifier and Type	Method	Description
boolean	download()	Fetches an up-to-date user-agents collection from the internet, saves the collection as user-agents.json in the invalid reference Friedolyn directory and imports it into the userAgents field.
static @NonNull UserAgentManager.UserAgentCollection	getDefaultUserAgents()	Returns the user-agent collection for different clients and platforms that is shipped with the application.
@NonNull UserAgentManager.UserAgentCollection	getUserAgents()
boolean	importFromConfigurationDirectory()	Tries to read the user agents from the user-agents.json file in the invalid reference Friedolyn directory .
void	importFromFile(@NonNull File file)	Updates the user agents with the contents of the given file.
void	importFromJson(@NonNull String json)	Loads the user agents from the given JSON string, validates them against the JSON schema and sets them as the new user agents.
private static void	loadSchemaAndDefaultUserAgentCollection()	Loads the JSON schema for the UserAgentManager.UserAgentCollection from user-agents.schema.json and imports the default user agents from user-agents.default.json.
boolean	wasDownloadedWithin(@NonNull Duration duration)	Checks if the user agents were downloaded 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

configuration

@NonNull
private @NonNull Configuration configuration

We need this in order to know where to store the user-agents file.

userAgentsSchema

@Nullable
private static String userAgentsSchema

The JSON schema for the user-agent collection. Expected to be user-agents.schema.json.

USER_AGENTS_URL

@NonNull
private static final @NonNull URL USER_AGENTS_URL

The URL where an up-to-date user-agent collection can be downloaded from in order to update userAgents. Defaults to the Friedolyn data repository.

USER_AGENTS_FILE_NAME

@NonNull
private static final @NonNull String USER_AGENTS_FILE_NAME

The file name under which the up-to-date user agents will be stored once they have been fetched from the internet.

See Also:

• Constant Field Values

DEFAULT_USER_AGENTS_FILE_NAME

@NonNull
private static final @NonNull String DEFAULT_USER_AGENTS_FILE_NAME

The file name of the default user-agents collection shipped with the application. The JSON file is expected to be available as a resource in the same package as this class.

See Also:

• Constant Field Values

DEFAULT_USER_AGENTS

@Nullable
private static UserAgentManager.UserAgentCollection DEFAULT_USER_AGENTS

Contains all the user agents for different clients and platforms that are available in the application by default. This collection is guaranteed to be available but may not be up-to-date. If necessary, it is loaded from the default pre-defined JSON file.

defaultUserAgentsAreInitialised

@NonNull
private static @NonNull Boolean defaultUserAgentsAreInitialised

Will be set to true once the user agents are fully initialised and translated. Remains false until then.

DEFAULT_USER_AGENTS_LOCK

@NonNull
private static final @NonNull ReentrantLock DEFAULT_USER_AGENTS_LOCK

A lock to ensure that the user agents are not used before they are fully initialised and translated.

userAgents

@Nullable
private UserAgentManager.UserAgentCollection userAgents

Contains all the user agents for different clients and platforms that are available in the application.

Constructor Details

UserAgentManager

public UserAgentManager(@NonNull
 @NonNull Configuration configuration)

Creates a new user-agent manager and tries to import the user-agents.json file from the

invalid reference

Friedolyn directory

specified in the given configuration.

Parameters:

configuration - The configuration that specifies the Friedolyn directory.

Method Details

loadSchemaAndDefaultUserAgentCollection

private static void loadSchemaAndDefaultUserAgentCollection()

Loads the JSON schema for the UserAgentManager.UserAgentCollection from user-agents.schema.json and imports the default user agents from user-agents.default.json. Will call notifyAll on DEFAULT_USER_AGENTS_LOCK once the user agents are fully initialised and translated.

Implementation Note:

TODO: Verify that this method is thread-safe.

importFromConfigurationDirectory

public boolean importFromConfigurationDirectory()

Tries to read the user agents from the user-agents.json file in the

invalid reference

Friedolyn directory

. It is expected that the file might not exist, in which case the method will just return false (but not throw an exception).

Returns:

true if the user agents were successfully imported, false otherwise.

wasDownloadedWithin

public boolean wasDownloadedWithin(@NonNull
 @NonNull Duration duration)

Checks if the user agents were downloaded more recently than the specified duration, i.e. whether the user agents were 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 user agents were downloaded within the specified duration, false otherwise.

download

public boolean download()

Fetches an up-to-date user-agents collection from the internet, saves the collection as user-agents.json in the

invalid reference

Friedolyn directory

and imports it into the userAgents field.

Specified by:

download in class Downloadable

Returns:

true in case of success, false if anything failed.

importFromFile

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

Updates the user agents with the contents of the given file. The file must contain a valid JSON string that matches the user-agents schema.

Parameters:

file - The file to import the user agents from.

Throws:

IOException - If the file could not be read.

IllegalArgumentException - If the file is not a file, if it does not exist, if the JSON in the file is invalid, if the JSON does not match the schema or if itlacks any of the clients in UserAgentManager.Client.

importFromJson

public void importFromJson(@NonNull
 @NonNull String json)
                    throws IllegalArgumentException,
com.fasterxml.jackson.core.JsonProcessingException

Loads the user agents from the given JSON string, validates them against the JSON schema and sets them as the new user agents.

Parameters:

json - The new user agents to load. Must include all the clients in UserAgentManager.Client, but may contain more.

Throws:

IllegalArgumentException - If the given JSON is invalid, does not match the schema or lacks any of the clients in UserAgentManager.Client.

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

getDefaultUserAgents

@NonNull
public static @NonNull UserAgentManager.UserAgentCollection getDefaultUserAgents()

Returns the user-agent collection for different clients and platforms that is shipped with the application. This means that the user agents are guaranteed to be available but may not be up-to-date. If necessary, they are loaded from the default pre-defined JSON file.

Returns:

The user agents for different clients and platforms.

See Also:

• getUserAgents()

API Note:

If you have already downloaded/imported a custom user agents collection, you should most likely use getUserAgents() on the instance that contains them, instead of calling this static method.

Implementation Note:

TODO: Verify that this method is thread-safe.

getUserAgents

@NonNull
public @NonNull UserAgentManager.UserAgentCollection getUserAgents()

Returns:

The user agents specific to this instance if they are not null, otherwise the default user agents shipped with the application. Therefore, it is guaranteed that this method will always return a valid user-agent collection, but it is NOT guaranteed that the user agents are up-to-date.

See Also:

• getDefaultUserAgents()
• importFromFile(File)
• importFromJson(String)