Package com.xebialabs.xlrelease.api.v1

# Interface BlackoutApi

All Superinterfaces:
  `ApiService`

@Path("/api/v1/blackouts") @Consumes("application/json") @Produces("application/json") public interface BlackoutApi extends ApiService
Operations on blackout periods.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `SERVICE_NAME`

  ### Fields inherited from interface com.xebialabs.xlrelease.api.ApiService

  `DEFAULT_RESULTS_PER_PAGE, DEFAULT_RESULTS_PER_PAGE_STRING, DEPTH, ORDER_BY, PAGE, PAGE_IS_OFFSET, RESULTS_PER_PAGE, ROLE_IDS_DATA`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Blackout`
  `addBlackout(Blackout blackout)`
  Creates a new blackout period.
  `Blackout`
  `addBlackout(BlackoutForm blackout)`
  Creates a new blackout period.
  `void`
  `deleteBlackout(String blackoutId)`
  Deletes the blackout period with the given identifier.
  `Blackout`
  `getBlackout(String blackoutId)`
  Returns the blackout period for the given identifier.
  `List<Blackout>`
  `getBlackouts()`
  Returns a list of all blackout periods.
  `List<Blackout>`
  `getBlackouts(Date startDate, Date endDate)`
  Returns a list of blackout periods that overlap with the given date range.
  `Blackout`
  `newBlackout(String label, Date startDate, Date endDate)`
  Convenience method to create a new `Blackout` object in memory.
  `default String`
  `serviceName()`
  `Blackout`
  `updateBlackout(Blackout blackout)`
  Updates the blackout period using the identifier from the object.
  `Blackout`
  `updateBlackout(String blackoutId, BlackoutForm blackout)`
  Updates the blackout period with the given identifier.
  `boolean`
  `withinBlackout()`
  Returns whether the current time falls within any active blackout period.

- ## Field Details

  - ### SERVICE_NAME

    static final String SERVICE_NAME
    See Also:
      - Constant Field Values

- ## Method Details

  - ### serviceName

    default String serviceName()
    Specified by:
      `serviceName` in interface `ApiService`

  - ### getBlackouts

    @GET List<Blackout> getBlackouts(@QueryParam("startDate") Date startDate, @QueryParam("endDate") Date endDate)
    Returns a list of blackout periods that overlap with the given date range.
    Parameters:
      `startDate` - the start of the date range.
      `endDate` - the end of the date range.
    Returns:
      the list of blackout periods.

  - ### getBlackouts

    List<Blackout> getBlackouts()
    Returns a list of all blackout periods.
    Returns:
      the list of all blackout periods.

  - ### getBlackout

    @GET @Path("/{blackoutId:.*/Blackout[^/]*}") Blackout getBlackout(@PathParam("blackoutId") String blackoutId)
    Returns the blackout period for the given identifier.
    Parameters:
      `blackoutId` - the full identifier of the blackout period; for example, Configuration/Blackout1.
    Returns:
      the blackout period.

  - ### addBlackout

    @POST Blackout addBlackout(BlackoutForm blackout)
    Creates a new blackout period.
    Parameters:
      `blackout` - the blackout period to add.
    Returns:
      the created blackout period.

  - ### addBlackout

    Blackout addBlackout(Blackout blackout)
    Creates a new blackout period.
    Parameters:
      `blackout` - the blackout period to add.
    Returns:
      the created blackout period.

  - ### updateBlackout

    @PUT @Path("/{blackoutId:.*/Blackout[^/]*}") Blackout updateBlackout(@PathParam("blackoutId") String blackoutId, BlackoutForm blackout)
    Updates the blackout period with the given identifier.
    Parameters:
      `blackoutId` - the full identifier of the blackout period; for example, Configuration/Blackout1.
      `blackout` - the new contents of the blackout period.
    Returns:
      the updated blackout period.

  - ### updateBlackout

    Blackout updateBlackout(Blackout blackout)
    Updates the blackout period using the identifier from the object.
    Parameters:
      `blackout` - the blackout period to update; must have an id set.
    Returns:
      the updated blackout period.

  - ### deleteBlackout

    @DELETE @Path("/{blackoutId:.*/Blackout[^/]*}") void deleteBlackout(@PathParam("blackoutId") String blackoutId)
    Deletes the blackout period with the given identifier.
    Parameters:
      `blackoutId` - the full identifier of the blackout period; for example, Configuration/Blackout1.

  - ### withinBlackout

    @GET @Path("/withinBlackout") boolean withinBlackout()
    Returns whether the current time falls within any active blackout period.
    Returns:
      `true` if the current time is within a blackout period, `false` otherwise.

  - ### newBlackout

    Blackout newBlackout(String label, Date startDate, Date endDate)
    Convenience method to create a new `Blackout` object in memory.

    This method does not persist or activate the blackout period. The blackout is not created in the system until `addBlackout` is called with the returned object.

    Parameters:
      `label` - blackout text
      `startDate` - the start date and time of the blackout
      `endDate` - the end date and time of the blackout
    Returns:
      the in-memory blackout object