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 and 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 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.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and 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.
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.
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

Constructor Detail

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.

Method Detail

close

public void close()
           throws IOException

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

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - An error occurred closing an HTTP client.

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()