javastrava.service.ClubService 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.model.StravaActivity;
import javastrava.model.StravaAthlete;
import javastrava.model.StravaClub;
import javastrava.model.StravaClubAnnouncement;
import javastrava.model.StravaClubEvent;
import javastrava.model.StravaClubMembershipResponse;
import javastrava.model.reference.StravaResourceState;
import javastrava.util.Paging;
/**
*
* {@link StravaClub} related services
*
*
*
* {@link StravaClub Clubs} represent groups of {@link StravaAthlete athletes} on Strava. They can be public or private.
*
*
*
* Only members of private clubs can access their details.
*
*
*
* The object is returned in summary or detailed {@link StravaResourceState representations}.
*
*
* @author Dan Shannon
*
*/
public interface ClubService extends StravaService {
/**
*
* Retrieve details about a specific {@link StravaClub club}. The club must be public or the current {@link StravaAthlete athlete} must be a member.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty club (with only the id set) if the club is private and the authenticated athlete is not a member
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id
*
*
* @see http://strava.github.io/api/v3/clubs/#get-details
*
* @param clubId
* The id of the {@link StravaClub} to be retrieved
* @return Returns a detailed club representation.
*/
public StravaClub getClub(final Integer clubId);
/**
*
* Retrieve details about a specific {@link StravaClub club}. The club must be public or the current {@link StravaAthlete athlete} must be a member.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty club (with only the id set) if the club is private and the authenticated athlete is not a member
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id
*
*
* @see http://strava.github.io/api/v3/clubs/#get-details
*
* @param clubId
* The id of the {@link StravaClub} to be retrieved
* @return Returns a detailed club representation.
*/
public CompletableFuture getClubAsync(final Integer clubId);
/**
*
* Join a club on behalf of the authenticated user. An access token with write permissions is required.
*
*
* @param clubId
* ID of the {@link StravaClub} to join
* @return Response detailing whether request was successful and whether the member is active
*/
public StravaClubMembershipResponse joinClub(final Integer clubId);
/**
*
* Join a club on behalf of the authenticated user. An access token with write permissions is required.
*
*
* @param clubId
* ID of the {@link StravaClub} to join
* @return Response detailing whether request was successful and whether the member is active
*/
public CompletableFuture joinClubAsync(final Integer clubId);
/**
*
* Leave a club on behalf of the authenticated user. An access token with write permissions is required.
*
*
* @param clubId
* ID of the club to join
* @return Response detailing whether request was successful and whether the member is active
*/
public StravaClubMembershipResponse leaveClub(final Integer clubId);
/**
*
* Leave a club on behalf of the authenticated user. An access token with write permissions is required.
*
*
* @param clubId
* ID of the club to join
* @return Response detailing whether request was successful and whether the member is active
*/
public CompletableFuture leaveClubAsync(final Integer clubId);
/**
*
* List the {@link StravaAthlete}s who are administrators of a club.
*
*
* The athletes are returned in summary representation
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club.
*
* Pagination is NOT supported
*
* @param clubId The club whose administrators should be listed
* @return List of administrators
*/
public List listAllClubAdmins(final Integer clubId);
/**
*
* List the {@link StravaAthlete}s who are administrators of a club.
*
*
* The athletes are returned in summary representation
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club.
*
* Pagination is NOT supported
*
* @param clubId The club whose administrators should be listed
* @return List of administrators - call {@link CompletableFuture#complete(Object)} when ready.
*/
public CompletableFuture> listAllClubAdminsAsync(final Integer clubId);
/**
*
* Convenience method for returning ALL of the members of a club
*
*
*
* Returns ALL the members, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* USE WITH CAUTION - CLUBS WITH MANY MEMBERS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the club is private
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id/members
*
*
* @see http://strava.github.io/api/v3/clubs/#get-members
*
* @param clubId
* The id of the {@link StravaClub} whose member {@link StravaAthlete athletes} should be returned
* @return Returns an array of {@link StravaAthlete athlete} summary {@link StravaResourceState representations}.
*/
public List listAllClubMembers(final Integer clubId);
/**
*
* Convenience method for returning ALL of the members of a club
*
*
*
* Returns ALL the members, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* USE WITH CAUTION - CLUBS WITH MANY MEMBERS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the club is private
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id/members
*
*
* @see http://strava.github.io/api/v3/clubs/#get-members
*
* @param clubId
* The id of the {@link StravaClub} whose member {@link StravaAthlete athletes} should be returned
* @return Returns an array of {@link StravaAthlete athlete} summary {@link StravaResourceState representations}.
*/
public CompletableFuture> listAllClubMembersAsync(final Integer clubId);
/**
*
* Retrieve ALL the recent {@link StravaActivity activities} performed by member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* The authenticated athlete must be a member of the club.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the authorised athlete is not a member of the club
*
*
*
* Pagination is supported. However, the results are limited to the last 200 total activities by club members.
*
*
* @see http://strava.github.io/api/v3/clubs/#get-activities
*
* @param clubId
* The id of the {@link StravaClub} for which recent {@link StravaActivity activities} are to be returned.
* @return Returns an array of {@link StravaActivity activity} summary {@link StravaResourceState representations}.
*/
public List listAllRecentClubActivities(final Integer clubId);
/**
*
* Retrieve ALL the recent {@link StravaActivity activities} performed by member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* The authenticated athlete must be a member of the club.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the authorised athlete is not a member of the club
*
*
*
* Pagination is supported. However, the results are limited to the last 200 total activities by club members.
*
*
* @see http://strava.github.io/api/v3/clubs/#get-activities
*
* @param clubId
* The id of the {@link StravaClub} for which recent {@link StravaActivity activities} are to be returned.
* @return Returns an array of {@link StravaActivity activity} summary {@link StravaResourceState representations}.
*/
public CompletableFuture> listAllRecentClubActivitiesAsync(final Integer clubId);
/**
*
* Fetch an array of {@link StravaClub clubs} that the currently authenticated {@link StravaAthlete athlete} is a member of.
*
*
*
* Pagination is not supported. Returns all clubs of which the athlete is a member.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/clubs
*
*
* @see http://strava.github.io/api/v3/clubs/#get-athletes
*
* @return Returns a list of {@link StravaClub club} {@link StravaResourceState summary} representations.
*/
public List listAuthenticatedAthleteClubs();
/**
*
* Fetch an array of {@link StravaClub clubs} that the currently authenticated {@link StravaAthlete athlete} is a member of.
*
*
*
* Pagination is not supported. Returns all clubs of which the athlete is a member.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/clubs
*
*
* @see http://strava.github.io/api/v3/clubs/#get-athletes
*
* @return Returns a list of {@link StravaClub club} {@link StravaResourceState summary} representations.
*/
public CompletableFuture> listAuthenticatedAthleteClubsAsync();
/**
*
* List the {@link StravaAthlete}s who are administrators of a club.
*
*
* The athletes are returned in summary representation
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club.
*
* Pagination is NOT supported
*
* @param clubId The club whose administrators should be listed
* @return List of administrators
*/
public List listClubAdmins(final Integer clubId);
/**
*
* List the {@link StravaAthlete}s who are administrators of a club.
*
*
* The athletes are returned in summary representation
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club.
*
* Pagination is supported
*
* @param clubId The club whose administrators should be listed
* @param paging Paging instruction
* @return List of administrators
*/
public List listClubAdmins(final Integer clubId, final Paging paging);
/**
*
* List the {@link StravaAthlete}s who are administrators of a club.
*
*
* The athletes are returned in summary representation
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club.
*
* Pagination is NOT supported
*
* @param clubId The club whose administrators should be listed
* @return {@link CompletableFuture} which will return the List of administrators
*/
public CompletableFuture> listClubAdminsAsync(final Integer clubId);
/**
*
* List the {@link StravaAthlete}s who are administrators of a club.
*
*
* The athletes are returned in summary representation
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club.
*
* Pagination is supported
*
* @param clubId The club whose administrators should be listed
* @param paging Paging instruction
* @return {@link CompletableFuture} which will return the List of administrators
*/
public CompletableFuture> listClubAdminsAsync(final Integer clubId, final Paging paging);
/**
* Announcements are posts sent by Club Admins or Owners to the members of a club.
*
* Only members of private clubs can access their announcements.
*
* The objects are returned in summary representation.
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club
*
* Pagination is not supported
*
* @see http://strava.github.io/api/v3/clubs/#get-announcements
*
* @param clubId The id of the {@link StravaClub} for which announcements should be returned.
* @return Returns a list of {@link StravaClubAnnouncement announcements}
*/
public List listClubAnnouncements(final Integer clubId);
/**
* Announcements are posts sent by Club Admins or Owners to the members of a club.
*
* Only members of private clubs can access their announcements.
*
* The objects are returned in summary representation.
*
* Returns null if the club with the given id does not exist.
*
* Returns an empty list if the club is private and the authorised athlete is not a member of the club
*
* Pagination is not supported
*
* @see http://strava.github.io/api/v3/clubs/#get-announcements
*
* @param clubId The id of the {@link StravaClub} for which announcements should be returned.
* @return Returns a list of {@link StravaClubAnnouncement announcements}
*/
public CompletableFuture> listClubAnnouncementsAsync(final Integer clubId);
/**
*
* Group Events are optionally recurring events for club members.
*
*
* Only club members can access private club events.
*
*
* The objects are returned in summary representation.
*
*
*
* Pagination is NOT supported
*
*
* @see http://strava.github.io/api/partner/v3/clubs/#get-group-events
* @param clubId Club identifier
* @return List of all club events
*/
public List listClubGroupEvents(final Integer clubId);
/**
*
* Group Events are optionally recurring events for club members.
*
*
* Only club members can access private club events.
*
*
* The objects are returned in summary representation.
*
*
*
* Pagination is NOT supported
*
*
* @see http://strava.github.io/api/partner/v3/clubs/#get-group-events
* @param clubId Club identifier
* @return List of all club events (to retrieve call {@link CompletableFuture#get()})
*/
public CompletableFuture> listClubGroupEventsAsync(final Integer clubId);
/**
*
* Retrieve summary information about member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* Pagination is not supported. Returns only the first page of members.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the club is private
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id/members
*
*
* @see http://strava.github.io/api/v3/clubs/#get-members
*
* @param clubId
* The id of the {@link StravaClub} whose member {@link StravaAthlete athletes} should be returned
* @return Returns an array of {@link StravaAthlete athlete} summary {@link StravaResourceState representations}.
*/
public List listClubMembers(final Integer clubId);
/**
*
* Retrieve summary information about member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the club is private
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id/members
*
*
* @see http://strava.github.io/api/v3/clubs/#get-members
*
* @param clubId
* The id of the {@link StravaClub} whose member {@link StravaAthlete athletes} should be returned
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaAthlete athlete} summary {@link StravaResourceState representations}.
*/
public List listClubMembers(final Integer clubId, final Paging pagingInstruction);
/**
*
* Retrieve summary information about member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* Pagination is not supported. Returns only the first page of members.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the club is private
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id/members
*
*
* @see http://strava.github.io/api/v3/clubs/#get-members
*
* @param clubId
* The id of the {@link StravaClub} whose member {@link StravaAthlete athletes} should be returned
* @return Returns an array of {@link StravaAthlete athlete} summary {@link StravaResourceState representations}.
*/
public CompletableFuture> listClubMembersAsync(final Integer clubId);
/**
*
* Retrieve summary information about member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the club is private
*
*
*
* URL GET https://www.strava.com/api/v3/clubs/:id/members
*
*
* @see http://strava.github.io/api/v3/clubs/#get-members
*
* @param clubId
* The id of the {@link StravaClub} whose member {@link StravaAthlete athletes} should be returned
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaAthlete athlete} summary {@link StravaResourceState representations}.
*/
public CompletableFuture> listClubMembersAsync(final Integer clubId, final Paging pagingInstruction);
/**
*
* Retrieve the recent {@link StravaActivity activities} performed by member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* The authenticated athlete must be a member of the club.
*
*
*
* Pagination is NOT supported. Returns only the first page of activities.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the authorised athlete is not a member of the club
*
*
* @see http://strava.github.io/api/v3/clubs/#get-activities
*
* @param clubId
* The id of the {@link StravaClub} for which recent {@link StravaActivity activities} are to be returned.
* @return Returns an array of {@link StravaActivity activity} summary {@link StravaResourceState representations}.
*/
public List listRecentClubActivities(final Integer clubId);
/**
*
* Retrieve the recent {@link StravaActivity activities} performed by member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* The authenticated athlete must be a member of the club.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the authorised athlete is not a member of the club
*
*
*
* Pagination is supported. However, the results are limited to the last 200 total activities by club members.
*
*
* @see http://strava.github.io/api/v3/clubs/#get-activities
*
* @param clubId
* The id of the {@link StravaClub} for which recent {@link StravaActivity activities} are to be returned.
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaActivity activity} summary {@link StravaResourceState representations}.
*/
public List listRecentClubActivities(final Integer clubId, final Paging pagingInstruction);
/**
*
* Retrieve the recent {@link StravaActivity activities} performed by member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* The authenticated athlete must be a member of the club.
*
*
*
* Pagination is NOT supported. Returns only the first page of activities.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the authorised athlete is not a member of the club
*
*
* @see http://strava.github.io/api/v3/clubs/#get-activities
*
* @param clubId
* The id of the {@link StravaClub} for which recent {@link StravaActivity activities} are to be returned.
* @return Returns an array of {@link StravaActivity activity} summary {@link StravaResourceState representations}.
*/
public CompletableFuture> listRecentClubActivitiesAsync(final Integer clubId);
/**
*
* Retrieve the recent {@link StravaActivity activities} performed by member {@link StravaAthlete athletes} of a specific {@link StravaClub club}.
*
*
*
* The authenticated athlete must be a member of the club.
*
*
*
* Returns null if club with the given id does not exist
*
*
*
* Returns an empty list if the authorised athlete is not a member of the club
*
*
*
* Pagination is supported. However, the results are limited to the last 200 total activities by club members.
*
*
* @see http://strava.github.io/api/v3/clubs/#get-activities
*
* @param clubId
* The id of the {@link StravaClub} for which recent {@link StravaActivity activities} are to be returned.
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaActivity activity} summary {@link StravaResourceState representations}.
*/
public CompletableFuture> listRecentClubActivitiesAsync(final Integer clubId, final Paging pagingInstruction);
}