Package com.draftable.api.client

Class Comparisons

java.lang.Object

com.draftable.api.client.Comparisons

All Implemented Interfaces:

Closeable, AutoCloseable

public class Comparisons
extends Object
implements Closeable

Client for the `comparisons` endpoint in the Draftable Comparison API.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Comparisons.BadRequestException	Thrown when a createComparison(com.draftable.api.client.Comparisons.Side, com.draftable.api.client.Comparisons.Side) request is made with bad parameters.
static class	Comparisons.ComparisonNotFoundException	Thrown when the a getComparison(String) or deleteComparison(String) request is made for a non-existent comparison.
static class	Comparisons.InvalidAuthenticationException	Thrown when a request is made, but the provided auth token is invalid.
static final class	Comparisons.Side	Represents a file passed in as one side of a comparison.
static class	Comparisons.UnknownErrorException	Thrown when an unknown error occurs while making a request.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	defaultApiBase

Constructor Summary

Constructors

Constructor	Description
Comparisons(String accountId, String authToken)	Constructs a Comparisons instance for the given credentials, which can then be used to make API requests.
Comparisons(String accountId, String authToken, String apiBaseUrl)	Constructs a Comparisons instance for the given credentials and apiBaseUrl, which can then be used to make API requests.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes any open inner HTTP clients, and ends any async event loops.
Comparison	createComparison(Comparisons.Side left, Comparisons.Side right)	Synchronously creates a *private* comparison that never expires with the given sides and an automatically generated identifier.
Comparison	createComparison(Comparisons.Side left, Comparisons.Side right, String identifier, boolean isPublic, Instant expires)	Synchronously creates a comparison with the given sides and properties.
CompletableFuture<Comparison>	createComparisonAsync(Comparisons.Side left, Comparisons.Side right)	Asynchronously creates a *private* comparison that never expires with the given sides and an automatically generated identifier.
CompletableFuture<Comparison>	createComparisonAsync(Comparisons.Side left, Comparisons.Side right, String identifier, boolean isPublic, Instant expires)	Asynchronously creates a comparison with the given sides and properties.
Export	createExport(String comparisonId, ExportKind exportKind)
Export	createExport(String comparisonId, ExportKind exportKind, boolean includeCoverPage)	Creates a new export of given kind for given comparison
void	deleteComparison(String identifier)	Synchronously deletes a given comparison.
CompletableFuture<Void>	deleteComparisonAsync(String identifier)	Asynchronously deletes a given comparison.
static String	generateIdentifier()
List<Comparison>	getAllComparisons()	Synchronously gets a list of all of the account's comparisons.
CompletableFuture<List<Comparison>>	getAllComparisonsAsync()	Asynchronously gets a list of all of the account's comparisons.
Comparison	getComparison(String identifier)	Synchronously gets metadata for a given comparison.
CompletableFuture<Comparison>	getComparisonAsync(String identifier)	Asynchronously gets metadata for a given comparison.
Export	getExport(String identifier)	Gets an existing export
String	publicViewerURL(String identifier)
String	publicViewerURL(String identifier, boolean wait)
String	signedViewerURL(String identifier)
String	signedViewerURL(String identifier, Duration validUntil, boolean wait)
String	signedViewerURL(String identifier, Instant validUntil, boolean wait)

Methods inherited from class java.lang.Object

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

Field Details

defaultApiBase

@Nonnull
public static final String defaultApiBase

See Also:

• Constant Field Values

Constructor Details

Comparisons

public Comparisons(@Nonnull
 String accountId,
 @Nonnull
 String authToken)

Constructs a Comparisons instance for the given credentials, which can then be used to make API requests.

Parameters:

accountId - The account ID to make requests for. This is located in your account console.

authToken - The auth token for the account. This is located in your account console.

Comparisons

public Comparisons(@Nonnull
 String accountId,
 @Nonnull
 String authToken,
 @Nullable
 String apiBaseUrl)

Constructs a Comparisons instance for the given credentials and apiBaseUrl, which can then be used to make API requests.

Parameters:

accountId - The account ID to make requests for. This is located in your account console.

authToken - The auth token for the account. This is located in your account console.

apiBaseUrl - The base API URL. If null, use the default Draftable cloud API URL. The URL must have the protocol (e.g. "https") and end in "v1" with no trailing slash, e.g. "https://api.draftable.com/v1"

Method Details

close

public void close()
           throws IOException

Closes any open inner HTTP clients, and ends any async event loops.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - An error occurred closing an HTTP client.

getExport

@Nonnull
public Export getExport(@Nonnull
 String identifier)
                 throws Comparisons.ComparisonNotFoundException,
IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Gets an existing export

Parameters:

identifier - Export identifier (note that this is different from comparison identifier).

Returns:

The object giving metadata about the existing export.

Throws:

Comparisons.ComparisonNotFoundException

IOException

Comparisons.InvalidAuthenticationException

Comparisons.UnknownErrorException

createExport

@Nonnull
public Export createExport(@Nonnull
 String comparisonId,
 @Nonnull
 ExportKind exportKind,
 boolean includeCoverPage)
                    throws Comparisons.BadRequestException,
IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Creates a new export of given kind for given comparison

Parameters:

comparisonId - The unique identifier of the comparison to export

exportKind - Export kind. Supported values: single_page, combined, left, right.

includeCoverPage - Relevant only for combined comparison, indicates whether it should include a cover page

Returns:

The object giving metadata about the newly created export.

Throws:

Comparisons.BadRequestException

IOException

Comparisons.InvalidAuthenticationException

Comparisons.UnknownErrorException

createExport

@Nonnull
public Export createExport(@Nonnull
 String comparisonId,
 @Nonnull
 ExportKind exportKind)
                    throws Comparisons.BadRequestException,
IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Throws:

Comparisons.BadRequestException

IOException

Comparisons.InvalidAuthenticationException

Comparisons.UnknownErrorException

getAllComparisons

@Nonnull
public List<Comparison> getAllComparisons()
                                   throws IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Synchronously gets a list of all of the account's comparisons.

Returns:

A List<Comparison> giving all of the account's comparisons.

Throws:

IOException - If an error occurs communicating with the server.

Comparisons.InvalidAuthenticationException - If the given auth token is invalid.

Comparisons.UnknownErrorException - If an unknown error occurs internally. This should never be thrown, but guarantees that no other kinds of exceptions are thrown.

getAllComparisonsAsync

@Nonnull
public CompletableFuture<List<Comparison>> getAllComparisonsAsync()

Asynchronously gets a list of all of the account's comparisons.

Returns:

A CompletableFuture<List<Comparison>> that will complete with a list all of the account's comparisons, or with one of the exceptions documented in getAllComparisons().

getComparison

@Nonnull
public Comparison getComparison(@Nonnull
 String identifier)
                         throws Comparisons.ComparisonNotFoundException,
IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Synchronously gets metadata for a given comparison.

Parameters:

identifier - The comparison's identifier.

Returns:

A Comparison giving the comparison's metadata.

Throws:

Comparisons.ComparisonNotFoundException - If no comparison with the given identifier exists.

IOException - If an error occurs communicating with the server.

Comparisons.InvalidAuthenticationException - If the given auth token is invalid.

Comparisons.UnknownErrorException - If an unknown error occurs internally. This should never be thrown, but guarantees that no other kinds of exceptions are thrown.

getComparisonAsync

@Nonnull
public CompletableFuture<Comparison> getComparisonAsync(@Nonnull
 String identifier)

Asynchronously gets metadata for a given comparison.

Parameters:

identifier - The comparison's identifier.

Returns:

A CompletableFuture<Comparison> that will complete with a Comparison giving the metadata, or with one of the exceptions documented in getComparison(java.lang.String).

deleteComparison

public void deleteComparison(@Nonnull
 String identifier)
                      throws Comparisons.ComparisonNotFoundException,
IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Synchronously deletes a given comparison.

Parameters:

identifier - The comparison's identifier.

Throws:

Comparisons.ComparisonNotFoundException - If no comparison with the given identifier exists.

IOException - If an error occurs communicating with the server.

Comparisons.InvalidAuthenticationException - If the given auth token is invalid.

Comparisons.UnknownErrorException - If an unknown error occurs internally. This should never be thrown, but guarantees that no other kinds of exceptions are thrown.

deleteComparisonAsync

@Nonnull
public CompletableFuture<Void> deleteComparisonAsync(@Nonnull
 String identifier)

Asynchronously deletes a given comparison.

Parameters:

identifier - The comparison's identifier.

Returns:

A CompletableFuture that will complete with Void if the comparison is successfully deleted, or with one of the exceptions documented in deleteComparison(java.lang.String).

createComparison

@Nonnull
public Comparison createComparison(@Nonnull
 Comparisons.Side left,
 @Nonnull
 Comparisons.Side right)
                            throws IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Synchronously creates a *private* comparison that never expires with the given sides and an automatically generated identifier.

Parameters:

left - A Comparisons.Side representing the left file.

right - A Comparisons.Side representing the right file.

Returns:

A Comparison instance representing the newly created comparison.

Throws:

IOException - If an error occurs communicating with the server.

Comparisons.InvalidAuthenticationException - If the given auth token is invalid.

Comparisons.UnknownErrorException - If an unknown error occurs internally. This should never be thrown, but guarantees that no other kinds of exceptions are thrown.

createComparison

@Nonnull
public Comparison createComparison(@Nonnull
 Comparisons.Side left,
 @Nonnull
 Comparisons.Side right,
 @Nullable
 String identifier,
 boolean isPublic,
 @Nullable
 Instant expires)
                            throws Comparisons.BadRequestException,
IOException,
Comparisons.InvalidAuthenticationException,
Comparisons.UnknownErrorException

Synchronously creates a comparison with the given sides and properties.

Parameters:

left - A Comparisons.Side representing the left file.

right - A Comparisons.Side representing the right file.

identifier - The identifier to use, or null to use an automatically generated one. If you provide an identifier that clashes with an existing comparison, a Comparisons.BadRequestException is thrown.

isPublic - Whether the comparison is publicly accessible, or requires authentication to view.

expires - An Instant at which the comparison will expire and be automatically deleted, or null for no expiry. If provided, the expiry time must be in the future.

Returns:

A Comparison instance representing the newly created comparison.

Throws:

Comparisons.BadRequestException - If you provide an identifier that is already in use, or other invalid information.

IOException - If an error occurs communicating with the server.

Comparisons.InvalidAuthenticationException - If the given auth token is invalid.

Comparisons.UnknownErrorException - If an unknown error occurs internally. This should never be thrown, but guarantees that no other kinds of exceptions are thrown.

createComparisonAsync

@Nonnull
public CompletableFuture<Comparison> createComparisonAsync(@Nonnull
 Comparisons.Side left,
 @Nonnull
 Comparisons.Side right)

Asynchronously creates a *private* comparison that never expires with the given sides and an automatically generated identifier.

Parameters:

left - A Comparisons.Side representing the left file.

right - A Comparisons.Side representing the right file.

Returns:

A CompletableFuture<Comparison> that will complete with the newly created comparison, or an exception as documented in createComparison(Side, Side).

createComparisonAsync

@Nonnull
public CompletableFuture<Comparison> createComparisonAsync(@Nonnull
 Comparisons.Side left,
 @Nonnull
 Comparisons.Side right,
 @Nullable
 String identifier,
 boolean isPublic,
 @Nullable
 Instant expires)

Asynchronously creates a comparison with the given sides and properties.

Parameters:

left - A Comparisons.Side representing the left file.

right - A Comparisons.Side representing the right file.

identifier - The identifier to use, or null to use an automatically generated one. If you provide an identifier that clashes with an existing comparison, a Comparisons.BadRequestException is thrown.

isPublic - Whether the comparison is publicly accessible, or requires authentication to view.

expires - An Instant at which the comparison will expire and be automatically deleted, or null for no expiry. If provided, the expiry time must be in the future.

Returns:

A CompletableFuture<Comparison> that will complete with the newly created comparison, or an exception as documented in createComparison(Side, Side, String, boolean, Instant).

publicViewerURL

@Nonnull
public String publicViewerURL(@Nonnull
 String identifier)

publicViewerURL

@Nonnull
public String publicViewerURL(@Nonnull
 String identifier,
 boolean wait)

signedViewerURL

@Nonnull
public String signedViewerURL(@Nonnull
 String identifier)

signedViewerURL

@Nonnull
public String signedViewerURL(@Nonnull
 String identifier,
 @Nonnull
 Duration validUntil,
 boolean wait)

signedViewerURL

@Nonnull
public String signedViewerURL(@Nonnull
 String identifier,
 @Nonnull
 Instant validUntil,
 boolean wait)

generateIdentifier

@Nonnull
public static String generateIdentifier()