Configuration

A client built with FilesClient.builder() takes its configuration from its builder; see Clients and Connections. The static methods, such as User.list(), are configured by calling FilesClient.setProperty().

Configuration Options

Base URL

Set this to the full https:// URL of your Files.com subdomain (e.g. https://MY-SUBDOMAIN.files.com). This is not required in most cases, but one benefit of setting it is that it ensures that authentication failures will be logged to your site's API logs. Without setting this, we won't know which site to associate the authentication failure with, and it won't be logged to your site's API logs. This is always required if your site is configured to disable global acceleration. This can also be set to use a mock server in development or CI.

Example setting

import com.files.FilesClient;

FilesClient.setProperty("apiRoot", "https://MY-SUBDOMAIN.files.com");

FilesClient client = FilesClient.builder()
    .apiKey("YOUR_API_KEY")
    .apiRoot("https://MY-SUBDOMAIN.files.com")
    .build();

Retries and Time Limits

These properties configure the static methods; a built client has builder methods of the same meaning.

maxNetworkRetries: the most times a request is sent again after its first attempt. Default 3.
initialRetryDelayMillis: the wait before the first retry, doubling for each later one. Default 100.
maximumRetrySeconds: the longest wait before a retry, including a server's Retry-After. Default 10.
connectTimeoutMillis and readTimeoutMillis: the longest waits to connect and for the next bytes of a response. Defaults 30000 and 80000.
regionRelocation: whether requests follow Files.com to its own server for a site after a region mismatch. Default true.

Example setting

import com.files.FilesClient;

FilesClient.setProperty("maxNetworkRetries", "5");
FilesClient.setProperty("readTimeoutMillis", "120000");

Timeouts

connectTimeoutMillis is how long the SDK waits to open a connection, 30000 (30 seconds) by default. readTimeoutMillis is how long it waits for data from an open connection, 80000 (80 seconds) by default; it limits each wait, not a whole response. Both are in milliseconds; 0 means no limit, and a negative value leaves the limit to the system default. The static methods read them when each call starts, so a change applies from the next call; a client you build keeps the timeouts it was built with. How long a request of the static methods waits for a connection from the SDK's connection pool is separate: 10 seconds, and not configurable. A client you build sets it with connectionAcquisitionTimeout.

Example setting

import com.files.FilesClient;

FilesClient.setProperty("connectTimeoutMillis", "30000");
FilesClient.setProperty("readTimeoutMillis", "80000");

Retry Attempts

upstreamMaxAttempts is how many times, at most, the SDK sends a request that keeps failing in a way it retries, counting the first request. The default, 4, allows the first request and up to 3 retries. Set it to 1 to turn the SDK's retries off; it must be at least 1. maxNetworkRetries, when set, takes its place. The SDK reads it before each attempt. The SDK retries a request after a connection or read failure that may be temporary, HTTP 429, HTTP 502 or above, or HTTP 500 in answer to a GET. It does not retry HTTP 501, a URL it cannot send, a certificate or host name that does not verify, or redirects that loop or go past the limit. Each resend is one of these attempts: the SDK turns off the Apache HTTP client's own resends.

Example setting

import com.files.FilesClient;

FilesClient.setProperty("upstreamMaxAttempts", "4");

Retry Delay

initialRetryDelayMillis is how long, in milliseconds, the SDK waits before the first retry of a request, 100 by default. Each later retry of that request waits twice as long as the one before. The SDK reads it for every retry, so a change applies from the next retry.

Example setting

import com.files.FilesClient;

FilesClient.setProperty("initialRetryDelayMillis", "100");

Logging

The SDK logs through the SLF4J 2 API, under logger names that begin with com.files. Apache HttpClient, which sends the SDK's requests, logs under org.apache.http. The SDK includes no logging provider or configuration, so your application's provider and configuration decide what is written. Without a provider, SLF4J prints a one-time notice that it found none, and the messages are discarded.

The SDK logs warnings, such as retried requests. At DEBUG level, com.files logs each request's URL, parameters and options, and org.apache.http logs request headers. Both can include your API key, so keep these loggers at INFO or above in production.

To send the SDK's messages to Log4j, add the Log4j SLF4J 2 provider and Log4j Core to your application:

pom.xml

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-slf4j2-impl</artifactId>
    <version>2.26.1</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.26.1</version>
</dependency>

Then choose the com.files level in your Log4j configuration:

src/main/resources/log4j2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Logger name="com.files" level="WARN"/>
        <Root level="INFO">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

Other SLF4J providers, such as Logback, are set up the same way. You can read more about Log4j configuration.

SLF4J 1.7

The SDK only calls SLF4J methods that version 1.7 also provides. An application that manages org.slf4j:slf4j-api at 1.7.x can keep it, together with a 1.7 binding such as org.slf4j:slf4j-simple:1.7.36. Keep the API and the provider on the same SLF4J generation: SLF4J 2 ignores 1.7 bindings, and SLF4J 1.7 cannot load SLF4J 2 providers, so either mix loses the SDK's messages.