javastrava.service.ClubGroupEventService Maven / Gradle / Ivy
Show all versions of javastrava-api Show documentation
package javastrava.service;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import javastrava.auth.model.Token;
import javastrava.auth.ref.AuthorisationScope;
import javastrava.model.StravaAthlete;
import javastrava.model.StravaClubEvent;
import javastrava.model.StravaClubEventJoinResponse;
import javastrava.service.exception.NotFoundException;
import javastrava.service.exception.UnauthorizedException;
import javastrava.util.Paging;
/**
*
* {@link StravaClubEvent} related services
*
*
*
* Group Events are optionally recurring events for club members.
*
*
*
* Only club members can access private club events.
*
*
*
* The objects are returned in summary or detailed representations.
*
*
* @author Dan Shannon
*
*/
public interface ClubGroupEventService extends StravaService {
/**
*
* Deletes (and cancels) an event, which must be editable by the authenticating user. An access token with write permissions is required.
*
*
* @param id
* The identifier of the event to be deleted
* @throws NotFoundException
* If the event does not exist
* @throws UnauthorizedException
* If the authenticated athlete or the token does not have permission to delete the event
*/
public void deleteEvent(Integer id) throws NotFoundException, UnauthorizedException;
/**
*
* Deletes (and cancels) an event, which must be editable by the authenticating user. An access token with write permissions is required.
*
*
* @param event
* The event to be deleted
* @throws NotFoundException
* If the event does not exist
* @throws UnauthorizedException
* If the authenticated athlete or the token does not have permission to delete the event
*/
public void deleteEvent(StravaClubEvent event) throws NotFoundException, UnauthorizedException;
/**
*
* Deletes (and cancels) an event, which must be editable by the authenticating user. An access token with write permissions is required.
*
*
* @param id
* The identifier of the event to be deleted
* @return Callback that can be used later to get results
* @throws NotFoundException
* If the event does not exist
* @throws UnauthorizedException
* If the authenticated athlete or the token does not have permission to delete the event
*/
public CompletableFuture deleteEventAsync(Integer id) throws NotFoundException, UnauthorizedException;
/**
*
* Deletes (and cancels) an event, which must be editable by the authenticating user. An access token with write permissions is required.
*
*
* @param event
* The event to be deleted
* @return Callback that can be used later to get results
* @throws NotFoundException
* If the event does not exist
* @throws UnauthorizedException
* If the authenticated athlete or the token does not have permission to delete the event
*/
public CompletableFuture deleteEventAsync(StravaClubEvent event) throws NotFoundException, UnauthorizedException;
/**
*
* Returns a single group event summary representation.
*
*
* @param id
* The identifier of the group event
* @return The group event, or null if the event does not exist, or an event with resource state set to PRIVATE if the club is private
*/
public StravaClubEvent getEvent(Integer id);
/**
*
* Returns a single group event summary representation.
*
*
* @param id
* The identifier of the group event
* @return The response indicating whether the authenticated athlete has joined the event, inside a completable future. Returned event will be null if the event with the given id
* doesn't exist
*/
public CompletableFuture getEventAsync(Integer id);
/**
*
* Join a group {@link StravaClubEvent event} on behalf of the authenticated {@link StravaAthlete athlete}. For recurring events, join the upcoming occurrence. An {@link Token access token} with
* {@link AuthorisationScope#WRITE write scope} is required.
*
*
* @param id
* The identifier of the group event
* @return The response indicating whether the authenticated athlete has joined the event
*/
public StravaClubEventJoinResponse joinEvent(Integer id);
/**
*
* Join a group {@link StravaClubEvent event} on behalf of the authenticated {@link StravaAthlete athlete}. For recurring events, join the upcoming occurrence. An {@link Token access token} with
* {@link AuthorisationScope#WRITE write scope} is required.
*
*
* @param id
* The identifier of the group event
* @return The response indicating whether the authenticated athlete has joined the event, inside a completable future
*/
public CompletableFuture joinEventAsync(Integer id);
/**
*
* Leave a group {@link StravaClubEvent event} on behalf of the authenticated {@link StravaAthlete athlete}. For recurring events, leave the upcoming occurrence. An {@link Token access token} with
* {@link AuthorisationScope#WRITE write scope} is required.
*
*
* @param id
* The identifier of the group event
* @return The response indicating whether the authenticated athlete has joined the event
*/
public StravaClubEventJoinResponse leaveEvent(Integer id);
/**
*
* Leave a group {@link StravaClubEvent event} on behalf of the authenticated {@link StravaAthlete athlete}. For recurring events, leave the upcoming occurrence. An {@link Token access token} with
* {@link AuthorisationScope#WRITE write scope} is required.
*
*
* @param id
* The identifier of the group event
* @return The response indicating whether the authenticated athlete has joined the event, inside a completable future
*/
public CompletableFuture leaveEventAsync(Integer id);
/**
*
* Retrieve summary information about ALL athletes joined a specific group event, or the upcoming occurrence for recurring events, regardless of how many there are.
*
*
*
* Pagination is NOT supported.
*
*
*
* Returns an array of athletes summary representations with athletes who the authenticated athlete is following first.
*
*
*
* Returns null if the event does not exist
*
*
*
* Returns an empty list if the event is private or belongs to a club that is private that the authenticated athlete is not a member of
*
*
* @param eventId
* The identifier of the event for which athletes should be listed
* @return Array of athletes who have joined the event
*/
public List listAllEventJoinedAthletes(Integer eventId);
/**
*
* Retrieve summary information about ALL athletes joined a specific group event, or the upcoming occurrence for recurring events, regardless of how many there are.
*
*
*
* Pagination is NOT supported.
*
*
*
* Returns a completable future which can later be used to return an array of athletes summary representations with athletes who the authenticated athlete is following first.
*
*
*
* Returns null if the event does not exist
*
*
*
* Returns an empty list if the event is private or belongs to a club that is private that the authenticated athlete is not a member of
*
*
* @param eventId
* The identifier of the event for which athletes should be listed
* @return Array of athletes who have joined the event
*/
public CompletableFuture> listAllEventJoinedAthletesAsync(Integer eventId);
/**
*
* Retrieve summary information about athletes joined a specific group event, or the upcoming occurrence for recurring events.
*
*
*
* Pagination is supported.
*
*
*
* Returns an array of athletes summary representations with athletes who the authenticated athlete is following first.
*
*
*
* Returns null if the event does not exist
*
*
*
* Returns an empty list if the event is private or belongs to a club that is private that the authenticated athlete is not a member of
*
*
* @param eventId
* The identifier of the event for which athletes should be listed
* @param pagingInstruction
* Paging instruction
* @return Array of athletes who have joined the event
*/
public List listEventJoinedAthletes(Integer eventId, Paging pagingInstruction);
/**
*
* Retrieve summary information about athletes joined a specific group event, or the upcoming occurrence for recurring events.
*
*
* Pagination is supported.
*
*
* Returns a completable future which can be used later to return an array of athletes summary representations with athletes who the authenticated athlete is following first.
*
*
* @param eventId
* The identifier of the event for which athletes should be listed
* @param pagingInstruction
* Paging instruction
* @return Array of athletes who have joined the event
*/
public CompletableFuture> listEventJoinedAthletesAsync(Integer eventId, Paging pagingInstruction);
}