/**
* Common methods for searching for objects in the UTBS database.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Get the currently authenticated API user.
*
* @return The API user, or null if authentication details have not been
* supplied.
*/
/**
* Get full list of privileges that the currently authenticated user has,
* including role privileges.
* <p>
* If a provider is not specified, this will only include privileges
* granted to all providers. Otherwise it will include privileges granted
* for the specified provider, in addition to all-provider privileges.
*
* @param provider [optional] The short name of a provider.
* @return The user's privileges (separated by newlines).
*/
/**
* Get the current API version number.
*
* @return The API version number string.
*/
/**
* Methods for querying and manipulating bookings.
*
* <h4>The fetch parameter for event bookings</h4>
* <p>
* All methods that return bookings also accept an optional
* <code>fetch</code> parameter that may be used to request additional
* information about the bookings returned. For more details about the
* general rules that apply to the <code>fetch</code> parameter, refer to the
* {@link EventMethods} documentation.
* <p>
* For bookings the <code>fetch</code> parameter may be used to fetch details
* about the individual sessions booked and the referenced event, people and
* institutions:
* <ul>
* <li>{@code "event"} - fetches details about the event booked.</li>
* <li>{@code "participant"} - fetches details about the person the booking
* is for.</li>
* <li>{@code "booked_by"} - fetches details about the person who made the
* booking.</li>
* <li>{@code "institution"} - fetches details about the participant's
* institution chosen at the time the booking was made.</li>
* <li>{@code "session_bookings"} - fetches the session booking details.</li>
* <li>{@code "institutions"} - fetches a list of all the participant's
* institutions, as they were at the time the booking was made.</li>
* </ul>
* <p>
* As with the event <code>fetch</code> parameter, this reference may be used
* in a chain by using the "dot" notation to fetch additional information
* about the referenced event or institutions. For example
* "institution.school" will fetch the participant's chosen institution and
* the school to which it belongs. For more information about what can be
* fetched from the referenced event or institutions, refer to the
* documentation for {@link EventMethods} and {@link InstitutionMethods}.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Get the event booking with the specified ID.
* <p>
* By default, only a few basic details about the booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* Note that viewing bookings requires authentication, and a booking is
* only visible to the following:
* <ul>
* <li>The participant.</li>
* <li>The person who made the booking (not necessarily the
* participant).</li>
* <li>The event's trainers.</li>
* <li>The event's administrator, owner and booker.</li>
* <li>People with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>People with the "view-3rd-party-booking" privilege for the event's
* provider.</li>
* </ul>
*
* @param id [required] The ID of the booking to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested booking or null if it was not found.
*/
/**
* Update an event booking to record whether or not the participant
* attended the event.
* <p>
* The attendance may be updated for a single session on the event, by
* specifying a particular session number, or for all booked sessions, by
* passing {@code null} as the session number.
* <p>
* The attendance may be set to {@code true} or {@code false} to indicate
* whether or not the participant attended, or it may be set to
* {@code null} (its original value) to indicate that their attendance
* has not yet been recorded, or is currently unknown.
* <p>
* Note that updating attendance requires authentication as a user with
* permission to view the booking (see
* {@link #getBooking(Long,String) getBooking()}) and record attendance
* on the event. So in addition to being able to view the booking, the
* user must be either one of the following:
* <ul>
* <li>The event administrator.</li>
* <li>A person with the "record-attendance" privilege for the event's
* provider.</li>
* </ul>
*
* @param id [required] The ID of the booking to update.
* @param sessionNumber [optional] The session to update the attendance
* for, or {@code null} to update all booked sessions (the default).
* @param attended [optional] Whether or not the participant attended, or
* {@code null} to record that their attendance has not been set (the
* default).
*
* @return The updated booking, together with all associated session
* bookings.
*/
/**
* Update an event booking to record whether or not the participant
* attended the event, and whether they passed or failed.
* <p>
* The attendance and outcome may be updated for a single session on the
* event, by specifying a particular session number, or for all booked
* sessions, by passing {@code null} as the session number.
* <p>
* The attendance and outcome may each be set to {@code true} or
* {@code false} to indicate whether or not the participant attended or
* passed, or it may be set to {@code null} (its original value) to
* indicate that their attendance/outcome has not yet been recorded, or
* is currently unknown.
* <p>
* Note that updating attendance/outcome requires authentication as a user
* with permission to view the booking (see
* {@link #getBooking(Long,String) getBooking()}) and record attendance
* on the event. So in addition to being able to view the booking, the
* user must be either one of the following:
* <ul>
* <li>The event administrator.</li>
* <li>A person with the "record-attendance" privilege for the event's
* provider.</li>
* </ul>
*
* @param id [required] The ID of the booking to update.
* @param sessionNumber [optional] The session to update the attendance
* for, or {@code null} to update all booked sessions (the default).
* @param attended [optional] Whether or not the participant attended, or
* {@code null} to record that their attendance has not been set (the
* default).
* @param passed [optional] Whether or not the participant passed, or
* {@code null} to record that their outcome has not been set (the
* default).
*
* @return The updated booking, together with all associated session
* bookings.
*/
/**
* Methods for querying and manipulating courses.
* <p>
* Note that all the course details are actually on the individual events for
* the course, and may vary each time the course is run, so most of the
* useful methods for querying course details are actually in
* {@link EventMethods}.
*
* <h4>The fetch parameter for courses</h4>
* <p>
* All methods that return courses also accept an optional <code>fetch</code>
* parameter that may be used to request additional information about the
* courses returned. For more details about the general rules that apply to
* the <code>fetch</code> parameter, refer to the {@link EventMethods}
* documentation.
* <p>
* For courses the <code>fetch</code> parameter may be used to fetch
* referenced events and themes. The following references are
* supported:
* <ul>
* <li>{@code "events"} - fetches all the course's events, in (date, ID)
* order.</li>
* <li>{@code "themes"} - fetches all the themes containing the course.</li>
* </ul>
* <p>
* As with the event <code>fetch</code> parameter, the references may be used
* in a chain by using the "dot" notation to fetch additional information
* about referenced events and themes. For example "events.sessions" will
* fetch all the course's events and all their sessions. For more information
* about what can be fetched from referenced events and themes, refer to the
* documentation for {@link EventMethods} and {@link ThemeMethods}.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Get the course with the specified ID.
* <p>
* Note that a course by itself has very few attributes, since all the
* interesting details are held on the events in the course, so typically
* the optional <code>fetch</code> parameter should be used to fetch the
* course's events.
* <p>
* The <code>fetch</code> parameter may also be used to fetch the themes
* that contain the course.
*
* @param id [required] The ID of the course to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested course or null if it was not found.
*/
/**
* Get the events for the specified course in the specified time period.
* <p>
* This will return any events that overlap the specified time period.
* More specifically, it will return events whose start is less than or
* equal to the end of the time period, and whose end is greater than or
* equal to the start of the time period (i.e., all the start and end
* timestamps are treated inclusively).
* <p>
* Optionally, this will also check the event's sessions and exclude any
* events that have no sessions overlapping the specified time period.
* This can happen for events with multiple sessions. For example,
* suppose an event has 2 sessions, one on Monday and the other on
* Friday, and that the specified time period to search was on Wednesday.
* Then by default, the event would be returned, because it starts on
* Monday and ends on Friday, which overlaps the time period being
* searched, but if session checking is enabled, the event would be
* excluded.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date-time
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param id [required] The ID of the course.
* @param start [optional] The start of the time period to search. If
* omitted, this will default to 0:00am today.
* @param end [optional] The end of the time period to search. If
* omitted, this will default to the first midnight after the start date.
* @param checkSessions [optional] If {@code true}, check the event
* sessions, and exclude any events that have no sessions overlapping the
* the time period being searched.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of events found, in (start date-time, ID) order.
*/
/**
* Get a course's self-taught events.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param id [required] The ID of the course.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of self-taught events, in (title, ID) order.
*/
/**
* Methods for querying and manipulating events.
*
* <h4>The fetch parameter for events</h4>
* <p>
* All methods that return events also accept an optional <code>fetch</code>
* parameter that may be used to request additional information about the
* events returned. The following additional information may be fetched:
* <ul>
* <li>{@code "provider"} - fetches the event's provider.</li>
* <li>{@code "programme"} - fetches the programme containing the event.</li>
* <li>{@code "course"} - fetches the event's course, from which other events
* for the same course may be fetched by specifying
* {@code "course.events"}.</li>
* <li>{@code "topics"} - fetches the event's topics sections.</li>
* <li>{@code "extra_info"} - fetches any extra information sections that the
* event has.</li>
* <li>{@code "related_courses"} - fetches any related courses for the event,
* from which related events may be fetched by specifying
* {@code "related_courses.events"}.</li>
* <li>{@code "themes"} - fetches the event's themes.</li>
* <li>{@code "sessions"} - fetches the event's sessions.</li>
* <li>{@code "sessions.trainers"} - fetches the event's sessions and the
* trainers for each session.</li>
* <li>{@code "sessions.venue"} - fetches the event's sessions and the venue
* for each session.</li>
* <li>{@code "trainers"} - fetches the event's trainers, but not the
* individual sessions that they are assigned to.</li>
* <li>{@code "venues"} - fetches the event's venues, but not the individual
* sessions held in each venue.</li>
* <li>{@code "bookings"} - fetches the event's bookings, if the user is
* authenticated and has the appropriate privileges for the event. This may
* be an incomplete list, if the user does not have permission to view all
* the event's bookings.</li>
* </ul>
*
* <h4>Additional notes on the fetch parameter</h4>
* <p>
* In addition to the above values, the <code>fetch</code> parameter may also
* be used in a chain using "dot" notation to fetch additional information
* about each entity returned. For example:
* <p>
* <code>fetch = "themes.events"</code><br/>
* This fetches the events's themes, and also all the events for each of
* those themes.
* <p>
* <code>fetch = "programme.events.sessions"</code><br/>
* This fetches the event's programme, all the events in that programme and
* all the sessions in each of those events.
* <p>
* For more information about what may be fetched from each entity type in
* such a chain of fetches, refer to the documentation for the relevent
* entity type's methods: {@link ProviderMethods}, {@link ProgrammeMethods},
* {@link ThemeMethods}, {@link CourseMethods}, {@link VenueMethods}.
* <p>
* The <code>fetch</code> parameter also supports fetching multiple different
* kinds of additional information, by specifying a comma-separated list of
* values, for example:
* <p>
* <code>fetch = "course.events.programme,themes.events.trainers"</code><br/>
* This fetches all the events for the same course, and their programmes,
* plus all the events in the same theme(s) as this event, together with
* their trainers.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Get all events in the specified time period.
* <p>
* This will return any events that overlap the specified time period.
* More specifically, it will return events whose start is less than or
* equal to the end of the time period, and whose end is greater than or
* equal to the start of the time period (i.e., all the start and end
* timestamps are treated inclusively).
* <p>
* Optionally, this will also check the event's sessions and exclude any
* events that have no sessions overlapping the specified time period.
* This can happen for events with multiple sessions. For example,
* suppose an event has 2 sessions, one on Monday and the other on
* Friday, and that the specified time period to search was on Wednesday.
* Then by default, the event would be returned, because it starts on
* Monday and ends on Friday, which overlaps the time period being
* searched, but if session checking is enabled, the event would be
* excluded.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date-time
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param start [optional] The start of the time period to search. If
* omitted, this will default to 0:00am today.
* @param end [optional] The end of the time period to search. If
* omitted, this will default to the first midnight after the start date.
* @param checkSessions [optional] If {@code true}, check the event
* sessions, and exclude any events that have no sessions overlapping the
* the time period being searched.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of events found, in (start date-time, ID) order.
*/
/**
* Get the event with the specified ID.
* <p>
* By default, only a few basic details about the event are returned, but
* the optional <code>fetch</code> parameter may be used to fetch
* additional details.
*
* @param id [required] The ID of the event to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested event or null if it was not found.
*/
/**
* Get the booking (if there is one) for the specified participant on this
* event.
* <p>
* By default, only a few basic details about each booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* NOTE: This will return cancelled bookings, waiting list places, etc.
* Check the booking's {@link UTBSEventBooking#status status} field to see
* if it is a confirmed bookings.
* <p>
* NOTE: It is normally only possible for a participant to have one
* booking on an event. An exception to this is a booking with a status
* of 'interested', which represents an expression of interest in the
* course as a whole, rather than this specific event. If a participant
* has a regular booking and an 'interested' booking, this method will
* return the regular one only. If they have only an 'interested'
* booking, then it will be returned. So always check the booking's
* {@link UTBSEventBooking#status status} field.
* <p>
* Note that viewing an event's bookings requires authentication as one
* of the following:
* <ul>
* <li>One of the event's trainers.</li>
* <li>The event's administrator, owner or booker.</li>
* <li>A person with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>A person with the "view-3rd-party-booking" privilege for the
* event's provider.</li>
* </ul>
*
* @param id [required] The ID of the event.
* @param crsid [required] The CRSid of the participant.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each booking.
*
* @return The participant's booking on this event, if they have one.
*/
/**
* Get the booking (if there is one) for the specified participant on this
* event.
* <p>
* By default, only a few basic details about each booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* NOTE: This will return cancelled bookings, waiting list places, etc.
* Check the booking's {@link UTBSEventBooking#status status} field to see
* if it is a confirmed bookings.
* <p>
* NOTE: It is normally only possible for a participant to have one
* booking on an event. An exception to this is a booking with a status
* of 'interested', which represents an expression of interest in the
* course as a whole, rather than this specific event. If a participant
* has a regular booking and an 'interested' booking, this method will
* return the regular one only. If they have only an 'interested'
* booking, then it will be returned. So always check the booking's
* {@link UTBSEventBooking#status status} field.
* <p>
* Note that viewing an event's bookings requires authentication as one
* of the following:
* <ul>
* <li>One of the event's trainers.</li>
* <li>The event's administrator, owner or booker.</li>
* <li>A person with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>A person with the "view-3rd-party-booking" privilege for the
* event's provider.</li>
* </ul>
*
* @param id [required] The ID of the event.
* @param email [required] The email address of the participant.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each booking.
*
* @return The participant's booking on this event, if they have one.
*/
/**
* Get the bookings for the specified event.
* <p>
* By default, only a few basic details about each booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* NOTE: This will return <b>all</b> bookings, including cancelled
* bookings. Check each booking's {@link UTBSEventBooking#status status}
* field to see which are confirmed bookings.
* <p>
* Note that viewing an event's bookings requires authentication as one
* of the following:
* <ul>
* <li>One of the event's trainers.</li>
* <li>The event's administrator, owner or booker.</li>
* <li>A person with the "view-event-bookings" privilege for the event's
* provider.</li>
* <li>A person with the "view-3rd-party-booking" privilege for the
* event's provider.</li>
* </ul>
*
* @param id [required] The ID of the event.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each booking.
*
* @return The event's bookings, in the order they were created.
*/
/**
* Update the attendance record for the specified event, recording the
* fact that the specified person attended the specified session.
* <p>
* Optionally, this will create a booking record for the participant, if
* they do not already have one. If a booking is created in this way, its
* status will be "did not book", to indicate that the participant did
* not book onto the event themselves.
* <p>
* Note that this requires authentication as a user with permission to
* view the event's bookings and record attendance on the event.
* Additionally, the "create-3rd-party-booking" privilege is required if
* {@code autoCreateBooking} is set.
*
* @param id [required] The ID of the event.
* @param sessionNumber [required] The session to record attendance for.
* @param crsid [required] The CRSid of the person who attended.
* @param autoCreateBooking [optional] If {@code true}, automatically
* create a booking for the person, if they do not already have one.
* Otherwise, an error will be raised if the person has not booked.
*
* @return The existing or newly created booking record for the person,
* together with all associated session bookings.
*/
/**
* Methods for querying and manipulating institutions.
*
* <h4>The fetch parameter for institutions</h4>
* <p>
* All methods that return institutions also accept an optional
* <code>fetch</code> parameter that may be used to request additional
* information about the institutions returned. For more details about the
* general rules that apply to the <code>fetch</code> parameter, refer to the
* {@link EventMethods} documentation.
* <p>
* For institutions the <code>fetch</code> parameter may be used to fetch
* referenced institutions. The following references are supported:
* <ul>
* <li>{@code "parent"} - fetches the institution's parent institution.</li>
* <li>{@code "school"} - fetches the institution's school institution.</li>
* <li>{@code "children"} - fetches all the institution's child institutions.
* This will exclude cancelled children, unless the parent is cancelled.</li>
* </ul>
* <p>
* As with the event <code>fetch</code> parameter, the references may be used
* in a chain by using the "dot" notation to fetch additional information
* about referenced institutions. For example "parent.children" will fetch
* the parent and all sibling institutions.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Get the institution with the specified ID.
* <p>
* By default, only a few basic details about the institution are
* returned, but the optional <code>fetch</code> parameter may be used to
* fetch additional details.
*
* @param instid [required] The ID of the institution to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested institution or null if it was not found.
*/
/**
* Methods for querying and manipulating people.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Get the person with the specified CRSid.
* <p>
* Note that viewing people requires authentication, and a person's
* details are only visible to the following:
* <ul>
* <li>The person themselves.</li>
* <li>People with the "view-person-details" privilege.</li>
* </ul>
*
* @param crsid [required] The CRSid of the person to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch. Currently there are no additional details about
* people that can be retrieved.
*
* @return The requested person or null if they were not found.
*/
/**
* Get the specified person's current bookings.
* <p>
* This returns all bookings whose status is not "interested",
* "cancelled" or "completed" on events that are not finished, and for
* which the participant's attendance has not yet been recorded.
* <p>
* By default, only a few basic details about each booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* @param crsid [required] The CRSid of the person.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each booking.
*
* @return The person's current bookings, in the order they were created.
*/
/**
* Get the specified person's interested bookings.
* <p>
* This returns all bookings whose status is "interested". These are the
* bookings created to register the person's interest in events.
* <p>
* By default, only a few basic details about each booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* @param crsid [required] The CRSid of the person.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each booking.
*
* @return The person's interested bookings, in the order they were
* created.
*/
/**
* Get the specified person's training history.
* <p>
* This returns all the person's bookings except their current bookings,
* as returned by
* {@link #getCurrentBookings(String,String) getCurrentBookings()} and
* their bookings with a status of "interested", as returned by
* {@link #getInterestedBookings(String,String) getInterestedBookings()}.
* Note that this may include cancelled bookings and bookings on events
* that the participant did not attend.
* <p>
* By default, only a few basic details about each booking are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details about each booking.
* <p>
* Note that viewing a person's bookings requires authentication as a
* user with permission to view the person's details. Additionally, the
* bookings returned are filtered according to whether the user has
* permission to view them, based on the user's privileges with respect
* to each booking's event and training provider.
*
* @param crsid [required] The CRSid of the person.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each booking.
*
* @return The person's training history, in the order in which the
* bookings were created.
*/
/**
* Methods for querying and manipulating programmes.
*
* <h4>The fetch parameter for programmes</h4>
* <p>
* All methods that return programmes also accept an optional
* <code>fetch</code> parameter that may be used to request additional
* information about the programmes returned. For more details about the
* general rules that apply to the <code>fetch</code> parameter, refer to the
* {@link EventMethods} documentation.
* <p>
* For programmes the <code>fetch</code> parameter may be used to fetch
* referenced providers and events. The following references are supported:
* <ul>
* <li>{@code "provider"} - fetches the programme's provider.</li>
* <li>{@code "events"} - fetches all the programme's events, in (date, ID)
* order.</li>
* </ul>
* <p>
* As with the event <code>fetch</code> parameter, the references may be used
* in a chain by using the "dot" notation to fetch additional information
* about referenced providers and events. For example "events.themes" will
* fetch all the themes for each of the programme's events. For more
* information about what can be fetched from referenced providers and
* events, refer to the documentation for {@link ProviderMethods} and
* {@link EventMethods}.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Get all programmes in the specified date range.
* <p>
* This will return any programmes that overlap the specified date range.
* More specifically, it will return programmes whose start is less than
* or equal to the end date specified, and whose end is greater than or
* equal to the start date specified (i.e., all the start and end dates
* are treated inclusively).
* <p>
* By default, only a few basic details about each programme are
* returned, but the optional <code>fetch</code> parameter may be used to
* fetch additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param startDate [optional] The start date. If omitted, this will
* default to today.
* @param endDate [optional] The end date. If omitted, this will default
* to today.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each programme.
*
* @return A list of programmes found, in (date, ID) order.
*/
/**
* Get the programme with the specified ID.
* <p>
* By default, only a few basic details about the programme are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional details.
*
* @param id [required] The ID of the programme to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested programme or null if it was not found.
*/
/**
* Get a programme's events in the specified time period.
* <p>
* This will return any events that overlap the specified time period.
* More specifically, it will return events whose start is less than or
* equal to the end of the time period, and whose end is greater than or
* equal to the start of the time period (i.e., all the start and end
* timestamps are treated inclusively).
* <p>
* Optionally, this will also check the event's sessions and exclude any
* events that have no sessions overlapping the specified time period.
* This can happen for events with multiple sessions. For example,
* suppose an event has 2 sessions, one on Monday and the other on
* Friday, and that the specified time period to search was on Wednesday.
* Then by default, the event would be returned, because it starts on
* Monday and ends on Friday, which overlaps the time period being
* searched, but if session checking is enabled, the event would be
* excluded.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date-time
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param id [required] The ID of the programme.
* @param start [optional] The start of the time period to search. If
* omitted, this will default to 0:00am today.
* @param end [optional] The end of the time period to search. If
* omitted, this will default to the first midnight after the start date.
* @param checkSessions [optional] If {@code true}, check the event
* sessions, and exclude any events that have no sessions overlapping the
* the time period being searched.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of events found, in (start date-time, ID) order.
*/
/**
* Get a programme's self-taught events.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param id [required] The ID of the programme.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of self-taught events, in (title, ID) order.
*/
/**
* Methods for querying and manipulating training providers.
*
* <h4>The fetch parameter for providers</h4>
* <p>
* All methods that return providers also accept an optional
* <code>fetch</code> parameter that may be used to request additional
* information about the providers returned. For more details about the
* general rules that apply to the <code>fetch</code> parameter, refer to the
* {@link EventMethods} documentation.
* <p>
* For providers the <code>fetch</code> parameter may be used to fetch
* referenced programmes, themes and venues. The following references are
* supported:
* <ul>
* <li>{@code "institution"} - fetches full details about the provider's
* institution.</li>
* <li>{@code "current_programme"} - fetches the provider's current
* programme, if there is one.</li>
* <li>{@code "programmes"} - fetches all the provider's programmes, in date
* order.</li>
* <li>{@code "themes"} - fetches all the provider's themes.</li>
* <li>{@code "venues"} - fetches all the venues belonging to the
* provider.</li>
* </ul>
* <p>
* As with the event <code>fetch</code> parameter, the references may be used
* in a chain by using the "dot" notation to fetch additional information
* about referenced programmes, themes and venues. For example
* "themes.courses" will fetch all the courses for each of the provider's
* themes. For more information about what can be fetched from referenced
* programmes, themes and venues, refer to the documentation for
* {@link ProgrammeMethods}, {@link ThemeMethods} and {@link VenueMethods}.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Return a list of all training providers.
* <p>
* By default, only a few basic details about each provider are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each provider.
*
* @return The requested providers (in name order).
*/
/**
* Get the training provider with the specified short name (e.g., "UCS").
* <p>
* By default, only a few basic details about the provider are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param shortName [required] The short name of the provider to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested provider or null if it was not found.
*/
/**
* Get the events run by the specified training provider in the specified
* time period.
* <p>
* This will return any events that overlap the specified time period.
* More specifically, it will return events whose start is less than or
* equal to the end of the time period, and whose end is greater than or
* equal to the start of the time period (i.e., all the start and end
* timestamps are treated inclusively).
* <p>
* Optionally, this will also check the event's sessions and exclude any
* events that have no sessions overlapping the specified time period.
* This can happen for events with multiple sessions. For example,
* suppose an event has 2 sessions, one on Monday and the other on
* Friday, and that the specified time period to search was on Wednesday.
* Then by default, the event would be returned, because it starts on
* Monday and ends on Friday, which overlaps the time period being
* searched, but if session checking is enabled, the event would be
* excluded.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date-time
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param shortName [required] The short name of the provider.
* @param start [optional] The start of the time period to search. If
* omitted, this will default to 0:00am today.
* @param end [optional] The end of the time period to search. If
* omitted, this will default to the first midnight after the start date.
* @param checkSessions [optional] If {@code true}, check the event
* sessions, and exclude any events that have no sessions overlapping the
* the time period being searched.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of events found, in (start date-time, ID) order.
*/
/**
* Get all the programmes run by the specified training provider.
* <p>
* By default, only a few basic details about each programme are
* returned, but the optional <code>fetch</code> parameter may be used to
* fetch additional attributes or references of each programme.
*
* @param shortName [required] The short name of the provider.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each programme.
*
* @return The provider's programmes, in (date, ID) order.
*/
/**
* Get the programmes run by the specified training provider in the
* specified date range.
* <p>
* This will return any programmes that overlap the specified date range.
* More specifically, it will return programmes whose start is less than
* or equal to the end date specified, and whose end is greater than or
* equal to the start date specified (i.e., all the start and end dates
* are treated inclusively).
* <p>
* By default, only a few basic details about each programme are
* returned, but the optional <code>fetch</code> parameter may be used to
* fetch additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param shortName [required] The short name of the provider.
* @param startDate [optional] The start date. If omitted, this will
* default to today.
* @param endDate [optional] The end date. If omitted, this will default
* to today.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each programme.
*
* @return A list of programmes found, in (date, ID) order.
*/
/**
* Get all the themes belonging to the specified training provider.
* <p>
* By default, only a few basic details about each theme are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references of each programme.
*
* @param shortName [required] The short name of the provider.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each theme.
*
* @return The provider's themes, in title order.
*/
/**
* Get all the venues belonging to the specified training provider.
* <p>
* By default, only a few basic details about each venue are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references of each programme.
*
* @param shortName [required] The short name of the provider.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each venue.
*
* @return The provider's venues, in name order.
*/
/**
* Methods for querying and manipulating themes.
*
* <h4>The fetch parameter for themes</h4>
* <p>
* All methods that return themes also accept an optional <code>fetch</code>
* parameter that may be used to request additional information about the
* themes returned. For more details about the general rules that apply to
* the <code>fetch</code> parameter, refer to the {@link EventMethods}
* documentation.
* <p>
* For themes the <code>fetch</code> parameter may be used to fetch
* referenced providers, courses and events. The following references are
* supported:
* <ul>
* <li>{@code "provider"} - fetches the theme's provider.</li>
* <li>{@code "courses"} - fetches the theme's courses.</li>
* <li>{@code "events"} - fetches all the theme's events, in (date, ID)
* order.</li>
* </ul>
* <p>
* As with the event <code>fetch</code> parameter, the references may be used
* in a chain by using the "dot" notation to fetch additional information
* about referenced providers, courses and events. For example
* "events.sessions" will fetch all the theme's events and all their
* sessions. For more information about what can be fetched from referenced
* providers, courses and events, refer to the documentation for
* {@link ProviderMethods}, {@link CourseMethods} and {@link EventMethods}.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Return a list of all themes.
* <p>
* By default, only a few basic details about each theme are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each theme.
*
* @return The requested themes, in title order.
*/
/**
* Get the themes with the specified name.
* <p>
* There may be multiple themes with the same name belonging to different
* training providers. If a provider name is also supplied, then at most
* one theme will be returned.
*
* @param name [required] The short name of the themes to fetch.
* @param provName [optional] The short name of a training provider.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each theme.
*
* @return The matching themes, in title order.
*/
/**
* Get the theme with the specified ID.
* <p>
* By default, only a few basic details about the theme are returned, but
* the optional <code>fetch</code> parameter may be used to fetch
* additional details, such as the events in the theme.
*
* @param id [required] The ID of the theme to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested theme or null if it was not found.
*/
/**
* Get the events in the specified theme in the specified time period.
* <p>
* This will return any events that overlap the specified time period.
* More specifically, it will return events whose start is less than or
* equal to the end of the time period, and whose end is greater than or
* equal to the start of the time period (i.e., all the start and end
* timestamps are treated inclusively).
* <p>
* Optionally, this will also check the event's sessions and exclude any
* events that have no sessions overlapping the specified time period.
* This can happen for events with multiple sessions. For example,
* suppose an event has 2 sessions, one on Monday and the other on
* Friday, and that the specified time period to search was on Wednesday.
* Then by default, the event would be returned, because it starts on
* Monday and ends on Friday, which overlaps the time period being
* searched, but if session checking is enabled, the event would be
* excluded.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date-time
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param id [required] The ID of the theme.
* @param start [optional] The start of the time period to search. If
* omitted, this will default to 0:00am today.
* @param end [optional] The end of the time period to search. If
* omitted, this will default to the first midnight after the start date.
* @param checkSessions [optional] If {@code true}, check the event
* sessions, and exclude any events that have no sessions overlapping the
* the time period being searched.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of events found, in (start date-time, ID) order.
*/
/**
* Get a theme's self-taught events.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param id [required] The ID of the theme.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of self-taught events, in (title, ID) order.
*/
/**
* Methods for querying and manipulating venues.
*
* <h4>The fetch parameter for venues</h4>
* <p>
* All methods that return venues also accept an optional <code>fetch</code>
* parameter that may be used to request additional information about the
* venues returned. For more details about the general rules that apply to
* the <code>fetch</code> parameter, refer to the {@link EventMethods}
* documentation.
* <p>
* For venues the <code>fetch</code> parameter may be used to fetch the
* venue's provider:
* <ul>
* <li>{@code "provider"} - fetches the venue's provider.</li>
* </ul>
* <p>
* As with the event <code>fetch</code> parameter, this reference may be used
* in a chain by using the "dot" notation to fetch additional information
* about referenced provider. For example "provider.venues" will fetch the
* venue's provider and all the other venues belonging to that provider. For
* more information about what can be fetched from the referenced provider,
* refer to the documentation for {@link ProviderMethods}.
*
* @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
*/
/**
* Return a list of all venues.
* <p>
* By default, only a few basic details about each venue are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each venue.
*
* @return The requested venues, in name order.
*/
/**
* Get the venue with the specified ID.
* <p>
* By default, only a few basic details about the venue are returned, but
* the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
*
* @param id [required] The ID of the venue to fetch.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch.
*
* @return The requested venue or null if it was not found.
*/
/**
* Get the events held in a venue in the specified time period.
* <p>
* This will return any events that overlap the specified time period.
* More specifically, it will return events whose start is less than or
* equal to the end of the time period, and whose end is greater than or
* equal to the start of the time period (i.e., all the start and end
* timestamps are treated inclusively).
* <p>
* Optionally, this will also check the event's sessions and exclude any
* events that have no sessions overlapping the specified time period.
* This can happen for events with multiple sessions. For example,
* suppose an event has 2 sessions, one on Monday and the other on
* Friday, and that the specified time period to search was on Wednesday.
* Then by default, the event would be returned, because it starts on
* Monday and ends on Friday, which overlaps the time period being
* searched, but if session checking is enabled, the event would be
* excluded.
* <p>
* By default, only a few basic details about each event are returned,
* but the optional <code>fetch</code> parameter may be used to fetch
* additional attributes or references.
* <p>
* NOTE: When using this API directly via the URL endpoints, date-time
* parameters should be supplied as either milliseconds since epoch, or
* as ISO 8601 formatted date or date-time strings.
*
* @param id [required] The ID of the venue.
* @param start [optional] The start of the time period to search. If
* omitted, this will default to 0:00am today.
* @param end [optional] The end of the time period to search. If
* omitted, this will default to the first midnight after the start date.
* @param checkSessions [optional] If {@code true}, check the event
* sessions, and exclude any events that have no sessions overlapping the
* the time period being searched.
* @param fetch [optional] A comma-separated list of any additional
* details to fetch for each event.
*
* @return A list of events found, in (start date-time, ID) order.
*/